1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header (This is for running Texinfo on a region.)
4 @settitle September Gnus Manual
11 @setchapternewpage odd
13 @comment %**end of header (This is for running Texinfo on a region.)
16 %\global\baselineskip 30pt % For printing in double spaces
21 This file documents Gnus, the GNU Emacs newsreader.
23 Copyright (C) 1995 Free Software Foundation, Inc.
25 Permission is granted to make and distribute verbatim copies of
26 this manual provided the copyright notice and this permission notice
27 are preserved on all copies.
30 Permission is granted to process this file through Tex and print the
31 results, provided the printed document carries copying permission
32 notice identical to this one except for the removal of this paragraph
33 (this paragraph not being relevant to the printed manual).
36 Permission is granted to copy and distribute modified versions of this
37 manual under the conditions for verbatim copying, provided also that the
38 entire resulting derived work is distributed under the terms of a
39 permission notice identical to this one.
41 Permission is granted to copy and distribute translations of this manual
42 into another language, under the above conditions for modified versions.
48 @title September Gnus Manual
50 @author by Lars Magne Ingebrigtsen
52 @vskip 0pt plus 1filll
53 Copyright @copyright{} 1995 Free Software Foundation, Inc.
55 Permission is granted to make and distribute verbatim copies of
56 this manual provided the copyright notice and this permission notice
57 are preserved on all copies.
59 Permission is granted to copy and distribute modified versions of this
60 manual under the conditions for verbatim copying, provided that the
61 entire resulting derived work is distributed under the terms of a
62 permission notice identical to this one.
64 Permission is granted to copy and distribute translations of this manual
65 into another language, under the above conditions for modified versions.
67 Cover art by Etienne Suvasa.
74 @top The Gnus Newsreader
76 You can read news (and mail) from within Emacs by using Gnus. The news
77 can be gotten by any nefarious means you can think of - @sc{nntp}, local
78 spool or your mbox file. All at the same time, if you want to push your
82 * History:: How Gnus got where it is today.
83 * Terminology:: We use really difficult, like, words here.
84 * Starting Up:: Finding news can be a pain.
85 * The Group Buffer:: Selecting, subscribing and killing groups.
86 * The Summary Buffer:: Reading, saving and posting articles.
87 * The Article Buffer:: Displaying and handling articles.
88 * The Server Buffer:: Making and editing virtual servers.
89 * 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 * Emacsen:: Gnus can be run on a few modern Emacsen.
138 * Contributors:: Oodles of people.
139 * New Features:: Pointers to some of the new stuff in Gnus.
140 * Newest Features:: Features so new that they haven't been written yet.
146 What's the point of Gnus?
148 I want to provide a "rad", "happening", "way cool" and "hep" newsreader,
149 that lets you do anything you can think of. That was my original
150 motivation, but while working on Gnus, it has become clear to me that
151 this generation of newsreaders really belong in the stone age.
152 Newsreaders haven't developed much since the infancy of the net. If the
153 volume continues to rise with the current rate of increase, all current
154 newsreaders will be pretty much useless. How do you deal with
155 newsgroups that have hundreds (or thousands) of new articles each day?
157 Gnus offer no real solutions to these questions, but I would very much
158 like to see Gnus being used as a testing ground for new methods of
159 reading and fetching news. Expanding on Umeda-san's wise decision to
160 separate the newsreader from the backends, Gnus now offers a simple
161 interface for anybody who wants to write new backends for fetching mail
162 and news from different sources. I have added hooks for customizations
163 everywhere I can imagine useful. By doing so, I'm inviting every one of
164 you to explore and invent new ways of reading news.
166 May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
169 @section Compatibility
171 @cindex compatibility
172 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
173 bindings have been kept. More key bindings have been added, of course,
174 but only in one or two obscure cases have old bindings been changed.
179 @center In a cloud bones of steel.
183 All commands have kept their names. Some internal functions have changed
186 The @code{gnus-uu} package has changed drastically. @xref{Decoding
189 One major compatibility question if the presence of several summary
190 buffers. All variables that are relevant while reading a group are
191 buffer-local to the summary buffer they belong in. Although most
192 important variables have their values copied into their global
193 counterparts whenever a command is executed in the summary buffer, this
194 change might lead to incorrect values being used unless you are careful.
196 All code that relies on knowledge of @sc{gnus} internals will probably
197 fail. To take two examples: Sorting @code{gnus-newsrc-assoc} (or
198 changing it in any way, as a matter of fact) is strictly verboten. Gnus
199 maintains a hash table that points to the entries in this assoc (which
200 speeds up many functions), and changing the assoc directly will lead to
205 Old hilit19 code does not work at all. In fact, you should probably
206 remove all hilit code from all Gnus hooks
207 (@code{gnus-group-prepare-hook}, @code{gnus-summary-prepare-hook} and
208 @code{gnus-summary-article-hook}). (Well, at the very least the first
209 two.) Gnus provides various integrated functions for highlighting.
210 These are faster and more accurate. To make life easier for everybody,
211 Gnus will by default remove all hilit calls from all hilit hooks.
214 Packages like @code{expire-kill} will no longer work. As a matter of
215 fact, you should probably remove all old @sc{gnus} packages (and other
216 code) when you start using Gnus. More likely than not, Gnus already
217 does what you have written code to make @sc{gnus} do. (Snicker.)
219 Even though old methods of doing things are still supported, only the
220 new methods are documented in this manual. If you detect a new method of
221 doing something while reading this manual, that does not mean you have
222 to stop doing it the old way.
224 Gnus understands all @sc{gnus} startup files.
227 Overall, a casual user who hasn't written much code that depends on
228 @sc{gnus} internals should suffer no problems. If problems occur,
229 please let me know (@kbd{M-x gnus-bug}).
231 Problems specific to GNU XEmacs can be reported to popineau@@ese-metz.fr
232 (Fabrice Popineau). I will just forward any such questions to him,
233 anyway, so you might have to wait longer if you mail XEmacs questions to
240 No rebels without a clue here, ma'am. We conform to all standards known
241 to man. Except, of course, where we disagree with the standards and/or
247 There are no known breaches to this standard.
250 There are no known breaches to this standard, either.
252 @item Usenet Seal of Approval
253 Gnus hasn't been formally through the Seal process, but I have read
254 through the Seal text, and I think that Gnus would pass.
256 @item Son-of-RFC 1036
257 We do have some breaches to this one.
261 Gnus does no MIME handling, and this standard-to-be seems to think that
262 MIME is the bees' knees, so we have major breakage here.
264 This is considered to be a "vanity header", while I consider it to be
265 consumer information. After seeing so many badly formatted articles
266 coming from @code{tin} and @code{Netscape} I know not to use either of
267 those for posting articles. I would not have known that if it wasn't
268 for the @code{X-Newsreader} header.
270 Gnus does line breaking on this header. I infer from RFC1036 that being
271 conservative in what you output is not creating 5000-character lines, so
272 it seems like a good idea to me. However, this standard-to-be says that
273 whitespace in the @code{References} header is to be preserved, so... It
274 doesn't matter one way or the other to Gnus, so if somebody tells me
275 what The Way is, I'll change it. Or not.
280 If you ever see Gnus act noncompliantly to the texts mentioned above,
281 don't hesitate to drop a note to Gnus Towers and let us know.
291 Gnus should work on Emacs 19.26 and up, XEmacs 19.12 and up and Mule.
292 There are some vague differences in what Gnus does, though:
297 The mouse-face on Gnus lines under Emacs and Mule is delimited to
298 certain parts of the lines while they cover the entire line under
302 The same with current-article marking -- XEmacs puts an underline under
303 the entire article while Emacs and Mule are nicer and kinder.
306 XEmacs features more graphics -- a logo and a toolbar.
309 Citation highlighting us better under Emacs and Mule than under XEmacs.
312 Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
319 @section Contributors
322 The new Gnus version couldn't have been done without the help of all the
323 people on the (ding) mailing list. Every day for months I have gotten
324 tens of nice bug reports from them, filling me with joy, every single
325 one of them. Smooches. The people on the list have been tried beyond
326 endurance, what with my "oh, that's a neat idea <type type>, yup, I'll
327 release it right away <ship off> no wait, that doesn't work at all <type
328 type>, yup, I'll ship that one off right away <ship off> no, wait, that
329 absolutely does not work" policy for releases. Microsoft - bah. I'm
332 I would like to take this opportunity to thank the Academy for... oops,
337 Of course, GNUS was written by Masanobu UMEDA.
339 Many excellent functions, especially dealing with scoring and
340 highlighting (as well as the soon-to-come @sc{soup} support) was written
343 Innumerable bug fixes were written by Sudish Joseph.
345 The refcard was written by Vladimir Alexiev.
347 I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
349 nnfolder has been much enhanced by Scott Byer.
351 The orphan scoring was written by Peter Mutsaers.
353 GNU XEmacs support has been added by Fabrice Popineau.
355 Various bits and pieces, especially dealing with .newsrc files, was
356 suggested and added by Hallvard B Furuseth.
358 Brian Edmonds has written @code{gnus-bbdb}, as well as other bits and
361 Ricardo Nassif did the proof-reading.
363 Kevin Davidson came up with the name @dfn{ding}, so blame him.
365 Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel Quinlan, Ilja
366 Weis, Frank D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have
367 all contributed code and suggestions.
372 @section New Features
378 The look of all buffers can be changed by setting format-like variables
379 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
382 Local spool and several @sc{nntp} servers can be used at once
383 (@pxref{Foreign Groups}).
386 You can combine groups into virtual groups (@pxref{nnvirtual}).
389 You can read a number of different mail formats (@pxref{Reading Mail}).
390 All the mail backends implement a convenient mail expiry scheme
391 (@code{Expiring Old Mail Articles}).
394 Gnus can use various strategies for gathering threads that have lost
395 their roots (thereby gathering loose sub-threads in one thread) or it
396 can go back and retrieve enough headers to build a complete thread
397 (@pxref{Customizing Threading}).
400 Killed groups can be displayed in the group buffer, and you can read
404 Gnus can do partial group updates - you do not have to retrieve the
405 entire active file just to check for new articles in a few groups
406 (@pxref{The Active File}).
409 Gnus implements a sliding scale of subscribedness to groups
410 (@pxref{Group Levels}).
413 You can score articles according to any number of criteria (@pxref{Score
414 Files}). You can even get Gnus to score articles for you
415 (@pxref{Adaptive Scoring}).
418 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
419 manner, so it should be difficult to lose much data on what you have
420 read if your machine should go down (@pxref{Auto Save}).
423 Gnus now has its own startup file to avoid cluttering up the
427 You can set the process mark on both groups and articles and perform
428 operations on all the marked items (@pxref{Process/Prefix}).
431 You can grep through a subset of groups and create a group from the
432 results (@pxref{nnkiboze}).
435 You can list subsets of groups according to, well, anything
436 (@pxref{Listing Groups}).
439 You can browse foreign servers and subscribe to groups from those
440 servers (@pxref{Browse Foreign Server}).
443 Gnus can fetch articles asynchronously on a second connection to the
444 server (@pxref{Asynchronous Fetching}).
447 You can cache articles locally (@pxref{Article Caching}).
450 The uudecode functions have been expanded and generalized
451 (@pxref{Decoding Articles}).
454 You can still post uuencoded articles, which was a little-known feature
455 of @sc{gnus} past (@pxref{Uuencoding & Posting}).
458 Fetching parents (and other articles) now actually works without
459 glitches (@pxref{Finding the Parent}).
462 Gnus can fetch FAQs to and descriptions of groups (@pxref{Group
466 Digests (and other files) can be used as the basis for groups
470 Articles can be highlighted and customized (@pxref{Customizing
474 All Gnus buffers can be customized in a difficult fashion
475 (@pxref{Windows Configuration}).
478 You can click on buttons instead of using the keyboard
483 This is, of course, just a @emph{short} overview of the @emph{most}
484 important new features. No, really. There are tons more. Yes, we have
485 feeping creaturism in full effect, but nothing too gratuitous, I would
489 @node Newest Features
490 @section Newest Features
493 Also known as the @dfn{todo list}. Sure to be implemented before the
496 Be afraid. Be very afraid.
500 Native @sc{mime} support is something that should be done. I was hoping
501 I could steal code from @code{Mew}, the @sc{mime} mail reader for Emacs,
502 but I'm not quite sure what the status of that project is. Gnus might
503 support @sc{mime} quite soon, and it might not.
506 @code{trn}-like trees.
508 @code{nn}-like pick-and-read summary interface.
514 Re-sending bounced mail and rejected articles.
516 Floating point group levels and group bubbling.
518 @file{/etc/nntpserver} usage.
520 Automatic re-scan of incoming mail.
522 Buttonize more stuff in the article buffer.
524 A better and simpler method for specifying mail composing methods.
526 Marks for saved, forwarded, etc articles.
528 Speed up caching and adaptive scoring.
530 Gather thread by filling in missing Message-IDs.
532 Slave Gnusii to enable several Gnusii to run at once.
536 Allow posting through mail-to-news gateways.
538 Allow renaming mail groups in a simple fashion.
540 Speed up massive group massacres.
542 @code{jka-compr} isn't fully supported.
544 Create better digests.
546 Do better word-wrap on cited text.
548 Better X-Face support with X-Face databases and stuff.
550 Support SELF-DISCIPLINE pins.
552 Really do unbinhexing.
554 Fetching by Message-ID should work in mail groups.
556 Listing of all active groups.
560 Do the X-Receipt-To thing.
562 Hierarchal group buffers.
564 Don't kill summary buffers upon exit from the groups.
566 Allow adaption on secondary marks.
569 And much, much, much more. There is more to come than has already been
570 implemented. (But that's always true, isn't it?)
572 You can probably sneak a look at the actual up-to-the-second todo list
573 by snooping @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>}.
582 This is what you are supposed to use this thing for - reading news.
583 News is generally fetched from a nearby @sc{nntp} server, and is
584 generally publicly available to everybody. If you post news, the entire
585 world is likely to read just what you have written, and they'll all
586 snigger mischievously. Behind your back.
589 Everything that's delivered to you personally is mail. Some news/mail
590 readers (like Gnus) blur the distinction between mail and news, but
591 there is a difference. Mail is private. News is public. Mailing is
592 not posting, and replying is not following up.
594 Send a mail to the person who has written what you are reading.
596 Post an article to the current newsgroup responding to the article you
599 Gnus gets fed articles from a number of backends, both news and mail
600 backends. Gnus does not handle the underlying media, so to speak - this
601 is all done by the backends.
603 Gnus will always use one method (and backend) as the @dfn{native}, or
604 default, way of getting news.
606 You can also have any number of foreign groups at the same time. These
607 are groups that use different backends for getting news.
610 The top part of an article, where administration information (etc.) is
614 The rest of an article. Everything that is not in the head is in the
618 A line from the head of an article.
621 A collection of such lines, or a collection of heads. Or even a
622 collection of @sc{nov} lines.
625 When Gnus enters a group, it asks the backend for the headers for all
626 the unread articles in the group. Most servers support the News OverView
627 format, which is much smaller and much faster to read than the normal
631 Each group is subscribed at some @dfn{level} or other (1-9). The ones
632 that have a lower level are "more" subscribed than the groups with a
633 higher level. In fact, groups on levels 1-5 are considered
634 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
635 are @dfn{killed}. Commands for listing groups and scanning for new
636 articles will all use the numeric prefix as @dfn{working level}.
638 @cindex killed groups
639 No information on killed groups is stored or updated, which makes killed
640 groups much easier to handle than subscribed groups.
642 @cindex zombie groups
643 Just like killed groups, only slightly less dead.
646 The news server has to keep track of what articles it carries, and what
647 groups exist. All this information in stored in the active file, which
648 is rather large, as you might surmise.
651 A group that exists in the @file{.newsrc} file, but isn't known to the
652 server (i. e., it isn't in the active file), is a @emph{bogus group}.
653 This means that the group probably doesn't exist (any more).
657 @chapter Starting Gnus
661 If your system administrator has set things up properly, starting Gnus
662 and reading news is extremely easy - you just type @kbd{M-x gnus}.
664 If things do not go smoothly at startup, you have to twiddle some
668 * Finding the News:: Choosing a method for getting news.
669 * The First Time:: What does Gnus do the first time you start it?
670 * The Server is Down:: How can I read my mail then?
671 * Slave Gnusii:: You can have more than one Gnus active at a time.
672 * New Groups:: What is Gnus supposed to do with new groups?
673 * Startup Files:: Those pesky startup files - @file{.newsrc}.
674 * Auto Save:: Recovering from a crash.
675 * The Active File:: Reading the active file over a slow line Takes Time.
676 * Startup Variables:: Other variables you might change.
679 @node Finding the News
680 @section Finding the News
682 @vindex gnus-select-method
683 The @code{gnus-select-method} variable controls how Gnus finds news.
684 This variable should be a list where the first element says @dfn{how}
685 and the second element says @dfn{where}. This method is is your native
686 method. All groups that are not fetched with this method are foreign
689 For instance, if you want to get your daily dosage of news from the
690 @samp{news.somewhere.edu} @sc{nntp} server, you'd say:
693 (setq gnus-select-method '(nntp "news.somewhere.edu"))
696 If you want to read directly from the local spool, say:
699 (setq gnus-select-method '(nnspool ""))
702 If you can use a local spool, you probably should, as it will almost
703 certainly be much faster.
705 @vindex gnus-nntpserver-file
708 If this variable is not set, Gnus will take a look at the
709 @code{NNTPSERVER} environment variable. If that variable isn't set,
710 Gnus will see whether @code{gnus-nntpserver-file} (default
711 @file{/etc/nntpserver}) has any opinions in the matter. It that fails
712 as well, Gnus will will try to use the machine that is running Emacs as
713 an @sc{nntp} server. That's a longshot, though.
715 @vindex gnus-nntp-server
716 If @code{gnus-nntp-server} is set, this variable will override
717 @code{gnus-select-method}. You should therefore set
718 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
720 @vindex gnus-secondary-servers
721 You can also make Gnus prompt you interactively for the name of an
722 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
723 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
724 in the @code{gnus-secondary-servers} list (if any). You can also just
725 type in the name of any server you feel like visiting.
727 However, if you use one @sc{nntp} server regularly, and are just
728 interested in a couple of groups from a different server, you would be
729 better served by using the @code{gnus-group-browse-foreign-server}
730 command from the group buffer. It will let you have a look at what
731 groups are available, and you can subscribe to any of the groups you
732 want to. This also makes @file{.newsrc} maintenance much tidier.
733 @xref{Foreign Groups}.
735 @vindex gnus-secondary-select-methods
736 A slightly different approach to foreign groups is to set the
737 @code{gnus-secondary-select-methods} variable. The select methods
738 listed in this variable are in many ways just as native as the
739 @code{gnus-select-method} server. They will also be queried for active
740 files during startup (if that's required), and new newsgroups that
741 appear on these servers will be subscribed (or not) just as native
744 For instance, if you use the @code{nnmbox} backend to read you mail, you
745 would typically set this variable to
748 (setq gnus-secondary-select-methods '((nnmbox "")))
752 @section The First Time
753 @cindex first time usage
755 If no startup files exist, Gnus will try to determine what groups should
756 be subscribed by default.
758 @vindex gnus-default-subscribed-newsgroups
759 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
760 will subscribe you to just those groups in that list, leaving the rest
761 killed. Your system administrator should have set this variable to
764 Since she hasn't, Gnus will just subscribe you to a few randomly picked
765 groups (i.e., @samp{*.newusers}). (@dfn{Random} is here defined as
766 "whatever Lars thinks you should read".)
768 You'll also be subscribed to the Gnus documentation group, which should
769 help you with most common problems.
771 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
772 use the normal functions for handling new groups, and not do anything
775 @node The Server is Down
776 @section The Server is Down
777 @cindex server errors
779 If the default server is down, Gnus will understandably have some
780 problems starting. However, if you have some mail groups in addition to
781 the news groups, you may want to start Gnus anyway.
783 Gnus, being the trusting sort of program, will ask whether to proceed
784 without a native select method if that server can't be contacted. This
785 will happen whether the server doesn't actually exist (i.e., you have
786 given the wrong address) or the server has just momentarily taken ill
787 for some reason or other.
789 If Gnus says "nntp server on <your server> can't be opened. Continue?",
790 you do not want to continue unless you have some foreign groups that you
791 want to read. Even if you don't, Gnus will let you continue, but you'll
792 find it difficult to actually do anything in the group buffer. But,
793 hey, that's your problem. Blllrph!
795 @findex gnus-no-server
796 If you know that the server is definitely down, or you just want to read
797 your mail without bothering with the server at all, you can use the
798 @code{gnus-no-server} command to start Gnus. That might come in handy
799 if you're in a hurry as well.
803 @section Slave Gnusii
806 You might with to run more than one Emacs with more than one Gnus at the
807 same time. If you are using different @file{.newsrc} files (eg., if you
808 are using the two different Gnusii to read from two different servers),
809 that is no problem whatsoever. You just do it.
811 The problem appears when you want to run two Gnusii that uses the same
814 To work around that problem some, we here at the Think-Tank at the Gnus
815 Towers have come up with a new concept: @dfn{Master} and
816 @dfn{servants}. (We have applied for a patent on this concept, and have
817 taken out a copyright on those words. If you wish to use those words in
818 conjunction with each other, you have to send ¢1 per usage to me. Usage
819 of the patent (@dfn{Master/Slave Relationships In Computer
820 Applications}), that will be much more expensive, of course.)
822 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
823 however you do it). Each subsequent slave Gnusii should be started with
824 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
825 files, but some slave files that contains only information on what
826 groups have been read in the slave session. When a master Gnus starts,
827 it will read (and delete) these slave files, incorporating all
828 information from all of them. (The slave files will be read in the
829 sequence they were created, so the latest changes will have presedence.)
831 Information from the slave files has, of course, presedence over the
832 information in the normal (i. e., master) @code{.newsrc} file.
839 @vindex gnus-subscribe-newsgroup-method
840 What Gnus does when it encounters a new group is determined by the
841 @code{gnus-subscribe-newsgroup-method} variable.
843 This variable should contain a function. Some handy pre-fab values
847 @item gnus-subscribe-randomly
848 @vindex gnus-subscribe-randomly
849 Subscribe all new groups randomly.
850 @item gnus-subscribe-alphabetically
851 @vindex gnus-subscribe-alphabetically
852 Subscribe all new groups alphabetically.
853 @item gnus-subscribe-hierarchically
854 @vindex gnus-subscribe-hierarchically
855 Subscribe all new groups hierarchically.
856 @item gnus-subscribe-interactively
857 @vindex gnus-subscribe-interactively
858 Subscribe new groups interactively. This means that Gnus will ask
859 you about @strong{all} new groups.
860 @item gnus-subscribe-zombies
861 @vindex gnus-subscribe-zombies
862 Make all new groups zombies. You can browse the zombies later and
863 either kill them all off properly, or subscribe to them. This is the
867 @vindex gnus-subscribe-hierarchical-interactive
868 A closely related variable is
869 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
870 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
871 hierarchical fashion whether to subscribe to new groups or not. Gnus
872 will ask you for each sub-hierarchy whether you want to descend the
875 One common way to control which new newsgroups should be subscribed or
876 ignored is to put an @dfn{options} line at the start of the
877 @file{.newsrc} file. Here's an example:
880 options -n !alt.all !rec.all sci.all
883 @vindex gnus-subscribe-options-newsgroup-method
884 This line obviously belongs to a serious-minded intellectual scientific
885 person (or she may just be plain old boring), because it says that all
886 groups that have names beginning with @samp{alt} and @samp{rec} should
887 be ignored, and all groups with names beginning with @samp{sci} should
888 be subscribed. Gnus will not use the normal subscription method for
889 subscribing these groups.
890 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
891 variable defaults to @code{gnus-subscribe-alphabetically}.
893 @vindex gnus-options-not-subscribe
894 @vindex gnus-options-subscribe
895 If you don't want to mess with your @file{.newsrc} file, you can just
896 set the two variables @code{gnus-options-subscribe} and
897 @code{gnus-options-not-subscribe}. These two variables do exactly the
898 same as the @file{.newsrc} options -n trick. Both are regexps, and if
899 the the new group matches the first, it will be unconditionally
900 subscribed, and if it matches the latter, it will be ignored.
902 @vindex gnus-check-new-newsgroups
903 If you are satisfied that you really never want to see any new groups,
904 you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
905 also save you some time at startup. Even if this variable is
906 @code{nil}, you can always subscribe to the new groups just by pressing
907 @kbd{U} in the group buffer (@pxref{Group Maintenance}).
909 Gnus normally determines whether a group is new or not by comparing the
910 list of groups from the active file(s) with the lists of subscribed and
911 dead groups. This isn't a particularly fast method. If
912 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
913 server for new groups since the last time. This is both faster &
914 cheaper. This also means that you can get rid of the list of killed
915 groups altogether, so you may set @code{gnus-save-killed-list} to
916 @code{nil}, which will save time both at startup, at exit, and all over.
917 Saves disk space, too. Why isn't this the default, then?
918 Unfortunately, not all servers support this function.
920 This variable can also be a list of select methods. If so, Gnus will
921 issue an @code{ask-server} command to each of the select methods, and
922 subscribe them (or not) using the normal methods. This might be handy
923 if you are monitoring a few servers for new groups. A side effect is
924 that startup will take much longer, so you can meditate while waiting.
925 Use the mantra "dingnusdingnusdingnus" to achieve permanent happiness.
928 @section Startup Files
929 @cindex startup files
932 Now, you all know about the @file{.newsrc} file. All subscription
933 information is traditionally stored in this file.
935 Things got a bit more complicated with @sc{gnus}. In addition to
936 keeping the @file{.newsrc} file updated, it also used a file called
937 @file{.newsrc.el} for storing all the information that didn't fit into
938 the @file{.newsrc} file. (Actually, it duplicated everything in the
939 @file{.newsrc} file.) @sc{gnus} would read whichever one of these files
940 that were the most recently saved, which enabled people to swap between
941 @sc{gnus} and other newsreaders.
943 That was kinda silly, so Gnus went one better: In addition to the
944 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
945 @file{.newsrc.eld}. It will read whichever of these files that are most
946 recent, but it will never write a @file{.newsrc.el} file.
948 @vindex gnus-save-newsrc-file
949 You can also turn off writing the @file{.newsrc} file by setting
950 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
951 the file and save some space, as well as making exit from Gnus faster.
952 However, this will make it impossible to use other newsreaders than
953 Gnus. But hey, who would want to, right?
955 @vindex gnus-save-killed-list
956 If @code{gnus-save-killed-list} is @code{nil}, Gnus will not save the
957 list of killed groups to the startup file. This will save both time
958 (when starting and quitting) and space (on disk). It will also means
959 that Gnus has no record of what groups are new or old, so the automatic
960 new groups subscription methods become meaningless. You should always
961 set @code{gnus-check-new-newsgroups} to @code{nil} or @code{ask-server}
962 if you set this variable to @code{nil} (@pxref{New Groups}).
964 @vindex gnus-startup-file
965 The @code{gnus-startup-file} variable says where the startup files are.
966 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
967 file being whatever that one is with a @samp{.eld} appended.
969 @vindex gnus-save-newsrc-hook
970 @code{gnus-save-newsrc-hook} is called before saving the @file{.newsrc}
978 Whenever you do something that changes the Gnus data (reading articles,
979 catching up, killing/subscribing groups), the change is added to a
980 special @dfn{dribble buffer}. This buffer is auto-saved the normal
981 Emacs way. If your Emacs should crash before you have saved the
982 @file{.newsrc} files, all changes you have made can be recovered from
985 If Gnus detects this file at startup, it will ask the user whether to
986 read it. The auto save file is deleted whenever the real startup file is
989 @vindex gnus-use-dribble-file
990 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
991 maintain a dribble buffer.
993 @node The Active File
994 @section The Active File
996 @cindex ignored groups
998 When Gnus starts, or indeed whenever it tries to determine whether new
999 articles have arrived, it reads the active file. This is a very large
1000 file that lists all the active groups and articles on the @sc{nntp}
1003 @vindex gnus-ignored-newsgroups
1004 Before examining the active file, Gnus deletes all lines that match the
1005 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
1006 any groups with bogus names, but you can use this variable to make Gnus
1007 ignore hierarchies you aren't ever interested in. This variable is
1008 @code{nil} by default, and will slow down active file handling somewhat
1009 if you set it to anything else.
1011 @vindex gnus-read-active-file
1012 The active file can be rather Huge, so if you have a slow network, you
1013 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
1014 reading the active file.
1016 Gnus will try to make do by just getting information on the groups
1017 that you actually subscribe to.
1019 Note that if you subscribe to lots and lots of groups, setting this
1020 variable to @code{nil} will probably make Gnus slower, not faster. At
1021 present, having this variable @code{nil} will slow Gnus down
1022 considerably, unless you read news over a 2400 baud modem.
1024 This variable can also have the value @code{some}. Gnus will then
1025 attempt to read active info only on the subscribed groups. On some
1026 servers this is quite fast (on sparkling, brand new INN servers that
1027 support the @samp{LIST ACTIVE group} command), on others this is not
1028 fast at all. In any case, @code{some} should be faster than @code{nil},
1029 and is certainly faster than @code{t} over slow lines.
1031 If this variable is @code{nil}, Gnus will as for group info in total
1032 lock-step, which isn't very fast. If it is @code{some} and you use an
1033 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
1034 read all the replies in one swoop. This will normally result in better
1035 performance, but if the server does not support the aforementioned
1036 @samp{LIST ACTIVE group} command, this isn't very nice to the server.
1038 In any case, if you use @code{some} or @code{nil}, you should kill all
1039 groups that you aren't interested in.
1041 @node Startup Variables
1042 @section Startup Variables
1045 @item gnus-load-hook
1046 @vindex gnus-load-hook
1047 A hook that is run while Gnus is being loaded. Note that this hook will
1048 normally be run just once in a single Emacs session, no matter how many
1049 times you start Gnus.
1051 @item gnus-startup-hook
1052 @vindex gnus-startup-hook
1053 A hook that is run after starting up Gnus successfully.
1055 @item gnus-check-bogus-newsgroups
1056 @vindex gnus-check-bogus-newsgroups
1057 If non-@code{nil}, Gnus will check for and delete all bogus groups at
1058 startup. A @dfn{bogus group} is a group that you have in your
1059 @file{.newsrc} file, but doesn't exist on the news server. Checking for
1060 bogus groups isn't very quick, so to save time and resources, it's best
1061 to leave this option off, and instead do the checking for bogus groups
1062 once in a while from the group buffer (@pxref{Group Maintenance}).
1064 @item gnus-inhibit-startup-message
1065 @vindex gnus-inhibit-startup-message
1066 If non-@code{nil}, the startup message won't be displayed. That way,
1067 your boss might not notice that you are reading news instead of doing
1070 @item gnus-no-groups-message
1071 @vindex gnus-no-groups-message
1072 Message displayed by Gnus when no groups are available.
1075 @node The Group Buffer
1076 @chapter The Group Buffer
1077 @cindex group buffer
1079 The @dfn{group buffer} lists all (or parts) of the available groups. It
1080 is the first buffer shown when Gnus starts, and will never be killed as
1081 long as Gnus is active.
1084 * Group Buffer Format:: Information listed and how you can change it.
1085 * Group Maneuvering:: Commands for moving in the group buffer.
1086 * Selecting a Group:: Actually reading news.
1087 * Group Subscribing:: Unsubscribing, killing, subscribing.
1088 * Group Levels:: Levels? What are those, then?
1089 * Marking Groups:: You can mark groups for later processing.
1090 * Foreign Groups:: How to create foreign groups.
1091 * Group Parameters:: Each group may have different parameters set.
1092 * Listing Groups:: Gnus can list various subsets of the groups.
1093 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
1094 * Browse Foreign Server:: You can browse a server. See what if has to offer.
1095 * Exiting Gnus:: Stop reading news and get some work done.
1096 * Misc Group Stuff:: Other stuff that you can to do.
1099 @node Group Buffer Format
1100 @section Group Buffer Format
1101 @cindex group buffer format
1103 The default format of the group buffer is nice and dull, but you can
1104 make it as exciting and ugly as you feel like.
1106 Here's a couple of example group lines:
1109 25: news.announce.newusers
1110 * 0: alt.fan.andrea-dworkin
1115 You can see that there are 25 unread articles in
1116 @samp{news.announce.newusers}. There are no unread articles, but some
1117 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1118 asterisk at the beginning of the line?)
1120 @vindex gnus-group-line-format
1121 You can fuck that up to your heart's delight by fiddling with the
1122 @code{gnus-group-line-format} variable. This variable works along the
1123 lines of a @code{format} specification, which is pretty much the same as
1124 a @code{printf} specifications, for those of you who use (feh!) C.
1126 In addition to the normal "padding" specs that @code{format} supports
1127 (eg. @samp{%7d}), specifications like @samp{%7,12s} are allowed. A spec
1128 of this type means that the field will be at least 7 characters long,
1129 and never more that 12 characters long.
1131 The default value that produced those lines above is
1132 @samp{"%M%S%5y: %(%g%)\n"}.
1134 There should always be a colon on the line; the cursor always moves to
1135 the colon after performing an operation. Nothing else is required - not
1136 even the group name. All displayed text is just window dressing, and is
1137 never examined by Gnus. Gnus stores all real information it needs using
1140 (Note that if you make a really strange, wonderful, spreadsheet-like
1141 layout, everybody will believe you are hard at work with the accounting
1142 instead of wasting time reading news.)
1144 Here's a list of all available format characters:
1148 Only marked articles.
1150 Whether the group is subscribed.
1152 Level of subscribedness.
1154 Number of unread articles.
1156 Number of dormant articles.
1158 Number of ticked articles.
1160 Number of read articles.
1162 Total number of articles.
1164 Number of unread, unticked, non-dormant articles.
1166 Number of ticked and dormant articles.
1172 Newsgroup description.
1182 A string that looks like @samp{<%s:%n>} if a foreign select method is
1185 User defined specifier. The next character in the format string should
1186 be a letter. @sc{gnus} will call the function
1187 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1188 following @samp{%u}. The function will be passed the current headers as
1189 argument. The function should return a string, which will be inserted
1190 into the buffer just like information from any other specifier.
1194 All the "number-of" specs will be filled with an asterisk (@samp{*}) if
1195 no info is available - for instance, if it is a non-activated foreign
1196 group, or a bogus (or semi-bogus) native group.
1198 @vindex gnus-group-mode-line-format
1199 The mode line can be changed by setting
1200 (@code{gnus-group-mode-line-format}). It doesn't understand that many
1205 Default news server.
1207 Default select method.
1210 @node Group Maneuvering
1211 @section Group Maneuvering
1212 @cindex group movement
1214 All movement commands understand the numeric prefix and will behave as
1215 expected, hopefully.
1220 @findex gnus-group-next-unread-group
1221 Go to the next group that has unread articles
1222 (@code{gnus-group-next-unread-group}).
1227 @findex gnus-group-prev-unread-group
1228 Go to the previous group group that has unread articles
1229 (@code{gnus-group-prev-unread-group}).
1232 @findex gnus-group-next-group
1233 Go to the next group (@code{gnus-group-next-group}).
1236 @findex gnus-group-prev-group
1237 Go to the previous group (@code{gnus-group-prev-group}).
1240 @findex gnus-group-next-unread-group-same-level
1241 Go to the next unread group on the same level (or lower)
1242 (@code{gnus-group-next-unread-group-same-level}).
1245 @findex gnus-group-prev-unread-group-same-level
1246 Go to the previous unread group on the same level (or lower)
1247 (@code{gnus-group-prev-unread-group-same-level}).
1250 Three commands for jumping to groups:
1255 @findex gnus-group-jump-to-group
1256 Jump to a group (and make it visible if it isn't already)
1257 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1261 @findex gnus-group-best-unread-group
1262 Jump to the unread group with the lowest level
1263 (@code{gnus-group-best-unread-group}).
1266 @findex gnus-group-first-unread-group
1267 Jump to the first group with unread articles
1268 (@code{gnus-group-first-unread-group}).
1271 @vindex gnus-group-goto-unread
1272 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1273 commands will move to the next group, not the next unread group. Even
1274 the commands that say they move to the next unread group.
1276 @node Selecting a Group
1277 @section Selecting a Group
1278 @cindex group selection
1282 @kindex SPACE (Group)
1283 @findex gnus-group-read-group
1284 Select the current group, switch to the summary buffer and display the
1285 first unread article (@code{gnus-group-read-group}). If there are no
1286 unread articles in the group, or if you give a non-numerical prefix to
1287 this command, Gnus will offer to fetch all the old articles in this
1288 group from the server. If you give a numerical prefix @var{N}, Gnus
1289 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1290 the @var{N} newest articles, if @var{N} is negative, fetch the
1291 @var{abs(N)} oldest articles.
1294 @findex gnus-group-select-group
1295 Select the current group and switch to the summary buffer
1296 (@code{gnus-group-select-group}). Takes the same arguments as
1297 @code{gnus-group-read-group} - the only difference is that this command
1298 does not display the first unread article automatically upon group
1302 @findex gnus-group-catchup-current
1303 Mark all unticked articles in this group as read
1304 (@code{gnus-group-catchup-current}).
1307 @findex gnus-group-catchup-current-all
1308 Mark all articles in this group, even the ticked ones, as read
1309 (@code{gnus-group-catchup-current-all}).
1312 @vindex gnus-large-newsgroup
1313 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1314 to be a big group. If the group has more unread articles than this,
1315 Gnus will query the user before entering the group. The user can then
1316 specify how many articles should be fetched from the server. If the
1317 user specifies a negative number (@samp{-n}), the @samp{n} oldest
1318 articles will be fetched. If it is positive, the @samp{n} articles that
1319 have arrived most recently will be fetched.
1321 @vindex gnus-select-group-hook
1322 @vindex gnus-auto-select-first
1323 If @code{gnus-auto-select-first} is non-@code{nil}, the first unread
1324 article in the group will be displayed when you enter the group. If you
1325 want to prevent automatic selection in some group (say, in a binary
1326 group with Huge articles) you can set this variable to @code{nil} in
1327 @code{gnus-select-group-hook}, which is called when a group is selected.
1329 @findex gnus-thread-sort-by-total-score
1330 @findex gnus-thread-sort-by-date
1331 @findex gnus-thread-sort-by-score
1332 @findex gnus-thread-sort-by-subject
1333 @findex gnus-thread-sort-by-author
1334 @findex gnus-thread-sort-by-number
1335 @vindex gnus-thread-sort-functions
1336 If you are using a threaded summary display, you can sort the threads by
1337 setting @code{gnus-thread-sort-functions}, which is a list of functions.
1338 By default, sorting is done on article numbers. Ready-made sorting
1339 functions include @code{gnus-thread-sort-by-number},
1340 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
1341 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score},
1342 @code{gnus-thread-sort-by-total-score}.
1344 Each function takes two threads and return non-@code{nil} if the first
1345 thread should be sorted before the other. If you use more than one
1346 function, the primary sort key should be the last function in the list.
1348 If you would like to sort by score, then by subject, and finally by
1349 date, you could do something like:
1352 (setq gnus-thread-sort-functions
1353 '(gnus-thread-sort-by-date
1354 gnus-thread-sort-by-subject
1355 gnus-thread-sort-by-score))
1358 @vindex gnus-thread-score-function
1359 The function in the @code{gnus-thread-score-function} variable (default
1360 @code{+}) is used for calculating the total score of a thread. Useful
1361 functions might be @code{max}, @code{min}, or squared means, or whatever
1364 @node Group Subscribing
1365 @section Group Subscribing
1373 @findex gnus-group-unsubscribe-current-group
1374 Toggle subscription to the current group
1375 (@code{gnus-group-unsubscribe-current-group}).
1380 @findex gnus-group-unsubscribe-group
1381 Prompt for a group to subscribe, and then subscribe it. If it was
1382 subscribed already, unsubscribe it instead
1383 (@code{gnus-group-unsubscribe-group}).
1388 @findex gnus-group-kill-group
1389 Kill the current group (@code{gnus-group-kill-group}).
1394 @findex gnus-group-yank-group
1395 Yank the last killed group (@code{gnus-group-yank-group}).
1400 @findex gnus-group-kill-region
1401 Kill all groups in the region (@code{gnus-group-kill-region}).
1404 @findex gnus-group-kill-all-zombies
1405 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1409 @section Group Levels
1412 All groups have a level of @dfn{subscribedness}. For instance, if a
1413 group is on level 2, it is more subscribed than a group on level 5. You
1414 can ask Gnus to just list groups on a given level or lower
1415 (@pxref{Listing Groups}), or to just check for new articles in groups on
1416 a given level or lower (@pxref{Misc Group Stuff}).
1421 @findex gnus-group-set-current-level
1422 Set the level of the current group. If a numeric prefix is given, the
1423 next @var{n} groups will have their levels set. The user will be
1424 prompted for a level.
1427 @vindex gnus-level-killed
1428 @vindex gnus-level-zombie
1429 @vindex gnus-level-unsubscribed
1430 @vindex gnus-level-subscribed
1431 Gnus considers groups on between levels 1 and
1432 @code{gnus-level-subscribed} (inclusive) to be subscribed,
1433 @code{gnus-level-subscribed} (exclusive) and
1434 @code{gnus-level-unsubscribed} (inclusive) to be unsubscribed,
1435 @code{gnus-level-zombie} to be zombies (walking dead) and
1436 @code{gnus-level-killed} to be killed, completely dead. Gnus treats
1437 subscribed and unsubscribed groups exactly the same, but zombie and
1438 killed groups have no information on what articles you have read, etc,
1439 stored. This distinction between dead and living groups isn't done
1440 because it is nice or clever, it is done purely for reasons of
1443 It is recommended that you keep all your mail groups (if any) on quite
1444 low levels (eg. 1 or 2).
1446 If you want to play with the level variables, you should show some care.
1447 Set them once, and don't touch them ever again. Better yet, don't touch
1448 them at all unless you know exactly what you're doing.
1450 @vindex gnus-level-default-unsubscribed
1451 @vindex gnus-level-default-subscribed
1452 Two closely related variables are @code{gnus-level-default-subscribed}
1453 and @code{gnus-level-default-unsubscribed}, which are the levels that new
1454 groups will be put on if they are (un)subscribed. These two variables
1455 should, of course, be inside the relevant legal ranges.
1457 @vindex gnus-keep-same-level
1458 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1459 will only move to groups that are of the same level (or lower). In
1460 particular, going from the last article in one group to the next group
1461 will go to the next group of the same level (or lower). This might be
1462 handy if you want to read the most important groups before you read the
1465 @vindex gnus-group-default-list-level
1466 All groups with a level less than or equal to
1467 @code{gnus-group-default-list-level} will be listed in the group buffer
1470 @vindex gnus-group-use-permament-levels
1471 If @code{gnus-group-use-permament-levels} is non-@code{nil}, once you
1472 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1473 use this level as the "work" level.
1475 @node Marking Groups
1476 @section Marking Groups
1477 @cindex marking groups
1479 If you want to perform some action on several groups, and they appear
1480 subsequently in the group buffer, you would normally just give a
1481 numerical prefix to the command. Most group commands will then do your
1482 bidding on those groups.
1484 However, if the groups are not in sequential order, you can still
1485 perform an action on several groups. You simply mark the groups first,
1486 and then execute the command.
1493 @findex gnus-group-mark-group
1494 Set the mark on the current group (@code{gnus-group-mark-group}).
1499 @findex gnus-group-unmark-group
1500 Remove the mark from the current group
1501 (@code{gnus-group-unmark-group}).
1504 @findex gnus-group-mark-region
1505 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1508 @node Foreign Groups
1509 @section Foreign Groups
1510 @cindex foreign groups
1512 A @dfn{foreign group} is a group that is not read by the usual (or
1513 default) means. It could be, for instance, a group from a different
1514 @sc{nntp} server, it could be a virtual group, or it could be your own
1515 personal mail group.
1517 A foreign group (or any group, really) is specified by a @dfn{name} and
1518 a @dfn{select method}. To take the latter first, a select method is a
1519 list where the first element says what backend to use (eg. @code{nntp},
1520 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
1521 name}. There may be additional elements in the select method, where the
1522 value may have special meaning for the backend in question.
1524 One could say that a select method defines a @dfn{virtual server} - so
1525 we do just that (@pxref{The Server Buffer}).
1527 The @dfn{name} of the group is the name the backend will recognize the
1530 For instance, the group @samp{soc.motss} on the @sc{nntp} server
1531 @samp{some.where.edu} will have the name @samp{soc.motss} and select
1532 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
1533 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
1534 nntp backend just knows this group as @samp{soc.motss}.
1536 Here are some commands for making and editing general foreign groups,
1537 and some commands to ease the creation of some special-purpose groups:
1542 @findex gnus-group-make-group
1543 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
1544 for a name, a method and possibly an @dfn{address}. For an easier way
1545 to subscribe to @sc{nntp} groups, @xref{Browse Foreign Server}.
1549 @findex gnus-group-edit-group-method
1550 Enter a buffer where you can edit the select method of the current
1551 group (@code{gnus-group-edit-group-method}).
1555 @findex gnus-group-edit-group-parameters
1556 Enter a buffer where you can edit the group parameters
1557 (@code{gnus-group-edit-group-parameters}).
1561 @findex gnus-group-edit-group
1562 Enter a buffer where you can edit the group info
1563 (@code{gnus-group-edit-group}).
1567 @findex gnus-group-make-directory-group
1568 Make a directory group. You will be prompted for a directory name
1569 (@code{gnus-group-make-directory-group}).
1573 @findex gnus-group-make-help-group
1574 Make the Gnus help group (@code{gnus-group-make-help-group}).
1578 @findex gnus-group-make-archive-group
1579 @vindex gnus-group-archive-directory
1580 @vindex gnus-group-recent-archive-directory
1581 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
1582 default a group pointing to the most recent articles will be created
1583 (@code{gnus-group-recent-archibe-directory}), but given a prefix, a full
1584 group will be created from from @code{gnus-group-archive-directory}.
1588 @findex gnus-group-make-kiboze-group
1589 Make a kiboze group. You will be prompted for a name, for a regexp to
1590 match groups to be "included" in the kiboze group, and a series of
1591 strings to match on headers (@code{gnus-group-make-kiboze-group}).
1595 @findex gnus-group-enter-directory
1596 Read a random directory as if with were a newsgroup with the
1597 @code{nneething} backend (@code{gnus-group-enter-directory}).
1601 @findex gnus-group-make-doc-group
1602 Make a group based on some file or other
1603 (@code{gnus-group-make-doc-group}). You will be prompted for a file
1604 name and a file type. Currently supported types are @code{babyl},
1605 @code{mbox} and @code{digest}.
1609 @findex gnus-group-make-empty-virtual
1610 Make a new, fresh, empty @code{nnvirtual} group
1611 (@code{gnus-group-make-empty-virtual}).
1615 @findex gnus-group-add-to-virtual
1616 Add the current group to an @code{nnvirtual} group
1617 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
1620 The different methods all have their peculiarities, of course.
1623 * nntp:: Reading news from a different @sc{nntp} server.
1624 * nnspool:: Reading news from the local spool.
1625 * nnvirtual:: Combining articles from many groups.
1626 * nnkiboze:: Looking through parts of the newsfeed for articles.
1627 * nndir:: You can read a directory as if it was a newsgroup.
1628 * nneething:: Dired? Who needs dired?
1629 * nndoc:: Single files can be the basis of a group.
1630 * Reading Mail:: Reading your personal mail with Gnus.
1633 @vindex gnus-activate-foreign-newsgroups
1634 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
1635 Gnus will check all foreign groups with this level or lower at startup.
1636 This might take quite a while, especially if you subscribe to lots of
1637 groups from different @sc{nntp} servers. It is @code{nil} by default,
1638 which means that you won't be told whether there are new articles in
1639 these groups. How many unread articles there are will be determined
1640 when, or if, you decide to enter them. You can also activate any group
1641 with @kbd{M-g} to see how many unread articles there are.
1647 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
1648 You just specify @code{nntp} as method and the address of the @sc{nntp}
1649 server as the, uhm, address.
1651 If the @sc{nntp} server is located at a non-standard port, setting the
1652 third element of the select method to this port number should allow you
1653 to connect to the right port. You'll have to edit the group info for
1654 that (@pxref{Foreign Groups}).
1656 The name of the foreign group can be the same as a native group. In
1657 fact, you can subscribe to the same group from as many different servers
1658 you feel like. There will be no name collisions.
1660 The following variables can be used to create a virtual @code{nntp}
1664 @item nntp-server-opened-hook
1665 @vindex nntp-server-opened-hook
1666 @cindex @sc{mode reader}
1668 @findex nntp-send-authinfo
1669 @findex nntp-send-mode-reader
1670 @code{nntp-server-opened-hook} is run after a connection has been made.
1671 It can be used to send commands to the @sc{nntp} server after it has
1672 been contacted. By default is sends the command @samp{MODE READER} to
1673 the server with the @code{nntp-send-mode-reader} function. Another
1674 popular function is @code{nntp-send-authinfo}, which will prompt you for
1675 an @sc{nntp} password and stuff.
1677 @item nntp-maximum-request
1678 @vindex nntp-maximum-request
1679 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
1680 will collect headers by sending a series of @code{head} commands. To
1681 speed things up, the backend sends lots of these commands without
1682 waiting for reply, and then reads all the replies. This is controlled
1683 by the @code{nntp-maximum-request} variable, and is 400 by default. If
1684 your network is buggy, you should set this to 1.
1686 @item nntp-connection-timeout
1687 @vindex nntp-connection-timeout
1688 If you have lots of foreign @code{nntp} groups that you connect to
1689 regularly, you're sure to have problems with @sc{nntp} servers not
1690 responding properly, or being too loaded to reply within reasonable
1691 time. This is can lead to awkward problems, which can be helped
1692 somewhat by setting @code{nntp-connection-timeout}. This is an integer
1693 that says how many seconds the @code{nntp} backend should wait for a
1694 connection before giving up. If it is @code{nil}, which is the default,
1695 no timeouts are done.
1697 @item nntp-server-hook
1698 @vindex nntp-server-hook
1699 This hook is run as the last step when connecting to an @sc{nntp}
1702 @c @findex nntp-open-rlogin
1703 @c @findex nntp-open-network-stream
1704 @c @item nntp-open-server-function
1705 @c @vindex nntp-open-server-function
1706 @c This function is used to connect to the remote system. Two pre-made
1707 @c functions are @code{nntp-open-network-stream}, which is the default, and
1708 @c simply connects to some port or other on the remote system. The other
1709 @c is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
1710 @c and then does a telnet to the @sc{nntp} server available there.
1712 @c @item nntp-rlogin-parameters
1713 @c @vindex nntp-rlogin-parameters
1714 @c If you use @code{nntp-open-rlogin} as the
1715 @c @code{nntp-open-server-function}, this list will be used as the
1716 @c parameter list given to @code{rsh}.
1718 @c @item nntp-rlogin-user-name
1719 @c @vindex nntp-rlogin-user-name
1720 @c User name on the remote system when using the @code{rlogin} connect
1724 @vindex nntp-address
1725 The address of the remote system running the @sc{nntp} server.
1727 @item nntp-port-number
1728 @vindex nntp-port-number
1729 Port number to connect to when using the @code{nntp-open-network-stream}
1732 @item nntp-buggy-select
1733 @vindex nntp-buggy-select
1734 Set this to non-@code{nil} if your select routine is buggy.
1736 @item nntp-nov-is-evil
1737 @vindex nntp-nov-is-evil
1738 If the @sc{nntp} server does not support @sc{nov}, you could set this
1739 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
1740 can be used automatically.
1742 @item nntp-xover-commands
1743 @vindex nntp-xover-commands
1744 List of strings that are used as commands to fetch @sc{nov} lines from a
1745 server. The default value of this variable is @code{("XOVER"
1749 @vindex nntp-nov-gap
1750 @code{nntp} normally sends just one big request for @sc{nov} lines to
1751 the server. The server responds with one huge list of lines. However,
1752 if you have read articles 2-5000 in the group, and only want to read
1753 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
1754 lines that you do not want, and will not use. This variable says how
1755 big a gap between two consecutive articles is allowed to be before the
1756 @code{XOVER} request is split into several request. Note that if your
1757 network is fast, setting this variable to a really small number means
1758 that fetching will probably be slower. If this variable is @code{nil},
1759 @code{nntp} will never split requests.
1761 @item nntp-prepare-server-hook
1762 @vindex nntp-prepare-server-hook
1763 A hook run before attempting to connect to an @sc{nntp} server.
1765 @item nntp-async-number
1766 @vindex nntp-async-number
1767 How many articles should be pre-fetched when in asynchronous mode. If
1768 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
1769 that it can without bound. If it is @code{nil}, no pre-fetching will be
1772 @item nntp-warn-about-losing-connection
1773 @vindex nntp-warn-about-losing-connection
1774 If this variable is non-@code{nil}, some noise will be made when a
1775 server closes connection.
1785 Subscribing to a foreign group from the local spool is extremely easy,
1786 and might be useful, for instance, to speed up reading groups like
1787 @samp{alt.binaries.pictures.furniture}.
1789 Anyways, you just specify @code{nnspool} as the method and @samp{""} (or
1790 anything else) as the address.
1792 If you have access to a local spool, you should probably use that as the
1793 native select method (@pxref{Finding the News}).
1796 @item nnspool-inews-program
1797 @vindex nnspool-inews-program
1798 Program used to post an article.
1800 @item nnspool-inews-switches
1801 @vindex nnspool-inews-switches
1802 Parameters given to the inews program when posting an article.
1804 @item nnspool-spool-directory
1805 @vindex nnspool-spool-directory
1806 Where nnspool looks for the articles. This is normally
1807 @file{/usr/spool/news/}.
1809 @item nnspool-nov-directory
1810 @vindex nnspool-nov-directory
1811 Where nnspool will look for @sc{nov} files. This is normally
1812 @file{/usr/spool/news/over.view/}.
1814 @item nnspool-lib-dir
1815 @vindex nnspool-lib-dir
1816 Where the news lib dir is (@file{/usr/lib/news/} by default).
1818 @item nnspool-active-file
1819 @vindex nnspool-active-file
1820 The path of the active file.
1822 @item nnspool-newsgroups-file
1823 @vindex nnspool-newsgroups-file
1824 The path of the group description file.
1826 @item nnspool-history-file
1827 @vindex nnspool-history-file
1828 The path of the news history file.
1830 @item nnspool-active-times-file
1831 @vindex nnspool-active-times-file
1832 The path of the active date file.
1834 @item nnspool-nov-is-evil
1835 @vindex nnspool-nov-is-evil
1836 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
1839 @item nnspool-sift-nov-with-sed
1840 @vindex nnspool-sift-nov-with-sed
1841 If non-@code{nil}, which is the default, use @code{sed} to get the
1842 relevant portion from the overview file. If nil, @code{nnspool} will
1843 load the entire file into a buffer and process it there.
1848 @subsection nnvirtual
1850 @cindex virtual groups
1852 An @dfn{nnvirtual group} is really nothing more than a collection of
1855 For instance, if you are tired of reading many small group, you can
1856 put them all in one big group, and then grow tired of reading one
1857 big, unwieldy group. The joys of computing!
1859 You specify @code{nnvirtual} as the method. The address should be a
1860 regexp to match component groups.
1862 All marks in the virtual group will stick to the articles in the
1863 component groups. So if you tick an article in a virtual group, the
1864 article will also be ticked in the component group from whence it came.
1865 (And vice versa - marks from the component groups will also be shown in
1868 Here's an example nnvirtual method that collects all Andrea Dworkin
1869 newsgroups into one, big, happy newsgroup:
1872 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
1875 The component groups can be native or foreign; everything should work
1876 smoothly, but if your computer explodes, it was probably my fault.
1878 Collecting the same group from several servers might actually be a good
1879 idea if users have set the Distribution header to limit distribution.
1880 If you would like to read @samp{soc.motss} both from a server in Japan
1881 and a server in Norway, you could use the following as the group regexp:
1884 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
1887 This should work kinda smoothly - all articles from both groups should
1888 end up in this one, and there should be no duplicates. Threading (and
1889 the rest) will still work as usual, but there might be problems with the
1890 sequence of articles. Sorting on date might be an option here
1891 (@pxref{Selecting a Group}.
1893 One limitation, however - all groups that are included in a virtual
1894 group has to be alive (i.e., subscribed or unsubscribed). Killed or
1895 zombie groups can't be component groups for nnvirtual groups.
1898 @subsection nnkiboze
1902 @dfn{Kibozing} is defined by OED as "grepping through (parts of) the
1903 news feed". nnkiboze is a backend that will do this for you. Oh joy!
1904 Now you can grind any @sc{nntp} server down to a halt with useless
1905 requests! Oh happiness!
1907 The address field of the nnkiboze method is, as with nnvirtual, a regexp
1908 to match groups to be "included" in the nnkiboze group. There most
1909 similarities between nnkiboze and nnvirtual ends.
1911 In addition to this regexp detailing component groups, an nnkiboze group
1912 must have a score file to say what articles that are to be included in
1913 the group (@pxref{Score Files}).
1915 @kindex M-x nnkiboze-generate-groups
1916 @findex nnkiboze-generate-groups
1917 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
1918 nnkiboze groups you want to have. This command will take time. Lots of
1919 time. Oodles and oodles of time. Gnus has to fetch the headers from
1920 all the articles in all the components groups and run them through the
1921 scoring process to determine if there are any articles in the groups
1922 that are to be part of the nnkiboze groups.
1924 Please limit the number of component groups by using restrictive
1925 regexps. Otherwise your sysadmin may become annoyed with you, and the
1926 @sc{nntp} site may throw you off and never let you back in again.
1927 Stranger things have happened.
1929 nnkiboze component groups do not have to be alive - they can be dead,
1930 and they can be foreign. No restrictions.
1932 @vindex nnkiboze-directory
1933 The generation of an nnkiboze group means writing two files in
1934 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
1935 contains the @sc{nov} header lines for all the articles in the group,
1936 and the other is an additional @file{.newsrc} file to store information
1937 on what groups that have been searched through to find component
1940 Articles that are marked as read in the nnkiboze group will have their
1941 @sc{nov} lines removed from the @sc{nov} file.
1946 @cindex directory groups
1948 If you have a directory that has lots of articles in separate files in
1949 it, you might treat it as a newsgroup. The files have to have numerical
1952 This might be an opportune moment to mention @code{ange-ftp}, that most
1953 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
1954 didn't think much about it - a backend to read directories. Big deal.
1956 @code{ange-ftp} changes that picture dramatically. For instance, if you
1957 enter @file{"/ftp@@sina.tcamc.uh.edu:/pub/emacs/ding-list/"} as the the
1958 directory name, ange-ftp will actually allow you to read this directory
1959 over at @samp{sina} as a newsgroup. Distributed news ahoy!
1961 @code{nndir} will use @sc{nov} files if they are present.
1963 @code{nndir} is a "read-only" backend - you can't delete or expire
1964 articles with this method. You can use @code{nnmh} or @code{nnml} for
1965 whatever you use @code{nndir} for, so you could switch to any of those
1966 methods if you feel the need to have a non-read-only @code{nndir}.
1969 @subsection nneething
1972 From the @code{nndir} backend (which reads a single spool-like
1973 directory), it's just a hop and a skip to @code{nneething}, which
1974 pretends that any random directory is a newsgroup. Strange, but true.
1976 When @code{nneething} is presented with a directory, it will scan this
1977 directory and assign article numbers to each file. When you enter such a
1978 group, @code{nneething} must create "headers" that Gnus can use. After
1979 all, Gnus is a newsreader, in case you're forgetting. @code{nneething}
1980 does this in a two-step process. First, it snoops each file in question.
1981 If the file looks like an article (i.e., the first few lines look like
1982 headers), it will use this as the head. If this is just some random file
1983 without a head (eg. a C source file), @code{nneething} will cobble up a
1984 header out of thin air. It will use file ownership, name and date and do
1985 whatever it can with these elements.
1987 All this should happen automatically for you, and you will be presented
1988 with something that looks very much like a newsgroup. Totally like a
1989 newsgroup, to be precise. If you select an article, it will be displayed
1990 in the article buffer, just as usual.
1992 If you select a line that represents a directory, Gnus will pop you into
1993 a new summary buffer for this @code{nneething} group. And so on. You can
1994 traverse the entire disk this way, if you feel like, but remember that
1995 Gnus is not dired, really, and does not intend to be, either.
1997 There are two overall modes to this action - ephemeral or solid. When
1998 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
1999 will not store information on what files you have read, and what files
2000 are new, and so on. If you create a solid @code{nneething} group the
2001 normal way with @kbd{G m}, Gnus will store a mapping table between
2002 article numbers and file names, and you can treat this group like any
2003 other groups. When you activate a solid @code{nneething} group, you will
2004 be told how many unread articles it contains, etc., etc.
2009 @item nneething-map-file-directory
2010 @vindex nneething-map-file-directory
2011 All the mapping files for solid @code{nneething} groups will be stored
2012 in this directory, which defaults to @file{~/.nneething/}.
2014 @item nneething-exclude-files
2015 @vindex nneething-exclude-files
2016 All files that match this regexp will be ignored. Nice to use to exclude
2017 auto-save files and the like, which is what it does by default.
2019 @item nneething-map-file
2020 @vindex nneething-map-file
2021 Name of the map files.
2028 @cindex documentation group
2031 nndoc is a cute little thing that will let you read a single file as a
2032 newsgroup. Currently supported file types are @code{babyl}, @code{mbox}
2035 nndoc will not try to change the file or insert any extra headers into
2036 it - it will simply, like, let you use the file as the basis for a
2037 group. And that's it.
2039 Virtual server variables:
2042 @item nndoc-article-type
2043 @vindex nndoc-article-type
2044 This should be one of @code{mbox}, @code{babyl} or @code{digest}.
2048 @subsection Reading Mail
2049 @cindex reading mail
2052 Reading mail with a newsreader - isn't that just plain WeIrD? But of
2055 Gnus will read the mail spool when you activate a mail group. The mail
2056 file is first copied to your home directory. What happens after that
2057 depends on what format you want to store your mail in.
2060 * Creating Mail Groups:: How to create mail groups.
2061 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
2062 * Mail & Procmail:: Reading mail groups that procmail create.
2063 * Expiring Old Mail Articles:: Getting rid of unwanted mail.
2064 * Not Reading Mail:: Using mail backends for reading other files.
2065 * nnmbox:: Using the (quite) standard Un*x mbox.
2066 * nnbabyl:: Emacs programs use the rmail babyl format.
2067 * nnml:: Store your mail in a private spool?
2068 * nnmh:: An mhspool-like backend.
2069 * nnfolder:: Having one file for each group.
2072 @vindex nnmail-read-incoming-hook
2073 The mail backends all call @code{nnmail-read-incoming-hook} after
2074 reading new mail. You can use this hook to notify any mail watch
2075 programs, if you want to.
2077 @vindex nnmail-spool-file
2078 @code{nnmail-spool-file} says where to look for new mail. If this
2079 variable is @code{nil}, the mail backends will never attempt to fetch
2080 mail by themselves. It is quite likely that Gnus supports POP-mail.
2081 Set this variable to begin with the string @samp{po:}, and everything
2082 should go smoothly, even though I have never tested this.
2084 @vindex nnmail-use-procmail
2085 If @code{nnmail-use-procmail} is non-@code{nil}, the mail backends will
2086 look in @code{nnmail-procmail-directory} for incoming mail. All the
2087 files in that directory that have names ending in
2088 @code{gnus-procmail-suffix} will be considered incoming mailboxes, and
2089 will be searched for new mail.
2091 @vindex nnmail-prepare-incoming-hook
2092 @code{nnmail-prepare-incoming-hook} is run in a buffer that holds all
2093 the new incoming mail, and can be used for, well, anything, really.
2095 @vindex nnmail-tmp-directory
2096 @code{nnmail-tmp-directory} says where to move the incoming mail to
2097 while processing it. This is usually done in the same directory that
2098 the mail backend inhabits (i.e., @file{~/Mail/}), but if this variable is
2099 non-@code{nil}, it will be used instead.
2101 @vindex nnmail-movemail-program
2102 @code{nnmail-movemail-program} is executed to move mail from the user's
2103 inbox to her home directory. The default is @samp{"movemail"}.
2105 @vindex nnmail-delete-incoming
2106 If @code{nnmail-delete-incoming} is non-@code{nil}, the mail backends
2107 will delete the temporary incoming file after splitting mail into the
2108 proper groups. This is @code{nil} by default for reasons of security.
2110 @vindex nnmail-message-id-cache-length
2111 @vindex nnmail-message-id-cache-file
2112 @vindex nnmail-delete-duplicates
2113 @cindex duplicate mails
2114 If you are a member of a couple of mailing list, you will sometime
2115 receive two copies of the same mail. This can be quite annoying, so
2116 @code{nnmail} checks for and discards any duplicates it might find. To
2117 do this, it keeps a cache of old @code{Message-ID}s -
2118 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
2119 default. The approximate maximum number of @code{Message-ID}s stored
2120 there is controlled by the @code{nnmail-message-id-cache-length}
2121 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
2122 stored.) If all this sounds scary to you, you can set
2123 @code{nnmail-delete-duplicates} to @code{nil} (which is what it is by
2124 default), and @code{nnmail} won't do any duplicate checking.
2126 Here's a neat feature: If you know that the recipient reads her mail
2127 with Gnus, and that she has @code{nnmail-delete-duplicates} set to
2128 @code{t}, you can send her as many insults as you like, just by using a
2129 @code{Message-ID} of a mail that you know that she's already received.
2130 Think of all the fun! She'll never see any of it! Whee!
2132 Gnus gives you all the opportunity you could possibly want for shooting
2133 yourself in the foot. Let's say you create a group that will contain
2134 all the mail you get from your boss. And then you accidentally
2135 unsubscribe from the group. Gnus will still put all the mail from your
2136 boss in the unsubscribed group, and so, when your boss mails you "Have
2137 that report ready by Monday or you're fired!", you'll never see it and,
2138 come Tuesday, you'll still believe that you're gainfully employed while
2139 you really should be out collecting empty bottles to save up for next
2142 @node Creating Mail Groups
2143 @subsubsection Creating Mail Groups
2144 @cindex creating mail groups
2146 You can make Gnus read your personal, private, secret mail.
2148 You should first set @code{gnus-secondary-select-methods} to, for
2149 instance, @code{((nnmbox ""))}. When you start up Gnus, Gnus will ask
2150 this backend for what groups it carries (@samp{mail.misc} by default)
2151 and subscribe it the normal way. (Which means you may have to look for
2152 it among the zombie groups, I guess, all depending on your
2153 @code{gnus-subscribe-newsgroup-method} variable.)
2155 @vindex nnmail-split-methods
2156 Then you should set the variable @code{nnmail-split-methods} to specify
2157 how the incoming mail is to be split into groups.
2160 (setq nnmail-split-methods
2161 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
2162 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
2166 This variable is a list of lists, where the first element of each of
2167 these lists is the name of the mail group (they do not have to be called
2168 something beginning with @samp{mail}, by the way), and the second
2169 element is a regular expression used on the header of each mail to
2170 determine if it belongs in this mail group.
2172 The second element can also be a function. In that case, it will be
2173 called narrowed to the headers with the first element of the rule as the
2174 argument. It should return a non-@code{nil} value if it thinks that the
2175 mail belongs in that group.
2177 The last of these groups should always be a general one, and the regular
2178 expression should @emph{always} be @samp{""} so that it matches any
2179 mails that haven't been matched by any of the other regexps.
2181 If you like to tinker with this yourself, you can set this variable to a
2182 function of your choice. This function will be called without any
2183 arguments in a buffer narrowed to the headers of an incoming mail
2184 message. The function should return a list of groups names that it
2185 thinks should carry this mail message.
2187 @vindex nnmail-crosspost
2188 The mail backends all support cross-posting. If several regexps match,
2189 the mail will be "cross-posted" to all those groups.
2190 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
2191 that no articles are crossposted to the general (@samp{""}) group.
2193 @node Fancy Mail Splitting
2194 @subsubsection Fancy Mail Splitting
2195 @cindex mail splitting
2196 @cindex fancy mail splitting
2198 @vindex nnmail-split-fancy
2199 @findex nnmail-split-fancy
2200 If the rather simple, standard method for specifying how to split mail
2201 doesn't allow you to do what you want, you can set
2202 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
2203 play with the @code{nnmail-split-fancy} variable.
2205 Let's look at an example value of this variable first:
2208 ;; Messages from the mailer daemon are not crossposted to any of
2209 ;; the ordinary groups. Warnings are put in a separate group
2210 ;; from real errors.
2211 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
2213 ;; Non-error messages are crossposted to all relevant
2214 ;; groups, but we don't crosspost between the group for the
2215 ;; (ding) list and the group for other (ding) related mail.
2216 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
2217 ("subject" "ding" "ding.misc"))
2218 ;; Other mailing lists...
2219 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
2220 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
2222 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
2223 ;; Unmatched mail goes to the catch all group.
2227 This variable has the format of a @dfn{split}. A split is a (possibly)
2228 recursive structure where each split may contain other splits. Here are
2229 the four possible split syntaxes:
2233 If the split is a string, that will be taken as a group name.
2234 @item (FIELD VALUE SPLIT)
2235 If the split is a list, and the first element is a string, then that
2236 means that if header FIELD (a regexp) contains VALUE (also a regexp),
2237 then store the message as specified by SPLIT.
2239 If the split is a list, and the first element is @code{|} (vertical
2240 bar), then process each SPLIT until one of them matches. A SPLIT is
2241 said to match if it will cause the mail message to be stored in one or
2244 If the split is a list, and the first element is @code{&}, then process
2245 all SPLITs in the list.
2248 In these splits, FIELD must match a complete field name. VALUE must
2249 match a complete word according to the fundamental mode syntax table.
2250 You can use @code{.*} in the regexps to match partial field names or
2253 @vindex nnmail-split-abbrev-alist
2254 FIELD and VALUE can also be lisp symbols, in that case they are expanded
2255 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
2256 an alist of cons cells, where the car of the cells contains the key, and
2257 the cdr contains a string.
2259 @node Mail & Procmail
2260 @subsubsection Mail & Procmail
2263 Many people use @code{procmail} to split incoming mail into groups. If
2264 you do that, you should set @code{nnmail-spool-file} to @code{procmail}
2265 to ensure that the mail backends never ever try to fetch mail by
2268 This also means that you probably don't want to set
2269 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
2272 When a mail backend is queried for what groups it carries, it replies
2273 with the contents of that variable, along with any groups it has figured
2274 out that it carries by other means. None of the backends (except
2275 @code{nnmh}) actually go out to the disk and check what groups actually
2276 exist. (It's not trivial to distinguish between what the user thinks is
2277 a basis for a newsgroup and what is just a plain old file or directory.)
2279 This means that you have to tell Gnus (and the backends) what groups
2282 Let's take the @code{nnmh} backend as an example.
2284 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
2285 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
2287 Go to the group buffer and type @kbd{G m}. When prompted, answer
2288 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
2289 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
2290 to include all your mail groups.
2292 That's it. You are now set to read your mail. An active file for this
2293 method will be created automatically.
2295 @vindex nnmail-procmail-suffix
2296 @vindex nnmail-procmail-directory
2297 If you use @code{nnfolder} or any other backend that store more than a
2298 single article in each file, you should never have procmail add mails to
2299 the file that Gnus sees. Instead, procmail should put all incoming mail
2300 in @code{nnmail-procmail-directory}. To arrive at the file name to put
2301 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
2302 name. The mail backends will read the mail from these files.
2304 @vindex nnmail-resplit-incoming
2305 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
2306 put in the @code{mail.misc}, as one would expect. However, if you want
2307 Gnus to split the mail the normal way, you could set
2308 @code{nnmail-resplit-incoming} to @code{t}.
2310 @vindex nnmail-keep-last-article
2311 If you use @code{procmail} to split things directory into an nnmh
2312 directory (which you shouldn't do), you should set
2313 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
2314 ever expiring the final article in a mail newsgroup. This is quite,
2318 @node Expiring Old Mail Articles
2319 @subsubsection Expiring Old Mail Articles
2320 @cindex article expiry
2322 Traditional mail readers have a tendency to remove mail articles when
2323 you mark them as read, in some way. Gnus takes a fundamentally
2324 different approach to mail reading.
2326 Gnus basically considers mail just to be news that has been received in
2327 a rather peculiar manner. It does not think that it has the power to
2328 actually change the mail, or delete any mail messages. If you enter a
2329 mail group, and mark articles as "read", or kill them in some other
2330 fashion, the mail articles will still exist on the system. I repeat:
2331 Gnus will not delete your old, read mail. Unless you ask it to, of
2334 To make Gnus get rid of your unwanted mail, you have to mark the
2335 articles as @dfn{expirable}. This does not mean that the articles will
2336 disappear right away, however. In general, a mail article will be
2337 deleted from your system if, 1) it is marked as expirable, AND 2) it is
2338 more than one week old. If you do not mark an article as expirable, it
2339 will remain on your system until hell freezes over. This bears
2340 repeating one more time, with some spurious capitalizations: IF you do
2341 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
2343 @vindex gnus-auto-expirable-newsgroups
2344 You do not have to mark articles as expirable by hand. Groups that
2345 match the regular expression @code{gnus-auto-expirable-newsgroups} will
2346 have all articles that you read marked as expirable automatically. All
2347 articles that are marked as expirable have an @samp{E} in the first
2348 column in the summary buffer.
2350 Let's say you subscribe to a couple of mailing lists, and you want the
2351 articles you have read to disappear after a while:
2354 (setq gnus-auto-expirable-newsgroups
2355 "mail.nonsense-list\\|mail.nice-list")
2358 Another way to have auto-expiry happen is to have the element
2359 @code{auto-expire} in the select method of the group.
2361 @vindex nnmail-expiry-wait
2362 The @code{nnmail-expiry-wait} variable supplies the default time an
2363 expirable article has to live. The default is seven days.
2365 Gnus also supplies a function that lets you fine-tune how long articles
2366 are to live, based on what group they are in. Let's say you want to
2367 have one month expiry period in the @samp{mail.private} group, a one day
2368 expiry period in the @samp{mail.junk} group, and a six day expiry period
2372 (setq nnmail-expiry-wait-function
2374 (cond ((string= group "mail.private")
2376 ((string= group "mail.junk")
2382 @vindex nnmail-keep-last-article
2383 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
2384 expire the final article in a mail newsgroup. This is to make life
2385 easier for procmail users.
2387 @vindex gnus-total-expirable-newsgroups
2388 By the way, that line up there about Gnus never expiring non-expirable
2389 articles is a lie. If you put @code{total-expire} in the group
2390 parameters, articles will not be marked as expirable, but all read
2391 articles will be put through the expiry process. Use with extreme
2392 caution. Even more dangerous is the
2393 @code{gnus-total-expirable-newsgroups} variable. All groups that match
2394 this regexp will have all read articles put through the expiry process,
2395 which means that @emph{all} old mail articles in the groups in question
2396 will be deleted after a while. Use with extreme caution, and don't come
2397 crying to me when you discover that the regexp you used matched the
2398 wrong group and all your important mail has disappeared. Be a
2399 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
2403 @node Not Reading Mail
2404 @subsubsection Not Reading Mail
2406 If you start using any of the mail backends, they have the annoying
2407 habit of assuming that you want to read mail with them. This might not
2408 be unreasonable, but it might not be what you want.
2410 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
2411 will ever attempt to read incoming mail, which should help.
2413 @vindex nnbabyl-get-new-mail
2414 @vindex nnmbox-get-new-mail
2415 @vindex nnml-get-new-mail
2416 @vindex nnmh-get-new-mail
2417 @vindex nnfolder-get-new-mail
2418 This might be too much, if, for instance, you are reading mail quite
2419 happily with @code{nnml} and just want to peek at some old @sc{rmail}
2420 file you have stashed away with @code{nnbabyl}. All backends have
2421 variables called backend-@code{get-new-mail}. If you want to disable
2422 the @code{nnbabyl} mail reading, you edit the virtual server for the
2423 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
2425 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
2426 narrowed to the article to be saved before saving it when reading
2430 @subsubsection nnmbox
2432 @cindex unix mail box
2434 @vindex nnmbox-active-file
2435 @vindex nnmbox-mbox-file
2436 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
2437 mail. @code{nnmbox} will add extra headers to each mail article to say
2438 which group it belongs in.
2440 Virtual server settings:
2443 @item nnmbox-mbox-file
2444 @vindex nnmbox-mbox-file
2445 The name of the mail box in the user's home directory.
2447 @item nnmbox-active-file
2448 @vindex nnmbox-active-file
2449 The name of the active file for the mail box.
2451 @item nnmbox-get-new-mail
2452 @vindex nnmbox-get-new-mail
2453 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
2458 @subsubsection nnbabyl
2462 @vindex nnbabyl-active-file
2463 @vindex nnbabyl-mbox-file
2464 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
2465 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
2466 article to say which group it belongs in.
2468 Virtual server settings:
2471 @item nnbabyl-mbox-file
2472 @vindex nnbabyl-mbox-file
2473 The name of the rmail mbox file.
2475 @item nnbabyl-active-file
2476 @vindex nnbabyl-active-file
2477 The name of the active file for the rmail box.
2479 @item nnbabyl-get-new-mail
2480 @vindex nnbabyl-get-new-mail
2481 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
2487 @cindex mail @sc{nov} spool
2489 The @dfn{nnml} spool mail format isn't compatible with any other known
2490 format. It should be used with some caution.
2492 @vindex nnml-directory
2493 If you use this backend, Gnus will split all incoming mail into files;
2494 one file for each mail, and put the articles into the correct
2495 directories under the directory specified by the @code{nnml-directory}
2496 variable. The default value is @file{~/Mail/}.
2498 You do not have to create any directories beforehand; Gnus will take
2501 If you have a strict limit as to how many files you are allowed to store
2502 in your account, you should not use this backend. As each mail gets its
2503 own file, you might very well occupy thousands of inodes within a few
2504 weeks. If this is no problem for you, and it isn't a problem for you
2505 having your friendly systems administrator walking around, madly,
2506 shouting "Who is eating all my inodes?! Who? Who!?!", then you should
2507 know that this is probably the fastest format to use. You do not have
2508 to trudge through a big mbox file just to read your new mail.
2510 @code{nnml} is probably the slowest backend when it comes to article
2511 splitting. It has to create lots of files, and it also generates
2512 @sc{nov} databases for the incoming mails. This makes is the fastest
2513 backend when it comes to reading mail.
2515 Virtual server settings:
2518 @item nnml-directory
2519 @vindex nnml-directory
2520 All @code{nnml} directories will be placed under this directory.
2522 @item nnml-active-file
2523 @vindex nnml-active-file
2524 The active file for the @code{nnml} server.
2526 @item nnml-newsgroups-file
2527 @vindex nnml-newsgroups-file
2528 The @code{nnml} group description file.
2530 @item nnml-get-new-mail
2531 @vindex nnml-get-new-mail
2532 If non-@code{nil}, @code{nnml} will read incoming mail.
2534 @item nnml-nov-is-evil
2535 @vindex nnml-nov-is-evil
2536 If non-@code{nil}, this backend will ignore any @sc{nov} files.
2538 @item nnml-nov-file-name
2539 @vindex nnml-nov-file-name
2540 The name of the @sc{nov} files. The default is @file{.overview}.
2544 @findex nnml-generate-nov-databases
2545 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
2546 you can do a complete update by typing @kbd{M-x
2547 nnml-generate-nov-databases}. This command will trawl through the
2548 entire @code{nnml} hierarchy, looking at each and every article, so it
2549 might take a while to complete.
2554 @cindex mh-e mail spool
2556 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
2557 @sc{nov} databases and it doesn't keep an active file. This makes
2558 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
2559 makes it easier to write procmail scripts for.
2561 Virtual server settings:
2564 @item nnmh-directory
2565 @vindex nnmh-directory
2566 All @code{nnmh} directories will be located under this directory.
2568 @item nnmh-get-new-mail
2569 @vindex nnmh-get-new-mail
2570 If non-@code{nil}, @code{nnmh} will read incoming mail.
2573 @vindex nnmh-be-safe
2574 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
2575 sure that the articles in the folder is actually what Gnus think they
2576 are. It will check date stamps, and stat everything in sight, so
2577 setting this to @code{t} will mean a serious slow-down. If you never
2578 use anything by Gnus to read the nnmh articles, you do not have to set
2579 this variable to @code{t}.
2583 @subsubsection nnfolder
2585 @cindex mbox folders
2587 @code{nnfolder} is a backend for storing each mail group in a separate
2588 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
2589 will add extra headers to keep track of article numbers and arrival
2592 Virtual server settings:
2595 @item nnfolder-directory
2596 @vindex nnfolder-directory
2597 All the @code{nnfolder} mail boxes will be stored under this directory.
2599 @item nnfolder-active-file
2600 @vindex nnfolder-active-file
2601 The name of the active file.
2603 @item nnfolder-newsgroups-file
2604 @vindex nnfolder-newsgroups-file
2605 The name of the group description file.
2607 @item nnfolder-get-new-mail
2608 @vindex nnfolder-get-new-mail
2609 If non-@code{nil}, @code{nnfolder} will read incoming mail.
2612 @node Group Parameters
2613 @section Group Parameters
2614 @cindex group parameters
2616 Gnus stores all information on a group in a list that is usually known
2617 as the @dfn{group info}. This list has from three to six elements.
2618 Here's an example info.
2621 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
2622 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
2625 The first element is the @dfn{group name}, as Gnus knows the group,
2626 anyway. The second element is the @dfn{subscription level}, which
2627 normally is a small integer. The third element is a list of ranges of
2628 read articles. The fourth element is a list of lists of article marks
2629 of various kinds. The fifth element is the select method (or virtual
2630 server, if you like). The sixth element is a list of @dfn{group
2631 parameters}, which is what this section is about.
2633 Any of the last three elements may be missing if they are not required.
2634 In fact, the vast majority of groups will normally only have the first
2635 three elements, which saves quite a lot of cons cells.
2637 The group parameters stores information local to a particular group:
2642 If the group parameter list contains an element that looks like
2643 @samp{(to-address . "some@@where.com")}, that address will be used by
2644 the backend when doing followups and posts. This is primarily useful in
2645 mail groups that represent mailing lists. You just set this address to
2646 whatever the list address is.
2648 This trick will actually work whether the group is foreign or not.
2649 Let's say there's a group on the server that is called @samp{fa.4ad-l}.
2650 This is a real newsgroup, but the server has gotten the articles from a
2651 mail-to-news gateway. Posting directly to this group is therefore
2652 impossible - you have to send mail to the mailing list address instead.
2656 IF the group parameter list contains an element like @code{(to-group
2657 . "some.group.name")}, all posts will be sent to that groups.
2661 If this symbol is present in the group parameter list, all articles that
2662 are read will be marked as expirable. For an alternative approach,
2663 @xref{Expiring Old Mail Articles}.
2666 @cindex total-expire
2667 If this symbol is present, all read articles will be put through the
2668 expiry process, even if they are not marked as expirable. Use with
2671 @item @var{(variable form)}
2672 You can use the group parameters to set variables local to the group you
2673 are entering. Say you want to turn threading off in
2674 @samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
2675 the group parameters of that group. @code{gnus-show-threads} will be
2676 made into a local variable in the summary buffer you enter, and the form
2677 @code{nil} will be @code{eval}ed there.
2679 This can also be used as a group-specific hook function, if you'd like.
2680 If you want to hear a beep when you enter the group
2681 @samp{alt.binaries.pictures.furniture}, you could put something like
2682 @code{(dummy-variable (ding))} in the parameters of that group.
2683 @code{dummy-variable} will be set to the result of the @code{(ding)}
2684 form, but who cares?
2688 If you want to change the group info you can use the @kbd{G E} command
2689 to enter a buffer where you can edit it.
2691 You usually don't want to edit the entire group info, so you'd be better
2692 off using the @kbd{G p} command to just edit the group parameters.
2694 @node Listing Groups
2695 @section Listing Groups
2696 @cindex group listing
2698 These commands all list various slices of the groups that are available.
2705 @findex gnus-group-list-groups
2706 List all groups that have unread articles
2707 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
2708 command will list only groups of level ARG and lower. By default, it
2709 only lists groups of level five or lower (i.e., just subscribed groups).
2714 @findex gnus-group-list-all-groups
2715 List all groups, whether they have unread articles or not
2716 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
2717 this command will list only groups of level ARG and lower. By default,
2718 it lists groups of level seven or lower (i.e., just subscribed and
2719 unsubscribed groups).
2722 @findex gnus-group-list-killed
2723 List all killed groups (@code{gnus-group-list-killed}).
2726 @findex gnus-group-list-zombies
2727 List all zombie groups (@code{gnus-group-list-zombies}).
2730 @findex gnus-group-list-matching
2731 List all subscribed groups with unread articles that match a regexp
2732 (@code{gnus-group-list-matching}).
2735 @findex gnus-group-list-all-matching
2736 List groups that match a regexp (@code{gnus-group-list-all-matching}).
2739 @node Group Maintenance
2740 @section Group Maintenance
2741 @cindex bogus groups
2746 @findex gnus-group-check-bogus-groups
2747 Find bogus groups and delete them
2748 (@code{gnus-group-check-bogus-groups}).
2751 @findex gnus-find-new-newsgroups
2752 Find new groups and process them (@code{gnus-find-new-newsgroups}).
2754 @kindex C-c C-x (Group)
2755 @findex gnus-group-expire-articles
2756 Run all expirable articles in the current group through the expiry
2757 process (if any) (@code{gnus-group-expire-articles}).
2759 @kindex C-c M-C-x (Group)
2760 @findex gnus-group-expire-all-groups
2761 Run all articles in all groups through the expiry process
2762 (@code{gnus-group-expire-all-groups}).
2764 @kindex C-c C-s (Group)
2765 @findex gnus-group-sort-groups
2766 @findex gnus-group-sort-by-level
2767 @findex gnus-group-sort-by-unread
2768 @findex gnus-group-sort-by-alphabet
2769 @vindex gnus-group-sort-function
2770 Sort the groups according to the function given by the
2771 @code{gnus-group-sort-function} variable
2772 (@code{gnus-group-sort-groups}). Available sorting functions include
2773 @code{gnus-group-sort-by-alphabet} (the default),
2774 @code{gnus-group-sort-by-unread} and @code{gnus-group-sort-by-level}.
2777 @node Browse Foreign Server
2778 @section Browse Foreign Server
2779 @cindex foreign servers
2780 @cindex browsing servers
2785 @findex gnus-group-browse-foreign-server
2786 You will be queried for a select method and a server name. Gnus will
2787 then attempt to contact this server and let you browse the groups there
2788 (@code{gnus-group-browse-foreign-server}).
2791 @findex gnus-browse-server-mode
2792 A new buffer with a list of available groups will appear. This buffer
2793 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
2794 (well, a lot) like a normal group buffer, but with one major difference
2795 - you can't enter any of the groups. If you want to read any of the
2796 news available on that server, you have to subscribe to the groups you
2797 think may be interesting, and then you have to exit this buffer. The
2798 new groups will be added to the group buffer, and then you can read them
2799 as you would any other group.
2801 Future versions of Gnus may possibly permit reading groups straight from
2804 Here's a list of keystrokes available in the browse mode:
2809 @findex gnus-group-next-group
2810 Go to the next group (@code{gnus-group-next-group}).
2814 @findex gnus-group-prev-group
2815 Go to the previous group (@code{gnus-group-prev-group}).
2818 @kindex SPC (Browse)
2819 @findex gnus-browse-read-group
2820 Enter the current group and display the first article
2821 (@code{gnus-browse-read-group}).
2824 @kindex RET (Browse)
2825 @findex gnus-browse-select-group
2826 Enter the current group (@code{gnus-browse-select-group}).
2830 @findex gnus-browse-unsubscribe-current-group
2831 Unsubscribe to the current group, or, as will be the case here,
2832 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
2838 @findex gnus-browse-exit
2839 Exit browse mode (@code{gnus-browse-exit}).
2843 @findex gnus-browse-describe-briefly
2844 Describe browse mode briefly (well, there's not much to describe, is
2845 there) (@code{gnus-browse-describe-briefly}).
2849 @section Exiting Gnus
2850 @cindex exiting Gnus
2852 Yes, Gnus is ex(c)iting.
2857 @findex gnus-group-suspend
2858 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
2859 but it kills all buffers except the Group buffer. I'm not sure why this
2860 is a gain, but then who am I to judge?
2863 @findex gnus-group-exit
2864 Quit Gnus (@code{gnus-group-exit}).
2867 @findex gnus-group-quit
2868 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
2871 @vindex gnus-exit-gnus-hook
2872 @vindex gnus-suspend-gnus-hook
2873 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
2874 @code{gnus-exit-gnus-hook} is called when you quit Gnus.
2878 If you wish to completely unload Gnus and all its adherents, you can use
2879 the @code{gnus-unload} command. This command is also very handy when
2880 trying to custoize meta-variables.
2885 Miss Lisa Cannifax, while sitting in English class, feels her feet go
2886 numbly heavy and herself fall into a hazy trance as the boy sitting
2887 behind her drew repeated lines with his pencil across the back of her
2891 @node Misc Group Stuff
2892 @section Misc Group Stuff
2897 @findex gnus-group-get-new-news
2898 Check server for new articles. If the numeric prefix is used, this
2899 command will check only groups of level ARG and lower
2900 (@code{gnus-group-get-new-news}).
2903 @findex gnus-group-get-new-news-this-group
2904 Check whether new articles have arrived in the current group
2905 (@code{gnus-group-get-new-news-this-group}).
2909 @findex gnus-group-enter-server-mode
2910 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
2915 @findex gnus-group-fetch-faq
2916 Try to fetch the FAQ for the current group
2917 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
2918 @code{gnus-group-faq-directory}, which is usually a directory on a
2919 remote machine. ange-ftp will be used for fetching the file.
2922 @findex gnus-group-restart
2923 Restart Gnus (@code{gnus-group-restart}).
2926 @findex gnus-group-read-init-file
2927 @vindex gnus-init-file
2928 Read the init file (@code{gnus-init-file}, which defaults to
2929 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
2932 @findex gnus-group-save-newsrc
2933 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
2934 (@code{gnus-group-save-newsrc}).
2937 @findex gnus-group-clear-dribble
2938 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
2941 @findex gnus-group-describe-group
2942 Describe the current group (@code{gnus-group-describe-group}). If given
2943 a prefix, force Gnus to re-read the description from the server.
2946 @findex gnus-group-apropos
2947 List all groups that have names that match a regexp
2948 (@code{gnus-group-apropos}).
2951 @findex gnus-group-description-apropos
2952 List all groups that have names or descriptions that match a regexp
2953 (@code{gnus-group-description-apropos}).
2956 @findex gnus-group-post-news
2957 Post an article to a group (@code{gnus-group-post-news}).
2960 @findex gnus-group-mail
2961 Mail a message somewhere (@code{gnus-group-mail}).
2963 @kindex C-x C-t (Group)
2964 @findex gnus-group-transpose-groups
2965 Transpose two groups (@code{gnus-group-transpose-groups}).
2968 @findex gnus-version
2969 Display current Gnus version numbers (@code{gnus-version}).
2972 @findex gnus-group-describe-all-groups
2973 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
2974 prefix, force Gnus to re-read the description file from the server.
2977 @findex gnus-group-describe-briefly
2978 Give a very short help message (@code{gnus-group-describe-briefly}).
2980 @kindex C-c C-i (Group)
2981 @findex gnus-info-find-node
2982 Go to the Gnus info node (@code{gnus-info-find-node}).
2985 @vindex gnus-group-prepare-hook
2986 @code{gnus-group-prepare-hook} is called after the group buffer is
2987 generated. It may be used to modify the buffer in some strange,
2990 @node The Summary Buffer
2991 @chapter The Summary Buffer
2992 @cindex summary buffer
2994 A line for each article is displayed in the summary buffer. You can
2995 move around, read articles, post articles and reply to articles.
2998 * Summary Buffer Format:: Deciding how the summary buffer is to look.
2999 * Summary Maneuvering:: Moving around the summary buffer.
3000 * Choosing Articles:: Reading articles.
3001 * Paging the Article:: Scrolling the current article.
3002 * Reply Followup and Post:: Posting articles.
3003 * Canceling and Superseding:: "Whoops, I shouldn't have called him that."
3004 * Marking Articles:: Marking articles as read, expirable, etc.
3005 * Limiting:: You can limit the summary buffer.
3006 * Threading:: How threads are made.
3007 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
3008 * Article Caching:: You may store articles in a cache.
3009 * Exiting the Summary Buffer:: Returning to the Group buffer.
3010 * Process/Prefix:: A convention used by many treatment commands.
3011 * Saving Articles:: Ways of customizing article saving.
3012 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
3013 * Article Treatment:: The article buffer can be mangled at will.
3014 * Various Article Stuff:: Various stuff dealing with articles.
3015 * Summary Sorting:: You can sort the summary buffer four ways.
3016 * Finding the Parent:: No child support? Get the parent.
3017 * Score Files:: Maintaining a score file.
3018 * Mail Group Commands:: Some commands can only be used in mail groups.
3019 * Various Summary Stuff:: What didn't fit anywhere else.
3022 @node Summary Buffer Format
3023 @section Summary Buffer Format
3024 @cindex summary buffer format
3027 * Summary Buffer Lines:: You can specify how summary lines should look.
3028 * Summary Buffer Mode Line:: You can say how the mode line should look.
3031 @findex mail-extract-address-components
3032 @findex gnus-extract-address-components
3033 @vindex gnus-extract-address-components
3034 Gnus will use the value of the @code{gnus-extract-address-components}
3035 variable as a function for getting the name and address parts of a
3036 @code{From} header. Two pre-defined function exist:
3037 @code{gnus-extract-address-components}, which is the default, quite
3038 fast, and too simplistic solution, and
3039 @code{mail-extract-address-components}, which works very nicely, but is
3042 @vindex gnus-summary-same-subject
3043 @code{gnus-summary-same-subject} is a string indicating that the current
3044 article has the same subject as the previous. This string will be used
3045 with those specs that require it.
3047 @node Summary Buffer Lines
3048 @subsection Summary Buffer Lines
3050 @vindex gnus-summary-line-format
3051 You can change the format of the lines in the summary buffer by changing
3052 the @code{gnus-summary-line-format} variable. It works along the same
3053 lines a a normal @code{format} string, with some extensions.
3055 The default string is @samp{"%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n"}.
3057 The following format specification characters are understood:
3065 Subject if the article is the root, @code{gnus-summary-same-subject}
3068 Full @code{From} line.
3070 The name (from the @code{From} header).
3072 The name (from the @code{From} header). This differs from the @code{n}
3073 spec in that it uses @code{gnus-extract-address-components}, which is
3074 slower, but may be more thorough.
3076 The address (from the @code{From} header). This works the same way as
3079 Number of lines in the article.
3081 Number of characters in the article.
3083 Indentation based on thread level (@pxref{Customizing Threading}).
3085 Nothing if the article is a root and lots of spaces if it isn't (it
3086 pushes everything after it off the screen).
3088 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
3089 for adopted articles.
3091 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
3092 for adopted articles.
3094 One space for each thread level.
3096 Twenty minus thread level spaces.
3104 @vindex gnus-summary-zcore-fuzz
3105 Zcore, @samp{+} if above the default level and @samp{-} if below the
3106 default level. If the difference between
3107 @code{gnus-summary-default-level} and the score is less than
3108 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
3118 Number of articles in the current sub-thread. Using this spec will slow
3119 down summary buffer generation somewhat.
3121 A single character will be displayed if the article has any children.
3123 User defined specifier. The next character in the format string should
3124 be a letter. @sc{gnus} will call the function
3125 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
3126 following @samp{%u}. The function will be passed the current header as
3127 argument. The function should return a string, which will be inserted
3128 into the summary just like information from any other summary specifier.
3131 Text between @samp{%(} and @samp{%)} will be highlighted with
3132 @code{gnus-mouse-face} when the mouse point is placed inside the area.
3133 There can only be one such area.
3135 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
3136 have to be handled with care. For reasons of efficiency, Gnus will
3137 compute what column these characters will end up in, and "hard-code"
3138 that. This means that it is illegal to have these specs after a
3139 variable-length spec. Well, you might not be arrested, but your summary
3140 buffer will look strange, which is bad enough.
3142 The smart choice is to have these specs as far to the left as possible.
3143 (Isn't that the case with everything, though? But I digress.)
3145 This restriction may disappear in later versions of Gnus.
3147 @node Summary Buffer Mode Line
3148 @subsection Summary Buffer Mode Line
3150 @vindex gnus-summary-mode-line-format
3151 You can also change the format of the summary mode bar. Set
3152 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
3153 elements you can play with:
3159 Unprefixed group name.
3161 Current article number.
3165 Number of unread articles in this group.
3167 Number of unselected articles in this group.
3169 A string with the number of unread and unselected articles represented
3170 either as @samp{<%U(+%u) more>} if there are both unread and unselected
3171 articles, and just as @samp{<%U more>} if there are just unread articles
3172 and no unselected ones.
3174 Shortish group name. For instance, @samp{rec.arts.anime} will be
3175 shortened to @samp{r.a.anime}.
3177 Subject of the current article.
3181 Name of the current score file.
3185 @node Summary Maneuvering
3186 @section Summary Maneuvering
3187 @cindex summary movement
3189 All the straight movement commands understand the numeric prefix and
3190 behave pretty much as you'd expect.
3192 None of these commands select articles.
3197 @kindex M-n (Summary)
3198 @kindex G M-n (Summary)
3199 @findex gnus-summary-next-unread-subject
3200 Go to the next summary line of an unread article
3201 (@code{gnus-summary-next-unread-subject}).
3204 @kindex M-p (Summary)
3205 @kindex G M-p (Summary)
3206 @findex gnus-summary-prev-unread-subject
3207 Go to the previous summary line of an unread article
3208 (@code{gnus-summary-prev-unread-subject}).
3212 @kindex G g (Summary)
3213 @findex gnus-summary-goto-subject
3214 Ask for an article number and then go to this summary line
3215 (@code{gnus-summary-goto-subject}).
3218 @vindex gnus-auto-select-next
3219 If you are at the end of the group and issue one of the movement
3220 commands, Gnus will offer to go to the next group. If
3221 @code{gnus-auto-select-next} is @code{t} and the next group is empty,
3222 Gnus will exit summary mode and return to the group buffer. If this
3223 variable is neither @code{t} nor @code{nil}, Gnus will select the next
3224 group, no matter whether it has any unread articles or not. As a
3225 special case, if this variable is @code{quietly}, Gnus will select the
3226 next group without asking for confirmation. Also @xref{Group Levels}.
3228 If Gnus asks you to press a key to confirm going to the next group, you
3229 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
3230 buffer, searching for the next group to read without actually returning
3231 to the group buffer.
3233 @vindex gnus-auto-select-same
3234 If @code{gnus-auto-select-same} is non-@code{nil}, all the movement
3235 commands will try to go to the next article with the same subject as the
3236 current. This variable is not particularly useful if you use a threaded
3239 @vindex gnus-summary-check-current
3240 If @code{gnus-summary-check-current} is non-@code{nil}, all the "unread"
3241 movement commands will not proceed to the next (or previous) article if
3242 the current article is unread. Instead, they will choose the current
3245 @vindex gnus-auto-center-summary
3246 If @code{gnus-auto-center-summary} is non-@code{nil}, Gnus will keep the
3247 point in the summary buffer centered at all times. This makes things
3248 quite tidy, but if you have a slow network connection, or simply do not
3249 like this un-Emacsism, you can set this variable to @code{nil} to get
3250 the normal Emacs scrolling action.
3252 @node Choosing Articles
3253 @section Choosing Articles
3254 @cindex selecting articles
3256 None of the following movement commands understand the numeric prefix,
3257 and they all select and display an article.
3261 @kindex SPACE (Summary)
3262 @findex gnus-summary-next-page
3263 Select the current article, or, if that one's read already, the next
3264 unread article (@code{gnus-summary-next-page}).
3268 @kindex G n (Summary)
3269 @findex gnus-summary-next-unread-article
3270 Go to next unread article (@code{gnus-summary-next-unread-article}).
3274 @findex gnus-summary-prev-unread-article
3275 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
3279 @kindex G N (Summary)
3280 @findex gnus-summary-next-article
3281 Go to the next article (@code{gnus-summary-next-article}).
3285 @kindex G P (Summary)
3286 @findex gnus-summary-prev-article
3287 Go to the previous article (@code{gnus-summary-prev-article}).
3289 @kindex G C-n (Summary)
3290 @findex gnus-summary-next-same-subject
3291 Go to the next article with the same subject
3292 (@code{gnus-summary-next-same-subject}).
3294 @kindex G C-p (Summary)
3295 @findex gnus-summary-prev-same-subject
3296 Go to the previous article with the same subject
3297 (@code{gnus-summary-prev-same-subject}).
3300 @kindex G f (Summary)
3302 @findex gnus-summary-first-unread-article
3303 Go to the first unread article
3304 (@code{gnus-summary-first-unread-article}).
3307 @kindex G b (Summary)
3309 Go to the article with the highest score
3310 (@code{gnus-summary-best-unread-article}).
3314 @kindex G l (Summary)
3315 @findex gnus-summary-goto-last-article
3316 Go to the previous article read (@code{gnus-summary-goto-last-article}).
3318 @kindex G p (Summary)
3319 @findex gnus-summary-pop-article
3320 Pop an article off the summary history and go to this article
3321 (@code{gnus-summary-pop-article}). This command differs from the
3322 command above in that you can pop as many previous articles off the
3323 history as you like.
3326 Some variables that are relevant for moving and selecting articles:
3329 @item gnus-auto-extend-newsgroup
3330 @vindex gnus-auto-extend-newsgroup
3331 All the movement commands will try to go to the previous (or next)
3332 article, even if that article isn't displayed in the Summary buffer if
3333 this variable is non-@code{nil}. Gnus will then fetch the article from
3334 the server and display it in the article buffer.
3335 @item gnus-select-article-hook
3336 @vindex gnus-select-article-hook
3337 This hook is called whenever an article is selected. By default it
3338 exposes any threads hidden under the selected article.
3339 @item gnus-mark-article-hook
3340 @vindex gnus-mark-article-hook
3341 This hook is called whenever an article is selected. It is intended to
3342 be used for marking articles as read.
3343 @item gnus-visual-mark-article-hook
3344 @vindex gnus-visual-mark-article-hook
3345 This hook is run after selecting an article. It is meant to be used for
3346 highlighting the article in some way. It is not run if
3347 @code{gnus-visual} is @code{nil}.
3348 @item gnus-summary-update-hook
3349 @vindex gnus-summary-update-hook
3350 This hook is called when a summary line is changed. It is not run if
3351 @code{gnus-visual} is @code{nil}.
3352 @item gnus-summary-selected-face
3353 @vindex gnus-summary-selected-face
3354 This is the face (or @dfn{font} as some people call it) that is used to
3355 highlight the current article in the summary buffer.
3356 @item gnus-summary-highlight
3357 @vindex gnus-summary-highlight
3358 Summary lines are highlighted according to this variable, which is a
3359 list where the elements are on the format @code{(FORM . FACE)}. If you
3360 would, for instance, like ticked articles to be italic and high-scored
3361 articles to be bold, you could set this variable to something like
3363 (((eq mark gnus-ticked-mark) . italic)
3364 ((> score default) . bold))
3366 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
3367 @var{FACE} will be applied to the line.
3370 @node Paging the Article
3371 @section Scrolling the Article
3372 @cindex article scrolling
3377 @kindex SPACE (Summary)
3378 @findex gnus-summary-next-page
3379 Pressing @kbd{SPACE} will scroll the current article forward one page,
3380 or, if you have come to the end of the current article, will choose the
3381 next article (@code{gnus-summary-next-page}).
3384 @kindex DEL (Summary)
3385 @findex gnus-summary-prev-page
3386 Scroll the current article back one page (@code{gnus-summary-prev-page}).
3388 @kindex RET (Summary)
3389 @findex gnus-summary-scroll-up
3390 Scroll the current article one line forward
3391 (@code{gnus-summary-scroll-up}).
3396 @kindex A < (Summary)
3397 @findex gnus-summary-beginning-of-article
3398 Scroll to the beginning of the article
3399 (@code{gnus-summary-beginning-of-article}).
3404 @kindex A > (Summary)
3405 @findex gnus-summary-end-of-article
3406 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
3409 @kindex A s (Summary)
3410 @findex gnus-summary-isearch-article
3411 Perform an isearch in the article buffer
3412 (@code{gnus-summary-isearch-article}).
3416 @node Reply Followup and Post
3417 @section Reply, Followup and Post
3422 @kindex C-c C-c (Post)
3423 All the commands for posting and mailing will put you in a post or mail
3424 buffer where you can edit the article all you like, before you send the
3425 article by pressing @kbd{C-c C-c}. If you are in a foreign news group,
3426 and you wish to post the article using the foreign server, you can give
3427 a prefix to @kbd{C-c C-c} to make Gnus try to post using the foreign
3431 * Mail:: Mailing & replying.
3432 * Post:: Posting and following up.
3433 * Mail & Post:: Mailing and posting at the same time.
3434 * Drafts:: Postponing messages and rejected messages.
3440 Commands for composing a mail message:
3445 @kindex S r (Summary)
3447 @findex gnus-summary-reply
3448 Mail a reply to the author of the current article
3449 (@code{gnus-summary-reply}).
3453 @kindex S R (Summary)
3454 @findex gnus-summary-reply-with-original
3455 Mail a reply to the author of the current article and include the
3456 original message (@code{gnus-summary-reply-with-original}). This
3457 command uses the process/prefix convention.
3459 @kindex S o m (Summary)
3460 @findex gnus-summary-mail-forward
3461 Forward the current article to some other person
3462 (@code{gnus-summary-mail-forward}).
3464 @kindex S o p (Summary)
3465 @findex gnus-summary-post-forward
3466 Forward the current article to a newsgroup
3467 (@code{gnus-summary-post-forward}).
3471 @kindex S m (Summary)
3472 @findex gnus-summary-mail-other-window
3473 Send a mail to some other person
3474 (@code{gnus-summary-mail-other-window}).
3476 @kindex S D b (Summary)
3477 @findex gnus-summary-resend-bounced-mail
3478 If you have sent a mail, but the mail was bounced back to you for some
3479 reason (wrong address, transient failure), you can use this command to
3480 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
3481 will be popped into a mail buffer where you can edit the headers before
3482 sending the mail off again. The headers that match the regexp
3483 @code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
3484 automatically deleted first. If you give a prefix to this command, and
3485 the bounced mail is a reply to some other mail, Gnus will try to fetch
3486 that mail and display it for easy perusal of its headers. This might
3487 very well fail, though.
3489 @kindex S O m (Summary)
3490 @findex gnus-uu-digest-mail-forward
3491 Digest the current series and forward the result using mail
3492 (@code{gnus-uu-digest-mail-forward}). This command uses the
3493 process/prefix convention (@pxref{Process/Prefix}).
3495 @kindex S O p (Summary)
3496 @findex gnus-uu-digest-post-forward
3497 Digest the current series and forward the result to a newsgroup
3498 (@code{gnus-uu-digest-mail-forward}).
3501 Variables for customizing outgoing mail:
3504 @item gnus-reply-to-function
3505 @vindex gnus-reply-to-function
3506 Gnus uses the normal methods to determine where replies are to go, but
3507 you can change the behavior to suit your needs by fiddling with this
3510 If you want the replies to go to the @samp{Sender} instead of the
3511 @samp{From} in the group @samp{mail.stupid-list}, you could do something
3515 (setq gnus-reply-to-function
3517 (cond ((string= group "mail.stupid-list")
3518 (mail-fetch-field "sender"))
3523 This function will be called narrowed to the head of the article that is
3526 As you can see, this function should return a string if it has an
3527 opinion as to what the To header should be. If it does not, it should
3528 just return @code{nil}, and the normal methods for determining the To
3529 header will be used.
3531 This function can also return a list. In that case, each list element
3532 should be a cons, where the car should be the name of an header
3533 (eg. @samp{Cc}) and the cdr should be the header value
3534 (eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
3535 the head of the outgoing mail.
3537 @item gnus-mail-send-method
3538 @vindex gnus-mail-send-method
3539 This variable says how a mail should be mailed. It uses the function in
3540 the @code{send-mail-function} variable as the default.
3542 @item gnus-uu-digest-headers
3543 @vindex gnus-uu-digest-headers
3544 List of regexps to match headers included in digested messages. The
3545 headers will be included in the sequence they are matched.
3547 @item gnus-mail-hook
3548 @vindex gnus-mail-hook
3549 Hook called as the last thing after setting up a mail buffer.
3551 @item gnus-required-mail-headers
3552 @vindex gnus-required-mail-headers
3553 Gnus will generate headers in all outgoing mail instead of letting
3554 @code{sendmail} do it for us. This makes it possible to do more neat
3555 stuff, like putting mail without sending it, do hairy @code{Fcc}
3556 handling, and much more. This variable controls what headers Gnus will
3557 generate, and is of the exact same form as @code{gnus-required-headers},
3558 which does the same for news articles (@pxref{Post}).
3560 The @code{Newsgroups} header is illegal in this list, while @code{To} is
3561 required, and @code{X-Mailer} can be added if you so should want.
3565 @kindex C-c C-c (Mail)
3566 @kindex C-c C-p (Mail)
3567 @findex gnus-put-message
3568 You normally send a mail message by pressing @kbd{C-c C-c}. However,
3569 you may wish to just put the mail message you have just written in your
3570 own local mail group instead of sending it. Sounds quite unlikely, but
3571 I found that useful, so you can now also press @kbd{C-c C-p} to
3572 @dfn{put} the article in the current mail group, or, if there is no such
3573 thing, you will be prompted for a mail group, and then the article will
3574 be put there. This means that the article is @dfn{not} mailed.
3576 There are three "methods" for handling all mail. The default is
3577 @code{sendmail}. Some people like what @code{mh} does better, and some
3578 people prefer @code{vm}.
3580 Three variables for customizing what to use when:
3584 @vindex gnus-mail-reply-method
3585 @item gnus-mail-reply-method
3586 This function is used to compose replies. The three functions avaibale
3589 @findex gnus-mail-reply-using-vm
3590 @findex gnus-mail-reply-using-mhe
3591 @findex gnus-mail-reply-using-mail
3594 @code{gnus-mail-reply-using-mail} (sendmail)
3596 @code{gnus-mail-reply-using-mhe} (mh)
3598 @code{gnus-mail-reply-using-vm} (vm)
3601 @vindex gnus-mail-forward-method
3602 @item gnus-mail-forward-method
3603 This function is used to forward messages. The three functions avaibale
3606 @findex gnus-mail-forward-using-vm
3607 @findex gnus-mail-forward-using-mhe
3608 @findex gnus-mail-forward-using-mail
3611 @code{gnus-mail-forward-using-mail} (sendmail)
3613 @code{gnus-mail-forward-using-mhe} (mh)
3615 @code{gnus-mail-forward-using-vm} (vm)
3618 @vindex gnus-mail-other-window-method
3619 @item gnus-mail-other-window-method
3620 This function is used to send mails. The three functions avaibale are:
3622 @findex gnus-mail-other-window-using-vm
3623 @findex gnus-mail-other-window-using-mhe
3624 @findex gnus-mail-other-window-using-mail
3627 @code{gnus-mail-other-window-using-mail} (sendmail)
3629 @code{gnus-mail-other-window-using-mhe} (mh)
3631 @code{gnus-mail-other-window-using-vm} (vm)
3640 Commands for posting an article:
3646 @kindex S p (Summary)
3647 @findex gnus-summary-post-news
3648 Post an article to the current group
3649 (@code{gnus-summary-post-news}).
3653 @kindex S f (Summary)
3654 @findex gnus-summary-followup
3655 Post a followup to the current article (@code{gnus-summary-followup}).
3658 @kindex S F (Summary)
3660 @findex gnus-summary-followup-with-original
3661 Post a followup to the current article and include the original message
3662 (@code{gnus-summary-followup-with-original}). This command uses the
3663 process/prefix convention.
3665 @kindex S u (Summary)
3666 @findex gnus-uu-post-news
3667 Uuencode a file, split it into parts, and post it as a series
3668 (@code{gnus-uu-post-news}).
3669 @c (@pxref{Uuencoding & Posting}).
3672 @vindex gnus-required-headers
3673 @code{gnus-required-headers} a list of header symbols. These headers
3674 will either be automatically generated, or, if that's impossible, they
3675 will be prompted for. The following symbols are legal:
3679 This required header will be filled out with the result of the
3680 @code{gnus-inews-user-name} function, which depends on the
3681 @code{gnus-user-from-line}, @code{gnus-user-login-name},
3682 @code{gnus-local-domain} and @code{user-mail-address} variables.
3684 This required header will be prompted for if not present already.
3686 This required header says which newsgroups the article is to be posted
3687 to. If it isn't present already, it will be prompted for.
3689 @cindex organization
3690 @vindex gnus-local-organization
3691 @vindex gnus-organization-file
3692 This optional header will be filled out depending on the
3693 @code{gnus-local-organization} variable. @code{gnus-organization-file}
3694 will be used if that variable is nil.
3696 This optional header will be computed by Gnus.
3698 This required header will be generated by Gnus. A unique ID will be
3699 created based on date, time, user name and system name.
3701 This optional header will be filled out with the Gnus version numbers.
3704 In addition, you can enter conses into this list. The car of this cons
3705 should be a symbol who's name is the name of the header, and the cdr can
3706 either a string to be entered verbatim as the value of this header, or
3707 it can be a function to be called. This function should return a string
3708 to be inserted. For instance, if you want to insert @samp{Mime-Version:
3709 1.0}, you should enter @code{(Mime-Version . "1.0")} into the list. If
3710 you want to insert a funny quote, you could enter something like
3711 @code{(X-Yow . yow)} into the list. The function @code{yow} will then
3712 be called without any arguments.
3714 Other variables for customizing outgoing articles:
3717 @item gnus-post-method
3718 @vindex gnus-post-method
3719 If non-@code{nil}, Gnus will use this method instead of the default
3720 select method when posting.
3722 @item nntp-news-default-headers
3723 @vindex nntp-news-default-headers
3724 If non-@code{nil}, this variable will override
3725 @code{mail-default-headers} when posting. This variable should then be
3726 a string. This string will be inserted, as is, in the head of all
3729 @item gnus-use-followup-to
3730 @vindex gnus-use-followup-to
3731 If @code{nil}, always ignore the Followup-To header. If it is @code{t},
3732 use its value, but ignore the special value @samp{poster}, which will
3733 send the followup as a reply mail to the person you are responding to.
3734 If it is the symbol @code{ask}, query the user before posting.
3735 If it is the symbol @code{use}, always use the value.
3737 @item gnus-followup-to-function
3738 @vindex gnus-followup-to-function
3739 This variable is most useful in mail groups, where "following up" really
3740 means sending a mail to a list address. Gnus uses the normal methods to
3741 determine where follow-ups are to go, but you can change the behavior
3742 to suit your needs by fiddling with this variable.
3744 If you want the followups to go to the @samp{Sender} instead of the
3745 @samp{From} in the group @samp{mail.stupid-list}, you could do something
3749 (setq gnus-followup-to-function
3751 (cond ((string= group "mail.stupid-list")
3752 (mail-fetch-field "sender"))
3757 This function will be called narrowed to header of the article that is
3760 @item gnus-removable-headers
3761 @vindex gnus-removable-headers
3762 Some headers that are generated are toxic to the @sc{nntp} server.
3763 These include the @code{NNTP-Posting-Host}, @code{Bcc} and @code{Xref},
3764 so these headers are deleted if they are present in this list of
3767 @item gnus-deletable-headers
3768 @vindex gnus-deletable-headers
3769 Headers in this list that were previously generated by Gnus will be
3770 deleted before posting. Let's say you post an article. Then you decide
3771 to post it again to some other group, you naughty boy, so you jump back
3772 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
3773 ship it off again. By default, this variable makes sure that the old
3774 generated @code{Message-ID} is deleted, and a new one generated. If
3775 this isn't done, the entire empire would probably crumble, anarchy would
3776 prevail, and cats would start walking on two legs and rule the world.
3779 @item gnus-signature-function
3780 @vindex gnus-signature-function
3781 If non-@code{nil}, this variable should be a function that returns a
3782 signature file name. The function will be called with the name of the
3783 group being posted to. If the function returns a string that doesn't
3784 correspond to a file, the string itself is inserted. If the function
3785 returns @code{nil}, the @code{gnus-signature-file} variable will be used
3788 @item gnus-post-prepare-function
3789 @vindex gnus-post-prepare-function
3790 This function is called with the name of the current group after the
3791 post buffer has been initialized, and can be used for inserting a
3792 signature. Nice if you use different signatures in different groups.
3794 @item gnus-post-prepapare-hook
3795 @vindex gnus-post-prepapare-hook
3796 This hook is called after a post buffer has been prepared. If you want
3797 to insert a signature at this point, you could put
3798 @code{gnus-inews-insert-signature} into this hook.
3800 @item news-reply-header-hook
3801 @vindex news-reply-header-hook
3802 A related variable when following up and replying is this variable,
3803 which inserts the @dfn{quote line}. The default value is:
3806 (defvar news-reply-header-hook
3808 (insert "In article " news-reply-yank-message-id
3809 " " news-reply-yank-from " writes:\n\n")))
3812 This will create lines like:
3815 In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
3818 Having the @code{Message-Id} in this line is probably overkill, so I
3819 would suggest this hook instead:
3822 (setq news-reply-header-hook
3823 (lambda () (insert news-reply-yank-from " writes:\n\n")))
3826 @item gnus-prepare-article-hook
3827 @vindex gnus-prepare-article-hook
3828 This hook is called before the headers have been prepared. By default
3829 it inserts the signature specified by @code{gnus-signature-file}.
3831 @item gnus-inews-article-function
3832 @vindex gnus-inews-article-function
3833 This function is used to do the actual article processing and header
3834 checking/generation.
3836 @item gnus-inews-article-hook
3837 @vindex gnus-inews-article-hook
3838 This hook is called right before the article is posted. By default it
3839 handles FCC processing (i.e., saving the article to a file.)
3841 @item gnus-inews-article-header-hook
3842 @vindex gnus-inews-article-header-hook
3843 This hook is called after inserting the required headers in an article
3844 to be posted. The hook is called from the @code{*post-news*} buffer,
3845 narrowed to the head, and is intended for people who would like to
3846 insert additional headers, or just change headers in some way or other.
3848 @item gnus-check-before-posting
3849 @vindex gnus-check-before-posting
3850 If non-@code{nil}, Gnus will attempt to check the legality of the
3851 headers, as well as some other stuff, before posting. You can control
3852 the granularity of the check by adding or removing elements from this
3853 list. Legal elemetents are:
3857 Check the subject for commands.
3858 @item multiple-headers
3859 Check for the existence of multiple equal headers.
3861 Check for the existence of version and sendsys commands.
3863 Check whether the @code{Message-ID} looks ok.
3865 Check whether the @code{From} header seems nice.
3867 Check for too long lines.
3869 Check for illegal characters.
3871 Check for excessive size.
3873 Check whether there is any new text in the messages.
3875 Check the length of the signature
3877 Check whether the article has an @code{Approved} header, which is
3878 something only moderators should include.
3885 @subsection Mail & Post
3887 Commands for sending mail and post at the same time:
3891 @kindex S b (Summary)
3892 @findex gnus-summary-followup-and-reply
3893 Post a followup and send a reply to the current article
3894 (@code{gnus-summary-followup-and-reply}).
3896 @kindex S B (Summary)
3897 @findex gnus-summary-followup-and-reply-with-original
3898 Post a followup and send a reply to the current article and include the
3899 original message (@code{gnus-summary-followup-and-reply-with-original}).
3900 This command uses the process/prefix convention.
3903 Here's a list of variables that are relevant to both mailing and
3907 @item gnus-signature-file
3908 @itemx mail-signature
3909 @vindex mail-signature
3910 @vindex gnus-signature-file
3911 @cindex double signature
3913 If @code{gnus-signature-file} is non-@code{nil}, it should be the name
3914 of a file containing a signature (@samp{~/.signature} by default). This
3915 signature will be appended to all outgoing post. Most people find it
3916 more convenient to use @code{mail-signature}, which (sort of) does the
3917 same, but inserts the signature into the buffer before you start editing
3918 the post (or mail). So - if you have both of these variables set, you
3919 will get two signatures. Note that @code{mail-signature} does not work
3920 the same way as @code{gnus-signature-file}, which is a bit confusing.
3921 If @code{mail-signature} is @code{t}, it will insert
3922 @file{~/.signature}. If it is a string, this string will be inserted.
3924 Note that RFC1036 says that a signature should be preceded by the three
3925 characters @samp{-- } on a line by themselves. This is to make it
3926 easier for the recipient to automatically recognize and process the
3927 signature. So don't remove those characters, even though you might feel
3928 that they ruin you beautiful design, like, totally.
3930 Also note that no signature should be more than four lines long.
3931 Including ASCII graphics is an efficient way to get everybody to believe
3932 that you are silly and have nothing important to say.
3934 @item mail-yank-prefix
3935 @vindex mail-yank-prefix
3938 When you are replying to or following up an article, you normally want
3939 to quote the person you are answering. Inserting quoted text is done by
3940 @dfn{yanking}, and each quoted line you yank will have
3941 @code{mail-yank-prefix} prepended to it. This is @samp{ } by default,
3942 which isn't very pretty. Most everybody prefers that lines are
3943 prepended with @samp{> }, so @code{(setq mail-yank-prefix "> ")} in your
3946 @item mail-yank-ignored-headers
3947 @vindex mail-yank-ignored-headers
3948 When you yank a message, you do not want to quote any headers, so
3949 @code{(setq mail-yank-ignored-headers ":")}.
3951 @item user-mail-address
3952 @vindex user-mail-address
3953 If all of @code{gnus-user-login-name}, @code{gnus-use-generic-from} and
3954 @code{gnus-local-domain} are @code{nil}, Gnus will use
3955 @code{user-mail-address} as the address part of the @code{From} header.
3957 @item gnus-user-from-line
3958 @vindex gnus-user-from-line
3959 Your full, complete e-mail address. This variable overrides the other
3960 Gnus variables if it is non-@code{nil}.
3962 Here are two example values of this variable: @samp{"larsi@@ifi.uio.no
3963 (Lars Magne Ingebrigtsen)"} and @samp{"Lars Magne Ingebrigtsen
3964 <larsi@@ifi.uio.no>"}. The latter version is recommended, but the name
3965 has to be quoted if it contains non-alpha-numerical characters -
3966 @samp{"\"Lars M. Ingebrigtsen\" <larsi@@ifi.uio.no>"}.
3968 @item mail-default-headers
3969 @vindex mail-default-headers
3970 This is a string that will be inserted into the header of all outgoing
3971 mail messages and news articles. Convenient to use to insert standard
3972 headers. If @code{nntp-news-default-headers} is non-@code{nil}, that
3973 variable will override this one when posting articles.
3975 @item gnus-auto-mail-to-author
3976 @vindex gnus-auto-mail-to-author
3977 If @code{ask}, you will be prompted for whether you want to send a mail
3978 copy to the author of the article you are following up. If
3979 non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
3980 all follow-ups to the authors of the articles you follow up. It's nice
3981 in one way - you make sure that the person you are responding to gets
3982 your response. Other people loathe this method and will hate you dearly
3983 for it, because it means that they will first get a mail, and then have
3984 to read the same article later when they read the news. It is
3985 @code{nil} by default.
3987 @item gnus-mail-courtesy-message
3988 @vindex gnus-mail-courtesy-message
3989 This is a string that will be prepended to all mails that are the result
3990 of using the variable described above.
3992 @item gnus-outgoing-message-group
3993 @vindex gnus-outgoing-message-group
3994 All outgoing messages will be put in this group. If you want to store
3995 all your outgoing mail and articles in the group @samp{nnml:archive},
3996 you set this variable to that value. This variable can also be a list of
3999 If you want to have greater control over what group to put each
4000 message in, you can set this variable to a function that checks the
4001 current newsgroup name and then returns a suitable group name (or list
4006 You may want to do spell-checking on messages that you send out. Or, if
4007 you don't want to spell-check by hand, you could add automatic
4008 spell-checking via the @code{ispell} package:
4010 @vindex news-inews-hook
4012 (add-hook 'news-inews-hook 'ispell-message) ;For news posts
4013 (add-hook 'mail-send-hook 'ispell-message) ;for mail posts via sendmail
4016 @findex gnus-inews-insert-mime-headers
4017 If you want to insert some @sc{mime} headers into the articles you post,
4018 without doing any actual encoding, you could add
4019 @code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
4026 If you are writing a message (mail or news) and suddenly remember that
4027 you have a steak in the oven (or pesto in the food processor, you craazy
4028 vegetarians), you'll probably wish there was a method to save the
4029 message you are writing so that you can continue editing it some other
4030 day, and send it when you feel its finished.
4032 @kindex C-c C-d (Mail)
4033 @kindex C-c C-d (Post)
4034 @findex gnus-enter-into-draft-group
4035 @vindex gnus-group-draft-directory
4036 What you then do is simply push @kbd{C-c C-d}
4037 (@code{gnus-enter-into-draft-group}). This will put the current
4038 (unfinished) message in a special draft group (which is implemented as
4039 an @code{nndir} group, if you absolutely have to know) called
4040 @samp{nndir:drafts}. The variable @code{gnus-group-draft-directory}
4041 controls both the name of the group and the location -- the leaf element
4042 in the path will be used as the name of the group.
4044 If the group doesn't exist, it will be created and subscribed to.
4046 @findex gnus-summary-send-draft
4048 When you want to continue editing, you simply enter the draft group and
4049 push @kbd{S D c} (@code{gnus-summary-send-draft}) to do that. You will
4050 be placed in a buffer where you left off.
4052 Rejected articles will also be put in this draft group (@pxref{Rejected
4055 @findex gnus-summary-send-all-drafts
4056 If you have lots of rejected messages you want to post (or mail) without
4057 doing further editing, you can use the @kbd{S D a} command
4058 (@code{gnus-summary-send-all-drafts}). This command understands the
4059 process/prefix convention.
4062 @node Rejected Articles
4063 @subsection Rejected Articles
4064 @cindex rejected articles
4066 Sometimes a news server will reject an article. Perhaps the server
4067 doesn't like your face. Perhaps it just feels miserable. Perhaps there
4068 be demons. Perhaps you have included too much cited text. Perhaps the
4069 disk is full. Perhaps the server is down.
4071 These situations are, of course, totally beyond the control of Gnus.
4072 (Gnus, of course, loves the way you look, always feels great, has angels
4073 fluttering around in it, doesn't care about how much cited text you
4074 include, never runs full and never goes down.) So what Gnus does is
4075 saves these articles until some later time when the server feels better.
4077 The rejected articles will automatically be put in a special draft group
4078 (@pxref{Drafts}). When the server comes back up again, you'd then
4079 typically enter that group and send all the articles off.
4082 @node Canceling and Superseding
4083 @section Canceling Articles
4084 @cindex canceling articles
4085 @cindex superseding articles
4087 Have you ever written something, and then decided that you really,
4088 really, really wish you hadn't posted that?
4090 Well, you can't cancel mail, but you can cancel posts.
4092 @findex gnus-summary-cancel-article
4094 Find the article you wish to cancel (you can only cancel your own
4095 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
4096 c} (@code{gnus-summary-cancel-article}). Your article will be
4097 canceled - machines all over the world will be deleting your article.
4099 Be aware, however, that not all sites honor cancels, so your article may
4100 live on here and there, while most sites will delete the article in
4103 If you discover that you have made some mistakes and want to do some
4104 corrections, you can post a @dfn{superseding} article that will replace
4105 your original article.
4107 @findex gnus-summary-supersede-article
4109 Go to the original article and press @kbd{S s}
4110 (@code{gnus-summary-supersede-article}). You will be put in a buffer
4111 where you can edit the article all you want before sending it off the
4114 @vindex gnus-delete-supersedes-headers
4115 You probably want to delete some of the old headers before sending the
4116 superseding article - @code{Path} and @code{Date} are probably
4117 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
4118 match the lines you want removed. The default is
4119 @samp{"^Path:\\|^Date"}.
4121 The same goes for superseding as for canceling, only more so: Some
4122 sites do not honor superseding. On those sites, it will appear that you
4123 have posted almost the same article twice.
4125 If you have just posted the article, and change your mind right away,
4126 there is a trick you can use to cancel/supersede the article without
4127 waiting for the article to appear on your site first. You simply return
4128 to the post buffer (which is called @code{*post-buf*}). There you will
4129 find the article you just posted, with all the headers intact. Change
4130 the @samp{Message-ID} header to a @samp{Cancel} or @samp{Supersedes}
4131 header by substituting one of those words for @samp{Message-ID}. Then
4132 just press @kbd{C-c C-c} to send the article as you would do normally.
4133 The previous article will be canceled/superseded.
4135 Just remember, kids: There is no 'c' in 'supersede'.
4137 @node Marking Articles
4138 @section Marking Articles
4139 @cindex article marking
4140 @cindex article ticking
4143 There are several marks you can set on an article.
4145 You have marks that decide the @dfn{readed-ness} (whoo, neato-keano
4146 neologism ohoy!) of the article. Alphabetic marks generally mean
4147 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
4149 In addition, you also have marks that do not affect readedness.
4152 * Unread Articles:: Marks for unread articles.
4153 * Read Articles:: Marks for read articles.
4154 * Other Marks:: Marks that do not affect readedness.
4158 There's a plethora of commands for manipulating these marks:
4162 * Setting Marks:: How to set and remove marks.
4163 * Setting Process Marks:: How to mark articles for later processing.
4166 @node Unread Articles
4167 @subsection Unread Articles
4169 The following marks mark articles as unread, in one form or other.
4171 @vindex gnus-dormant-mark
4172 @vindex gnus-ticked-mark
4175 @dfn{Ticked articles} are articles that will remain visible always. If
4176 you see an article that you find interesting, or you want to put off
4177 reading it, or replying to it, until sometime later, you'd typically
4178 tick it. However, articles can be expired, so if you want to keep an
4179 article forever, you'll have to save it. Ticked articles have a
4180 @samp{!} (@code{gnus-ticked-mark}) in the first column.
4182 A @dfn{dormant} article is marked with a @samp{?}
4183 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
4184 if there are followups to it.
4186 An @dfn{unread} article is marked with a @samp{SPC}
4187 (@code{gnus-unread-mark}). These are articles that haven't been read at
4192 @subsection Read Articles
4193 @cindex expirable mark
4195 All the following marks mark articles as read.
4199 Articles that are marked as read. They have a @samp{r}
4200 (@code{gnus-del-mark}) in the first column. These are articles that the
4201 user has marked as read more or less manually.
4203 Articles that are actually read are marked with @samp{R}
4204 (@code{gnus-read-mark}).
4206 Articles that were marked as read in previous sessions are now
4207 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
4209 Marked as killed (@code{gnus-killed-mark}).
4211 Marked as killed by kill files (@code{gnus-kill-file-mark}).
4213 Marked as read by having a too low score (@code{gnus-low-score-mark}).
4215 Marked as read by a catchup (@code{gnus-catchup-mark}).
4217 Canceled article (@code{gnus-cancelled-mark})
4220 All these marks just mean that the article is marked as read, really.
4221 They are interpreted differently by the adaptive scoring scheme,
4224 One more special mark, though:
4228 You can also mark articles as @dfn{expirable} (or have them marked as
4229 such automatically). That doesn't make much sense in normal groups,
4230 because a user does not control the expiring of news articles, but in
4231 mail groups, for instance, articles that are marked as @dfn{expirable}
4232 can be deleted by Gnus at any time. Expirable articles are marked with
4233 @samp{E} (@code{gnus-expirable-mark}).
4237 @subsection Other Marks
4238 @cindex process mark
4241 There are some marks that have nothing to do with whether the article is
4244 You can set a bookmark in the current article. Say you are reading a
4245 long thesis on cat's urinary tracts, and have to go home for dinner
4246 before you've finished reading the thesis. You can then set a bookmark
4247 in the article, and Gnus will jump to this bookmark the next time it
4248 encounters the article.
4250 All articles that you have replied to or made a followup to (i.e., have
4251 answered) will be marked with an @samp{A} in the second column
4252 (@code{gnus-replied-mark}).
4254 @vindex gnus-not-empty-thread-mark
4255 @vindex gnus-empty-thread-mark
4256 It the @samp{%e} spec is used, the presence of threads or not will be
4257 marked with @code{gnus-not-empty-thread-mark} and
4258 @code{gnus-empty-thread-mark}, respectively.
4260 @vindex gnus-process-mark
4261 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
4262 variety of commands react to the presence of the process mark. For
4263 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
4264 all articles that have been marked with the process mark. Articles
4265 marked with the process mark have a @samp{#} in the second column.
4268 @subsection Setting Marks
4269 @cindex setting marks
4271 All the marking commands understand the numeric prefix.
4277 @kindex M t (Summary)
4278 @findex gnus-summary-tick-article-forward
4279 Tick the current article (@code{gnus-summary-tick-article-forward}).
4283 @kindex M ? (Summary)
4284 @findex gnus-summary-mark-as-dormant
4285 Mark the current article as dormant
4286 (@code{gnus-summary-mark-as-dormant}).
4289 @kindex M d (Summary)
4291 @findex gnus-summary-mark-as-read-forward
4292 Mark the current article as read
4293 (@code{gnus-summary-mark-as-read-forward}).
4297 @kindex M k (Summary)
4298 @findex gnus-summary-kill-same-subject-and-select
4299 Mark all articles that have the same subject as the current one as read,
4300 and then select the next unread article
4301 (@code{gnus-summary-kill-same-subject-and-select}).
4304 @kindex M K (Summary)
4305 @kindex C-k (Summary)
4306 @findex gnus-summary-kill-same-subject
4307 Mark all articles that have the same subject as the current one as read
4308 (@code{gnus-summary-kill-same-subject}).
4310 @kindex M C (Summary)
4311 @findex gnus-summary-catchup
4312 Catchup the current group (@code{gnus-summary-catchup}).
4314 @kindex M C-c (Summary)
4315 @findex gnus-summary-catchup-all
4316 Catchup all articles in the current group (@code{gnus-summary-catchup-all}).
4318 @kindex M H (Summary)
4319 @findex gnus-summary-catchup-to-here
4320 Catchup the current group to point
4321 (@code{gnus-summary-catchup-to-here}).
4323 @kindex C-w (Summary)
4324 @findex gnus-summary-mark-region-as-read
4325 Mark all articles between point and mark as read
4326 (@code{gnus-summary-mark-region-as-read}).
4328 @kindex M V k (Summary)
4329 @findex gnus-summary-kill-below
4330 Kill all articles with scores below the default score (or below the
4331 numeric prefix) (@code{gnus-summary-kill-below}).
4334 @kindex M c (Summary)
4335 @kindex M-u (Summary)
4336 @findex gnus-summary-clear-mark-forward
4337 Clear all readedness-marks from the current article
4338 (@code{gnus-summary-clear-mark-forward}).
4341 @kindex M e (Summary)
4343 @findex gnus-summary-mark-as-expirable
4344 Mark the current article as expirable
4345 (@code{gnus-summary-mark-as-expirable}).
4347 @kindex M b (Summary)
4348 @findex gnus-summary-set-bookmark
4349 Set a bookmark in the current article
4350 (@code{gnus-summary-set-bookmark}).
4352 @kindex M B (Summary)
4353 @findex gnus-summary-remove-bookmark
4354 Remove the bookmark from the current article
4355 (@code{gnus-summary-remove-bookmark}).
4357 @kindex M V c (Summary)
4358 @findex gnus-summary-clear-above
4359 Clear all marks from articles with scores over the default score (or
4360 over the numeric prefix) (@code{gnus-summary-clear-above}).
4362 @kindex M V u (Summary)
4363 @findex gnus-summary-tick-above
4364 Tick all articles with scores over the default score (or over the
4365 numeric prefix) (@code{gnus-summary-tick-above}).
4367 @kindex M V m (Summary)
4368 @findex gnus-summary-mark-above
4369 Prompt for a mark, and mark all articles with scores over the default
4370 score (or over the numeric prefix) with this mark
4371 (@code{gnus-summary-clear-above}).
4374 @code{gnus-summary-goto-unread}
4375 The @code{gnus-summary-goto-unread} variable controls what action should
4376 be taken after setting a mark. If non-@code{nil}, point will move to
4377 the next/previous unread article. If @code{nil}, point will just move
4378 one line up or down.
4381 @node Setting Process Marks
4382 @subsection Setting Process Marks
4383 @cindex setting process marks
4389 @kindex M P p (Summary)
4390 @findex gnus-summary-mark-as-processable
4391 Mark the current article with the process mark
4392 (@code{gnus-summary-mark-as-processable}).
4393 @findex gnus-summary-unmark-as-processable
4396 @kindex M P u (Summary)
4397 @kindex M-# (Summary)
4398 Remove the process mark, if any, from the current article
4399 (@code{gnus-summary-unmark-as-processable}).
4401 @kindex M P U (Summary)
4402 @findex gnus-summary-unmark-all-processable
4403 Remove the process mark from all articles
4404 (@code{gnus-summary-unmark-all-processable}).
4406 @kindex M P R (Summary)
4407 @findex gnus-uu-mark-by-regexp
4408 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
4410 @kindex M P r (Summary)
4411 @findex gnus-uu-mark-region
4412 Mark articles in region (@code{gnus-uu-mark-region}).
4414 @kindex M P t (Summary)
4415 @findex gnus-uu-mark-thread
4416 Mark all articles in the current (sub)thread
4417 (@code{gnus-uu-mark-thread}).
4419 @kindex M P T (Summary)
4420 @findex gnus-uu-unmark-thread
4421 Unmark all articles in the current (sub)thread
4422 (@code{gnus-uu-unmark-thread}).
4424 @kindex M P s (Summary)
4425 @findex gnus-uu-mark-series
4426 Mark all articles in the current series (@code{gnus-uu-mark-series}).
4428 @kindex M P S (Summary)
4429 @findex gnus-uu-mark-sparse
4430 Mark all series that have already had some articles marked
4431 (@code{gnus-uu-mark-sparse}).
4433 @kindex M P a (Summary)
4434 @findex gnus-uu-mark-all
4435 Mark all articles in series order (@code{gnus-uu-mark-series}).
4437 @kindex M P b (Summary)
4438 @findex gnus-uu-mark-buffer
4439 Mark all articles in the buffer in the order they appear
4440 (@code{gnus-uu-mark-buffer}).
4445 @subsection Limiting
4447 It can be convenient to limit the summary buffer to just show some
4448 subset of the articles currently in the group. The effect most limit
4449 commands have is to remove a few (or many) articles from the summary
4456 @kindex M N u (Summary)
4458 @findex gnus-summary-limit-to-unread
4459 Limit the summary buffer to articles that are not marked as read
4460 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
4461 buffer to articles that are strictly unread. This means that ticked and
4462 dormant articles will also be excluded.
4465 @kindex M N m (Summary)
4466 @findex gnus-summary-limit-to-marks
4467 Ask for a mark and then limit to all articles that have not been marked
4468 with that mark (@code{gnus-summary-limit-to-marks}).
4471 @kindex M N n (Summary)
4473 Limit the summary buffer to the current article
4474 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
4475 convention (@pxref{Process/Prefix}).
4478 @kindex M N w (Summary)
4479 @findex gnus-summary-pop-limit
4480 Pop the previous limit off the stack and restore it
4481 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
4486 @kindex M N s (Summary)
4488 @findex gnus-summary-limit-to-subject
4489 Limit the summary buffer to articles that have a subject that matches a
4490 regexp (@code{gnus-summary-limit-to-subject}).
4493 @kindex M N v (Summary)
4494 @findex gnus-summary-limit-to-score
4495 Limit the summary buffer to articles that have a score at or above some
4496 score (@code{gnus-summary-limit-to-score}).
4499 @kindex M S (Summary)
4500 @findex gnus-summary-show-all-expunged
4501 Display all expunged articles (@code{gnus-summary-show-all-expunged}).
4504 @kindex M N D (Summary)
4505 @findex gnus-summary-limit-include-dormant
4506 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
4509 @kindex M N d (Summary)
4510 @findex gnus-summary-limit-exclude-dormant
4511 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
4514 @kindex M N c (Summary)
4515 @findex gnus-summary-limit-exclude-childless-dormant
4516 Hide all dormant articles that have no children
4517 (@code{gnus-summary-limit-exclude-childless-dormant}).
4525 @cindex article threading
4527 Gnus threads articles by default. @dfn{To thread} is to put replies to
4528 articles directly after the articles they reply to - in a hierarchical
4532 * Customizing Threading:: Variables you can change to affect the threading.
4533 * Thread Commands:: Thread based commands in the summary buffer.
4536 @node Customizing Threading
4537 @subsection Customizing Threading
4538 @cindex customizing threading
4543 @item gnus-show-threads
4544 @vindex gnus-show-threads
4545 If this variable is @code{nil}, no threading will be done, and all of
4546 the rest of the variables here will have no effect. Turning threading
4547 off will speed group selection up a bit, but it is sure to make reading
4548 slower and more awkward.
4550 @item gnus-fetch-old-headers
4551 @vindex gnus-fetch-old-headers
4552 If non-@code{nil}, Gnus will attempt to build old threads by fetching
4553 more old headers - headers to articles that are marked as read. If you
4554 would like to display as few summary lines as possible, but still
4555 connect as many loose threads as possible, you should set this variable
4556 to @code{some} or a number. If you set it to a number, no more than
4557 that number of extra old headers will be fetched. In either case,
4558 fetching old headers only works if the backend you are using carries
4559 overview files -- this would normally be @code{nntp}, @code{nnspool} and
4560 @code{nnml}. Also remember that if the root of the thread has been
4561 expired by the server, there's not much Gnus can do about that.
4563 @item gnus-summary-gather-subject-limit
4564 Loose threads are gathered by comparing subjects of articles. If this
4565 variable is @code{nil}, Gnus requires an exact match between the
4566 subjects of the loose threads before gathering them into one big
4567 super-thread. This might be too strict a requirement, what with the
4568 presence of stupid newsreaders that chop off long subjects lines. If
4569 you think so, set this variable to, say, 20 to require that only the
4570 first 20 characters of the subjects have to match. If you set this
4571 variable to a real low number, you'll find that Gnus will gather
4572 everything in sight into one thread, which isn't very helpful.
4574 @cindex fuzzy article gathering
4575 If you set this variable to the special value @code{fuzzy}, Gnus will
4576 use a fuzzy string comparison algorithm on the subjects.
4578 @vindex gnus-summary-gather-exclude-subject
4579 Since loose thread gathering is done on subjects only, that might lead
4580 to many false hits, especially with certain common subjects like
4581 @samp{""} and @samp{"(none)"}. To make the situation slightly better,
4582 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
4583 what subjects should be excluded from the gathering process. The
4584 default is @samp{"^ *$\\|^(none)$"}.
4586 @item gnus-summary-make-false-root
4587 @vindex gnus-summary-make-false-root
4588 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
4589 and create a dummy root at the top. (Wait a minute. Root at the top?
4590 Yup.) Loose subtrees occur when the real root has expired, or you've
4591 read or killed the root in a previous session.
4593 When there is no real root of a thread, Gnus will have to fudge
4594 something. This variable says what fudging method Gnus should use.
4595 There are four possible values:
4597 @cindex adopting articles
4601 Gnus will make the first of the orphaned articles the parent. This
4602 parent will adopt all the other articles. The adopted articles will be
4603 marked as such by pointy brackets (@samp{<>}) instead of the standard
4604 square brackets (@samp{[]}). This is the default method.
4606 Gnus will create a dummy summary line that will pretend to be the
4607 parent. This dummy line does not correspond to any real article, so
4608 selecting it will just select the first real article after the dummy
4611 Gnus won't actually make any article the parent, but simply leave the
4612 subject field of all orphans except the first empty. (Actually, it will
4613 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
4616 Don't make any article parent at all. Just gather the threads and
4617 display them after one another.
4619 Don't gather loose threads.
4622 @item gnus-thread-hide-subtree
4623 @vindex gnus-thread-hide-subtree
4624 If non-@code{nil}, all threads will be hidden when the summary buffer is
4626 @item gnus-thread-hide-killed
4627 @vindex gnus-thread-hide-killed
4628 if you kill a thread and this variable is non-@code{nil}, the subtree
4630 @item gnus-thread-ignore-subject
4631 @vindex gnus-thread-ignore-subject
4632 Sometimes somebody changes the subject in the middle of a thread. If
4633 this variable is non-@code{nil}, the subject change is ignored. If it
4634 is @code{nil}, which is the default, a change in the subject will result
4636 @item gnus-thread-indent-level
4637 @vindex gnus-thread-indent-level
4638 This is a number that says how much each sub-thread should be indented.
4639 The default is @samp{4}.
4642 @node Thread Commands
4643 @subsection Thread Commands
4644 @cindex thread commands
4649 @kindex T k (Summary)
4650 @kindex M-C-k (Summary)
4651 @findex gnus-summary-kill-thread
4652 Mark all articles in the current sub-thread as read
4653 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
4654 remove all marks instead. If the prefix argument is negative, tick
4658 @kindex T l (Summary)
4659 @kindex M-C-l (Summary)
4660 @findex gnus-summary-lower-thread
4661 Lower the score of the current thread
4662 (@code{gnus-summary-lower-thread}).
4664 @kindex T i (Summary)
4665 @findex gnus-summary-raise-thread
4666 Increase the score of the current thread
4667 (@code{gnus-summary-raise-thread}).
4669 @kindex T # (Summary)
4670 @findex gnus-uu-mark-thread
4671 Set the process mark on the current thread
4672 (@code{gnus-uu-mark-thread}).
4674 @kindex T M-# (Summary)
4675 @findex gnus-uu-unmark-thread
4676 Remove the process mark from the current thread
4677 (@code{gnus-uu-unmark-thread}).
4679 @kindex T T (Summary)
4680 @findex gnus-summary-toggle-threads
4681 Toggle threading (@code{gnus-summary-toggle-threads}).
4683 @kindex T s (Summary)
4684 @findex gnus-summary-show-thread
4685 Expose the thread hidden under the current article, if any
4686 (@code{gnus-summary-show-thread}).
4688 @kindex T h (Summary)
4689 @findex gnus-summary-hide-thread
4690 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
4692 @kindex T S (Summary)
4693 @findex gnus-summary-show-all-threads
4694 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
4696 @kindex T H (Summary)
4697 @findex gnus-summary-hide-all-threads
4698 Hide all threads (@code{gnus-summary-hide-all-threads}).
4701 The following commands are thread movement commands. They all
4702 understand the numeric prefix.
4706 @kindex T n (Summary)
4707 @findex gnus-summary-next-thread
4708 Go to the next thread (@code{gnus-summary-next-thread}).
4710 @kindex T p (Summary)
4711 @findex gnus-summary-prev-thread
4712 Go to the previous thread (@code{gnus-summary-prev-thread}).
4714 @kindex T d (Summary)
4715 @findex gnus-summary-down-thread
4716 Descend the thread (@code{gnus-summary-down-thread}).
4718 @kindex T u (Summary)
4719 @findex gnus-summary-up-thread
4720 Ascend the thread (@code{gnus-summary-up-thread}).
4723 @node Asynchronous Fetching
4724 @section Asynchronous Article Fetching
4725 @cindex asynchronous article fetching
4727 If you read your news from an @sc{nntp} server that's far away, the
4728 network latencies may make reading articles a chore. You have to wait
4729 for a while after pressing @kbd{n} to go to the next article before the
4730 article appears. Why can't Gnus just go ahead and fetch the article
4731 while you are reading the previous one? Why not, indeed.
4733 First, some caveats. There are some pitfalls to using asynchronous
4734 article fetching, especially the way Gnus does it.
4736 Let's say you are reading article 1, which is short, and article 2 is
4737 quite long, and you are not interested in reading that. Gnus does not
4738 know this, so it goes ahead and fetches article 2. You decide to read
4739 article 3, but since Gnus is in the process of fetching article 2, the
4740 connection is blocked.
4742 To avoid these situations, Gnus will open two (count 'em two)
4743 connections to the server. Some people may think this isn't a very nice
4744 thing to do, but I don't see any real alternatives. Setting up that
4745 extra connection takes some time, so Gnus startup will be slower.
4747 Gnus will fetch more articles than you will read. This will mean that
4748 the link between your machine and the @sc{nntp} server will become more
4749 loaded than if you didn't use article pre-fetch. The server itself will
4750 also become more loaded - both with the extra article requests, and the
4753 Ok, so now you know that you shouldn't really use this thing... unless
4756 @vindex gnus-asynchronous
4757 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
4758 happen automatically.
4760 @vindex nntp-async-number
4761 You can control how many articles that are to be pre-fetched by setting
4762 @code{nntp-async-number}. This is five by default, which means that when
4763 you read an article in the group, @code{nntp} will pre-fetch the next
4764 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
4765 all the articles that it can without bound. If it is @code{nil}, no
4766 pre-fetching will be made.
4768 @vindex gnus-asynchronous-article-function
4769 You may wish to create some sort of scheme for choosing which articles
4770 that @code{nntp} should consider as candidates for pre-fetching. For
4771 instance, you may wish to pre-fetch all articles with high scores, and
4772 not pre-fetch low-scored articles. You can do that by setting the
4773 @code{gnus-asynchronous-article-function}, which will be called with an
4774 alist where the keys are the article numbers. Your function should
4775 return an alist where the articles you are not interested in have been
4776 removed. You could also do sorting on article score and the like.
4778 @node Article Caching
4779 @section Article Caching
4780 @cindex article caching
4783 If you have an @emph{extremely} slow @sc{nntp} connection, you may
4784 consider turning article caching on. Each article will then be stored
4785 locally under your home directory. As you may surmise, this could
4786 potentially use @emph{huge} amounts of disk space, as well as eat up all
4787 your inodes so fast it will make your head swim. In vodka.
4789 Used carefully, though, it could be just an easier way to save articles.
4791 @vindex gnus-use-long-file-name
4792 @vindex gnus-cache-directory
4793 @vindex gnus-use-cache
4794 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
4795 all articles that are ticked or marked as dormant will then be copied
4796 over to your local cache (@code{gnus-cache-directory}). Whether this
4797 cache is flat or hierarchal is controlled by the
4798 @code{gnus-use-long-file-name} variable, as usual.
4800 When re-select a ticked or dormant article, it will be fetched from the
4801 cache instead of from the server. As articles in your cache will never
4802 expire, this might serve as a method of saving articles while still
4803 keeping them where they belong. Just mark all articles you want to save
4804 as dormant, and don't worry.
4806 When an article is marked as read, is it removed from the cache.
4808 @vindex gnus-cache-remove-articles
4809 @vindex gnus-cache-enter-articles
4810 The entering/removal of articles from the cache is controlled by the
4811 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
4812 variables. Both are lists of symbols. The first is @code{(ticked
4813 dormant)} by default, meaning that ticked and dormant articles will be
4814 put in the cache. The latter is @code{(read)} by default, meaning that
4815 articles that are marked as read are removed from the cache. Possibly
4816 symbols in these two lists are @code{ticked}, @code{dormant},
4817 @code{unread} and @code{read}.
4819 @findex gnus-jog-cache
4820 So where does the massive article-fetching and storing come into the
4821 picture? The @code{gnus-jog-cache} command will go through all
4822 subscribed newsgroups, request all unread articles, and store them in
4823 the cache. You should only ever, ever ever ever, use this command if 1)
4824 your connection to the @sc{nntp} server is really, really, really slow
4825 and 2) you have a really, really, really huge disk. Seriously.
4828 @node Exiting the Summary Buffer
4829 @section Exiting the Summary Buffer
4830 @cindex summary exit
4832 Exiting from the summary buffer will normally update all info on the
4833 group and return you to the group buffer.
4838 @kindex Z Z (Summary)
4840 @findex gnus-summary-exit
4841 @vindex gnus-summary-exit-hook
4842 @vindex gnus-summary-prepare-exit-hook
4843 Exit the current group and update all information on the group
4844 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
4845 called before doing much of the exiting, and calls
4846 @code{gnus-summary-expire-articles} by default.
4847 @code{gnus-summary-exit-hook} is called after finishing the exiting
4851 @kindex Z E (Summary)
4853 @findex gnus-summary-exit-no-update
4854 Exit the current group without updating any information on the group
4855 (@code{gnus-summary-exit-no-update}).
4858 @kindex Z c (Summary)
4860 @findex gnus-summary-catchup-and-exit
4861 Mark all unticked articles in the group as read and then exit
4862 (@code{gnus-summary-catchup-and-exit}).
4864 @kindex Z C (Summary)
4865 @findex gnus-summary-catchup-all-and-exit
4866 Mark all articles, even the ticked ones, as read and then exit
4867 (@code{gnus-summary-catchup-all-and-exit}).
4869 @kindex Z n (Summary)
4870 @findex gnus-summary-catchup-and-goto-next-group
4871 Mark all articles as read and go to the next group
4872 (@code{gnus-summary-catchup-and-goto-next-group}).
4874 @kindex Z R (Summary)
4875 @findex gnus-summary-reselect-current-group
4876 Exit this group, and then enter it again
4877 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
4878 all articles, both read and unread.
4881 @kindex Z G (Summary)
4882 @kindex M-g (Summary)
4883 @findex gnus-summary-rescan-group
4884 Exit the group, check for new articles in the group, and select the
4885 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
4886 articles, both read and unread.
4888 @kindex Z N (Summary)
4889 @findex gnus-summary-next-group
4890 Exit the group and go to the next group
4891 (@code{gnus-summary-next-group}).
4893 @kindex Z P (Summary)
4894 @findex gnus-summary-prev-group
4895 Exit the group and go to the previous group
4896 (@code{gnus-summary-prev-group}).
4899 @vindex gnus-exit-group-hook
4900 @code{gnus-exit-group-hook} is called when you exit the current
4903 @vindex gnus-use-cross-reference
4904 The data on the current group will be updated (which articles you have
4905 read, which articles you have replied to, etc.) when you exit the
4906 summary buffer. If the @code{gnus-use-cross-reference} variable is
4907 @code{t}, articles that are cross-referenced to this group and are
4908 marked as read, will also be marked as read in the other subscribed
4909 groups they were cross-posted to. If this variable is neither
4910 @code{nil} nor @code{t}, the article will be marked as read in both
4911 subscribed and unsubscribed groups.
4913 Marking cross-posted articles as read ensures that you'll never have to
4914 read the same article more than once. Unless, of course, somebody has
4915 posted it to several groups separately. Posting the same article to
4916 several groups (not cross-posting) is called @dfn{spamming}, and you are
4917 by law required to send nasty-grams to anyone who perpetrates such a
4920 Remember: Cross-posting is kinda ok, but posting the same article
4921 separately to several groups is not.
4923 One thing that may cause Gnus to not do the cross-posting thing
4924 correctly is if you use an @sc{nntp} server that supports @sc{xover}
4925 (which is very nice, because it speeds things up considerably) which
4926 does not include the @code{Xref} header in its @sc{nov} lines. This is
4927 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
4928 even with @sc{xover} by registering the @code{Xref} lines of all
4929 articles you actually read, but if you kill the articles, or just mark
4930 them as read without reading them, Gnus will not get a chance to snoop
4931 the @code{Xref} lines out of these articles, and will be unable to use
4932 the cross reference mechanism.
4934 @vindex gnus-nov-is-evil
4935 If you want Gnus to get the @code{Xref}s right all the time, you have to
4936 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
4941 @node Process/Prefix
4942 @section Process/Prefix
4943 @cindex process/prefix convention
4945 Many functions, among them functions for moving, decoding and saving
4946 articles, use what is known as the @dfn{Process/Prefix convention}.
4948 This is a method for figuring out what articles that the user wants the
4949 command to be performed on.
4953 If the numeric prefix is N, perform the operation on the next N
4954 articles, starting with the current one. If the numeric prefix is
4955 negative, perform the operation on the previous N articles, starting
4956 with the current one.
4958 If there is no numeric prefix, but some articles are marked with the
4959 process mark, perform the operation on the articles that are marked with
4962 If there is neither a numeric prefix nor any articles marked with the
4963 process mark, just perform the operation on the current article.
4965 Quite simple, really, but it needs to be made clear so that surprises
4968 @node Saving Articles
4969 @section Saving Articles
4970 @cindex saving articles
4972 Gnus can save articles in a number of ways. Below is the documentation
4973 for saving articles in a fairly straight-forward fashion (i.e., little
4974 processing of the article is done before it is saved). For a different
4975 approach (uudecoding, unsharing) you should use @code{gnus-uu}
4976 (@pxref{Decoding Articles}).
4978 @vindex gnus-save-all-headers
4979 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
4980 unwanted headers before saving the article.
4985 @kindex O o (Summary)
4987 @findex gnus-summary-save-article
4988 Save the current article using the default article saver
4989 (@code{gnus-summary-save-article}).
4991 @kindex O m (Summary)
4992 @findex gnus-summary-save-article-mail
4993 Save the current article in mail format
4994 (@code{gnus-summary-save-article-mail}).
4996 @kindex O r (Summary)
4997 @findex gnus-summary-save-article-mail
4998 Save the current article in rmail format
4999 (@code{gnus-summary-save-article-rmail}).
5001 @kindex O f (Summary)
5002 @findex gnus-summary-save-article-file
5003 Save the current article in plain file format
5004 (@code{gnus-summary-save-article-file}).
5006 @kindex O h (Summary)
5007 @findex gnus-summary-save-article-folder
5008 Save the current article in mh folder format
5009 (@code{gnus-summary-save-article-folder}).
5011 @kindex O p (Summary)
5012 @findex gnus-summary-pipe-output
5013 Save the current article in a pipe. Uhm, like, what I mean is - Pipe
5014 the current article to a process (@code{gnus-summary-pipe-output}).
5017 All these commands use the process/prefix convention
5018 (@pxref{Process/Prefix}).
5020 @vindex gnus-default-article-saver
5021 You can customize the @code{gnus-default-article-saver} variable to make
5022 Gnus do what you want it to. You can use any of the four ready-made
5023 functions below, or you can create your own.
5026 @item gnus-summary-save-in-rmail
5027 @vindex gnus-summary-save-in-rmail
5028 This is the default format, @dfn{babyl}. Uses the function in the
5029 @code{gnus-rmail-save-name} variable to get a file name to save the
5030 article in. The default is @code{gnus-plain-save-name}.
5031 @item gnus-summary-save-in-mail
5032 @vindex gnus-summary-save-in-mail
5033 Save in a Unix mail (mbox) file. Uses the function in the
5034 @code{gnus-mail-save-name} variable to get a file name to save the
5035 article in. The default is @code{gnus-plain-save-name}.
5036 @item gnus-summary-save-in-file
5037 @vindex gnus-summary-save-in-file
5038 Append the article straight to an ordinary file. Uses the function in
5039 the @code{gnus-file-save-name} variable to get a file name to save the
5040 article in. The default is @code{gnus-numeric-save-name}.
5041 @item gnus-summary-save-in-folder
5042 @vindex gnus-summary-save-in-folder
5043 Save the article to an MH folder using @code{rcvstore} from the MH
5045 @item gnus-summary-save-in-vm
5046 @vindex gnus-summary-save-in-vm
5047 Save the article in a VM folder. You have to have the VM mail
5048 reader to use this setting.
5051 All of these functions, except for the last one, will save the article
5052 in the @code{gnus-article-save-directory}, which is initialized from the
5053 @samp{SAVEDIR} environment variable.
5055 As you can see above, the functions use different functions to find a
5056 suitable name of a file to save the article in. Below is a list of
5057 available functions that generate names:
5060 @item gnus-Numeric-save-name
5061 @findex gnus-Numeric-save-name
5062 Generates file names that look like @samp{~/News/Alt.andrea-dworkin/45}.
5063 @item gnus-numeric-save-name
5064 @findex gnus-numeric-save-name
5065 Generates file names that look like @samp{~/News/alt.andrea-dworkin/45}.
5066 @item gnus-Plain-save-name
5067 @findex gnus-Plain-save-name
5068 Generates file names that look like @samp{~/News/Alt.andrea-dworkin}.
5069 @item gnus-plain-save-name
5070 @findex gnus-plain-save-name
5071 Generates file names that look like @samp{~/News/alt.andrea-dworkin}.
5074 @vindex gnus-use-long-file-name
5075 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
5076 @code{nil}, all the preceding functions will replace all periods
5077 (@samp{.}) in the group names with slashes (@samp{/}) - which means that
5078 the functions will generate hierarchies of directories instead of having
5079 all the files in the toplevel directory
5080 (@samp{~/News/alt/andrea-dworkin} instead of
5081 @samp{~/News/alt.andrea-dworkin}.)
5083 This function also affects kill and score file names. If this variable
5084 is a list, and the list contains the element @code{not-score}, long file
5085 names will not be used for score files, if it contains the element
5086 @code{not-save}, long file names will not be used for saving, and if it
5087 contains the element @code{not-kill}, long file names will not be used
5090 If you'd like to save articles in a hierarchy that looks something like
5094 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
5095 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
5098 Then just save with @kbd{o}. You'd then read this hierarchy with
5099 ephemeral @code{nneething} groups - @kbd{G D} in the group buffer, and
5100 the toplevel directory as the argument (@file{~/News/}). Then just walk
5101 around to the groups/directories with @code{nneething}.
5104 @node Decoding Articles
5105 @section Decoding Articles
5106 @cindex decoding articles
5108 Sometime users post articles (or series of articles) that have been
5109 encoded in some way or other. Gnus can decode them for you.
5112 * Uuencoded Articles:: Uudecode articles.
5113 * Shared Articles:: Unshar articles.
5114 * PostScript Files:: Split PostScript.
5115 * Decoding Variables:: Variables for a happy decoding.
5116 * Viewing Files:: You want to look at the result of the decoding?
5119 All these functions use the process/prefix convention
5120 (@pxref{Process/Prefix}) for finding out what articles to work on, with
5121 the extension that a "single article" means "a single series". Gnus can
5122 find out by itself what articles belong to a series, decode all the
5123 articles and unpack/view/save the resulting file(s).
5125 Gnus guesses what articles are in the series according to the following
5126 simplish rule: The subjects must be (nearly) identical, except for the
5127 last two numbers of the line. (Spaces are largely ignored, however.)
5129 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
5130 will find all the articles that match the regexp @samp{^cat.gif
5131 ([0-9]+/[0-9]+).*$}.
5133 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
5134 series}, will not be properly recognized by any of the automatic viewing
5135 commands, and you have to mark the articles manually with @key{#}.
5137 @node Uuencoded Articles
5138 @subsection Uuencoded Articles
5140 @cindex uuencoded articles
5144 @kindex X u (Summary)
5145 @findex gnus-uu-decode-uu
5146 Uudecodes the current series (@code{gnus-uu-decode-uu}).
5148 @kindex X U (Summary)
5149 @findex gnus-uu-decode-uu-and-save
5150 Uudecodes and saves the current series
5151 (@code{gnus-uu-decode-uu-and-save}).
5153 @kindex X v u (Summary)
5154 @findex gnus-uu-decode-uu-view
5155 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
5157 @kindex X v U (Summary)
5158 @findex gnus-uu-decode-uu-and-save-view
5159 Uudecodes, views and saves the current series
5160 (@code{gnus-uu-decode-uu-and-save-view}).
5163 Remember that these all react to the presence of articles marked with
5164 the process mark. If, for instance, you'd like to uncode and save an
5165 entire newsgroup, you'd typically do @kbd{M P a}
5166 (@code{gnus-uu-mark-all}) and then @kbd{X U}
5167 (@code{gnus-uu-decode-uu-and-save}).
5169 All this is very much different from how @code{gnus-uu} worked with
5170 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
5171 the sun. This version of @code{gnus-uu} generally assumes that you mark
5172 articles in some way (@pxref{Setting Process Marks}) and then press
5175 Note: When trying to decode articles that have names matching
5176 @code{gnus-uu-notify-files}, which is hard-coded to
5177 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
5178 automatically post an article on @samp{comp.unix.wizards} saying that
5179 you have just viewed the file in question. This feature can't be turned
5182 @node Shared Articles
5183 @subsection Shared Articles
5185 @cindex shared articles
5189 @kindex X s (Summary)
5190 @findex gnus-uu-decode-unshar
5191 Unshars the current series (@code{gnus-uu-decode-unshar}).
5193 @kindex X S (Summary)
5194 @findex gnus-uu-decode-unshar-and-save
5195 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
5197 @kindex X v s (Summary)
5198 @findex gnus-uu-decode-unshar-view
5199 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
5201 @kindex X v S (Summary)
5202 @findex gnus-uu-decode-unshar-and-save-view
5203 Unshars, views and saves the current series
5204 (@code{gnus-uu-decode-unshar-and-save-view}).
5207 @node PostScript Files
5208 @subsection PostScript Files
5213 @kindex X p (Summary)
5214 @findex gnus-uu-decode-postscript
5215 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
5217 @kindex X P (Summary)
5218 @findex gnus-uu-decode-postscript-and-save
5219 Unpack and save the current PostScript series
5220 (@code{gnus-uu-decode-postscript-and-save}).
5222 @kindex X v p (Summary)
5223 @findex gnus-uu-decode-postscript-view
5224 View the current PostScript series
5225 (@code{gnus-uu-decode-postscript-view}).
5227 @kindex X v P (Summary)
5228 @findex gnus-uu-decode-postscript-and-save-view
5229 View and save the current PostScript series
5230 (@code{gnus-uu-decode-postscript-and-save-view}).
5233 @node Decoding Variables
5234 @subsection Decoding Variables
5236 Adjective, not verb.
5239 * Rule Variables:: Variables that say how a file is to be viewed.
5240 * Other Decode Variables:: Other decode variables.
5241 * Uuencoding & Posting:: Variables for customizing uuencoding.
5244 @node Rule Variables
5245 @subsubsection Rule Variables
5246 @cindex rule variables
5248 Gnus uses @dfn{rule variables} to decide how to view a file. All these
5249 variables are on the form
5252 (list '(regexp1 command2)
5258 @item gnus-uu-user-view-rules
5259 @vindex gnus-uu-user-view-rules
5260 This variable is consulted first when viewing files. If you wish to use,
5261 for instance, @code{sox} to convert an @samp{.au} sound file, you could
5264 (setq gnus-uu-user-view-rules
5265 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
5267 @item gnus-uu-user-view-rules-end
5268 @vindex gnus-uu-user-view-rules-end
5269 This variable is consulted if Gnus couldn't make any matches from the
5270 user and default view rules.
5271 @item gnus-uu-user-archive-rules
5272 @vindex gnus-uu-user-archive-rules
5273 This variable can be used to say what commands should be used to unpack
5277 @node Other Decode Variables
5278 @subsubsection Other Decode Variables
5281 @item gnus-uu-ignore-files-by-name
5282 @vindex gnus-uu-ignore-files-by-name
5283 Files with name matching this regular expression won't be viewed.
5285 @item gnus-uu-ignore-files-by-type
5286 @vindex gnus-uu-ignore-files-by-type
5287 Files with a @sc{mime} type matching this variable won't be viewed.
5288 Note that Gnus tries to guess what type the file is based on the name.
5289 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
5292 @item gnus-uu-tmp-dir
5293 @vindex gnus-uu-tmp-dir
5294 Where @code{gnus-uu} does its work.
5296 @item gnus-uu-do-not-unpack-archives
5297 @vindex gnus-uu-do-not-unpack-archives
5298 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
5299 looking for files to display.
5301 @item gnus-uu-view-and-save
5302 @vindex gnus-uu-view-and-save
5303 Non-@code{nil} means that the user will always be asked to save a file
5306 @item gnus-uu-ignore-default-view-rules
5307 @vindex gnus-uu-ignore-default-view-rules
5308 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
5311 @item gnus-uu-ignore-default-archive-rules
5312 @vindex gnus-uu-ignore-default-archive-rules
5313 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
5316 @item gnus-uu-kill-carriage-return
5317 @vindex gnus-uu-kill-carriage-return
5318 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
5321 @item gnus-uu-unmark-articles-not-decoded
5322 @vindex gnus-uu-unmark-articles-not-decoded
5323 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
5324 unsuccessfully decoded as unread.
5326 @item gnus-uu-correct-stripped-uucode
5327 @vindex gnus-uu-correct-stripped-uucode
5328 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
5329 uuencoded files that have had trailing spaces deleted.
5331 @item gnus-uu-view-with-metamail
5332 @vindex gnus-uu-view-with-metamail
5333 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
5334 commands defined by the rule variables and just fudge a @sc{mime}
5335 content type based on the file name. The result will be fed to
5336 @code{metamail} for viewing.
5338 @item gnus-uu-save-in-digest
5339 @vindex gnus-uu-save-in-digest
5340 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
5341 decoding, will save in digests. If this variable is @code{nil},
5342 @code{gnus-uu} will just save everything in a file without any
5343 embellishments. The digesting almost conforms to RFC1153 - no easy way
5344 to specify any meaningful volume and issue numbers were found, so I
5345 simply dropped them.
5349 @node Uuencoding & Posting
5350 @subsubsection Uuencoding & Posting
5354 @item gnus-uu-post-include-before-composing
5355 @vindex gnus-uu-post-include-before-composing
5356 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
5357 before you compose the article. If this variable is @code{t}, you can
5358 either include an encoded file with @key{C-c C-i} or have one included
5359 for you when you post the article.
5361 @item gnus-uu-post-length
5362 @vindex gnus-uu-post-length
5363 Maximum length of an article. The encoded file will be split into how
5364 many articles it takes to post the entire file.
5366 @item gnus-uu-post-threaded
5367 @vindex gnus-uu-post-threaded
5368 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
5369 thread. This may not be smart, as no other decoder I have seen are able
5370 to follow threads when collecting uuencoded articles. (Well, I have
5371 seen one package that does that - @code{gnus-uu}, but somehow, I don't
5372 think that counts...) Default is @code{nil}.
5374 @item gnus-uu-post-separate-description
5375 @vindex gnus-uu-post-separate-description
5376 Non-@code{nil} means that the description will be posted in a separate
5377 article. The first article will typically be numbered (0/x). If this
5378 variable is @code{nil}, the description the user enters will be included
5379 at the beginning of the first article, which will be numbered (1/x).
5380 Default is @code{t}.
5385 @subsection Viewing Files
5386 @cindex viewing files
5387 @cindex pseudo-articles
5389 After decoding, if the file is some sort of archive, Gnus will attempt
5390 to unpack the archive and see if any of the files in the archive can be
5391 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
5392 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
5393 uncompress and detar the main file, and then view the two pictures.
5394 This unpacking process is recursive, so if the archive contains archives
5395 of archives, it'll all be unpacked.
5397 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
5398 extracted file into the summary buffer. If you go to these "articles",
5399 you will be prompted for a command to run (usually Gnus will make a
5400 suggestion), and then the command will be run.
5402 @vindex gnus-view-pseudo-asynchronously
5403 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
5404 until the viewing is done before proceeding.
5406 @vindex gnus-view-pseudos
5407 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
5408 the pseudo-articles into the summary buffer, but view them
5409 immediately. If this variable is @code{not-confirm}, the user won't even
5410 be asked for a confirmation before viewing is done.
5412 @vindex gnus-view-pseudos-separately
5413 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
5414 pseudo-article will be created for each file to be viewed. If
5415 @code{nil}, all files that use the same viewing command will be given as
5416 a list of parameters to that command.
5418 So; there you are, reading your @emph{pseudo-articles} in your
5419 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
5420 Why isn't anything real anymore? How did we get here?
5423 @node Article Treatment
5424 @section Article Treatment
5426 Reading through this huge manual, you may have quite forgotten that the
5427 object of newsreaders are to actually, like, read what people have
5428 written. Reading articles. Unfortunately, people are quite bad at
5429 writing, so there are tons of functions and variables to make reading
5430 these articles easier.
5433 * Article Highlighting:: You want to make the article look like fruit salad.
5434 * Article Hiding:: You also want to make certain info go away.
5435 * Article Mangling:: Lots of way-neat functions to make life better.
5436 * Article Date:: Grumble, UT!
5440 @node Article Highlighing
5441 @subsection Article Highlighting
5444 Not only do you want your article buffer to look like fruit salad, but
5445 you want it to look like techicolor fruit salad.
5451 @findex gnus-article-highlight
5452 Highlight the current article (@code{gnus-article-highlight}).
5456 @findex gnus-article-highlight-headers
5457 @vindex gnus-header-face-alist
5458 Highlight the headers (@code{gnus-article-highlight-headers}). The
5459 highlighting will be done according to the @code{gnus-header-face-alist}
5460 variable, which is a list where each element has the form @var{(regexp
5461 name content)}. @var{regexp} is a regular expression for matching the
5462 header, @var{name} is the face used for highling the header name and
5463 @var{content} is the face for highlighting the header value. The first
5464 match made will be used.
5468 @findex gnus-article-highlight-citation
5469 Highlight cited text (@code{gnus-article-highlight-citation}).
5471 Some variables to customize the citation highlights:
5474 @vindex gnus-cite-parse-max-size
5475 @item gnus-cite-parse-max-size
5476 If the article size if bigger than this variable (which is 25000 by
5477 default), no citation highlighting will be performed.
5479 @item gnus-cite-prefix-regexp
5480 @vindex gnus-cite-prefix-regexp
5481 Regexp mathcing the longest possible citation prefix on a line.
5483 @item gnus-cite-max-prefix
5484 @vindex gnus-cite-max-prefix
5485 Maximum possible length for a citation prefix (default 20).
5487 @item gnus-supercite-regexp
5488 @vindex gnus-supercite-regexp
5489 Regexp matching normal SuperCite attribution lines.
5491 @item gnus-supercite-secondary-regexp
5492 @vindex gnus-supercite-secondary-regexp
5493 Regexp matching mangled SuperCite attribution lines.
5495 @item gnus-cite-minimum-match-count
5496 @vindex gnus-cite-minimum-match-count
5497 Minimum number of identical prefixes we have to see before we believe
5498 that it's a citation.
5500 @item gnus-cire-attribution-prefix
5501 @vindex gnus-cire-attribution-prefix
5502 Regexp matching the beginning of an attribution line.
5504 @item gnus-cite-addtribution-suffix
5505 @vindex gnus-cite-addtribution-suffix
5506 Regexp matching the end of an attribution line.
5508 @item gnus-cite-attribution-face
5509 @vindex gnus-cite-attribution-face
5510 Face used for attribution lines. It is merged with the face for the
5511 cited text belonging to the attribution.
5518 @vindex gnus-signature-separator
5519 @findex gnus-article-highlight-signature
5520 Highlight the signature (@code{gnus-article-highlight-signature}).
5521 Everything after @code{gnus-signature-separator} in an article will be
5522 considered a signature.
5527 @node Article Hiding
5529 Or rather, hiding certain things in each article. There usually is much
5530 to much gruft in most articles.
5535 @kindex W W a (Summary)
5536 @findex gnus-article-hide
5537 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
5540 @kindex W W h (Summary)
5541 @findex gnus-article-hide-headers
5542 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
5546 @kindex W W s (Summary)
5547 @findex gnus-article-hide-signature
5548 Hide signature (@code{gnus-article-hide-signature}).
5551 @kindex W W c (Summary)
5552 @findex gnus-article-hide-citation
5553 Hide citation (@code{gnus-article-hide-citation}). Two variables for
5554 customizing the hiding:
5558 @item gnus-cite-hide-percentage
5559 @vindex gnus-cite-hide-percentage
5560 If the cited text is of a bigger percentage than this variable (default
5561 50), hide the cited text.
5563 @item gnus-cite-hide-absolute
5564 @vindex gnus-cite-hide-absolute
5565 The cited text must be have at least this length (default 10) before it
5570 Also see @xref{Article Highlighting} for further variables for
5571 citation customization.
5578 @node Article Washing
5579 @section Article Washin
5581 We call this "article washing" for a really good reason. Namely, the
5582 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
5584 @dfn{Washing} is defined by us as "changing something from something to
5585 something else", but normally results in something looking better.
5591 @kindex W l (Summary)
5592 @findex gnus-summary-stop-page-breaking
5593 Remove page breaks from the current article
5594 (@code{gnus-summary-stop-page-breaking}).
5597 @kindex W r (Summary)
5598 @findex gnus-summary-caesar-message
5599 Do a Caesar rotate (rot13) on the article buffer
5600 (@code{gnus-summary-caesar-message}).
5603 @kindex A g (Summary)
5604 @findex gnus-summary-show-article
5605 (Re)fetch the current article (@code{gnus-summary-show-article}). If
5606 given a prefix, don't actually refetch any articles, just jump to the
5607 current article and configure the windows to display the current
5611 @kindex W t (Summary)
5612 @findex gnus-summary-toggle-header
5613 Toggle whether to display all headers in the article buffer
5614 (@code{gnus-summary-toggle-header}).
5617 @kindex W m (Summary)
5618 @findex gnus-summary-toggle-mime
5619 Toggle whether to run the article through @sc{mime} before displaying
5620 (@code{gnus-summary-toggle-mime}).
5623 @kindex W o (Summary)
5624 @findex gnus-article-treat-overstrike
5625 Treat overstrike (@code{gnus-article-treat-overstrike}).
5628 @kindex W w (Summary)
5629 @findex gnus-article-word-wrap
5630 Do word wrap (@code{gnus-article-word-wrap}).
5633 @kindex W c (Summary)
5634 @findex gnus-article-remove-cr
5635 Remove CR (@code{gnus-article-remove-cr}).
5638 @kindex W q (Summary)
5639 @findex gnus-article-de-quoted-unreadable
5640 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
5643 @kindex W f (Summary)
5645 @findex gnus-article-display-x-face
5646 @findex gnus-article-x-face-command
5647 @vindex gnus-article-x-face-command
5648 @vindex gnus-article-x-face-too-ugly
5649 Look for and display any X-Face headers
5650 (@code{gnus-article-display-x-face}). The command executed by this
5651 function is given by the @code{gnus-article-x-face-command} variable. If
5652 this variable is a string, this string will be executed in a sub-shell.
5653 If it is a function, this function will be called with the face as the
5654 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
5655 matches the @code{From} header, the face will not be shown.
5660 @section Article Date
5662 The date is most likely generated in some obscure timezone you've never
5663 heard of, so it's quite nice to be able to find out what the time was
5664 when the article was sent.
5669 @kindex W T u (Summary)
5670 @findex gnus-article-date-ut
5671 Display the date in UT (aka. GMT, aka ZULU)
5672 (@code{gnus-article-date-ut}).
5675 @kindex W T l (Summary)
5676 @findex gnus-article-date-local
5677 Display the date in the local timezone (@code{gnus-article-date-local}).
5680 @kindex W T e (Summary)
5681 @findex gnus-article-date-lapsed
5682 Say how much time has (e)lapsed between the article was posted and now
5683 (@code{gnus-article-date-lapsed}).
5686 @item W T o (Summary)
5687 @findex gnus-article-date-original
5688 Display the original date (@code{gnus-article-date-original}). This can
5689 be useful if you normally use some other conversion function and is
5690 worried that it might be doing something totally wrong. Say, claiming
5691 that the article was posted in 1854. Although something like that is
5692 @emph{totally} impossible. Don't you trust me? *titter*
5697 @node Summary Sorting
5698 @section Summary Sorting
5699 @cindex summary sorting
5701 You can have the summary buffer sorted in various ways, even though I
5702 can't really see why you'd want that.
5706 @kindex C-c C-s C-n (Summary)
5707 @findex gnus-summary-sort-by-number
5708 Sort by article number (@code{gnus-summary-sort-by-number}).
5710 @kindex C-c C-s C-a (Summary)
5711 @findex gnus-summary-sort-by-author
5712 Sort by author (@code{gnus-summary-sort-by-author}).
5714 @kindex C-c C-s C-s (Summary)
5715 @findex gnus-summary-sort-by-subject
5716 Sort by subject (@code{gnus-summary-sort-by-subject}).
5718 @kindex C-c C-s C-d (Summary)
5719 @findex gnus-summary-sort-by-date
5720 Sort by date (@code{gnus-summary-sort-by-date}).
5722 @kindex C-c C-s C-i (Summary)
5723 @findex gnus-summary-sort-by-score
5724 Sort by score (@code{gnus-summary-sort-by-score}).
5727 These functions will work both when you use threading and when you don't
5728 use threading. In the latter case, all summary lines will be sorted,
5729 line by line. In the former case, sorting will be done on a
5730 root-by-root basis, which might not be what you were looking for. To
5731 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
5735 @node Finding the Parent
5736 @section Finding the Parent
5737 @cindex parent articles
5738 @cindex referring articles
5740 @findex gnus-summary-refer-parent-article
5742 If you'd like to read the parent of the current article, and it is not
5743 displayed in the article buffer, you might still be able to. That is,
5744 if the current group is fetched by @sc{nntp}, the parent hasn't expired
5745 and the @code{References} in the current article are not mangled, you
5746 can just press @kbd{^} or @kbd{A r}
5747 (@code{gnus-summary-refer-parent-article}). If everything goes well,
5748 you'll get the parent. If the parent is already displayed in the
5749 summary buffer, point will just move to this article.
5751 @findex gnus-summary-refer-references
5752 @kindex A R (Summary)
5753 You can have Gnus fetch all articles mentioned in the @code{References}
5754 header of the article by pushing @kbd{A R}
5755 (code{gnus-summary-refer-references}).
5757 @findex gnus-summary-refer-article
5758 @kindex M-^ (Summary)
5759 You can also ask the @sc{nntp} server for an arbitrary article, no
5760 matter what group it belongs to. @kbd{M-^}
5761 (@code{gnus-summary-refer-article}) will ask you for a
5762 @code{Message-Id}, which is one of those long thingies that look
5763 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
5764 it all exactly right. No fuzzy searches, I'm afraid.
5766 @vindex gnus-refer-article-method
5767 If the group you are reading is located on a backend that does not
5768 support fetching by @code{Message-Id} very well (like @code{nnspool}),
5769 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
5770 would, perhaps, be best if the @sc{nntp} server you consult is the same
5771 as the one that keeps the spool you are reading from updated, but that's
5772 not really necessary.
5774 Most of the mail backends support fetching by @code{Message-ID}, but do
5775 not do a particularly excellent job of it. That is, @code{nnmbox} and
5776 @code{nnbabyl} are able to locate articles from any groups, while
5777 @code{nnml} and @code{nnfolder} are only able to locate articles that
5778 have been posted to the current group. (Anything else would be too time
5779 consuming.) @code{nnmh} does not support this at all.
5782 @section Score Files
5785 Other people use @dfn{kill files}, but we here at Gnus Towers like
5786 scoring better than killing, so we'd rather switch than fight. They do
5787 something completely different as well, so sit up straight and pay
5790 @vindex gnus-summary-mark-below
5791 All articles have a default score (@code{gnus-summary-default-score}).
5792 This score may be raised or lowered either interactively or by score
5793 files. Articles that have a score lower than
5794 @code{gnus-summary-mark-below} are marked as read.
5796 Gnus will read any @dfn{score files} that apply to the current group
5797 before generating the summary buffer.
5799 There are several commands in the summary buffer that insert score
5800 entries based on the current article. You can, for instance, ask Gnus to
5801 lower or increase the score of all articles with a certain subject.
5803 There are two sorts of scoring entries: Permanent and temporary.
5804 Temporary score entries are self-expiring entries. Any entries that are
5805 temporary and have not been used for, say, a week, will be removed
5806 silently to help keep the sizes of the score files down.
5809 * Summary Score Commands:: Adding score commands to the score file.
5810 * Score Variables:: Customize your scoring. (My, what terminology).
5811 * Score File Format:: What a score file may contain.
5812 * Score File Editing:: You can edit score files by hand as well.
5813 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
5814 * Scoring Tips:: How to score effectively.
5815 * Reverse Scoring:: That problem child of old is not problem.
5816 * Global Score Files:: Earth-spanning, ear-splitting score files.
5817 * Kill Files:: They are still here, but they can be ignored.
5820 @node Summary Score Commands
5821 @subsection Summary Score Commands
5822 @cindex score commands
5824 The score commands that alter score entries do not actually modify real
5825 score files. That would be too inefficient. Gnus maintains a cache of
5826 previously loaded score files, one of which is considered the
5827 @dfn{current score file alist}. The score commands simply insert
5828 entries into this list, and upon group exit, this list is saved.
5830 The current score file is by default the group's local score file, even
5831 if no such score file actually exists. To insert score commands into
5832 some other score file (eg. @file{all.SCORE}), you must first make this
5833 score file the current one.
5835 General score commands that don't actually change the score file:
5839 @kindex V s (Summary)
5840 @findex gnus-summary-set-score
5841 Set the score of the current article (@code{gnus-summary-set-score}).
5843 @kindex V S (Summary)
5844 @findex gnus-summary-current-score
5845 Display the score of the current article
5846 (@code{gnus-summary-current-score}).
5848 @kindex V t (Summary)
5849 @findex gnus-score-find-trace
5850 Display all score rules that have been used on the current article
5851 (@code{gnus-score-find-trace}).
5853 @kindex V a (Summary)
5854 @findex gnus-summary-score-entry
5855 Add a new score entry, and allow specifying all elements
5856 (@code{gnus-summary-score-entry}).
5858 @kindex V c (Summary)
5859 @findex gnus-score-change-score-file
5860 Make a different score file the current
5861 (@code{gnus-score-change-score-file}).
5863 @kindex V e (Summary)
5864 @findex gnus-score-edit-alist
5865 Edit the current score file (@code{gnus-score-edit-alist}). You will be
5866 popped into a @code{gnus-score-mode} buffer (@pxref{Score File
5869 @kindex V f (Summary)
5870 @findex gnus-score-edit-file
5871 Edit a score file and make this score file the current one
5872 (@code{gnus-score-edit-file}).
5874 @kindex I C-i (Summary)
5875 @findex gnus-summary-raise-score
5876 Increase the score of the current article
5877 (@code{gnus-summary-raise-score}).
5879 @kindex L C-l (Summary)
5880 @findex gnus-summary-lower-score
5881 Lower the score of the current article
5882 (@code{gnus-summary-lower-score}).
5885 The rest of these commands modify the local score file.
5889 @kindex V m (Summary)
5890 @findex gnus-score-set-mark-below
5891 Prompt for a score, and mark all articles with a score below this as
5892 read (@code{gnus-score-set-mark-below}).
5894 @kindex V E (Summary)
5895 @findex gnus-score-set-expunge-below
5896 Expunge all articles with a score below the default score (or the
5897 numeric prefix) (@code{gnus-score-set-expunge-below}).
5900 The keystrokes for actually making score entries follow a very regular
5901 pattern, so there's no need to list all the commands. (Hundreds of
5906 The first key is either @kbd{I} (upper case i) for increasing the score
5907 or @kbd{L} for lowering the score.
5909 The second key says what header you want to score on. The following
5913 Score on the author name.
5915 Score on the subject line.
5917 Score on the Xref line - i.e., the cross-posting line.
5919 Score on thread - the References line.
5923 Score on the number of lines.
5925 Score on the Message-ID.
5935 The third key is the match type. Which match types are legal depends on
5936 what headers you are scoring on.
5969 Greater than number.
5974 The fourth and final key says whether this is a temporary (i.e., expiring)
5975 score entry, or a permanent (i.e., non-expiring) score entry, or whether
5976 it is to be done immediately, without adding to the score file.
5979 Temporary score entry.
5981 Permanent score entry.
5983 Immediately scoring.
5988 So, let's say you want to increase the score on the current author with
5989 exact matching permanently: @kbd{I a e p}. If you want to lower the
5990 score based on the subject line, using substring matching, and make a
5991 temporary score entry: @kbd{L s s t}. Pretty easy.
5993 To make things a bit more complicated, there are shortcuts. If you use
5994 a capital letter on either the second or third keys, Gnus will use
5995 defaults for the remaining one or two keystrokes. The defaults are
5996 "substring" and "temporary". So @kbd{I A} is the same as @kbd{I a s t},
5997 and @kbd{I a R} is the same as @kbd{I a r t}.
5999 @vindex gnus-score-mimic-keymap
6000 The @code{gnus-score-mimic-keymap} says whether these commands will
6001 pretend they are keymaps or not.
6003 @node Score Variables
6004 @subsection Score Variables
6005 @cindex score variables
6008 @item gnus-use-scoring
6009 @vindex gnus-use-scoring
6010 If @code{nil}, Gnus will not check for score files, and will not, in
6011 general, do any score-related work.
6012 @item gnus-kill-killed
6013 @vindex gnus-kill-killed
6014 If this variable is @code{nil}, Gnus will never apply score files to
6015 articles that have already been through the kill process. While this
6016 may save you lots of time, it also means that if you apply a kill file
6017 to a group, and then change the kill file and want to run it over you
6018 group again to kill more articles, it won't work. You have to set this
6019 variable to @code{t} to do that.
6020 @item gnus-kill-files-directory
6021 @vindex gnus-kill-files-directory
6022 All kill and score files will be stored in this directory, which is
6023 initialized from the @samp{SAVEDIR} environment variable by default.
6024 @item gnus-score-file-suffix
6025 @vindex gnus-score-file-suffix
6026 Suffix to add to the group name to arrive at the score file name
6027 (@samp{SCORE} by default.)
6028 @item gnus-score-interactive-default-score
6029 @vindex gnus-score-interactive-default-score
6030 Score used by all the interactive raise/lower commands to raise/lower
6031 score with. Default is 1000, which may seem excessive, but this is to
6032 ensure that the adaptive scoring scheme gets enough room to play with.
6033 We don't want the small changes from the adaptive scoring to overwrite
6034 manually entered data.
6035 @item gnus-summary-default-score
6036 @vindex gnus-summary-default-score
6037 Default score of an article, which is 0 by default.
6038 @item gnus-score-over-mark
6039 @vindex gnus-score-over-mark
6040 Mark (in the third column) used for articles with a score over the
6041 default. Default is @samp{+}.
6042 @item gnus-score-below-mark
6043 @vindex gnus-score-below-mark
6044 Mark (in the third column) used for articles with a score below the
6045 default. Default is @samp{-}.
6046 @item gnus-score-find-score-files-function
6047 @vindex gnus-score-find-score-files-function
6048 Function used to find score files for the current group. This function
6049 is called with the name of the group as the argument.
6051 Predefined functions available are:
6054 @item gnus-score-find-single
6055 @findex gnus-score-find-single
6056 Only apply the group's own score file.
6058 @item gnus-score-find-bnews
6059 @findex gnus-score-find-bnews
6060 Apply all score files that match, using bnews syntax. For instance, if
6061 the current group is @samp{gnu.emacs.gnus}, @samp{all.emacs.all.SCORE},
6062 @samp{not.alt.all.SCORE} and @samp{gnu.all.SCORE} would all apply. In
6063 short, the instances of @samp{all} in the score file names are
6064 translated into @samp{.*}, and then a regexp match is done.
6066 If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
6067 very will. It will find stuff like @file{gnu/all/SCORE}, but will not
6068 find files like @file{not/gnu/all/SCORE}.
6070 @item gnus-score-find-hierarchical
6071 @findex gnus-score-find-hierarchical
6072 Apply all score files from all the parent groups.
6074 This variable can also be a list of functions. In that case, all these
6075 functions will be called, and all the returned lists of score files will
6076 be applied. These functions can also return lists of score alists
6077 directly. In that case, the functions that return these non-file score
6078 alists should probably be placed before the "real" score file functions,
6079 to ensure that the last score file returned is the local score file.
6081 @item gnus-score-expiry-days
6082 @vindex gnus-score-expiry-days
6083 This variable says how many days should pass before an unused score file
6084 entry is expired. The default is 7.
6087 @node Score File Format
6088 @subsection Score File Format
6089 @cindex score file format
6091 A score file is an @code{emacs-lisp} file that normally contains just a
6092 single form. Casual users are not expected to edit these files;
6093 everything can be changed from the summary buffer.
6095 Anyway, if you'd like to dig into it yourself, here's an example:
6099 ("Lars Ingebrigtsen" -10000)
6101 ("larsi\\|lmi" -50000 nil R))
6103 ("Ding is Badd" nil 728373))
6105 ("alt.politics" -1000 728372 s))
6110 (mark-and-expunge -10)
6114 (files "/hom/larsi/News/gnu.SCORE")
6115 (local (gnus-newsgroup-auto-expire t)
6116 (gnus-summary-make-false-root 'empty))
6120 This example demonstrates absolutely everything about a score file.
6122 Even though this looks much like lisp code, nothing here is actually
6123 @code{eval}ed. The lisp reader is used to read this form, though, so it
6124 has to be legal syntactically, if not semantically.
6126 Six keys are supported by this alist:
6130 If the key is a string, it is the name of the header to perform the
6131 match on. Scoring can only be performed on these eight headers:
6132 @samp{From}, @samp{Subject}, @samp{References}, @samp{Message-ID},
6133 @samp{Xref}, @samp{Lines}, @samp{Chars} and @samp{Date}. In addition to
6134 these headers, there are three strings to tell Gnus to fetch the entire
6135 article and do the match on larger parts of the article: @samp{Body}
6136 will perform the match on the body of the article, @samp{Head} will
6137 perform the match on the head of the article, and @samp{All} will
6138 perform the match on the entire article. Note that using any of these
6139 last three keys will slow down group entry @emph{considerably}.
6141 Following this key is a random number of score entries, where each score
6142 entry has one to four elements.
6145 The first element is the @dfn{match element}. On most headers this will
6146 be a string, but on the Lines and Chars headers, this must be an
6149 If the second element is present, it should be a number - the @dfn{score
6150 element}. This number should be an integer in the neginf to posinf
6151 interval. This number is added to the score of the article if the match
6152 is successful. If this element is not present, the
6153 @code{gnus-score-interactive-default-score} number will be used instead.
6155 If the third element is present, it should be a number - the @dfn{date
6156 element}. This date says when the last time this score entry matched,
6157 which provides a mechanism for expiring the score entries. It this
6158 element is not present, the score entry is permanent. The date is
6159 represented by the number of days since December 31, 1 ce.
6161 If the fourth element is present, it should be a symbol - the @dfn{type
6162 element}. This element specifies what function should be used to see
6163 whether this score entry matches the article. What match types that can
6164 be used depends on what header you wish to perform the match on.
6166 @item From, Subject, References, Xref, Message-ID
6167 For most header types, there are the @code{r} and @code{R} (regexp) as
6168 well as @code{s} and @code{S} (substring) types and @code{e} and
6169 @code{E} (exact match) types. If this element is not present, Gnus will
6170 assume that substring matching should be used. @code{R} and @code{S}
6171 differ from the other two in that the matches will be done in a
6172 case-sensitive manner. All these one-letter types are really just
6173 abbreviations for the @code{regexp}, @code{string} and @code{exact}
6174 types, which you can use instead, if you feel like.
6176 These two headers use different match types: @code{<}, @code{>},
6177 @code{=}, @code{>=} and @code{<=}.
6179 For the Date header we have three match types: @code{before}, @code{at}
6180 and @code{after}. I can't really imagine this ever being useful, but,
6181 like, it would feel kinda silly not to provide this function. Just in
6182 case. You never know. Better safe than sorry. Once burnt, twice shy.
6183 Don't judge a book by its cover. Never not have sex on a first date.
6184 @item Head, Body, All
6185 These three match keys use the same match types as the @code{From} (etc)
6188 This match key will add a score entry on all articles that followup to
6189 some author. Uses the same match types as the @code{From} header uses.
6194 The value of this entry should be a number. Any articles with a score
6195 lower than this number will be marked as read.
6197 The value of this entry should be a number. Any articles with a score
6198 lower than this number will be removed from the summary buffer.
6199 @item mark-and-expunge
6200 The value of this entry should be a number. Any articles with a score
6201 lower than this number will be marked as read and removed from the
6204 The value of this entry should be any number of file names. These files
6205 are assumed to be score files as well, and will be loaded the same way
6208 The clue of this entry should be any number of files. This files will
6209 not be loaded, even though they would normally be so, for some reason or
6212 The value of this entry will be @code{eval}el. This element will be
6213 ignored when handling global score files.
6215 Read-only score files will not be updated or saved. Global score files
6216 should feature this atom (@pxref{Global Score Files}).
6218 The value of this entry should be a number. Articles that do not have
6219 parents will get this number added to their scores.
6221 This entry controls the adaptive scoring. If it is @code{t}, the
6222 default adaptive scoring rules will be used. If it is @code{ignore}, no
6223 adaptive scoring will be performed on this group. If it is a list, this
6224 list will be used as the adaptive scoring rules. If it isn't present,
6225 or is something other than @code{t} or @code{ignore}, the default
6226 adaptive scoring rules will be used. If you want to use adaptive
6227 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
6228 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
6229 not want adaptive scoring. If you only want adaptive scoring in a few
6230 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
6231 insert @code{(adapt t)} in the score files of the groups where you want
6234 @cindex local variables
6235 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
6236 Each @var{var} will be made buffer-local to the current summary buffer,
6237 and set to the value specified. This is a convenient, if somewhat
6238 strange, way of setting variables in some groups if you don't like hooks
6242 @node Score File Editing
6243 @subsection Score File Editing
6245 You normally enter all scoring commands from the summary buffer, but you
6246 might feel the urge to edit them by hand as well, so we've supplied you
6247 with a mode for that.
6249 It's simply a slightly customized @code{emacs-lisp} mode, with these
6250 additional commands:
6254 @kindex C-c C-c (Score)
6255 @findex gnus-score-edit-done
6256 Save the changes you have made and return to the summary buffer
6257 (@code{gnus-score-edit-done}).
6259 @kindex C-c C-d (Score)
6260 @findex gnus-score-edit-insert-date
6261 Insert the current date in numerical format
6262 (@code{gnus-score-edit-insert-date}). This is really the day number, if
6266 @node Adaptive Scoring
6267 @subsection Adaptive Scoring
6268 @cindex adaptive scoring
6270 If all this scoring is getting you down, Gnus has a way of making it all
6271 happen automatically - as if by magic. Or rather, as if by artificial
6272 stupidity, to be precise.
6274 @vindex gnus-use-adaptive-scoring
6275 When you read an article, or mark an article as read, or kill an
6276 article, you leave marks behind. On exit from the group, Gnus can sniff
6277 these marks and add score elements depending on what marks it finds.
6278 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
6281 @vindex gnus-default-adaptive-score-alist
6282 To give you complete control over the scoring process, you can customize
6283 the @code{gnus-default-adaptive-score-alist} variable. By default, it
6284 looks something like this:
6287 (defvar gnus-default-adaptive-score-alist
6288 '((gnus-unread-mark)
6289 (gnus-ticked-mark (from 4))
6290 (gnus-dormant-mark (from 5))
6291 (gnus-del-mark (from -4) (subject -1))
6292 (gnus-read-mark (from 4) (subject 2))
6293 (gnus-expirable-mark (from -1) (subject -1))
6294 (gnus-killed-mark (from -1) (subject -3))
6295 (gnus-kill-file-mark)
6296 (gnus-catchup-mark (from -1) (subject -1))))
6299 As you see, each element in this alist has a mark as a key (either a
6300 variable name or a "real" mark - a character). Following this key is a
6301 random number of header/score pairs.
6303 To take @code{gnus-del-mark} as an example - this alist says that all
6304 articles that have that mark (i.e., are marked with @samp{D}) will have a
6305 score entry added to lower based on the @code{From} header by -4, and
6306 lowered by @code{Subject} by -1. Change this to fit your prejudices.
6308 If you use this scheme, you should set @code{mark-below} to something
6309 small - like -300, perhaps, to avoid having small random changes result
6310 in articles getting marked as read.
6312 After using adaptive scoring for a week or so, Gnus should start to
6313 become properly trained and enhance the authors you like best, and kill
6314 the authors you like least, without you having to say so explicitly.
6316 You can control what groups the adaptive scoring is to be performed on
6317 by using the score files (@pxref{Score File Format}). This will also
6318 let you use different rules in different groups.
6320 @vindex gnus-adaptive-file-suffix
6321 The adaptive score entries will be put into a file where the name is the
6322 group name with @code{gnus-adaptive-file-suffix} appended.
6324 @vindex gnus-score-exact-adapt-limit
6325 When doing adaptive scoring, substring or fuzzy matching would probably
6326 give you the best results in most cases. However, if the header one
6327 matches is short, the possibility for false positives is great, so if
6328 the length of the match is less than
6329 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
6330 this variable is @code{nil}, exact matching will always be used to avoid
6334 @subsection Scoring Tips
6335 @cindex scoring tips
6339 If you want to lower the score of crossposts, the line to match on is
6340 the @code{Xref} header.
6342 ("xref" (" talk.politics.misc:" -1000))
6344 @item Multiple crossposts
6345 If you want to lower the score of articles that have been crossposted to
6346 more than, say, 3 groups:
6348 ("xref" (" +[^ ]+:[0-9]+ +[^ ]+:[0-9]+ +[^ ]+:[0-9]+" -1000 nil r))
6350 @item Matching on the body
6351 This is generally not a very good idea - it takes a very long time.
6352 Gnus actually has to fetch each individual article from the server. But
6353 you might want to anyway, I guess. Even though there are three match
6354 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
6355 and stick with it in each score file. If you use any two, each article
6356 will be fetched @emph{twice}. If you want to match a bit on the
6357 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
6359 @item Marking as read
6360 You will probably want to mark articles that has a score below a certain
6361 number as read. This is most easily achieved by putting the following
6362 in your @file{all.SCORE} file:
6366 You may also consider doing something similar with @code{expunge}.
6368 @item Negated charater classes
6369 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
6370 That will match newlines, which might lead to, well, The Unknown. Say
6371 @code{[^abcd\n]*} instead.
6374 @node Reverse Scoring
6375 @subsection Reverse Scoring
6376 @cindex reverse scoring
6378 If you want to keep just articles that have @samp{Sex with Emacs} in the
6379 subject header, and expunge all other articles, you could put something
6380 like this in your score file:
6384 ("Sex with Emacs" 2))
6389 So, you raise all articles that match @samp{Sex with Emacs} and mark the
6390 rest as read, and expunge them to boot.
6392 @node Global Score Files
6393 @subsection Global Score Files
6394 @cindex global score files
6396 Sure, other newsreaders have "global kill files". These are usually
6397 nothing more than a single kill file that applies to all groups, stored
6398 in the user's home directory. Bah! Puny, weak newsreaders!
6400 What I'm talking about here are Global Score Files. Score files from
6401 all over the world, from users everywhere, uniting all nations in one
6402 big, happy score file union! Ange-score! New and untested!
6404 @vindex gnus-global-score-files
6405 All you have to do to use other people's score files is to set the
6406 @code{gnus-global-score-files} variable. One entry for each score file,
6407 or each score file directory. Gnus will decide by itself what score
6408 files are applicable to which group.
6410 Say you want to use all score files in the
6411 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
6412 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
6415 (setq gnus-global-score-files
6416 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
6417 "/ftp@@ftp.some-where:/pub/score/"))
6420 @findex gnus-score-search-global-directories
6421 Simple, eh? Directory names must end with a @samp{/}. These
6422 directories are typically scanned only once during each Gnus session.
6423 If you feel the need to manually re-scan the remote directories, you can
6424 use the @code{gnus-score-search-global-directories} command.
6426 Note that, at present, using this option will slow down group entry
6427 somewhat. (That is - a lot.)
6429 If you want to start maintaining score files for other people to use,
6430 just put your score file up for anonymous ftp and announce it to the
6431 world. Become a retro-moderator! Participate in the retro-moderator
6432 wars sure to ensue, where retro-moderators battle it out for the
6433 sympathy of the people, luring them to use their score files on false
6434 premises! Yay! The net is saved!
6436 Here are some tips for the would-be retro-moderator, off the top of my
6441 Articles that are heavily crossposted are probably junk.
6443 To lower a single inappropriate article, lower by @code{Message-Id}.
6445 Particularly brilliant authors can be raised on a permanent basis.
6447 Authors that repeatedly post off-charter for the group can safely be
6448 lowered out of existence.
6450 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
6451 articles completely.
6453 Use expiring score entries to keep the size of the file down. You
6454 should probably have a long expiry period, though, as some sites keep
6455 old articles for a long time.
6458 ... I wonder whether other newsreaders will support global score files
6459 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
6460 Wave, xrn and 1stReader are bound to implement scoring. Should we start
6461 holding our breath yet?
6464 @subsection Kill Files
6467 Gnus still supports those pesky old kill files. In fact, the kill file
6468 entries can now be expiring, which is something I wrote before Per
6469 thought of doing score files, so I've left the code in there.
6471 In short, kill processing is a lot slower (and I do mean @emph{a lot})
6472 than score processing, so it might be a good idea to rewrite your kill
6473 files into score files.
6475 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
6476 forms into this file, which means that you can use kill files as some
6477 sort of primitive hook function to be run on group entry, even though
6478 that isn't a very good idea.
6480 XCNormal kill files look like this:
6483 (gnus-kill "From" "Lars Ingebrigtsen")
6484 (gnus-kill "Subject" "ding")
6488 This will mark every article written by me as read, and remove them from
6489 the summary buffer. Very useful, you'll agree.
6491 Other programs use a totally different kill file syntax. If Gnus
6492 encounters what looks like a @code{rn} kill file, it will take a stab at
6495 Two functions for editing a GNUS kill file:
6499 @kindex M-k (Summary)
6500 @findex gnus-summary-edit-local-kill
6501 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
6504 @kindex M-K (Summary)
6505 @findex gnus-summary-edit-global-kill
6506 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
6509 @vindex gnus-kill-file-name
6510 A kill file for the group @samp{soc.motss} is normally called
6511 @file{soc.motss.KILL}. The suffix appended to the group name to get
6512 this file name is detailed by the @code{gnus-kill-file-name} variable.
6513 The "global" kill file (not in the score file sense of "global", of
6514 course) is called just @file{KILL}.
6516 @vindex gnus-kill-save-kill-file
6517 If @code{gnus-kill-save-kill-file} is non-@code{nil}, Gnus will save the
6518 kill file after processing, which is necessary if you use expiring
6522 @node Mail Group Commands
6523 @section Mail Group Commands
6524 @cindex mail group commands
6526 Some commands only make sense in mail groups. If these commands are
6527 illegal in the current group, they will raise a hell and let you know.
6529 All these commands (except the expiry and edit commands) use the
6530 process/prefix convention (@pxref{Process/Prefix}).
6534 @kindex B e (Summary)
6535 @findex gnus-summary-expire-articles
6536 Expire all expirable articles in the group
6537 (@code{gnus-summary-expire-articles}).
6540 @kindex B M-C-e (Summary)
6541 @findex gnus-summary-expire-articles-now
6542 Expunge all the expirable articles in the group
6543 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
6544 articles that are eligeble for expiry in the current group will
6545 disappear forever into that big @file{/dev/null} in the sky.
6548 @kindex B DEL (Summary)
6549 @findex gnus-summary-delete-articles
6550 Delete the mail article. This is "delete" as in "delete it from your
6551 disk forever and ever, never to return again." Use with caution.
6552 (@code{gnus-summary-delete-article}).
6555 @kindex B m (Summary)
6557 @findex gnus-summary-move-article
6558 Move the article from one mail group to another
6559 (@code{gnus-summary-move-article}).
6562 @kindex B c (Summary)
6564 @findex gnus-summary-copy-article
6565 Copy the article from one group (mail group or not) to a mail group
6566 (@code{gnus-summary-copy-article}).
6569 @kindex B i (Summary)
6570 @findex gnus-summary-import-article
6571 Import a random file into the current mail newsgroup
6572 (@code{gnus-summary-import-article}). You will be prompted for a file
6573 name, a @code{From} header and a @code{Subject} header.
6575 Something similar can be done by just starting to compose a mail
6576 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
6577 @kbd{C-c C-p} instead. This will put the message you have just created
6578 into the current mail group.
6581 @kindex B r (Summary)
6582 @findex gnus-summary-respool-article
6583 Respool the mail article (@code{gnus-summary-move-article}).
6587 @kindex B w (Summary)
6589 @findex gnus-summary-edit-article
6590 @kindex C-c C-c (Article)
6591 Edit the current article (@code{gnus-summary-edit-article}). To finish
6592 editing and make the changes permanent, type @kbd{C-c C-c}
6593 (@kbd{gnus-summary-edit-article-done}).
6596 @kindex B q (Summary)
6597 @findex gnus-summary-fancy-query
6598 If you are using fancy splitting, this command will tell you where an
6599 article would go (@code{gnus-summary-fancy-query}).
6602 @node Various Summary Stuff
6603 @section Various Summary Stuff
6606 * Group Information:: Information oriented commands.
6607 * Searching for Articles:: Multiple article commands.
6608 * Really Various Summary Commands:: Those pesky non-conformant commands.
6611 @vindex gnus-summary-prepare-hook
6612 @code{gnus-summary-prepare-hook} is called after the summary buffer has
6613 been generated. You might use it to, for instance, highlight lines or
6614 modify the look of the buffer in some other ungodly manner. I don't
6617 @node Group Information
6618 @subsection Group Information
6622 @kindex H f (Summary)
6623 @findex gnus-summary-fetch-faq
6624 @vindex gnus-group-faq-directory
6625 Try to fetch the FAQ (list of frequently asked questions) for the
6626 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
6627 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
6628 on a remote machine. @code{ange-ftp} will be used for fetching the file.
6630 @kindex H d (Summary)
6631 @findex gnus-summary-describe-group
6632 Give a brief description of the current group
6633 (@code{gnus-summary-describe-group}). If given a prefix, force
6634 rereading the description from the server.
6636 @kindex H h (Summary)
6637 @findex gnus-summary-describe-briefly
6638 Give a very brief description of the most important summary keystrokes
6639 (@code{gnus-summary-describe-briefly}).
6641 @kindex H i (Summary)
6642 @findex gnus-info-find-node
6643 Go to the Gnus info node (@code{gnus-info-find-node}).
6646 @node Searching for Articles
6647 @subsection Searching for Articles
6651 @kindex M-s (Summary)
6652 @findex gnus-summary-search-article-forward
6653 Search through all subsequent articles for a regexp
6654 (@code{gnus-summary-search-article-forward}).
6656 @kindex M-r (Summary)
6657 @findex gnus-summary-search-article-backward
6658 Search through all previous articles for a regexp
6659 (@code{gnus-summary-search-article-backward}).
6662 @findex gnus-summary-execute-command
6663 This command will prompt you for a header field, a regular expression to
6664 match on this field, and a command to be executed if the match is made
6665 (@code{gnus-summary-execute-command}).
6667 @kindex M-& (Summary)
6668 @findex gnus-summary-universal-argument
6669 Perform any operation on all articles that have been marked with
6670 the process mark (@code{gnus-summary-universal-argument}).
6673 @node Really Various Summary Commands
6674 @subsection Really Various Summary Commands
6678 @kindex A D (Summary)
6679 @findex gnus-summary-enter-digest-group
6680 If the current article is a digest, you might use this command to enter
6681 you into a group based on the current digest to ease reading
6682 (@code{gnus-summary-enter-digest-group}).
6684 @kindex C-t (Summary)
6685 @findex gnus-summary-toggle-truncation
6686 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
6689 @findex gnus-summary-expand-window
6690 Expand the summary buffer window (@code{gnus-summary-expand-window}).
6691 If given a prefix, force an @code{article} window configuration.
6694 @node The Article Buffer
6695 @chapter The Article Buffer
6696 @cindex article buffer
6698 The articles are displayed in the article buffer, of which there is only
6699 one. All the summary buffer share the same article buffer.
6702 * Hiding Headers:: Deciding what headers should be displayed.
6703 * Using Mime:: Pushing articles through @sc{mime} before reading them.
6704 * Customizing Articles:: Tailoring the look of the articles.
6705 * Article Keymap:: Keystrokes available in the article buffer
6706 * Misc Article:: Other stuff.
6709 @node Hiding Headers
6710 @section Hiding Headers
6711 @cindex hiding headers
6712 @cindex deleting headers
6714 The top section of each article is the @dfn{head}. (The rest is the
6715 @dfn{body}, but you may have guessed that already.)
6717 @vindex gnus-show-all-headers
6718 There is a lot of useful information in the head: the name of the person
6719 who wrote the article, the date it was written and the subject of the
6720 article. That's well and nice, but there's also lots of information
6721 most people do not want to see - what systems the article has passed
6722 through before reaching you, the @code{Message-Id}, the
6723 @code{References}, etc. ad nauseum - and you'll probably want to get rid
6724 of some of those lines. If you want to keep all those lines in the
6725 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
6727 Gnus provides you with two variables for sifting headers:
6730 @item gnus-visible-headers
6731 @vindex gnus-visible-headers
6732 If this variable is non-@code{nil}, it should be a regular expression
6733 that says what headers you wish to keep in the article buffer. All
6734 headers that do not match this variable will be hidden.
6736 For instance, if you only want to see the name of the person who wrote
6737 the article and the subject, you'd say:
6740 (setq gnus-visible-headers "^From:\\|^Subject:")
6743 @item gnus-ignored-headers
6744 @vindex gnus-ignored-headers
6745 This variable is the reverse of @code{gnus-visible-headers}. If this
6746 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
6747 should be a regular expression that matches all lines that you want to
6748 hide. All lines that do not match this variable will remain visible.
6750 For instance, if you just want to get rid of the @code{References} line
6751 and the @code{Xref} line, you might say:
6754 (setq gnus-ignored-headers "^References:\\|^Xref:")
6757 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
6758 variable will have no effect.
6761 @vindex gnus-sorted-header-list
6762 Gnus can also sort the headers for you. (It does this by default.) You
6763 can control the sorting by setting the @code{gnus-sorted-header-list}
6764 variable. It is a list of regular expressions that says in what order
6765 the headers are to be displayed.
6767 For instance, if you want the name of the author of the article first,
6768 and then the subject, you might say something like:
6771 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
6774 Any headers that are to remain visible, but are not listed in this
6775 variable, will be displayed in random order after all the headers that
6776 are listed in this variable.
6782 Mime is a standard for waving your hands through the air, aimlessly,
6783 while people stand around yawning.
6785 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
6786 while all newsreaders die of fear.
6788 @sc{mime} may specify what character set the article uses, the encoding
6789 of the characters, and it also makes it possible to embed pictures and
6790 other naughty stuff in innocent-looking articles.
6792 @vindex gnus-show-mime
6793 @vindex gnus-show-mime-method
6794 Gnus handles @sc{mime} by shoving the articles through
6795 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
6796 default. If @code{gnus-strict-mime} is non-@code{nil}, the @sc{mime}
6797 method will only be used it there are @sc{mime} headers in the article.
6798 Set @code{gnus-show-mime} to @code{t} if you want to use @sc{mime} all
6799 the time; it might be best to just use the toggling functions from the
6800 summary buffer to avoid getting nasty surprises. (For instance, you
6801 enter the group @samp{alt.sing-a-long} and, before you know it,
6802 @sc{mime} has decoded the sound file in the article and some horrible
6803 sing-a-long song comes streaming out out your speakers, and you can't
6804 find the volume button, because there isn't one, and people are starting
6805 to look at you, and you try to stop the program, but you can't, and you
6806 can't find the program to control the volume, and everybody else in the
6807 room suddenly decides to look at you disdainfully, and you'll feel
6810 Any similarity to real events and people is purely coincidental. Ahem.
6812 @node Customizing Articles
6813 @section Customizing Articles
6814 @cindex article customization
6816 @vindex gnus-article-display-hook
6817 The @code{gnus-article-display-hook} is called after the article has
6818 been inserted into the article buffer. It is meant to handle all
6819 treatment of the article before it is displayed. By default it contains
6820 @code{gnus-article-hide-headers}, which hides unwanted headers.
6822 @findex gnus-article-subcite
6823 @findex gnus-article-hide-signature
6824 @findex gnus-article-hide-citation
6825 Other useful functions you might add to this hook is:
6828 @item gnus-article-hide-citation
6829 Hide all cited text.
6830 @item gnus-article-hide-signature
6831 Umn, hides the signature.
6832 @item gnus-article-treat-overstrike
6833 Treat @samp{^H_} in a reasonable manner.
6834 @item gnus-article-maybe-highlight
6835 Do fancy article highlighting.
6836 @item gnus-article-remove-cr
6837 Removes trailing carriage returns.
6838 @item gnus-article-de-quoted-unreadable
6839 Do naive decoding of articles encoded with Quoted-Printable.
6840 @item gnus-article-display-x-face
6841 Displays any X-Face headers.
6844 You can, of course, write your own functions. The functions are called
6845 from the article buffer, and you can do anything you like, pretty much.
6846 There is no information that you have to keep in the buffer - you can
6847 change everything. However, you shouldn't delete any headers. Instead
6848 make them invisible if you want to make them go away.
6850 @node Article Keymap
6851 @section Article Keymap
6853 @c Most of the keystrokes in the summary buffer can also be used in the
6854 @c article buffer. They should behave as if you typed them in the summary
6855 @c buffer, which means that you don't actually have to have a summary
6856 @c buffer displayed while reading. You can do it all from the article
6859 A few additional keystrokes are available:
6863 @kindex SPACE (Article)
6864 @findex gnus-article-next-page
6865 Scroll forwards one page (@code{gnus-article-next-page}).
6867 @kindex DEL (Article)
6868 @findex gnus-article-prev-page
6869 Scroll backwards one page (@code{gnus-article-prev-page}).
6871 @kindex C-c ^ (Article)
6872 @findex gnus-article-refer-article
6873 If point is in the neighborhood of a @code{Message-Id} and you press
6874 @kbd{r}, Gnus will try to get that article from the server
6875 (@code{gnus-article-refer-article}).
6877 @kindex C-c C-m (Article)
6878 @findex gnus-article-mail
6879 Send a reply to the address near point (@code{gnus-article-mail}). If
6880 given a prefix, include the mail.
6883 @findex gnus-article-show-summary
6884 Reconfigure the buffers so that the summary buffer becomes visible
6885 (@code{gnus-article-show-summary}).
6888 @findex gnus-article-describe-briefly
6889 Give a very brief description of the available keystrokes
6890 (@code{gnus-article-describe-briefly}).
6894 @section Misc Article
6897 @vindex gnus-article-prepare-hook
6898 @item gnus-article-prepare-hook
6899 This hook is called right after the article has been inserted into the
6900 article buffer. It is mainly intended for functions that do something
6901 depending on the contents; it should probably not be used for changing
6902 the contents of the article buffer.
6903 @vindex gnus-article-display-hook
6904 @item gnus-article-display-hook
6905 This hook is called as the last thing when displaying an article, and is
6906 intended for modifying the contents of the buffer, doing highlights,
6907 hiding headers, and the like.
6908 @vindex gnus-article-mode-line-format
6909 @item gnus-article-mode-line-format
6910 This variable is a format string along the same lines as
6911 @code{gnus-summary-mode-line-format}. It accepts exactly the same
6912 format specifications as that variable.
6913 @vindex gnus-break-pages
6914 @item gnus-break-pages
6915 Controls whether @dfn{page breaking} is to take place. If this variable
6916 is non-@code{nil}, the articles will be divided into pages whenever a
6917 page delimiter appears in the article. If this variable is @code{nil},
6918 paging will not be done.
6919 @item gnus-page-delimiter
6920 @vindex gnus-page-delimiter
6921 This is the delimiter mentioned above. By default, it is @samp{^L}
6925 @node The Server Buffer
6926 @chapter The Server Buffer
6928 Traditionally, a @dfn{server} is a machine or a piece of software that
6929 one connects to, and then requests information from. Gnus does not
6930 connect directly to any real servers, but does all transactions through
6931 one backend or other. But that's just putting one layer more between
6932 the actual media and Gnus, so we might just as well say that each
6933 backend represents a virtual server.
6935 For instance, the @code{nntp} backend may be used to connect to several
6936 different actual nntp servers, or, perhaps, to many different ports on
6937 the same actual nntp server. You tell Gnus which backend to use, and
6938 what parameters to set by specifying a @dfn{select method}.
6940 These select methods specifications can sometimes become quite
6941 complicated - say, for instance, that you want to read from the nntp
6942 server @samp{news.funet.fi} on port number @samp{13}, which hangs if
6943 queried for @sc{nov} headers and has a buggy select. Ahem. Anyways, if
6944 you had to specify that for each group that used this server, that would
6945 be too much work, so Gnus offers a way of putting names to methods,
6946 which is what you do in the server buffer.
6949 * Server Buffer Format:: You can customize the look of this buffer.
6950 * Server Commands:: Commands to manipulate servers.
6951 * Example Methods:: Examples server specifications.
6952 * Servers & Methods:: You can use server names as select methods.
6955 @node Server Buffer Format
6956 @section Server Buffer Format
6957 @cindex server buffer format
6959 @vindex gnus-server-line-format
6960 You can change the look of the server buffer lines by changing the
6961 @code{gnus-server-line-format} variable. This is a @code{format}-like
6962 variable, with some simple extensions:
6966 How the news is fetched - the backend name.
6968 The name of this server.
6970 Where the news is to be fetched from - the address.
6973 @node Server Commands
6974 @section Server Commands
6975 @cindex server commands
6979 Browse the current server (@code{gnus-server-read-server}).
6981 Return to the group buffer (@code{gnus-server-exit}).
6983 List all servers (@code{gnus-server-list-servers}).
6985 Kill the current server (@code{gnus-server-kill-server}).
6987 Yank the previously killed server (@code{gnus-server-yank-server}).
6989 Copy the current server (@code{gnus-server-copy-server}).
6991 Add a new server (@code{gnus-server-add-server}).
6993 Edit a server (@code{gnus-server-edit-server}).
6996 @node Example Methods
6997 @section Example Methods
6999 Most select methods are pretty simple and self-explanatory:
7002 (nntp "news.funet.fi")
7005 Reading directly from the spool is even simpler:
7011 As you can see, the first element in a select method is the name of the
7012 backend, and the second is the @dfn{address}, or @dfn{name}, if you
7015 After these two elements, there may be a random number of @var{(variable
7018 To go back to the first example - imagine that you want to read from
7019 port @code{15} from that machine. This is what the select method should
7023 (nntp "news.funet.fi" (nntp-port-number 15))
7026 You should read the documentation to each backend to find out what
7027 variables are relevant, but here's an @code{nnmh} example.
7029 @code{nnmh} is a mail backend that reads a spool-like structure. Say
7030 you have two structures that you wish to access: One is your private
7031 mail spool, and the other is a public one. Here's the possible spec for
7035 (nnmh "private" (nnmh-directory "~/private/mail/"))
7038 (This server is then called @samp{private}, but you may have guessed
7041 Here's the method for the public spool:
7045 (nnmh-directory "/usr/information/spool/")
7046 (nnmh-get-new-mail nil))
7049 @node Servers & Methods
7050 @section Servers & Methods
7052 Wherever you would normally use a select method
7053 (eg. @code{gnus-secondary-select-method}, in the group select method,
7054 when browsing a foreign server) you can use a virtual server name
7055 instead. This could potentially save lots of typing. And it's nice all
7063 * Interactive:: Making Gnus ask you many questions.
7064 * Windows Configuration:: Configuring the Gnus buffer windows.
7065 * Buttons:: Get tendonitis in ten easy steps!
7066 * Various Various:: Things that are really various.
7070 @section Interactive
7074 @item gnus-novice-user
7075 @vindex gnus-novice-user
7076 If this variable is non-@code{nil}, you are either a newcomer to the
7077 World of Usenet, or you are very cautious, which is a nice thing to be,
7078 really. You will be given questions of the type "Are you sure you want
7079 to do this?" before doing anything dangerous.
7080 @item gnus-expert-user
7081 @vindex gnus-expert-user
7082 If this variable is non-@code{nil}, you will never ever be asked any
7083 questions by Gnus. It will simply assume you know what your are doing,
7084 no matter how strange.
7085 @item gnus-interactive-catchup
7086 @vindex gnus-interactive-catchup
7087 Require confirmation before catching up a group if non-@code{nil}.
7088 @item gnus-interactive-post
7089 @vindex gnus-interactive-post
7090 If non-@code{nil}, the user will be prompted for a group name when
7092 @item gnus-interactive-exit
7093 @vindex gnus-interactive-exit
7094 Require confirmation before exiting Gnus.
7097 @node Windows Configuration
7098 @section Windows Configuration
7099 @cindex windows configuration
7101 No, there's nothing here about X, so be quiet.
7104 @item gnus-use-full-window
7105 @vindex gnus-use-full-window
7106 If non-@code{nil}, Gnus will delete all other windows and occupy the
7107 entire Emacs screen by itself. It is @code{t} by default.
7109 @item gnus-buffer-configuration
7110 @vindex gnus-buffer-configuration
7111 This variable describes how much space each Gnus buffer should be given.
7112 Here's an excerpt of this variable:
7115 ((group ([group 1.0 point]
7116 (if gnus-carpal [group-carpal 4])))
7117 (article ([summary 0.25 point]
7121 This is an alist. The @dfn{key} is a symbol that names some action or
7122 other. For instance, when displaying the group buffer, the window
7123 configuration function will use @code{group} as the key. A full list of
7124 possible names is listed below.
7126 The @dfn{value} is a @dfn{rule} that says how much space each buffer
7127 should occupy. To take the @code{article} rule as an example -
7130 (article ([summary 0.25 point]
7134 This rule says that the summary buffer should occupy 25% of the screen,
7135 and that it is placed over the article buffer. As you may have noticed,
7136 100% + 25% is actually 125% (yup, I saw y'all reaching for that
7137 calculator there). However, the special number @code{1.0} is used to
7138 signal that this buffer should soak up all the rest of the space
7139 avaiable after the rest of the buffers have taken whatever they need.
7140 There should be only one buffer with the @code{1.0} size spec.
7142 Point will be put in the buffer that has the optional third element
7145 Here's a more complicated example:
7149 [summary 0.25 point]
7150 (if gnus-carpal [summary-carpal 4])
7154 If the size spec is an integer instead of a floating point number,
7155 then that number will be used to say how many lines a buffer should
7156 occupy, not a percentage.
7158 If an element is a list instead of a vector, this list will be
7159 @code{eval}ed. If the result is non-@code{nil}, it will be used. This
7160 means that there will be three buffers if @code{gnus-carpal} is
7161 @code{nil}, and four buffers if @code{gnus-carpal} is non-@code{nil}.
7163 Not complicated enough for you? Well, try this on for size:
7166 (article ([group 1.0]
7169 [summary 0.25 point]
7174 Whoops. Two buffers with the mystery 100% tag. And what's that
7175 @code{horizontal} thingie?
7177 If the first element in one of the rule lists is a list with
7178 @code{horizontal} as the first element, Gnus will split the window
7179 horizontally, giving you two windows side-by-side. Inside each of these
7180 strips you may carry on all you like in the normal fashion. The number
7181 following @code{horizontal} says what percentage of the screen is to be
7182 given to this strip.
7184 For each horizontal split, there @emph{must} be one element that has the
7185 100% tag. The splitting is never accurate, and this buffer will eat any
7186 leftover lines from the splits.
7188 Here's a list of all possible keys:
7190 @code{group}, @code{summary}, @code{article}, @code{server},
7191 @code{browse}, @code{group-mail}, @code{summary-mail},
7192 @code{summary-reply}, @code{info}, @code{summary-faq},
7193 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
7194 @code{followup}, @code{followup-yank}, @code{edit-score}.
7196 @findex gnus-add-configuration
7197 Since this variable is so long and complicated, there's a function you
7198 can use to ease changing the config of a single setting:
7199 @code{gnus-add-configuration}. If, for instance, you want to change the
7200 @code{article} setting, you could say:
7203 (gnus-add-configuration
7204 '(article ([group 4]
7217 Those new-fangled @dfn{mouse} contraptions is very popular with the
7218 young, hep kids who don't want to learn the proper way to do things
7219 these days. Why, I remember way back in the summer of '89, when I was
7220 using Emacs on a Tops 20 system. Three hundred users on one single
7221 machine, and every user was running Simula compilers. Bah!
7226 Well, you can make Gnus display bufferfuls of buttons you can click to
7227 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
7228 really. Tell the chiropractor I sent you.
7232 @item gnus-carpal-mode-hook
7233 @vindex gnus-carpal-mode-hook
7234 Hook run in all carpal mode buffers.
7235 @item gnus-carpal-button-face
7236 @vindex gnus-carpal-button-face
7237 Face used on buttons.
7238 @item gnus-carpal-group-buffer-buttons
7239 @vindex gnus-carpal-group-buffer-buttons
7240 Buttons in the group buffer.
7241 @item gnus-carpal-summary-buffer-buttons
7242 @vindex gnus-carpal-summary-buffer-buttons
7243 Buttons in the summary buffer.
7244 @item gnus-carpal-server-buffer-buttons
7245 @vindex gnus-carpal-server-buffer-buttons
7246 Buttons in the server buffer.
7247 @item gnus-carpal-browse-buffer-buttons
7248 @vindex gnus-carpal-browse-buffer-buttons
7249 Buttons in the browse buffer.
7252 All the @code{buttons} variables are lists. The elements in these list
7253 is either a cons cell where the car contains a text to be displayed and
7254 the cdr contains a function symbol, or a simple string.
7256 @node Various Various
7257 @section Various Various
7263 @vindex gnus-verbose
7264 This variable is an integer between zero and ten. The higher the value,
7265 the more messages will be displayed. If this variable is zero, Gnus
7266 will never flash any messages, if it is seven, most important messages
7267 will be shown, and if it is ten, Gnus won't ever shut up, but will flash
7268 so many messages it will make your head swim.
7269 @item gnus-updated-mode-lines
7270 @vindex gnus-updated-mode-lines
7271 This is a list of buffers that should keep their mode lines updated.
7272 The list may contain the symbols @code{group}, @code{article} and
7273 @code{summary}. If the corresponding symbol is present, Gnus will keep
7274 that mode line updated with information that may be pertinent. If this
7275 variable is @code{nil}, screen refresh may be quicker.
7277 @cindex display-time
7278 @item gnus-mode-non-string-length
7279 @vindex gnus-mode-non-string-length
7280 By default, Gnus displays information on the current article in the mode
7281 lines of the summary and article buffers. The information Gnus wishes
7282 to display (eg. the subject of the article) is often longer than the
7283 mode lines, and therefore have to be cut off at some point. This
7284 variable says how long the other elements on the line is (i.e., the
7285 non-info part). If you put additional elements on the mode line (eg. a
7286 clock), you should modify this variable:
7287 @c Hook written by Keinonen Kari <kk85613@cs.tut.fi>.
7289 (add-hook 'display-time-hook
7291 (setq gnus-mode-non-string-length
7292 (+ 21 (length display-time-string)))))
7297 If @code{nil}, Gnus won't attempt to create menus or use fancy colors
7298 or fonts. This will also inhibit loading the @file{gnus-visual.el}
7300 @item gnus-mouse-face
7301 @vindex gnus-mouse-face
7302 This is the face (i.e., font) used for mouse highlighting in Gnus. No
7303 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
7305 @item gnus-display-type
7306 @vindex gnus-display-type
7307 This variable is symbol indicating the display Emacs is running under.
7308 The symbol should be one of @code{color}, @code{grayscale} or
7309 @code{mono}. If Gnus guesses this display attribute wrongly, either set
7310 this variable in your @file{~/.emacs} or set the resource
7311 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
7313 @item gnus-background-mode
7314 @vindex gnus-background-mode
7315 This is a symbol indicating the Emacs background brightness. The symbol
7316 should be one of @code{light} or @code{dark}. If Gnus guesses this
7317 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
7318 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
7319 `gnus-display-type'.
7321 @item nnheader-max-head-length
7322 @vindex nnheader-max-head-length
7323 When the backends read straight heads of articles, they all try to read
7324 as little as possible. This variable (default @code{4096}) specifies
7325 the absolute max length the backends will try to read before giving up
7326 on finding a separator line between the head and the body. If this
7327 variable is @code{nil}, there is no upper read bound. If it is
7328 @code{t}, the backends won't try to read the articles piece by piece,
7329 but read the entire articles. This makes sense with some versions of
7336 @chapter Customization
7337 @cindex general customization
7339 All variables are properly documented elsewhere in this manual. This
7340 section is designed to give general pointers on how to customize Gnus
7341 for some quite common situations.
7344 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
7345 * Slow Terminal Connection:: You run a remote Emacs.
7346 * Little Disk Space:: You feel that having large setup files is icky.
7347 * Slow Machine:: You feel like buying a faster machine.
7350 @node Slow/Expensive Connection
7351 @section Slow/Expensive @sc{nntp} Connection
7353 If you run Emacs on a machine locally, and get your news from a machine
7354 over some very thin strings, you want to cut down on the amount of data
7355 Gnus has to get from the @sc{nntp} server.
7358 @item gnus-read-active-file
7359 Set this to @code{nil}, which will inhibit Gnus from requesting the
7360 entire active file from the server. This file is often v. large. You
7361 also have to set @code{gnus-check-new-news} and
7362 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
7363 doesn't suddenly decide to fetch the active file anyway.
7364 @item gnus-nov-is-evil
7365 This one has to be @code{nil}. If not, grabbing article headers from
7366 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
7367 support @sc{xover}; Gnus will detect this by itself.
7370 @node Slow Terminal Connection
7371 @section Slow Terminal Connection
7373 Let's say you use your home computer for dialing up the system that
7374 runs Emacs and Gnus. If your modem is slow, you want to reduce the
7375 amount of data that is sent over the wires as much as possible.
7378 @item gnus-auto-center-summary
7379 Set this to @code{nil} to inhibit Gnus from recentering the summary
7380 buffer all the time.
7381 @item gnus-visible-headers
7382 Cut down on the headers that are included in the articles to the
7383 minimum. You can, in fact, make do without them altogether - most of the
7384 useful data is in the summary buffer, anyway. Set this variable to
7385 @samp{"^NEVVVVER"} or @samp{"From:"}, or whatever you feel you need.
7386 @item gnus-article-display-hook
7387 Set this hook to all the available hiding commands:
7389 (setq gnus-article-display-hook
7390 '(gnus-article-hide-headers gnus-article-hide-signature
7391 gnus-article-hide-citation))
7393 @item gnus-use-full-window
7394 By setting this to @code{nil}, you can make all the windows smaller.
7395 While this doesn't really cut down much generally, it means that you
7396 have to see smaller portions of articles before deciding that you didn't
7397 want to read them anyway.
7398 @item gnus-thread-hide-subtree
7399 If this is non-@code{nil}, all threads in the summary buffer will be
7401 @item gnus-updated-mode-lines
7402 If this is @code{nil}, Gnus will not put information in the buffer mode
7403 lines, which might save some time.
7406 @node Little Disk Space
7407 @section Little Disk Space
7409 The startup files can get rather large, so you may want to cut their
7410 sizes a bit if you are running out of space.
7413 @item gnus-save-newsrc-file
7414 If this is @code{nil}, Gnus will never save @file{.newsrc} - it will
7415 only save @file{.newsrc.eld}. This means that you will not be able to
7416 use any other newsreaders than Gnus.
7417 @item gnus-save-killed-list
7418 If this is @code{nil}, Gnus will not save the list of dead groups. You
7419 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
7420 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
7421 variable to @code{nil}.
7425 @section Slow Machine
7427 If you have a slow machine, or are just really impatient, there are a
7428 few things you can do to make Gnus run faster.
7430 Set@code{gnus-check-new-newsgroups} and
7431 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
7433 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
7434 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
7435 summary buffer faster.
7437 Set @code{gnus-article-display-hook} to @code{nil} to make article
7438 processing a bit faster.
7440 @node Troubleshooting
7441 @chapter Troubleshooting
7442 @cindex troubleshooting
7444 Gnus works @emph{so} well straight out of the box - I can't imagine any
7451 Make sure your computer is switched on.
7453 Make sure that you really load the current Gnus version. If you have
7454 been running @sc{gnus}, you need to exit Emacs and start it up again before
7457 Try doing an @kbd{M-x gnus-version}. If you get something that looks
7458 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
7459 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
7460 flee}, you have some old @file{.el} files lying around. Delete these.
7462 Read the help group (@kbd{M h} in the group buffer) for a FAQ and a
7466 If all else fails, report the problem as a bug,
7469 @cindex reporting bugs
7471 @kindex M-x gnus-bug
7473 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
7474 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
7475 me the backtrace. I will fix bugs, but I can only fix them if you send
7476 me a precise description as to how to reproduce the bug.
7478 @c If you just need help, you are better off asking on
7479 @c @samp{gnu.emacs.gnus}.
7484 Well, that's the manual - you can get on with your life now. Keep in
7485 touch. Say hello to your cats from me.
7487 My @strong{ghod} - I just can't stand goodbyes. Sniffle.
7489 Ol' Chuck Reznikoff said it pretty well, so I leave the floor to him:
7494 Not because of victories @*
7497 but for the common sunshine,@*
7499 the largess of the spring.
7502 but for the day's work done@*
7503 as well as I was able;@*
7504 not for a seat upon the dais@*
7505 but at the common table.@*
7509 @chapter A Programmer's Guide to Gnus
7511 It is my hope that other people will figure out smart stuff that Gnus
7512 can do, and that other people will write those smart things as well. To
7513 facilitate that I thought it would be a good idea to describe the inner
7514 workings of Gnus. And some of the not-so-inner workings, while I'm at
7517 You can never expect the internals of a program not to change, but I
7518 will be defining (in some details) the interface between Gnus and its
7519 backends (this is written in stone), the format of the score files
7520 (ditto), data structures (some are less likely to change than others)
7521 and general method of operations.
7524 * Backend Interface:: How Gnus communicates with the servers.
7525 * Score File Syntax:: A BNF definition of the score file standard.
7526 * Headers:: How Gnus stores headers internally.
7527 * Ranges:: A handy format for storing mucho numbers.
7528 * Group Info:: The group info format.
7532 @node Backend Interface
7533 @section Backend Interface
7535 Gnus doesn't know anything about nntp, spools, mail or virtual groups.
7536 It only knows how to talk to @dfn{virtual servers}. A virtual server is
7537 a @dfn{backend} and some @dfn{backend variables}. As examples of the
7538 first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
7539 examples of the latter we have @code{nntp-port-number} and
7540 @code{nnmbox-directory}.
7542 When Gnus asks for information from a backend -- say @code{nntp} -- on
7543 something, it will normally include a virtual server name in the
7544 function parameters. (If not, the backend should use the "current"
7545 virtual server.) For instance, @code{nntp-request-list} takes a virtual
7546 server as its only (optional) parameter. If this virtual server hasn't
7547 been opened, the function should fail.
7549 Note that a virtual server name has no relation to some physical server
7550 name. Take this example:
7554 (nntp-address "ifi.uio.no")
7555 (nntp-port-number 4324))
7558 Here the virtual server name is @samp{"odd-one"} while the name of
7559 the physical server is @samp{"ifi.uio.no"}.
7561 The backends should be able to switch between several virtual servers.
7562 The standard backends implement this by keeping an alist of virtual
7563 server environments that it pulls down/pushes up when needed.
7565 There are two groups of interface functions: @dfn{required functions},
7566 which must be present, and @dfn{optional functions}, which Gnus will
7567 always check whether are present before attempting to call.
7569 All these functions are expected to return data in the buffer
7570 @code{nntp-server-buffer} (@samp{" *nntpd*"}), which is somewhat
7571 unfortunately named, but we'll have to live with it. When I talk about
7572 "resulting data", I always refer to the data in that buffer. When I
7573 talk about "return value", I talk about the function value returned by
7576 Some backends could be said to be @dfn{server-forming} backends, and
7577 some might be said to not be. The latter are backends that generally
7578 only operate on one group at a time, and have no concept of "server" --
7579 they have a group, and they deliver info on that group and nothing more.
7581 In the examples and definitions I will refer to the imaginary backend
7587 * Required Backend Functions:: Functions that must be implemented.
7588 * Optional Backend Functions:: Functions that need not be implemented.
7592 @node Required Backend Functions
7593 @subsection Required Backend Functions
7597 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
7599 @var{articles} is either a range of article numbers or a list of
7600 @code{Message-ID}s. Current backends do not fully support either - only
7601 sequences (lists) of article numbers, and most backends do not support
7602 retrieval of @code{Message-ID}s. But they should try for both.
7604 The result data should either be HEADs or NOV lines, and the result
7605 value should either be @code{headers} or @code{nov} to reflect this.
7606 This might later be expanded to @code{various}, which will be a mixture
7607 of HEADs and NOV lines, but this is currently not supported by Gnus.
7609 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra"
7610 headers, in some meaning of the word. This is generally done by
7611 fetching (at most) @var{fetch-old} extra headers less than the smallest
7612 article number in @code{articles}, and fill in the gaps as well. The
7613 presence of this parameter can be ignored if the backend finds it
7614 cumbersome to follow the request. If this is non-@code{nil} and not a
7615 number, do maximum fetches.
7617 Here's an example HEAD:
7620 221 1056 Article retrieved.
7621 Path: ifi.uio.no!sturles
7622 From: sturles@@ifi.uio.no (Sturle Sunde)
7623 Newsgroups: ifi.discussion
7624 Subject: Re: Something very droll
7625 Date: 27 Oct 1994 14:02:57 +0100
7626 Organization: Dept. of Informatics, University of Oslo, Norway
7628 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
7629 References: <38jdmq$4qu@@visbur.ifi.uio.no>
7630 NNTP-Posting-Host: holmenkollen.ifi.uio.no
7634 So a @code{headers} return value would imply that there's a number of
7635 these in the data buffer.
7637 Here's a BNF definition of such a buffer:
7641 head = error / valid-head
7642 error-message = [ "4" / "5" ] 2number " " <error message> eol
7643 valid-head = valid-message *header "." eol
7644 valid-message = "221 " <number> " Article retrieved." eol
7648 If the return value is @code{nov}, the data buffer should contain
7649 @dfn{network overview database} lines. These are basically fields
7653 nov-buffer = *nov-line
7654 nov-line = 8*9 [ field <TAB> ] eol
7655 field = <text except TAB>
7658 For a closer explanation what should be in those fields,
7662 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
7664 @var{server} is here the virtual server name. @var{definitions} is a
7665 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
7667 If the server can't be opened, no error should be signaled. The backend
7668 may then choose to refuse further attempts at connecting to this
7669 server. In fact, it should do so.
7671 If the server is opened already, this function should return a
7672 non-@code{nil} value. There should be no data returned.
7675 @item (nnchoke-close-server &optional SERVER)
7677 Close connection to @var{server} and free all resources connected
7680 There should be no data returned.
7683 @item (nnchoke-request-close)
7685 Close connection to all servers and free all resources that the backend
7686 have reserved. All buffers that have been created by that backend
7687 should be killed. (Not the @code{nntp-server-buffer}, though.)
7689 There should be no data returned.
7692 @item (nnchoke-server-opened &optional SERVER)
7694 This function should return whether @var{server} is opened, and that the
7695 connection to it is still alive. This function should under no
7696 circumstances attempt to reconnect to a server that is has lost
7699 There should be no data returned.
7702 @item (nnchoke-status-message &optional SERVER)
7704 This function should return the last error message from @var{server}.
7706 There should be no data returned.
7709 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
7711 The result data from this function should be the article specified by
7712 @var{article}. This might either be a @code{Message-ID} or a number.
7713 It is optional whether to implement retrieval by @code{Message-ID}, but
7714 it would be nice if that were possible.
7716 If @var{to-buffer} is non-@code{nil}, the result data should be returned
7717 in this buffer instead of the normal data buffer. This is to make it
7718 possible to avoid copying large amounts of data from one buffer to
7719 another, and Gnus mainly request articles to be inserted directly into
7723 @item (nnchoke-open-group GROUP &optional SERVER)
7725 Make @var{group} the current group.
7727 There should be no data returned by this function.
7730 @item (nnchoke-request-group GROUP &optional SERVER)
7732 Get data on @var{group}. This function also has the side effect of
7733 making @var{group} the current group.
7735 Here's an example of some result data and a definition of the same:
7738 211 56 1000 1059 ifi.discussion
7741 The first number is the status, which should be @samp{211}. Next is the
7742 total number of articles in the group, the lowest article number, the
7743 highest article number, and finally the group name. Note that the total
7744 number of articles may be less than one might think while just
7745 considering the highest and lowest article numbers, but some articles
7746 may have been cancelled. Gnus just discards the total-number, so
7747 whether one should take the bother to generate it properly (if that is a
7748 problem) is left as an excercise to the reader.
7751 group-status = [ error / info ] eol
7752 error = [ "4" / "5" ] 2<number> " " <Error message>
7753 info = "211 " 3* [ <number> " " ] <string>
7757 @item (nnchoke-close-group GROUP &optional SERVER)
7759 Close @var{group} and free any resources connected to it. This will be
7760 a no-op on most backends.
7762 There should be no data returned.
7765 @item (nnchoke-request-list &optional SERVER)
7767 Return a list of all groups available on @var{server}. And that means
7770 Here's an example from a server that only carries two groups:
7773 ifi.test 0000002200 0000002000 y
7774 ifi.discussion 3324 3300 n
7777 On each line we have a group name, then the highest article number in
7778 that group, the lowest article number, and finally a flag.
7781 active-file = *active-line
7782 active-line = name " " <number> " " <number> " " flags eol
7784 flags = "n" / "y" / "m" / "x" / "j" / "=" name
7787 The flag says whether the group is read-only (@samp{n}), is moderated
7788 (@samp{m}), is dead (@samp{x}), is aliased to some other group
7789 (@samp{=other-group} or none of the above (@samp{y}).
7792 @item (nnchoke-request-post &optional SERVER)
7794 This function should post the current buffer. It might return whether
7795 the posting was successful or not, but that's not required. If, for
7796 instance, the posting is done asynchronously, it has generally not been
7797 completed by the time this function concludes. In that case, this
7798 function should set up some kind of sentinel to beep the user loud and
7799 clear if the posting could not be completed.
7801 There should be no result data from this function.
7804 @item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
7806 This function should return a buffer suitable for composing an article
7807 to be posted by @code{nnchoke-request-post}. If @var{post} is
7808 non-@code{nil}, this is not a followup, but a totally new article.
7809 @var{group} is the name of the group to be posted to. @var{subject} is
7810 the subject of the message. @var{article-buffer} is the buffer being
7811 followed up, if that is the case. @var{info} is the group info.
7812 @var{follow-to} is the group that one is supposed to re-direct the
7813 article to. If @var{respect-poster} is non-@code{nil}, the special
7814 @samp{"poster"} value of a @code{Followup-To} header is to be respected.
7816 There should be no result data returned.
7820 @node Optional Backend Functions
7821 @subsection Optional Backend Functions
7825 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
7827 @var{groups} is a list of groups, and this function should request data
7828 on all those groups. How it does it is of no concern to Gnus, but it
7829 should attempt to do this in a speedy fashion.
7831 The return value of this function can be either @code{active} or
7832 @code{group}, which says what the format of the result data is. The
7833 former is in the same format as the data from
7834 @code{nnchoke-request-list}, while the latter is a buffer full of lines
7835 in the same format as @code{nnchoke-request-group} gives.
7838 group-buffer = *active-line / *group-status
7842 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
7844 A Gnus group info (@pxref{Group Info}) is handed to the backend for
7845 alterations. This comes in handy if the backend really carries all the
7846 information (as is the case with virtual an imap groups). This function
7847 may alter the info in any manner it sees fit, and should return the
7848 (altered) group info. This function may alter the group info
7849 destructively, so no copying is needed before boogying.
7851 There should be no result data from this function.
7854 @item (nnchoke-request-scan &optional GROUP SERVER)
7856 This function may be called at any time (by Gnus or anything else) to
7857 request that the backend check for incoming articles, in one way or
7858 another. A mail backend will typically read the spool file or query the
7859 POP server when this function is invoked. The @var{group} doesn't have
7860 to be heeded -- if the backend decides that it is too much work just
7861 scanning for a single group, it may do a total scan of all groups. It
7862 would be nice, however, to keep things local if that's practical.
7864 There should be no result data from this function.
7867 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
7869 This is a request to fetch articles asynchronously later.
7870 @var{articles} is an alist of @var{(article-number line-number)}. One
7871 would generally expect that if one later fetches article number 4, for
7872 instance, some sort of asynchronous fetching of the articles after 4
7873 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
7874 alist) would be fetched asynchronouly, but that is left up to the
7875 backend. Gnus doesn't care.
7877 There should be no result data from this function.
7880 @item (nnchoke-request-group-description GROUP &optional SERVER)
7882 The result data from this function should be a description of
7886 description-line = name <TAB> description eol
7888 description = <text>
7891 @item (nnchoke-request-list-newsgroups &optional SERVER)
7893 The result data from this function should be the description of all
7894 groups available on the server.
7897 description-buffer = *description-line
7901 @item (nnchoke-request-newgroups DATE &optional SERVER)
7903 The result data from this function should be all groups that were
7904 created after @samp{date}, which is in normal human-readable date
7905 format. The data should be in the active buffer format.
7908 @item (nnchoke-request-create-groups GROUP &optional SERVER)
7910 This function should create an empty group with name @var{group}.
7912 There should be no return data.
7915 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
7917 This function should run the expiry process on all articles in the
7918 @var{articles} range (which is currently a simple list of article
7919 numbers.) It is left up to the backend to decide how old articles
7920 should be before they are removed by this function. If @var{force} is
7921 non-@code{nil}, all @var{articles} should be deleted, no matter how new
7924 This function should return a list of articles that it did not/was not
7927 There should be no result data returned.
7930 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
7933 This function should move @var{article} (which is a number) from
7934 @var{group} by calling @var{accept-form}.
7936 This function should ready the article in question for moving by
7937 removing any header lines it has added to the article, and generally
7938 should "tidy up" the article. Then it should @code{eval}
7939 @var{accept-form} in the buffer where the "tidy" article is. This will
7940 do the actual copying. If this @code{eval} returns a non-@code{nil}
7941 value, the article should be removed.
7943 If @var{last} is @code{nil}, that means that there is a high likelihood
7944 that there will be more requests issued shortly, so that allows some
7947 There should be no data returned.
7950 @item (nnchoke-request-accept-article GROUP &optional LAST)
7952 This function takes the current buffer and inserts it into @var{group}.
7953 If @var{last} in @code{nil}, that means that there will be more calls to
7954 this function in short order.
7956 There should be no data returned.
7959 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
7961 This function should remove @var{article} (which is a number) from
7962 @var{group} and insert @var{buffer} there instead.
7964 There should be no data returned.
7969 @node Score File Syntax
7970 @section Score File Syntax
7972 Score files are meant to be easily parsable, but yet extremely
7973 mallable. It was decided that something that had the same read syntax
7974 as an Emacs Lisp list would fit that spec.
7976 Here's a typical score file:
7980 ("win95" -10000 nil s)
7987 BNF definition of a score file:
7990 score-file = "" / "(" *element ")"
7991 element = rule / atom
7992 rule = string-rule / number-rule / date-rule
7993 string-rule = "(" quote string-header quote space *string-match ")"
7994 number-rule = "(" quote number-header quote space *number-match ")"
7995 date-rule = "(" quote date-header quote space *date-match ")"
7997 string-header = "subject" / "from" / "references" / "message-id" /
7998 "xref" / "body" / "head" / "all" / "followup"
7999 number-header = "lines" / "chars"
8000 date-header = "date"
8001 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
8002 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
8003 score = "nil" / <integer>
8004 date = "nil" / <natural number>
8005 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
8006 "r" / "regex" / "R" / "Regex" /
8007 "e" / "exact" / "E" / "Exact" /
8008 "f" / "fuzzy" / "F" / "Fuzzy"
8009 number-match = "(" <integer> [ "" / [ space score [ "" /
8010 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
8011 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
8012 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
8013 space date [ "" / [ space date-match-t ] ] ] ] ")"
8014 date-match-t = "nil" / "at" / "before" / "after"
8015 atom = "(" [ required-atom / optional-atom ] ")"
8016 required-atom = mark / expunge / mark-and-expunge / files /
8017 exclude-files / read-only / touched
8018 optional-atom = adapt / local / eval
8019 mark = "mark" space nil-or-number
8020 nil-or-t = "nil" / <integer>
8021 expunge = "expunge" space nil-or-number
8022 mark-and-expunge = "mark-and-expunge" space nil-or-number
8023 files = "files" *[ space <string> ]
8024 exclude-files = "exclude-files" *[ space <string> ]
8025 read-only = "read-only" [ space "nil" / space "t" ]
8026 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
8027 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
8028 local = "local" *[ space "(" <string> space <form> ")" ]
8029 eval = "eval" space <form>
8030 space = *[ " " / <TAB> / <NEWLINE> ]
8033 Any unrecognized elements in a score file should be ignored, but not
8036 As you can see, white space is needed, but the type and amount of white
8037 space is irrelevant. This means that formatting of the score file is
8038 left up to the programmer -- if it's simpler to just spew it all out on
8039 one looong line, then that's ok.
8041 The meaning of the various atoms are explained elsewhere in this
8047 Gnus uses internally a format for storing article headers that
8048 corresponds to the @sc{nov} format in a mysterious fashion. One could
8049 almost suspect that the author looked at the @sc{nov} specification and
8050 just shamelessly @emph{stole} the entire thing, and one would be right.
8052 @dfn{Header} is a severly overloaded term. "Header" is used in RFC1036
8053 to talk about lines in the head of an article (eg., @code{From}). It is
8054 used by many people as a synonym for "head" -- "the header and the
8055 body". (That should be avoided, in my opinion.) And Gnus uses a format
8056 interanally that it calls "header", which is what I'm talking about
8057 here. This is a 9-element vector, basically, with each header (ouch)
8060 These slots are, in order: @code{number}, @code{subject}, @code{from},
8061 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
8062 @code{xref}. There are macros for accessing and setting these slots --
8063 they all have predicatable names beginning with @code{mail-header-} and
8064 @code{mail-header-set-}, respectively.
8066 The @code{xref} slot is really a @code{misc} slot. Any extra info will
8072 @sc{gnus} introduced a concept that I found so useful that I've started
8073 using it a lot and have elaborated on it greatly.
8075 The question is simple: If you have a large amount of objects that are
8076 identified by numbers (say, articles, to take a @emph{wild} example)
8077 that you want to callify as being "included", a normal sequence isn't
8078 very useful. (A 200,000 length sequence is a bit long-winded.)
8080 The solution is as simple as the question: You just collapse the
8084 (1 2 3 4 5 6 10 11 12)
8093 To avoid having those nasty @samp{(13 . 13)} elements to denote a
8094 lonesome object, a @samp{13} is a valid element:
8097 ((1 . 6) 7 (10 . 12))
8100 This means that comparing two ranges to find out whether they are equal
8104 ((1 . 6) 7 8 (10 . 12))
8110 ((1 . 5) (7 . 8) (10 . 12))
8113 are equal. In fact, any non-descending list is a range:
8119 is a perfectly valid range, although a pretty longwinded one. This is
8126 and is equal to the previous range.
8128 Here's a BNF definition of ranges. Of course, one must remember the
8129 semantic requirement that the numbers are non-descending. (Any number
8130 of repetition of the same number is allowed, but apt to disappear in
8134 range = simple-range / normal-range
8135 simple-range = "(" number " . " number ")"
8136 normal-range = "(" start-contents ")"
8137 contents = "" / simple-range *[ " " contents ] /
8138 number *[ " " contents ]
8141 Gnus currently uses ranges to keep track of read articles and article
8142 marks. I plan on implementing a number of range operators in C if The
8143 Powers That Be are willing to let me. (I haven't asked yet, because I
8144 need to do some more thinking on what operators I need to make life
8145 totally range-based without ever having to convert back to normal
8152 Gnus stores all permanent info on groups in a @dfn{group info} list.
8153 This list is from three to six elements (or more) long and exhaustively
8154 describes the group.
8156 Here are two example group infos; one is a very simple group while the
8157 second is a more complex one:
8160 ("no.group" 5 (1 . 54324))
8162 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
8163 ((tick (15 . 19)) (replied 3 6 (19 . 23)))
8165 (auto-expire (to-address "ding@@ifi.uio.no")))
8168 The first element is the group name as Gnus knows the group; the second
8169 is the group level; the third is the read articles in range format; the
8170 fourth is a list of article marks lists; the fifth is the select method;
8171 and the sixth contains the group parameters.
8173 Here's a BNF definition of the group info format:
8176 info = "(" group space level space read
8177 [ "" / [ space marks-list [ "" / [ space method [ "" /
8178 space parameters ] ] ] ] ] ")"
8179 group = quote <string> quote
8180 level = <integer in the range of 1 to inf>
8182 marks-lists = nil / "(" *marks ")"
8183 marks = "(" <string> range ")"
8184 method = "(" <string> *elisp-forms ")"
8185 parameters = "(" *elisp-forms ")"
8188 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
8189 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
8207 @c outline-regexp: "@chap\\|@\\(sub\\)*section\\|@appendix \\|@appendix\\(sub\\)*sec\\|\^L"