1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header (This is for running Texinfo on a region.)
4 @settitle September Gnus Manual
11 @setchapternewpage odd
13 @comment %**end of header (This is for running Texinfo on a region.)
16 %\global\baselineskip 30pt % For printing in double spaces
21 This file documents Gnus, the GNU Emacs newsreader.
23 Copyright (C) 1995 Free Software Foundation, Inc.
25 Permission is granted to make and distribute verbatim copies of
26 this manual provided the copyright notice and this permission notice
27 are preserved on all copies.
30 Permission is granted to process this file through Tex and print the
31 results, provided the printed document carries copying permission
32 notice identical to this one except for the removal of this paragraph
33 (this paragraph not being relevant to the printed manual).
36 Permission is granted to copy and distribute modified versions of this
37 manual under the conditions for verbatim copying, provided also that the
38 entire resulting derived work is distributed under the terms of a
39 permission notice identical to this one.
41 Permission is granted to copy and distribute translations of this manual
42 into another language, under the above conditions for modified versions.
48 @title September Gnus Manual
50 @author by Lars Magne Ingebrigtsen
52 @vskip 0pt plus 1filll
53 Copyright @copyright{} 1995 Free Software Foundation, Inc.
55 Permission is granted to make and distribute verbatim copies of
56 this manual provided the copyright notice and this permission notice
57 are preserved on all copies.
59 Permission is granted to copy and distribute modified versions of this
60 manual under the conditions for verbatim copying, provided that the
61 entire resulting derived work is distributed under the terms of a
62 permission notice identical to this one.
64 Permission is granted to copy and distribute translations of this manual
65 into another language, under the above conditions for modified versions.
67 Cover art by Etienne Suvasa.
74 @top The Gnus Newsreader
76 You can read news (and mail) from within Emacs by using Gnus. The news
77 can be gotten by any nefarious means you can think of---@sc{nntp}, local
78 spool or your mbox file. All at the same time, if you want to push your
82 * History:: How Gnus got where it is today.
83 * Terminology:: We use really difficult, like, words here.
84 * Starting Up:: Finding news can be a pain.
85 * The Group Buffer:: Selecting, subscribing and killing groups.
86 * The Summary Buffer:: Reading, saving and posting articles.
87 * The Article Buffer:: Displaying and handling articles.
88 * The Server Buffer:: Making and editing virtual servers.
89 * Scoring:: Assigning values to articles.
90 * Various:: General purpose settings.
91 * Customization:: Tailoring Gnus to your needs.
92 * Troubleshooting:: What you might try if things do not work.
93 * The End:: Farewell and goodbye.
94 * Appendices:: Technical stuff, Emacs intro, FAQ
95 * Index:: Variable, function and concept index.
96 * Key Index:: Key Index.
103 @sc{gnus} was written by Masanobu UMEDA. When autumn crept up in '94,
104 Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
106 If you want to investigate the person responsible for this outrage, you
107 can point your (feh!) web browser to
108 @file{http://www.ifi.uio.no/~larsi/}. This is also the primary
109 distribution point for the new and spiffy versions of Gnus, also know as
110 The Site That Destroys Newsrcs And Drives People Mad.
112 During the first extended alpha period of develpment, the new Gnus was
113 called "(ding) Gnus". @dfn{(ding)}, is, of course, short for @dfn{ding
114 is not Gnus}, which is a total and utter lie, but who cares? (Besides,
115 the "Gnus" in this abbreviation should probably be pronounced "news" as
116 UMEDA intended, which makes it a more appropriate name, don't you
119 In any case, after spending all that energy with coming up with a new
120 and spiffy name, we decided that the name was @emph{too} spiffy, so we
121 renamamed it back again to "Gnus". But in mixed case. "Gnus" vs.
122 "@sc{gnus}". New vs. old.
124 Incidentally, the next Gnus generation will be called "September Gnus",
125 and won't be released until February. Confused? You will be.
128 * Why?:: What's the point of Gnus?
129 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
130 * Conformity:: Gnus tries to conform to all standards.
131 * Emacsen:: Gnus can be run on a few modern Emacsen.
132 * Contributors:: Oodles of people.
133 * New Features:: Pointers to some of the new stuff in Gnus.
134 * Newest Features:: Features so new that they haven't been written yet.
140 What's the point of Gnus?
142 I want to provide a "rad", "happening", "way cool" and "hep" newsreader,
143 that lets you do anything you can think of. That was my original
144 motivation, but while working on Gnus, it has become clear to me that
145 this generation of newsreaders really belong in the stone age.
146 Newsreaders haven't developed much since the infancy of the net. If the
147 volume continues to rise with the current rate of increase, all current
148 newsreaders will be pretty much useless. How do you deal with
149 newsgroups that have hundreds (or thousands) of new articles each day?
151 Gnus offer no real solutions to these questions, but I would very much
152 like to see Gnus being used as a testing ground for new methods of
153 reading and fetching news. Expanding on Umeda-san's wise decision to
154 separate the newsreader from the backends, Gnus now offers a simple
155 interface for anybody who wants to write new backends for fetching mail
156 and news from different sources. I have added hooks for customizations
157 everywhere I can imagine useful. By doing so, I'm inviting every one of
158 you to explore and invent new ways of reading news.
160 May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
163 @section Compatibility
165 @cindex compatibility
166 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
167 bindings have been kept. More key bindings have been added, of course,
168 but only in one or two obscure cases have old bindings been changed.
173 @center In a cloud bones of steel.
177 All commands have kept their names. Some internal functions have changed
180 The @code{gnus-uu} package has changed drastically. @xref{Decoding
183 One major compatibility question if the presence of several summary
184 buffers. All variables that are relevant while reading a group are
185 buffer-local to the summary buffer they belong in. Although most
186 important variables have their values copied into their global
187 counterparts whenever a command is executed in the summary buffer, this
188 change might lead to incorrect values being used unless you are careful.
190 All code that relies on knowledge of @sc{gnus} internals will probably
191 fail. To take two examples: Sorting @code{gnus-newsrc-assoc} (or
192 changing it in any way, as a matter of fact) is strictly verboten. Gnus
193 maintains a hash table that points to the entries in this assoc (which
194 speeds up many functions), and changing the assoc directly will lead to
199 Old hilit19 code does not work at all. In fact, you should probably
200 remove all hilit code from all Gnus hooks
201 (@code{gnus-group-prepare-hook}, @code{gnus-summary-prepare-hook} and
202 @code{gnus-summary-article-hook}). (Well, at the very least the first
203 two.) Gnus provides various integrated functions for highlighting.
204 These are faster and more accurate. To make life easier for everybody,
205 Gnus will by default remove all hilit calls from all hilit hooks.
208 Packages like @code{expire-kill} will no longer work. As a matter of
209 fact, you should probably remove all old @sc{gnus} packages (and other
210 code) when you start using Gnus. More likely than not, Gnus already
211 does what you have written code to make @sc{gnus} do. (Snicker.)
213 Even though old methods of doing things are still supported, only the
214 new methods are documented in this manual. If you detect a new method of
215 doing something while reading this manual, that does not mean you have
216 to stop doing it the old way.
218 Gnus understands all @sc{gnus} startup files.
221 Overall, a casual user who hasn't written much code that depends on
222 @sc{gnus} internals should suffer no problems. If problems occur,
223 please let me know (@kbd{M-x gnus-bug}).
229 No rebels without a clue here, ma'am. We conform to all standards known
230 to (wo)man. Except for those standards and/or conventions we disagree
236 There are no known breaches of this standard.
239 There are no known breaches of this standard, either.
241 @item Usenet Seal of Approval
242 Gnus hasn't been formally through the Seal process, but I have read
243 through the Seal text and I think Gnus would pass.
245 @item Son-of-RFC 1036
246 We do have some breaches to this one.
250 Gnus does no MIME handling, and this standard-to-be seems to think that
251 MIME is the bees' knees, so we have major breakage here.
253 This is considered to be a "vanity header", while I consider it to be
254 consumer information. After seeing so many badly formatted articles
255 coming from @code{tin} and @code{Netscape} I know not to use either of
256 those for posting articles. I would not have known that if it wasn't
257 for the @code{X-Newsreader} header.
259 Gnus breaks lines if this header is long. I infer from RFC1036 that
260 being conservative in what you output is not creating 5000-character
261 lines, so it seems like a good idea to me. However, this standard-to-be
262 says that whitespace in the @code{References} header is to be preserved,
263 so... It doesn't matter one way or the other to Gnus, so if somebody
264 tells me what The Way is, I'll change it. Or not.
269 If you ever see Gnus act noncompliantly to the texts mentioned above,
270 don't hesitate to drop a note to Gnus Towers and let us know.
280 Gnus should work on :
291 Mule versions based on Emacs 19.26 and up.
295 Gnus will absolutely not work on any Emacsen older than that. Not
298 There are some vague differences in what Gnus does, though:
303 The mouse-face on Gnus lines under Emacs and Mule is delimited to
304 certain parts of the lines while they cover the entire line under
308 The same with current-article marking---XEmacs puts an underline under
309 the entire summary line while Emacs and Mule are nicer and kinder.
312 XEmacs features more graphics---a logo and a toolbar.
315 Citation highlighting us better under Emacs and Mule than under XEmacs.
318 Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
325 @section Contributors
328 The new Gnus version couldn't have been done without the help of all the
329 people on the (ding) mailing list. Every day for months I have gotten
330 tens of nice bug reports from them, filling me with joy, every single
331 one of them. Smooches. The people on the list have been tried beyond
332 endurance, what with my "oh, that's a neat idea <type type>, yup, I'll
333 release it right away <ship off> no wait, that doesn't work at all <type
334 type>, yup, I'll ship that one off right away <ship off> no, wait, that
335 absolutely does not work" policy for releases. Micro$oft---bah.
336 Amateurs. I'm @emph{much} worse. (Or is that "worser"? "much worser"?
339 I would like to take this opportunity to thank the Academy for... oops,
344 Of course, GNUS was written by Masanobu UMEDA.
346 Many excellent functions, especially dealing with scoring and
347 highlighting (as well as the @sc{soup} support) was written
350 Innumerable bug fixes were written by Sudish Joseph.
352 @code{gnus-topic} was written by Ilja Weis.
354 The refcard was written by Vladimir Alexiev.
356 I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
358 @code{nnfolder} has been much enhanced by Scott Byer.
360 The orphan scoring was written by Peter Mutsaers.
362 GNU XEmacs support has been added by Fabrice Popineau.
364 POP mail support was written by Ken Raeburn.
366 Various bits and pieces, especially dealing with .newsrc files, were
367 suggested and added by Hallvard B Furuseth.
369 Brian Edmonds has written @code{gnus-bbdb}.
371 Ricardo Nassif did the proof-reading.
373 Kevin Davidson came up with the name @dfn{ding}, so blame him.
375 Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
376 Quinlan, Frank D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have
377 all contributed code and suggestions.
382 @section New Features
388 The look of all buffers can be changed by setting format-like variables
389 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
392 Local spool and several @sc{nntp} servers can be used at once
393 (@pxref{Foreign Groups}).
396 You can combine groups into virtual groups (@pxref{nnvirtual}).
399 You can read a number of different mail formats (@pxref{Reading Mail}).
400 All the mail backends implement a convenient mail expiry scheme
401 (@pxref{Expiring Old Mail Articles}).
404 Gnus can use various strategies for gathering threads that have lost
405 their roots (thereby gathering loose sub-threads into one thread) or it
406 can go back and retrieve enough headers to build a complete thread
407 (@pxref{Customizing Threading}).
410 Killed groups can be displayed in the group buffer, and you can read
414 Gnus can do partial group updates---you do not have to retrieve the
415 entire active file just to check for new articles in a few groups
416 (@pxref{The Active File}).
419 Gnus implements a sliding scale of subscribedness to groups
420 (@pxref{Group Levels}).
423 You can score articles according to any number of criteria
424 (@pxref{Scoring}). You can even get Gnus to find out how to score
425 articles for you (@pxref{Adaptive Scoring}).
428 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
429 manner, so it should be difficult to lose much data on what you have
430 read if your machine should go down (@pxref{Auto Save}).
433 Gnus now has its own startup file to avoid cluttering up the
437 You can set the process mark on both groups and articles and perform
438 operations on all the marked items (@pxref{Process/Prefix}).
441 You can grep through a subset of groups and create a group from the
442 results (@pxref{nnkiboze}).
445 You can list subsets of groups according to, well, anything
446 (@pxref{Listing Groups}).
449 You can browse foreign servers and subscribe to groups from those
450 servers (@pxref{Browse Foreign Server}).
453 Gnus can fetch articles asynchronously on a second connection to the
454 server (@pxref{Asynchronous Fetching}).
457 You can cache articles locally (@pxref{Article Caching}).
460 The uudecode functions have been expanded and generalized
461 (@pxref{Decoding Articles}).
464 You can still post uuencoded articles, which was a little-known feature
465 of @sc{gnus} past (@pxref{Uuencoding & Posting}).
468 Fetching parents (and other articles) now actually works without
469 glitches (@pxref{Finding the Parent}).
472 Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
475 Digests (and other files) can be used as the basis for groups
479 Articles can be highlighted and customized (@pxref{Customizing
483 URLs and other external references can be buttonized (@pxref{Article
487 All Gnus buffers can be customized in a difficult fashion
488 (@pxref{Windows Configuration}).
491 You can click on buttons instead of using the keyboard
496 This is, of course, just a @emph{short} overview of the @emph{most}
497 important new features. No, really. There are tons more. Yes, we have
498 feeping creaturism in full effect, but nothing too gratuitous, I would
502 @node Newest Features
503 @section Newest Features
506 Also known as the @dfn{todo list}. Sure to be implemented before the
509 Be afraid. Be very afraid.
513 Native @sc{mime} support is something that should be done.
515 @code{trn}-like trees.
517 @code{nn}-like pick-and-read summary interface.
523 Floating point group levels and group bubbling.
525 Automatic re-scan of incoming mail.
527 Buttonize more stuff in the article buffer.
529 A better and simpler method for specifying mail composing methods.
531 Marks for saved, forwarded, etc articles.
533 Speed up caching and adaptive scoring.
535 Gather thread by filling in missing Message-IDs.
539 Allow posting through mail-to-news gateways.
541 Speed up massive group massacres.
543 @code{jka-compr} isn't fully supported.
545 Create better digests.
547 Do better word-wrap on cited text.
549 Better X-Face support with X-Face databases and stuff.
551 Support SELF-DISCIPLINE pins.
553 Really do unbinhexing.
555 Listing of all active groups.
559 Do the X-Receipt-To thing.
561 Don't kill summary buffers upon exit from the groups.
563 Allow adaption on secondary marks.
566 And much, much, much more. There is more to come than has already been
567 implemented. (But that's always true, isn't it?)
569 @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
570 up-to-the-second todo list is located, so if you're really curious, you
571 could point your Web browser over that-a-way.
580 This is what you are supposed to use this thing for---reading news.
581 News is generally fetched from a nearby @sc{nntp} server, and is
582 generally publicly available to everybody. If you post news, the entire
583 world is likely to read just what you have written, and they'll all
584 snigger mischievously. Behind your back.
587 Everything that's delivered to you personally is mail. Some news/mail
588 readers (like Gnus) blur the distinction between mail and news, but
589 there is a difference. Mail is private. News is public. Mailing is
590 not posting, and replying is not following up.
592 Send a mail to the person who has written what you are reading.
594 Post an article to the current newsgroup responding to the article you
597 Gnus gets fed articles from a number of backends, both news and mail
598 backends. Gnus does not handle the underlying media, so to speak---this
599 is all done by the backends.
601 Gnus will always use one method (and backend) as the @dfn{native}, or
602 default, way of getting news.
604 You can also have any number of foreign groups at the same time. These
605 are groups that use different backends for getting news.
608 The top part of an article, where administration information (etc.) is
612 The rest of an article. Everything that is not in the head is in the
616 A line from the head of an article.
619 A collection of such lines, or a collection of heads. Or even a
620 collection of @sc{nov} lines.
623 When Gnus enters a group, it asks the backend for the headers for all
624 the unread articles in the group. Most servers support the News OverView
625 format, which is much smaller and much faster to read than the normal
629 Each group is subscribed at some @dfn{level} or other (1-9). The ones
630 that have a lower level are "more" subscribed than the groups with a
631 higher level. In fact, groups on levels 1-5 are considered
632 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
633 are @dfn{killed}. Commands for listing groups and scanning for new
634 articles will all use the numeric prefix as @dfn{working level}.
636 @cindex killed groups
637 No information on killed groups is stored or updated, which makes killed
638 groups much easier to handle than subscribed groups.
640 @cindex zombie groups
641 Just like killed groups, only slightly less dead.
644 The news server has to keep track of what articles it carries, and what
645 groups exist. All this information in stored in the active file, which
646 is rather large, as you might surmise.
649 A group that exists in the @file{.newsrc} file, but isn't known to the
650 server (i. e., it isn't in the active file), is a @emph{bogus group}.
651 This means that the group probably doesn't exist (any more).
655 @chapter Starting Gnus
659 If your system administrator has set things up properly, starting Gnus
660 and reading news is extremely easy---you just type @kbd{M-x gnus}.
662 If things do not go smoothly at startup, you have to twiddle some
666 * Finding the News:: Choosing a method for getting news.
667 * The First Time:: What does Gnus do the first time you start it?
668 * The Server is Down:: How can I read my mail then?
669 * Slave Gnusii:: You can have more than one Gnus active at a time.
670 * Fetching a Group:: Starting Gnus just to read a group.
671 * New Groups:: What is Gnus supposed to do with new groups?
672 * Startup Files:: Those pesky startup files---@file{.newsrc}.
673 * Auto Save:: Recovering from a crash.
674 * The Active File:: Reading the active file over a slow line Takes Time.
675 * Startup Variables:: Other variables you might change.
678 @node Finding the News
679 @section Finding the News
681 @vindex gnus-select-method
682 The @code{gnus-select-method} variable controls how Gnus finds news.
683 This variable should be a list where the first element says @dfn{how}
684 and the second element says @dfn{where}. This method is is your native
685 method. All groups that are not fetched with this method are foreign
688 For instance, if you want to get your daily dosage of news from the
689 @samp{news.somewhere.edu} @sc{nntp} server, you'd say:
692 (setq gnus-select-method '(nntp "news.somewhere.edu"))
695 If you want to read directly from the local spool, say:
698 (setq gnus-select-method '(nnspool ""))
701 If you can use a local spool, you probably should, as it will almost
702 certainly be much faster.
704 @vindex gnus-nntpserver-file
706 @cindex @sc{nntp} server
707 If this variable is not set, Gnus will take a look at the
708 @code{NNTPSERVER} environment variable. If that variable isn't set,
709 Gnus will see whether @code{gnus-nntpserver-file} (default
710 @file{/etc/nntpserver}) has any opinions in the matter. It that fails
711 as well, Gnus will will try to use the machine that is running Emacs as
712 an @sc{nntp} server. That's a longshot, though.
714 @vindex gnus-nntp-server
715 If @code{gnus-nntp-server} is set, this variable will override
716 @code{gnus-select-method}. You should therefore set
717 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
719 @vindex gnus-secondary-servers
720 You can also make Gnus prompt you interactively for the name of an
721 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
722 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
723 in the @code{gnus-secondary-servers} list (if any). You can also just
724 type in the name of any server you feel like visiting.
726 However, if you use one @sc{nntp} server regularly, and are just
727 interested in a couple of groups from a different server, you would be
728 better served by using the @code{gnus-group-browse-foreign-server}
729 command from the group buffer. It will let you have a look at what
730 groups are available, and you can subscribe to any of the groups you
731 want to. This also makes @file{.newsrc} maintenance much tidier.
732 @xref{Foreign Groups}.
734 @vindex gnus-secondary-select-methods
735 A slightly different approach to foreign groups is to set the
736 @code{gnus-secondary-select-methods} variable. The select methods
737 listed in this variable are in many ways just as native as the
738 @code{gnus-select-method} server. They will also be queried for active
739 files during startup (if that's required), and new newsgroups that
740 appear on these servers will be subscribed (or not) just as native
743 For instance, if you use the @code{nnmbox} backend to read you mail, you
744 would typically set this variable to
747 (setq gnus-secondary-select-methods '((nnmbox "")))
751 @section The First Time
752 @cindex first time usage
754 If no startup files exist, Gnus will try to determine what groups should
755 be subscribed by default.
757 @vindex gnus-default-subscribed-newsgroups
758 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
759 will subscribe you to just those groups in that list, leaving the rest
760 killed. Your system administrator should have set this variable to
763 Since she hasn't, Gnus will just subscribe you to a few randomly picked
764 groups (i.e., @samp{*.newusers}). (@dfn{Random} is here defined as
765 "whatever Lars thinks you should read".)
767 You'll also be subscribed to the Gnus documentation group, which should
768 help you with most common problems.
770 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
771 use the normal functions for handling new groups, and not do anything
774 @node The Server is Down
775 @section The Server is Down
776 @cindex server errors
778 If the default server is down, Gnus will understandably have some
779 problems starting. However, if you have some mail groups in addition to
780 the news groups, you may want to start Gnus anyway.
782 Gnus, being the trusting sort of program, will ask whether to proceed
783 without a native select method if that server can't be contacted. This
784 will happen whether the server doesn't actually exist (i.e., you have
785 given the wrong address) or the server has just momentarily taken ill
786 for some reason or other.
788 If Gnus says "nntp server on <your server> can't be opened. Continue?",
789 you do not want to continue unless you have some foreign groups that you
790 want to read. Even if you don't, Gnus will let you continue, but you'll
791 find it difficult to actually do anything in the group buffer. But,
792 hey, that's your problem. Blllrph!
794 @findex gnus-no-server
795 If you know that the server is definitely down, or you just want to read
796 your mail without bothering with the server at all, you can use the
797 @code{gnus-no-server} command to start Gnus. That might come in handy
798 if you're in a hurry as well.
802 @section Slave Gnusiï
805 You might want to run more than one Emacs with more than one Gnus at the
806 same time. If you are using different @file{.newsrc} files (eg., if you
807 are using the two different Gnusiï to read from two different servers),
808 that is no problem whatsoever. You just do it.
810 The problem appears when you want to run two Gnusiï that use the same
813 To work around that problem some, we here at the Think-Tank at the Gnus
814 Towers have come up with a new concept: @dfn{Masters} and
815 @dfn{servants}. (We have applied for a patent on this concept, and have
816 taken out a copyright on those words. If you wish to use those words in
817 conjunction with each other, you have to send $1 per usage instance to
818 me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
819 Applications}) will be much more expensive, of course.)
821 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
822 however you do it). Each subsequent slave Gnusiï should be started with
823 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
824 files, but some slave files that contains information only on what
825 groups have been read in the slave session. When a master Gnus starts,
826 it will read (and delete) these slave files, incorporating all
827 information from all of them. (The slave files will be read in the
828 sequence they were created, so the latest changes will have precedence.)
830 Information from the slave files has, of course, presedence over the
831 information in the normal (i. e., master) @code{.newsrc} file.
834 @node Fetching a Group
835 @section Fetching a Group
837 @findex gnus-fetch-group
838 It it sometime convenient to be able to just say "I want to read this
839 group and I don't care whether Gnus has been started or not". This is
840 perhaps more useful for people who write code than for users, but the
841 command @code{gnus-fetch-group} provides this functionality in any
842 case. It takes the group name as a paramenter.
849 @vindex gnus-subscribe-newsgroup-method
850 What Gnus does when it encounters a new group is determined by the
851 @code{gnus-subscribe-newsgroup-method} variable.
853 This variable should contain a function. Some handy pre-fab values
857 @item gnus-subscribe-randomly
858 @vindex gnus-subscribe-randomly
859 Subscribe all new groups randomly.
860 @item gnus-subscribe-alphabetically
861 @vindex gnus-subscribe-alphabetically
862 Subscribe all new groups alphabetically.
863 @item gnus-subscribe-hierarchically
864 @vindex gnus-subscribe-hierarchically
865 Subscribe all new groups hierarchically.
866 @item gnus-subscribe-interactively
867 @vindex gnus-subscribe-interactively
868 Subscribe new groups interactively. This means that Gnus will ask
869 you about @strong{all} new groups.
871 @item gnus-subscribe-zombies
872 @vindex gnus-subscribe-zombies
873 Make all new groups zombies. You can browse the zombies later (with
874 @kbd{A z}) and either kill them all off properly, or subscribe to them.
878 @vindex gnus-subscribe-hierarchical-interactive
879 A closely related variable is
880 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
881 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
882 hierarchical fashion whether to subscribe to new groups or not. Gnus
883 will ask you for each sub-hierarchy whether you want to descend the
886 One common way to control which new newsgroups should be subscribed or
887 ignored is to put an @dfn{options} line at the start of the
888 @file{.newsrc} file. Here's an example:
891 options -n !alt.all !rec.all sci.all
894 @vindex gnus-subscribe-options-newsgroup-method
895 This line obviously belongs to a serious-minded intellectual scientific
896 person (or she may just be plain old boring), because it says that all
897 groups that have names beginning with @samp{alt} and @samp{rec} should
898 be ignored, and all groups with names beginning with @samp{sci} should
899 be subscribed. Gnus will not use the normal subscription method for
900 subscribing these groups.
901 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
902 variable defaults to @code{gnus-subscribe-alphabetically}.
904 @vindex gnus-options-not-subscribe
905 @vindex gnus-options-subscribe
906 If you don't want to mess with your @file{.newsrc} file, you can just
907 set the two variables @code{gnus-options-subscribe} and
908 @code{gnus-options-not-subscribe}. These two variables do exactly the
909 same as the @file{.newsrc} options -n trick. Both are regexps, and if
910 the the new group matches the first, it will be unconditionally
911 subscribed, and if it matches the latter, it will be ignored.
913 @vindex gnus-auto-subscribed-groups
914 Yet another variable that meddles here is
915 @code{gnus-auto-subscribed-groups}. It works exactly like
916 @code{gnus-options-subscribe}, and is therefore really superfluos, but I
917 thought it would be nice to have two of these. This variable is more
918 meant for setting some ground rules, while the other variable is used
919 more for user fiddling. By default this variable makes all new groups
920 that come from mail backends (@code{nnml}, @code{nnbabyl},
921 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
922 don't like that, just set this variable to @code{nil}.
924 @vindex gnus-check-new-newsgroups
925 If you are satisfied that you really never want to see any new groups,
926 you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
927 also save you some time at startup. Even if this variable is
928 @code{nil}, you can always subscribe to the new groups just by pressing
929 @kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
930 is @code{t} by default.
932 Gnus normally determines whether a group is new or not by comparing the
933 list of groups from the active file(s) with the lists of subscribed and
934 dead groups. This isn't a particularly fast method. If
935 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
936 server for new groups since the last time. This is both faster &
937 cheaper. This also means that you can get rid of the list of killed
938 groups altogether, so you may set @code{gnus-save-killed-list} to
939 @code{nil}, which will save time both at startup, at exit, and all over.
940 Saves disk space, too. Why isn't this the default, then?
941 Unfortunately, not all servers support this function.
943 This variable can also be a list of select methods. If so, Gnus will
944 issue an @code{ask-server} command to each of the select methods, and
945 subscribe them (or not) using the normal methods. This might be handy
946 if you are monitoring a few servers for new groups. A side effect is
947 that startup will take much longer, so you can meditate while waiting.
948 Use the mantra "dingnusdingnusdingnus" to achieve permanent happiness.
951 @section Startup Files
952 @cindex startup files
955 Now, you all know about the @file{.newsrc} file. All subscription
956 information is traditionally stored in this file.
958 Things got a bit more complicated with @sc{gnus}. In addition to
959 keeping the @file{.newsrc} file updated, it also used a file called
960 @file{.newsrc.el} for storing all the information that didn't fit into
961 the @file{.newsrc} file. (Actually, it duplicated everything in the
962 @file{.newsrc} file.) @sc{gnus} would read whichever one of these files
963 that were the most recently saved, which enabled people to swap between
964 @sc{gnus} and other newsreaders.
966 That was kinda silly, so Gnus went one better: In addition to the
967 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
968 @file{.newsrc.eld}. It will read whichever of these files that are most
969 recent, but it will never write a @file{.newsrc.el} file.
971 @vindex gnus-save-newsrc-file
972 You can also turn off writing the @file{.newsrc} file by setting
973 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
974 the file and save some space, as well as making exit from Gnus faster.
975 However, this will make it impossible to use other newsreaders than
976 Gnus. But hey, who would want to, right?
978 @vindex gnus-save-killed-list
979 If @code{gnus-save-killed-list} is @code{nil}, Gnus will not save the
980 list of killed groups to the startup file. This will save both time
981 (when starting and quitting) and space (on disk). It will also means
982 that Gnus has no record of what groups are new or old, so the automatic
983 new groups subscription methods become meaningless. You should always
984 set @code{gnus-check-new-newsgroups} to @code{nil} or @code{ask-server}
985 if you set this variable to @code{nil} (@pxref{New Groups}).
987 @vindex gnus-startup-file
988 The @code{gnus-startup-file} variable says where the startup files are.
989 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
990 file being whatever that one is with a @samp{.eld} appended.
992 @vindex gnus-save-newsrc-hook
993 @vindex gnus-save-quick-newsrc-hook
994 @vindex gnus-save-standard-newsrc-hook
995 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
996 files, while @code{gnus-save-quick-newsrc-hook} is called just before
997 saving the @file{.newsrc.eld} file, and
998 @code{gnus-save-standard-newsrc-hook} is called just before saving the
999 @file{.newsrc} file. The latter two are commonly used to turn version
1000 control on or off. Version control is off by default when saving.
1004 @cindex dribble file
1007 Whenever you do something that changes the Gnus data (reading articles,
1008 catching up, killing/subscribing groups), the change is added to a
1009 special @dfn{dribble buffer}. This buffer is auto-saved the normal
1010 Emacs way. If your Emacs should crash before you have saved the
1011 @file{.newsrc} files, all changes you have made can be recovered from
1014 If Gnus detects this file at startup, it will ask the user whether to
1015 read it. The auto save file is deleted whenever the real startup file is
1018 @vindex gnus-use-dribble-file
1019 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
1020 maintain a dribble buffer. The default is @code{t}.
1022 @vindex gnus-dribble-directory
1023 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
1024 this variable is @code{nil}, which it is by default, Gnus will dribble
1025 into the same directory as the @file{.newsrc} file is located. (This is
1026 normally the user's home directory.)
1028 @node The Active File
1029 @section The Active File
1031 @cindex ignored groups
1033 When Gnus starts, or indeed whenever it tries to determine whether new
1034 articles have arrived, it reads the active file. This is a very large
1035 file that lists all the active groups and articles on the @sc{nntp}
1038 @vindex gnus-ignored-newsgroups
1039 Before examining the active file, Gnus deletes all lines that match the
1040 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
1041 any groups with bogus names, but you can use this variable to make Gnus
1042 ignore hierarchies you aren't ever interested in. This variable is
1043 @code{nil} by default, and will slow down active file handling somewhat
1044 if you set it to anything else.
1046 @vindex gnus-read-active-file
1047 The active file can be rather Huge, so if you have a slow network, you
1048 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
1049 reading the active file. This variable is @code{t} by default.
1051 Gnus will try to make do by just getting information on the groups
1052 that you actually subscribe to.
1054 Note that if you subscribe to lots and lots of groups, setting this
1055 variable to @code{nil} will probably make Gnus slower, not faster. At
1056 present, having this variable @code{nil} will slow Gnus down
1057 considerably, unless you read news over a 2400 baud modem.
1059 This variable can also have the value @code{some}. Gnus will then
1060 attempt to read active info only on the subscribed groups. On some
1061 servers this is quite fast (on sparkling, brand new INN servers that
1062 support the @samp{LIST ACTIVE group} command), on others this is not
1063 fast at all. In any case, @code{some} should be faster than @code{nil},
1064 and is certainly faster than @code{t} over slow lines.
1066 If this variable is @code{nil}, Gnus will as for group info in total
1067 lock-step, which isn't very fast. If it is @code{some} and you use an
1068 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
1069 read all the replies in one swoop. This will normally result in better
1070 performance, but if the server does not support the aforementioned
1071 @samp{LIST ACTIVE group} command, this isn't very nice to the server.
1073 In any case, if you use @code{some} or @code{nil}, you should kill all
1074 groups that you aren't interested in.
1076 @node Startup Variables
1077 @section Startup Variables
1080 @item gnus-load-hook
1081 @vindex gnus-load-hook
1082 A hook that is run while Gnus is being loaded. Note that this hook will
1083 normally be run just once in each Emacs session, no matter how many
1084 times you start Gnus.
1086 @item gnus-startup-hook
1087 @vindex gnus-startup-hook
1088 A hook that is run after starting up Gnus successfully.
1090 @item gnus-check-bogus-newsgroups
1091 @vindex gnus-check-bogus-newsgroups
1092 If non-@code{nil}, Gnus will check for and delete all bogus groups at
1093 startup. A @dfn{bogus group} is a group that you have in your
1094 @file{.newsrc} file, but doesn't exist on the news server. Checking for
1095 bogus groups isn't very quick, so to save time and resources, it's best
1096 to leave this option off, and instead do the checking for bogus groups
1097 once in a while from the group buffer (@pxref{Group Maintenance}).
1099 @item gnus-inhibit-startup-message
1100 @vindex gnus-inhibit-startup-message
1101 If non-@code{nil}, the startup message won't be displayed. That way,
1102 your boss might not notice that you are reading news instead of doing
1105 @item gnus-no-groups-message
1106 @vindex gnus-no-groups-message
1107 Message displayed by Gnus when no groups are available.
1110 @node The Group Buffer
1111 @chapter The Group Buffer
1112 @cindex group buffer
1114 The @dfn{group buffer} lists all (or parts) of the available groups. It
1115 is the first buffer shown when Gnus starts, and will never be killed as
1116 long as Gnus is active.
1119 * Group Buffer Format:: Information listed and how you can change it.
1120 * Group Maneuvering:: Commands for moving in the group buffer.
1121 * Selecting a Group:: Actually reading news.
1122 * Subscription Commands:: Unsubscribing, killing, subscribing.
1123 * Group Levels:: Levels? What are those, then?
1124 * Group Score:: A mechanism for finding out what groups you like.
1125 * Marking Groups:: You can mark groups for later processing.
1126 * Foreign Groups:: How to create foreign groups.
1127 * Group Parameters:: Each group may have different parameters set.
1128 * Listing Groups:: Gnus can list various subsets of the groups.
1129 * Sorting Groups:: Re-arrange the group order.
1130 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
1131 * Browse Foreign Server:: You can browse a server. See what if has to offer.
1132 * Exiting Gnus:: Stop reading news and get some work done.
1133 * Group Topics:: A folding group mode divided into topics.
1134 * Misc Group Stuff:: Other stuff that you can to do.
1137 @node Group Buffer Format
1138 @section Group Buffer Format
1139 @cindex group buffer format
1141 The default format of the group buffer is nice and dull, but you can
1142 make it as exciting and ugly as you feel like.
1144 Here's a couple of example group lines:
1147 25: news.announce.newusers
1148 * 0: alt.fan.andrea-dworkin
1153 You can see that there are 25 unread articles in
1154 @samp{news.announce.newusers}. There are no unread articles, but some
1155 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1156 asterisk at the beginning of the line?)
1158 @vindex gnus-group-line-format
1159 You can fuck that up to your heart's delight by fiddling with the
1160 @code{gnus-group-line-format} variable. This variable works along the
1161 lines of a @code{format} specification, which is pretty much the same as
1162 a @code{printf} specifications, for those of you who use (feh!) C.
1163 @xref{Formatting Variables}.
1165 The default value that produced those lines above is
1166 @samp{"%M%S%5y: %(%g%)\n"}.
1168 There should always be a colon on the line; the cursor always moves to
1169 the colon after performing an operation. Nothing else is required---not
1170 even the group name. All displayed text is just window dressing, and is
1171 never examined by Gnus. Gnus stores all real information it needs using
1174 (Note that if you make a really strange, wonderful, spreadsheet-like
1175 layout, everybody will believe you are hard at work with the accounting
1176 instead of wasting time reading news.)
1178 Here's a list of all available format characters:
1182 Only marked articles.
1184 Whether the group is subscribed.
1186 Level of subscribedness.
1188 Number of unread articles.
1190 Number of dormant articles.
1192 Number of ticked articles.
1194 Number of read articles.
1196 Total number of articles.
1198 Number of unread, unticked, non-dormant articles.
1200 Number of ticked and dormant articles.
1206 Newsgroup description.
1216 A string that looks like @samp{<%s:%n>} if a foreign select method is
1219 Short (collapsed) group name.
1221 User defined specifier. The next character in the format string should
1222 be a letter. @sc{gnus} will call the function
1223 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1224 following @samp{%u}. The function will be passed the current headers as
1225 argument. The function should return a string, which will be inserted
1226 into the buffer just like information from any other specifier.
1230 All the "number-of" specs will be filled with an asterisk (@samp{*}) if
1231 no info is available---for instance, if it is a non-activated foreign
1232 group, or a bogus (or semi-bogus) native group.
1234 @vindex gnus-group-mode-line-format
1235 The mode line can be changed by setting
1236 (@code{gnus-group-mode-line-format}). It doesn't understand that many
1241 Default news server.
1243 Default select method.
1246 @node Group Maneuvering
1247 @section Group Maneuvering
1248 @cindex group movement
1250 All movement commands understand the numeric prefix and will behave as
1251 expected, hopefully.
1256 @findex gnus-group-next-unread-group
1257 Go to the next group that has unread articles
1258 (@code{gnus-group-next-unread-group}).
1263 @findex gnus-group-prev-unread-group
1264 Go to the previous group group that has unread articles
1265 (@code{gnus-group-prev-unread-group}).
1268 @findex gnus-group-next-group
1269 Go to the next group (@code{gnus-group-next-group}).
1272 @findex gnus-group-prev-group
1273 Go to the previous group (@code{gnus-group-prev-group}).
1276 @findex gnus-group-next-unread-group-same-level
1277 Go to the next unread group on the same level (or lower)
1278 (@code{gnus-group-next-unread-group-same-level}).
1281 @findex gnus-group-prev-unread-group-same-level
1282 Go to the previous unread group on the same level (or lower)
1283 (@code{gnus-group-prev-unread-group-same-level}).
1286 Three commands for jumping to groups:
1291 @findex gnus-group-jump-to-group
1292 Jump to a group (and make it visible if it isn't already)
1293 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1297 @findex gnus-group-best-unread-group
1298 Jump to the unread group with the lowest level
1299 (@code{gnus-group-best-unread-group}).
1302 @findex gnus-group-first-unread-group
1303 Jump to the first group with unread articles
1304 (@code{gnus-group-first-unread-group}).
1307 @vindex gnus-group-goto-unread
1308 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1309 commands will move to the next group, not the next unread group. Even
1310 the commands that say they move to the next unread group. The default
1313 @node Selecting a Group
1314 @section Selecting a Group
1315 @cindex group selection
1320 @kindex SPACE (Group)
1321 @findex gnus-group-read-group
1322 Select the current group, switch to the summary buffer and display the
1323 first unread article (@code{gnus-group-read-group}). If there are no
1324 unread articles in the group, or if you give a non-numerical prefix to
1325 this command, Gnus will offer to fetch all the old articles in this
1326 group from the server. If you give a numerical prefix @var{N}, Gnus
1327 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1328 the @var{N} newest articles, if @var{N} is negative, fetch the
1329 @var{abs(N)} oldest articles.
1333 @findex gnus-group-select-group
1334 Select the current group and switch to the summary buffer
1335 (@code{gnus-group-select-group}). Takes the same arguments as
1336 @code{gnus-group-read-group}---the only difference is that this command
1337 does not display the first unread article automatically upon group
1341 @kindex M-RET (Group)
1342 @findex gnus-group-quick-select-group
1343 This does the same as the command above, but tries to do it with the
1344 minimum amount off fuzz (@code{gnus-group-quick-select-group}). No
1345 scoring/killing will be performed, there will be no highlights and no
1346 expunging. This might be useful if you're in a real hurry and have to
1347 enter some humongous groups.
1351 @findex gnus-group-catchup-current
1352 Mark all unticked articles in this group as read
1353 (@code{gnus-group-catchup-current}).
1357 @findex gnus-group-catchup-current-all
1358 Mark all articles in this group, even the ticked ones, as read
1359 (@code{gnus-group-catchup-current-all}).
1362 @vindex gnus-large-newsgroup
1363 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1364 to be a big group. This is 200 by default. If the group has more
1365 unread articles than this, Gnus will query the user before entering the
1366 group. The user can then specify how many articles should be fetched
1367 from the server. If the user specifies a negative number (@samp{-n}),
1368 the @samp{n} oldest articles will be fetched. If it is positive, the
1369 @samp{n} articles that have arrived most recently will be fetched.
1371 @vindex gnus-select-group-hook
1372 @vindex gnus-auto-select-first
1373 @code{gnus-auto-select-first} control whether any articles are selected
1374 automatically when entering a group.
1378 Don't select any articles when entering the group. Just display the
1379 full summary buffer.
1382 Select the first unread article when entering the group.
1385 Select the most high-scored article in the group when entering the
1389 If you want to prevent automatic selection in some group (say, in a
1390 binary group with Huge articles) you can set this variable to @code{nil}
1391 in @code{gnus-select-group-hook}, which is called when a group is
1394 @findex gnus-thread-sort-by-total-score
1395 @findex gnus-thread-sort-by-date
1396 @findex gnus-thread-sort-by-score
1397 @findex gnus-thread-sort-by-subject
1398 @findex gnus-thread-sort-by-author
1399 @findex gnus-thread-sort-by-number
1400 @vindex gnus-thread-sort-functions
1401 If you are using a threaded summary display, you can sort the threads by
1402 setting @code{gnus-thread-sort-functions}, which is a list of functions.
1403 By default, sorting is done on article numbers. Ready-made sorting
1404 functions include @code{gnus-thread-sort-by-number},
1405 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
1406 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score},
1407 @code{gnus-thread-sort-by-total-score}.
1409 Each function takes two threads and return non-@code{nil} if the first
1410 thread should be sorted before the other. If you use more than one
1411 function, the primary sort key should be the last function in the list.
1413 If you would like to sort by score, then by subject, and finally by
1414 date, you could do something like:
1417 (setq gnus-thread-sort-functions
1418 '(gnus-thread-sort-by-date
1419 gnus-thread-sort-by-subject
1420 gnus-thread-sort-by-score))
1423 @vindex gnus-thread-score-function
1424 The function in the @code{gnus-thread-score-function} variable (default
1425 @code{+}) is used for calculating the total score of a thread. Useful
1426 functions might be @code{max}, @code{min}, or squared means, or whatever
1430 @node Subscription Commands
1431 @section Subscription Commands
1439 @findex gnus-group-unsubscribe-current-group
1440 Toggle subscription to the current group
1441 (@code{gnus-group-unsubscribe-current-group}).
1446 @findex gnus-group-unsubscribe-group
1447 Prompt for a group to subscribe, and then subscribe it. If it was
1448 subscribed already, unsubscribe it instead
1449 (@code{gnus-group-unsubscribe-group}).
1454 @findex gnus-group-kill-group
1455 Kill the current group (@code{gnus-group-kill-group}).
1460 @findex gnus-group-yank-group
1461 Yank the last killed group (@code{gnus-group-yank-group}).
1466 @findex gnus-group-kill-region
1467 Kill all groups in the region (@code{gnus-group-kill-region}).
1470 @findex gnus-group-kill-all-zombies
1471 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1474 Also @xref{Group Levels}.
1477 @section Group Levels
1480 All groups have a level of @dfn{subscribedness}. For instance, if a
1481 group is on level 2, it is more subscribed than a group on level 5. You
1482 can ask Gnus to just list groups on a given level or lower
1483 (@pxref{Listing Groups}), or to just check for new articles in groups on
1484 a given level or lower (@pxref{Misc Group Stuff}).
1489 @findex gnus-group-set-current-level
1490 Set the level of the current group. If a numeric prefix is given, the
1491 next @var{n} groups will have their levels set. The user will be
1492 prompted for a level.
1495 @vindex gnus-level-killed
1496 @vindex gnus-level-zombie
1497 @vindex gnus-level-unsubscribed
1498 @vindex gnus-level-subscribed
1499 Gnus considers groups on between levels 1 and
1500 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
1501 @code{gnus-level-subscribed} (exclusive) and
1502 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
1503 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
1504 (default 8) and @code{gnus-level-killed} to be killed (default 9),
1505 completely dead. Gnus treats subscribed and unsubscribed groups exactly
1506 the same, but zombie and killed groups have no information on what
1507 articles you have read, etc, stored. This distinction between dead and
1508 living groups isn't done because it is nice or clever, it is done purely
1509 for reasons of efficiency.
1511 It is recommended that you keep all your mail groups (if any) on quite
1512 low levels (eg. 1 or 2).
1514 If you want to play with the level variables, you should show some care.
1515 Set them once, and don't touch them ever again. Better yet, don't touch
1516 them at all unless you know exactly what you're doing.
1518 @vindex gnus-level-default-unsubscribed
1519 @vindex gnus-level-default-subscribed
1520 Two closely related variables are @code{gnus-level-default-subscribed}
1521 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
1522 which are the levels that new groups will be put on if they are
1523 (un)subscribed. These two variables should, of course, be inside the
1524 relevant legal ranges.
1526 @vindex gnus-keep-same-level
1527 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1528 will only move to groups that are of the same level (or lower). In
1529 particular, going from the last article in one group to the next group
1530 will go to the next group of the same level (or lower). This might be
1531 handy if you want to read the most important groups before you read the
1534 @vindex gnus-group-default-list-level
1535 All groups with a level less than or equal to
1536 @code{gnus-group-default-list-level} will be listed in the group buffer
1539 @vindex gnus-group-use-permament-levels
1540 If @code{gnus-group-use-permament-levels} is non-@code{nil}, once you
1541 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1542 use this level as the "work" level.
1546 @section Group Score
1549 You would normally keep important groups on high levels, but that scheme
1550 is somewhat restrictive. Don't you wish you could have Gnus sort the
1551 group buffer according to how often you read groups, perhaps? Within
1554 This is what @dfn{group score} is for. You can assign a score to each
1555 group. You can then sort the group buffer based on this score.
1556 Alternatively, you can sort on score and then level. (Taken together,
1557 the level and the score is called the @dfn{rank} of the group. A group
1558 that is on level 4 and has a score of 1 has a higher rank than a group
1559 on level 5 that has a score of 300. (The level is the most significant
1560 part and the score is the least significant part.)
1562 @findex gnus-summary-bubble-group
1563 If you want groups you read often to get higher scores than groups you
1564 read seldom you can add the @code{gnus-summary-bubble-group} function to
1565 the @code{gnus-summary-exit-hook} hook. This will result (after
1566 sorting) in a bubbling sort of action. If you want to see that in
1567 action after each summary exit, you can add
1568 @code{gnus-group-sort-groups-by-rank} or
1569 @code{gnus-group-sort-groups-by-score} to the same hook, but that will
1570 slow things down somewhat.
1573 @node Marking Groups
1574 @section Marking Groups
1575 @cindex marking groups
1577 If you want to perform some command on several groups, and they appear
1578 subsequently in the group buffer, you would normally just give a
1579 numerical prefix to the command. Most group commands will then do your
1580 bidding on those groups.
1582 However, if the groups are not in sequential order, you can still
1583 perform a command on several groups. You simply mark the groups first
1584 with the process mark and then execute the command.
1592 @findex gnus-group-mark-group
1593 Set the mark on the current group (@code{gnus-group-mark-group}).
1599 @findex gnus-group-unmark-group
1600 Remove the mark from the current group
1601 (@code{gnus-group-unmark-group}).
1605 @findex gnus-group-mark-region
1606 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1610 @findex gnus-group-mark-regexp
1611 Mark all groups that match some regular expression
1612 (@code{gnus-group-mark-regexp}).
1615 Also @xref{Process/Prefix}.
1618 @node Foreign Groups
1619 @section Foreign Groups
1620 @cindex foreign groups
1622 A @dfn{foreign group} is a group that is not read by the usual (or
1623 default) means. It could be, for instance, a group from a different
1624 @sc{nntp} server, it could be a virtual group, or it could be your own
1625 personal mail group.
1627 A foreign group (or any group, really) is specified by a @dfn{name} and
1628 a @dfn{select method}. To take the latter first, a select method is a
1629 list where the first element says what backend to use (eg. @code{nntp},
1630 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
1631 name}. There may be additional elements in the select method, where the
1632 value may have special meaning for the backend in question.
1634 One could say that a select method defines a @dfn{virtual server}---so
1635 we do just that (@pxref{The Server Buffer}).
1637 The @dfn{name} of the group is the name the backend will recognize the
1640 For instance, the group @samp{soc.motss} on the @sc{nntp} server
1641 @samp{some.where.edu} will have the name @samp{soc.motss} and select
1642 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
1643 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
1644 @code{nntp} backend just knows this group as @samp{soc.motss}.
1646 Here are some commands for making and editing general foreign groups,
1647 and some commands to ease the creation of some special-purpose groups:
1652 @findex gnus-group-make-group
1653 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
1654 for a name, a method and possibly an @dfn{address}. For an easier way
1655 to subscribe to @sc{nntp} groups, @xref{Browse Foreign Server}.
1659 @findex gnus-group-rename-group
1660 Rename the current group to something else
1661 (@code{gnus-group-rename-group}). This is legal only on some groups --
1662 mail groups mostly. This command might very well be quite slow on some
1667 @findex gnus-group-edit-group-method
1668 Enter a buffer where you can edit the select method of the current
1669 group (@code{gnus-group-edit-group-method}).
1673 @findex gnus-group-edit-group-parameters
1674 Enter a buffer where you can edit the group parameters
1675 (@code{gnus-group-edit-group-parameters}).
1679 @findex gnus-group-edit-group
1680 Enter a buffer where you can edit the group info
1681 (@code{gnus-group-edit-group}).
1685 @findex gnus-group-make-directory-group
1686 Make a directory group. You will be prompted for a directory name
1687 (@code{gnus-group-make-directory-group}).
1691 @findex gnus-group-make-help-group
1692 Make the Gnus help group (@code{gnus-group-make-help-group}).
1696 @findex gnus-group-make-archive-group
1697 @vindex gnus-group-archive-directory
1698 @vindex gnus-group-recent-archive-directory
1699 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
1700 default a group pointing to the most recent articles will be created
1701 (@code{gnus-group-recent-archibe-directory}), but given a prefix, a full
1702 group will be created from from @code{gnus-group-archive-directory}.
1706 @findex gnus-group-make-kiboze-group
1707 Make a kiboze group. You will be prompted for a name, for a regexp to
1708 match groups to be "included" in the kiboze group, and a series of
1709 strings to match on headers (@code{gnus-group-make-kiboze-group}).
1713 @findex gnus-group-enter-directory
1714 Read a random directory as if with were a newsgroup with the
1715 @code{nneething} backend (@code{gnus-group-enter-directory}).
1719 @findex gnus-group-make-doc-group
1720 Make a group based on some file or other
1721 (@code{gnus-group-make-doc-group}). If you give a prefix to this
1722 command, you will be prompted for a file name and a file type.
1723 Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
1724 @code{mmdf}, and @code{forward}. If you run this command without a
1725 prefix, Gnus will guess at the file type.
1728 @kindex G DEL (Group)
1729 @findex gnus-group-delete-group
1730 This function will delete the current group
1731 (@code{gnus-group-delete-group}). If given a prefix, this function will
1732 actually delete all the articles in the group, and forcibly remove the
1733 group itself from the face of the Earth. Use a prefix only if you are
1734 sure of what you are doing.
1738 @findex gnus-group-make-empty-virtual
1739 Make a new, fresh, empty @code{nnvirtual} group
1740 (@code{gnus-group-make-empty-virtual}).
1744 @findex gnus-group-add-to-virtual
1745 Add the current group to an @code{nnvirtual} group
1746 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
1749 The different methods all have their peculiarities, of course.
1752 * nntp:: Reading news from a different @sc{nntp} server.
1753 * nnspool:: Reading news from the local spool.
1754 * nnvirtual:: Combining articles from many groups.
1755 * nnkiboze:: Looking through parts of the newsfeed for articles.
1756 * nndir:: You can read a directory as if it was a newsgroup.
1757 * nneething:: Dired? Who needs dired?
1758 * nndoc:: Single files can be the basis of a group.
1759 * SOUP:: Reading @sc{SOUP} packets "offline".
1760 * Reading Mail:: Reading your personal mail with Gnus.
1763 @vindex gnus-activate-foreign-newsgroups
1764 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
1765 Gnus will check all foreign groups with this level or lower at startup.
1766 This might take quite a while, especially if you subscribe to lots of
1767 groups from different @sc{nntp} servers.
1773 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
1774 You just specify @code{nntp} as method and the address of the @sc{nntp}
1775 server as the, uhm, address.
1777 If the @sc{nntp} server is located at a non-standard port, setting the
1778 third element of the select method to this port number should allow you
1779 to connect to the right port. You'll have to edit the group info for
1780 that (@pxref{Foreign Groups}).
1782 The name of the foreign group can be the same as a native group. In
1783 fact, you can subscribe to the same group from as many different servers
1784 you feel like. There will be no name collisions.
1786 The following variables can be used to create a virtual @code{nntp}
1790 @item nntp-server-opened-hook
1791 @vindex nntp-server-opened-hook
1792 @cindex @sc{mode reader}
1794 @cindex authentification
1795 @cindex nntp authentification
1796 @findex nntp-send-authinfo
1797 @findex nntp-send-mode-reader
1798 @code{nntp-server-opened-hook} is run after a connection has been made.
1799 It can be used to send commands to the @sc{nntp} server after it has
1800 been contacted. By default is sends the command @samp{MODE READER} to
1801 the server with the @code{nntp-send-mode-reader} function. Another
1802 popular function is @code{nntp-send-authinfo}, which will prompt you for
1803 an @sc{nntp} password and stuff.
1805 @item nntp-maximum-request
1806 @vindex nntp-maximum-request
1807 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
1808 will collect headers by sending a series of @code{head} commands. To
1809 speed things up, the backend sends lots of these commands without
1810 waiting for reply, and then reads all the replies. This is controlled
1811 by the @code{nntp-maximum-request} variable, and is 400 by default. If
1812 your network is buggy, you should set this to 1.
1814 @item nntp-connection-timeout
1815 @vindex nntp-connection-timeout
1816 If you have lots of foreign @code{nntp} groups that you connect to
1817 regularly, you're sure to have problems with @sc{nntp} servers not
1818 responding properly, or being too loaded to reply within reasonable
1819 time. This is can lead to awkward problems, which can be helped
1820 somewhat by setting @code{nntp-connection-timeout}. This is an integer
1821 that says how many seconds the @code{nntp} backend should wait for a
1822 connection before giving up. If it is @code{nil}, which is the default,
1823 no timeouts are done.
1825 @item nntp-server-hook
1826 @vindex nntp-server-hook
1827 This hook is run as the last step when connecting to an @sc{nntp}
1830 @c @findex nntp-open-rlogin
1831 @c @findex nntp-open-network-stream
1832 @c @item nntp-open-server-function
1833 @c @vindex nntp-open-server-function
1834 @c This function is used to connect to the remote system. Two pre-made
1835 @c functions are @code{nntp-open-network-stream}, which is the default, and
1836 @c simply connects to some port or other on the remote system. The other
1837 @c is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
1838 @c and then does a telnet to the @sc{nntp} server available there.
1840 @c @item nntp-rlogin-parameters
1841 @c @vindex nntp-rlogin-parameters
1842 @c If you use @code{nntp-open-rlogin} as the
1843 @c @code{nntp-open-server-function}, this list will be used as the
1844 @c parameter list given to @code{rsh}.
1846 @c @item nntp-rlogin-user-name
1847 @c @vindex nntp-rlogin-user-name
1848 @c User name on the remote system when using the @code{rlogin} connect
1852 @vindex nntp-address
1853 The address of the remote system running the @sc{nntp} server.
1855 @item nntp-port-number
1856 @vindex nntp-port-number
1857 Port number to connect to when using the @code{nntp-open-network-stream}
1860 @item nntp-buggy-select
1861 @vindex nntp-buggy-select
1862 Set this to non-@code{nil} if your select routine is buggy.
1864 @item nntp-nov-is-evil
1865 @vindex nntp-nov-is-evil
1866 If the @sc{nntp} server does not support @sc{nov}, you could set this
1867 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
1868 can be used automatically.
1870 @item nntp-xover-commands
1871 @vindex nntp-xover-commands
1872 List of strings that are used as commands to fetch @sc{nov} lines from a
1873 server. The default value of this variable is @code{("XOVER"
1877 @vindex nntp-nov-gap
1878 @code{nntp} normally sends just one big request for @sc{nov} lines to
1879 the server. The server responds with one huge list of lines. However,
1880 if you have read articles 2-5000 in the group, and only want to read
1881 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
1882 lines that you do not want, and will not use. This variable says how
1883 big a gap between two consecutive articles is allowed to be before the
1884 @code{XOVER} request is split into several request. Note that if your
1885 network is fast, setting this variable to a really small number means
1886 that fetching will probably be slower. If this variable is @code{nil},
1887 @code{nntp} will never split requests.
1889 @item nntp-prepare-server-hook
1890 @vindex nntp-prepare-server-hook
1891 A hook run before attempting to connect to an @sc{nntp} server.
1893 @item nntp-async-number
1894 @vindex nntp-async-number
1895 How many articles should be pre-fetched when in asynchronous mode. If
1896 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
1897 that it can without bound. If it is @code{nil}, no pre-fetching will be
1900 @item nntp-warn-about-losing-connection
1901 @vindex nntp-warn-about-losing-connection
1902 If this variable is non-@code{nil}, some noise will be made when a
1903 server closes connection.
1910 @cindex @code{nnspool}
1913 Subscribing to a foreign group from the local spool is extremely easy,
1914 and might be useful, for instance, to speed up reading groups like
1915 @samp{alt.binaries.pictures.furniture}.
1917 Anyways, you just specify @code{nnspool} as the method and @samp{""} (or
1918 anything else) as the address.
1920 If you have access to a local spool, you should probably use that as the
1921 native select method (@pxref{Finding the News}). It is normally faster
1922 than using an @code{nntp} select method, but might not be. It depends.
1923 You just have to try to find out what's best at your site.
1926 @item nnspool-inews-program
1927 @vindex nnspool-inews-program
1928 Program used to post an article.
1930 @item nnspool-inews-switches
1931 @vindex nnspool-inews-switches
1932 Parameters given to the inews program when posting an article.
1934 @item nnspool-spool-directory
1935 @vindex nnspool-spool-directory
1936 Where @code{nnspool} looks for the articles. This is normally
1937 @file{/usr/spool/news/}.
1939 @item nnspool-nov-directory
1940 @vindex nnspool-nov-directory
1941 Where @code{nnspool} will look for @sc{nov} files. This is normally
1942 @file{/usr/spool/news/over.view/}.
1944 @item nnspool-lib-dir
1945 @vindex nnspool-lib-dir
1946 Where the news lib dir is (@file{/usr/lib/news/} by default).
1948 @item nnspool-active-file
1949 @vindex nnspool-active-file
1950 The path of the active file.
1952 @item nnspool-newsgroups-file
1953 @vindex nnspool-newsgroups-file
1954 The path of the group descriptions file.
1956 @item nnspool-history-file
1957 @vindex nnspool-history-file
1958 The path of the news history file.
1960 @item nnspool-active-times-file
1961 @vindex nnspool-active-times-file
1962 The path of the active date file.
1964 @item nnspool-nov-is-evil
1965 @vindex nnspool-nov-is-evil
1966 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
1969 @item nnspool-sift-nov-with-sed
1970 @vindex nnspool-sift-nov-with-sed
1971 If non-@code{nil}, which is the default, use @code{sed} to get the
1972 relevant portion from the overview file. If nil, @code{nnspool} will
1973 load the entire file into a buffer and process it there.
1978 @subsection nnvirtual
1979 @cindex @code{nnvirtual}
1980 @cindex virtual groups
1982 An @dfn{nnvirtual group} is really nothing more than a collection of
1985 For instance, if you are tired of reading many small group, you can
1986 put them all in one big group, and then grow tired of reading one
1987 big, unwieldy group. The joys of computing!
1989 You specify @code{nnvirtual} as the method. The address should be a
1990 regexp to match component groups.
1992 All marks in the virtual group will stick to the articles in the
1993 component groups. So if you tick an article in a virtual group, the
1994 article will also be ticked in the component group from whence it came.
1995 (And vice versa---marks from the component groups will also be shown in
1998 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
1999 newsgroups into one, big, happy newsgroup:
2002 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
2005 The component groups can be native or foreign; everything should work
2006 smoothly, but if your computer explodes, it was probably my fault.
2008 Collecting the same group from several servers might actually be a good
2009 idea if users have set the Distribution header to limit distribution.
2010 If you would like to read @samp{soc.motss} both from a server in Japan
2011 and a server in Norway, you could use the following as the group regexp:
2014 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
2017 This should work kinda smoothly---all articles from both groups should
2018 end up in this one, and there should be no duplicates. Threading (and
2019 the rest) will still work as usual, but there might be problems with the
2020 sequence of articles. Sorting on date might be an option here
2021 (@pxref{Selecting a Group}.
2023 One limitation, however---all groups that are included in a virtual
2024 group has to be alive (i.e., subscribed or unsubscribed). Killed or
2025 zombie groups can't be component groups for @code{nnvirtual} groups.
2029 @subsection nnkiboze
2030 @cindex @code{nnkiboze}
2033 @dfn{Kibozing} is defined by @sc{oed} as "grepping through (parts of)
2034 the news feed". @code{nnkiboze} is a backend that will do this for you. Oh
2035 joy! Now you can grind any @sc{nntp} server down to a halt with useless
2036 requests! Oh happiness!
2038 The address field of the @code{nnkiboze} method is, as with
2039 @code{nnvirtual}, a regexp to match groups to be "included" in the
2040 @code{nnkiboze} group. There most similarities between @code{nnkiboze}
2041 and @code{nnvirtual} ends.
2043 In addition to this regexp detailing component groups, an @code{nnkiboze} group
2044 must have a score file to say what articles that are to be included in
2045 the group (@pxref{Scoring}).
2047 @kindex M-x nnkiboze-generate-groups
2048 @findex nnkiboze-generate-groups
2049 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
2050 @code{nnkiboze} groups you want to have. This command will take time. Lots of
2051 time. Oodles and oodles of time. Gnus has to fetch the headers from
2052 all the articles in all the components groups and run them through the
2053 scoring process to determine if there are any articles in the groups
2054 that are to be part of the @code{nnkiboze} groups.
2056 Please limit the number of component groups by using restrictive
2057 regexps. Otherwise your sysadmin may become annoyed with you, and the
2058 @sc{nntp} site may throw you off and never let you back in again.
2059 Stranger things have happened.
2061 @code{nnkiboze} component groups do not have to be alive---they can be dead,
2062 and they can be foreign. No restrictions.
2064 @vindex nnkiboze-directory
2065 The generation of an @code{nnkiboze} group means writing two files in
2066 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
2067 contains the @sc{nov} header lines for all the articles in the group,
2068 and the other is an additional @file{.newsrc} file to store information
2069 on what groups that have been searched through to find component
2072 Articles that are marked as read in the @code{nnkiboze} group will have their
2073 @sc{nov} lines removed from the @sc{nov} file.
2077 @cindex @code{nndir}
2078 @cindex directory groups
2080 If you have a directory that has lots of articles in separate files in
2081 it, you might treat it as a newsgroup. The files have to have numerical
2084 This might be an opportune moment to mention @code{ange-ftp}, that most
2085 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
2086 didn't think much about it---a backend to read directories. Big deal.
2088 @code{ange-ftp} changes that picture dramatically. For instance, if you
2089 enter @file{"/ftp@@sina.tcamc.uh.edu:/pub/emacs/ding-list/"} as the the
2090 directory name, ange-ftp will actually allow you to read this directory
2091 over at @samp{sina} as a newsgroup. Distributed news ahoy!
2093 @code{nndir} will use @sc{nov} files if they are present.
2095 @code{nndir} is a "read-only" backend---you can't delete or expire
2096 articles with this method. You can use @code{nnmh} or @code{nnml} for
2097 whatever you use @code{nndir} for, so you could switch to any of those
2098 methods if you feel the need to have a non-read-only @code{nndir}.
2101 @subsection nneething
2102 @cindex @code{nneething}
2104 From the @code{nndir} backend (which reads a single spool-like
2105 directory), it's just a hop and a skip to @code{nneething}, which
2106 pretends that any random directory is a newsgroup. Strange, but true.
2108 When @code{nneething} is presented with a directory, it will scan this
2109 directory and assign article numbers to each file. When you enter such a
2110 group, @code{nneething} must create "headers" that Gnus can use. After
2111 all, Gnus is a newsreader, in case you're forgetting. @code{nneething}
2112 does this in a two-step process. First, it snoops each file in question.
2113 If the file looks like an article (i.e., the first few lines look like
2114 headers), it will use this as the head. If this is just some random file
2115 without a head (eg. a C source file), @code{nneething} will cobble up a
2116 header out of thin air. It will use file ownership, name and date and do
2117 whatever it can with these elements.
2119 All this should happen automatically for you, and you will be presented
2120 with something that looks very much like a newsgroup. Totally like a
2121 newsgroup, to be precise. If you select an article, it will be displayed
2122 in the article buffer, just as usual.
2124 If you select a line that represents a directory, Gnus will pop you into
2125 a new summary buffer for this @code{nneething} group. And so on. You can
2126 traverse the entire disk this way, if you feel like, but remember that
2127 Gnus is not dired, really, and does not intend to be, either.
2129 There are two overall modes to this action---ephemeral or solid. When
2130 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
2131 will not store information on what files you have read, and what files
2132 are new, and so on. If you create a solid @code{nneething} group the
2133 normal way with @kbd{G m}, Gnus will store a mapping table between
2134 article numbers and file names, and you can treat this group like any
2135 other groups. When you activate a solid @code{nneething} group, you will
2136 be told how many unread articles it contains, etc., etc.
2141 @item nneething-map-file-directory
2142 @vindex nneething-map-file-directory
2143 All the mapping files for solid @code{nneething} groups will be stored
2144 in this directory, which defaults to @file{~/.nneething/}.
2146 @item nneething-exclude-files
2147 @vindex nneething-exclude-files
2148 All files that match this regexp will be ignored. Nice to use to exclude
2149 auto-save files and the like, which is what it does by default.
2151 @item nneething-map-file
2152 @vindex nneething-map-file
2153 Name of the map files.
2159 @cindex @code{nndoc}
2160 @cindex documentation group
2163 @code{nndoc} is a cute little thing that will let you read a single file
2164 as a newsgroup. Currently supported file types are @code{babyl} (the
2165 RMAIL file type), @code{mbox} (standard Unix mbox files), @code{digest}
2166 (various digests, MIME and otherwise), @code{mmdf} (the MMDF mail box
2167 format), and @code{forward} (a single forwarded mail). You can also use
2168 the special "file type" @code{guess}, which means that @code{nndoc} will
2169 try to guess what file type it is looking at.
2171 @code{nndoc} will not try to change the file or insert any extra headers into
2172 it---it will simply, like, let you use the file as the basis for a
2173 group. And that's it.
2175 If you have some old archived articles that you want to insert into your
2176 new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
2177 that. Say you have an old @file{RMAIL} file with mail that you now want
2178 to split into your new @code{nnml} groups. You look at that file using
2179 @code{nndoc}, set the process mark on all the articles in the buffer
2180 (@kbd{M P b}, for instance), and then respool (@kbd{B r}) using
2181 @code{nnml}. If all goes well, all the mail in the @file{RMAIL} file is
2182 now also stored in lots of @code{nnml} directories, and you can delete
2183 that pesky @file{RMAIL} file. If you have the guts!
2185 Virtual server variables:
2188 @item nndoc-article-type
2189 @vindex nndoc-article-type
2190 This should be one of @code{mbox}, @code{babyl}, @code{digest},
2191 @code{mmdf}, @code{forward}, or @code{guess}.
2196 @subsection @sc{soup}
2200 In the PC world people often talk about "offline" newsreaders. These
2201 are thingies that are combined reader/news transport monstrosities.
2202 With built-in modem programs. Yecchh!
2204 Of course, us Unix Weenie types of human beans use things like
2205 @code{uucp} and, like, @code{nntpd} and set up proper news and mail
2206 transport things like Ghod inteded. And then we just use normal
2209 However, it can sometimes be convenient to do something a that's a bit
2210 easier on the brain if you have a very slow modem, and you're not really
2211 that interested in doing things properly.
2213 A file format called @sc{soup} has been developed for transporting news
2214 and mail from servers to home machines and back again. It can be a bit
2220 You log in on the server and create a @sc{soup} packet. You can either
2221 use a dedicated @sc{soup} thingie, or you can use Gnus to create the
2222 packet with the @kbd{O s} command.
2225 You transfer the packet home. Rail, boat, car or modem will do fine.
2228 You put the packet in your home directory.
2231 You fire up Gnus using the @code{nnsoup} backend as the native server.
2234 You read articles and mail and answer and followup to the things you
2238 You do the @kbd{G S r} command to pack these replies into a @sc{soup}
2242 You transfer this packet to the server.
2245 You use Gnus to mail this packet out with the @kbd{G S s} command.
2248 You then repeat until you die.
2252 So you basically have a bipartite system---you use @code{nnsoup} for
2253 reading and Gnus for packing/sending these @sc{soup} packets.
2256 * SOUP Commands:: Commands for creating and sending @sc{soup} packets
2257 * nnsoup:: A backend for reading @sc{soup} packets.
2258 * SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
2263 @subsubsection @sc{soup} Commands
2267 @kindex G s b (Group)
2268 @findex gnus-group-brew-soup
2269 Pack all unread articles in the current group
2270 (@code{gnus-group-brew-soup}). This command understands the
2271 process/prefix convention.
2274 @kindex G s w (Group)
2275 @findex gnus-soup-save-areas
2276 Save all data files (@code{gnus-soup-save-areas}).
2279 @kindex G s s (Group)
2280 @findex gnus-soup-send-replies
2281 Send all replies from the replies packet
2282 (@code{gnus-soup-send-replies}).
2285 @kindex G s p (Group)
2286 @findex gnus-soup-pack-packet
2287 Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
2290 @kindex G s r (Group)
2291 @findex nnsoup-pack-replies
2292 Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
2295 @kindex O s (Summary)
2296 @findex gnus-soup-add-article
2297 This summary-mode command adds the current article to a @sc{soup} packet
2298 (@code{gnus-soup-add-article}). It understands the process/prefix
2304 There are a few variables to customize where Gnus will put all these
2309 @item gnus-soup-directory
2310 @vindex gnus-soup-directory
2311 Directory where Gnus will save intermediate files while composing
2312 @sc{soup} packets. The default is @file{~/SoupBrew/}.
2314 @item gnus-soup-replies-directory
2315 @vindex gnus-soup-replies-directory
2316 This is what Gnus will use as a temporary directory while sending our
2317 reply packets. The default is @file{~/SoupBrew/SoupReplies/}.
2319 @item gnus-soup-prefix-file
2320 @vindex gnus-soup-prefix-file
2321 Name of the file where Gnus stores the last used prefix. The default is
2322 @samp{"gnus-prefix"}.
2324 @item gnus-soup-packer
2325 @vindex gnus-soup-packer
2326 A format string command for packing a @sc{soup} packet. The default is
2327 @samp{ "tar cf - %s | gzip > $HOME/Soupout%d.tgz"}.
2329 @item gnus-soup-unpacker
2330 @vindex gnus-soup-unpacker
2331 Format string command for unpacking a @sc{soup} packet. The default is
2332 @samp{"gunzip -c %s | tar xvf -"}.
2334 @item gnus-soup-packet-directory
2335 @vindex gnus-soup-packet-directory
2336 Wehre Gnus will look for reply packets. The default is @file{~/}.
2338 @item gnus-soup-packet-regexp
2339 @vindex gnus-soup-packet-regexp
2340 Regular expression matching @sc{soup} reply packets in
2341 @code{gnus-soup-packet-directory}.
2347 @subsubsection nnsoup
2348 @cindex @code{nnsoup}
2350 @code{nnsoup} is the backend for reading @sc{soup} packets. It will
2351 read incoming packets, unpack them, and put them in a directory where
2352 you can read them at leisure.
2354 These are the variables you can use to customize its behavior:
2358 @item nnsoup-directory
2359 @vindex nnsoup-directory
2360 @code{nnsoup} will move all incoming @sc{soup} packets to this directory
2361 and unpack them there. The default is @file{~/SOUP/}.
2363 @item nnsoup-replies-directory
2364 @vindex nnsoup-replies-directory
2365 All replies will stored in this directory before being packed into a
2366 reply packet. The default is @file{~/SOUP/replies/"}.
2368 @item nnsoup-replies-format-type
2369 @vindex nnsoup-replies-format-type
2370 The @sc{soup} format of the replies packets. The default is @samp{?n}
2371 (rnews), and I don't think you should touch that variable. I probaly
2372 shouldn't even have documented it. Drats! Too late!
2374 @item nnsoup-replies-index-type
2375 @vindex nnsoup-replies-index-type
2376 The index type of the replies packet. The is @samp{?n}, which means
2377 "none". Don't fiddle with this one either!
2379 @item nnsoup-active-file
2380 @vindex nnsoup-active-file
2381 Where @code{nnsoup} stores lots of information. This is not an "active
2382 file" in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
2383 this file or mess it up in any way, you're dead. The default is
2384 @file{~/SOUP/active}.
2387 @vindex nnsoup-packer
2388 Format string command for packing a reply @sc{soup} packet. The default
2389 is @samp{"tar cf - %s | gzip > $HOME/Soupin%d.tgz"}.
2391 @item nnsoup-unpacker
2392 @vindex nnsoup-unpacker
2393 Format string command for unpacking incoming @sc{soup} packets. The
2394 default is @samp{"gunzip -c %s | tar xvf -"}.
2396 @item nnsoup-packet-directory
2397 @vindex nnsoup-packet-directory
2398 Where @code{nnsoup} will look for incoming packets. The default is
2401 @item nnsoup-packet-regexp
2402 @vindex nnsoup-packet-regexp
2403 Regular expression matching incoming @sc{soup} packets. The default is
2410 @subsubsection SOUP Replies
2412 Just using @code{nnsoup} won't mean that your postings and mailings end
2413 up in @sc{soup} reply packets automagically. You have to work a bit
2414 more for that to happen.
2416 @findex nnsoup-set-variables
2417 The @code{nnsoup-set-variables} command will set the appropriate
2418 variables to ensure that all your followups and replies end up in the
2421 In specific, this is what it does:
2424 (setq gnus-inews-article-function 'nnsoup-request-post)
2425 (setq send-mail-function 'nnsoup-request-mail)
2428 And that's it, really. If you only want news to go into the @sc{soup}
2429 system you just use the first line. If you only want mail to be
2430 @sc{soup}ed you use the second.
2434 @subsection Reading Mail
2435 @cindex reading mail
2438 Reading mail with a newsreader---isn't that just plain WeIrD? But of
2441 Gnus will read the mail spool when you activate a mail group. The mail
2442 file is first copied to your home directory. What happens after that
2443 depends on what format you want to store your mail in.
2446 * Creating Mail Groups:: How to create mail groups.
2447 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
2448 * Mail & Procmail:: Reading mail groups that procmail create.
2449 * Expiring Old Mail Articles:: Getting rid of unwanted mail.
2450 * Not Reading Mail:: Using mail backends for reading other files.
2451 * nnmbox:: Using the (quite) standard Un*x mbox.
2452 * nnbabyl:: Emacs programs use the rmail babyl format.
2453 * nnml:: Store your mail in a private spool?
2454 * nnmh:: An mhspool-like backend.
2455 * nnfolder:: Having one file for each group.
2458 @vindex nnmail-read-incoming-hook
2459 The mail backends all call @code{nnmail-read-incoming-hook} after
2460 reading new mail. You can use this hook to notify any mail watch
2461 programs, if you want to.
2463 @vindex nnmail-spool-file
2465 @code{nnmail-spool-file} says where to look for new mail. If this
2466 variable is @code{nil}, the mail backends will never attempt to fetch
2467 mail by themselves. If you are using a POP mail server and your name is
2468 @samp{"larsi"}, you should set this variable to @samp{"po:larsi"}. If
2469 your name is not @samp{"larsi"}, you should probably modify that
2470 slightly, but you may have guessed that already, you smart & handsome
2471 devil! You can also set this variable to @code{pop}, and Gnus will try
2472 to figure out the POP mail string by itself.
2474 When you use a mail backend, Gnus will slurp all your mail from your
2475 inbox and plonk it down in your home directory. Gnus doesn't move any
2476 mail if you're not using a mail backend---you have to do a lot of magic
2477 invocations first. At the time when you have finished drawing the
2478 pentagram, lightened the candles, and sacrificed the goat, you really
2479 shouldn't be too suprised when Gnus moves your mail.
2481 @vindex nnmail-use-procmail
2482 If @code{nnmail-use-procmail} is non-@code{nil}, the mail backends will
2483 look in @code{nnmail-procmail-directory} for incoming mail. All the
2484 files in that directory that have names ending in
2485 @code{gnus-procmail-suffix} will be considered incoming mailboxes, and
2486 will be searched for new mail.
2488 @vindex nnmail-prepare-incoming-hook
2489 @code{nnmail-prepare-incoming-hook} is run in a buffer that holds all
2490 the new incoming mail, and can be used for, well, anything, really.
2492 @vindex nnmail-tmp-directory
2493 @code{nnmail-tmp-directory} says where to move the incoming mail to
2494 while processing it. This is usually done in the same directory that
2495 the mail backend inhabits (i.e., @file{~/Mail/}), but if this variable is
2496 non-@code{nil}, it will be used instead.
2498 @vindex nnmail-movemail-program
2499 @code{nnmail-movemail-program} is executed to move mail from the user's
2500 inbox to her home directory. The default is @samp{"movemail"}.
2502 @vindex nnmail-delete-incoming
2503 If @code{nnmail-delete-incoming} is non-@code{nil}, the mail backends
2504 will delete the temporary incoming file after splitting mail into the
2505 proper groups. This is @code{nil} by default for reasons of security.
2507 @vindex nnmail-use-long-file-names
2508 If @code{nnmail-use-long-file-names} is non-@code{nil} the mail backends
2509 will use long file and directory names. Groups like @samp{mail.misc}
2510 will end up in directories like @file{mail.misc/}. If it is @code{nil},
2511 the same group will end up in @file{mail/misc/}.
2513 @vindex nnmail-message-id-cache-length
2514 @vindex nnmail-message-id-cache-file
2515 @vindex nnmail-delete-duplicates
2516 @cindex duplicate mails
2517 If you are a member of a couple of mailing list, you will sometime
2518 receive two copies of the same mail. This can be quite annoying, so
2519 @code{nnmail} checks for and discards any duplicates it might find. To
2520 do this, it keeps a cache of old @code{Message-ID}s -
2521 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
2522 default. The approximate maximum number of @code{Message-ID}s stored
2523 there is controlled by the @code{nnmail-message-id-cache-length}
2524 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
2525 stored.) If all this sounds scary to you, you can set
2526 @code{nnmail-delete-duplicates} to @code{nil} (which is what it is by
2527 default), and @code{nnmail} won't do any duplicate checking.
2529 Here's a neat feature: If you know that the recipient reads her mail
2530 with Gnus, and that she has @code{nnmail-delete-duplicates} set to
2531 @code{t}, you can send her as many insults as you like, just by using a
2532 @code{Message-ID} of a mail that you know that she's already received.
2533 Think of all the fun! She'll never see any of it! Whee!
2535 Gnus gives you all the opportunity you could possibly want for shooting
2536 yourself in the foot. Let's say you create a group that will contain
2537 all the mail you get from your boss. And then you accidentally
2538 unsubscribe from the group. Gnus will still put all the mail from your
2539 boss in the unsubscribed group, and so, when your boss mails you "Have
2540 that report ready by Monday or you're fired!", you'll never see it and,
2541 come Tuesday, you'll still believe that you're gainfully employed while
2542 you really should be out collecting empty bottles to save up for next
2545 @node Creating Mail Groups
2546 @subsubsection Creating Mail Groups
2547 @cindex creating mail groups
2549 You can make Gnus read your personal, private, secret mail.
2551 You should first set @code{gnus-secondary-select-methods} to, for
2552 instance, @code{((nnmbox ""))}. When you start up Gnus, Gnus will ask
2553 this backend for what groups it carries (@samp{mail.misc} by default)
2554 and subscribe it the normal way. (Which means you may have to look for
2555 it among the zombie groups, I guess, all depending on your
2556 @code{gnus-subscribe-newsgroup-method} variable.)
2558 @vindex nnmail-split-methods
2559 Then you should set the variable @code{nnmail-split-methods} to specify
2560 how the incoming mail is to be split into groups.
2563 (setq nnmail-split-methods
2564 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
2565 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
2569 This variable is a list of lists, where the first element of each of
2570 these lists is the name of the mail group (they do not have to be called
2571 something beginning with @samp{mail}, by the way), and the second
2572 element is a regular expression used on the header of each mail to
2573 determine if it belongs in this mail group.
2575 The second element can also be a function. In that case, it will be
2576 called narrowed to the headers with the first element of the rule as the
2577 argument. It should return a non-@code{nil} value if it thinks that the
2578 mail belongs in that group.
2580 The last of these groups should always be a general one, and the regular
2581 expression should @emph{always} be @samp{""} so that it matches any
2582 mails that haven't been matched by any of the other regexps.
2584 If you like to tinker with this yourself, you can set this variable to a
2585 function of your choice. This function will be called without any
2586 arguments in a buffer narrowed to the headers of an incoming mail
2587 message. The function should return a list of groups names that it
2588 thinks should carry this mail message.
2590 Note that the mail backends are free to maul the poor, innocent
2591 incoming headers all they want to. They all add @code{Lines} headers;
2592 some add @code{X-Gnus-Group} headers; most rename the Unix mbox
2593 @code{From<SPC>} line to something else.
2595 @vindex nnmail-crosspost
2596 The mail backends all support cross-posting. If several regexps match,
2597 the mail will be "cross-posted" to all those groups.
2598 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
2599 that no articles are crossposted to the general (@samp{""}) group.
2603 @node Fancy Mail Splitting
2604 @subsubsection Fancy Mail Splitting
2605 @cindex mail splitting
2606 @cindex fancy mail splitting
2608 @vindex nnmail-split-fancy
2609 @findex nnmail-split-fancy
2610 If the rather simple, standard method for specifying how to split mail
2611 doesn't allow you to do what you want, you can set
2612 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
2613 play with the @code{nnmail-split-fancy} variable.
2615 Let's look at an example value of this variable first:
2618 ;; Messages from the mailer daemon are not crossposted to any of
2619 ;; the ordinary groups. Warnings are put in a separate group
2620 ;; from real errors.
2621 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
2623 ;; Non-error messages are crossposted to all relevant
2624 ;; groups, but we don't crosspost between the group for the
2625 ;; (ding) list and the group for other (ding) related mail.
2626 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
2627 ("subject" "ding" "ding.misc"))
2628 ;; Other mailing lists...
2629 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
2630 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
2632 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
2633 ;; Unmatched mail goes to the catch all group.
2637 This variable has the format of a @dfn{split}. A split is a (possibly)
2638 recursive structure where each split may contain other splits. Here are
2639 the four possible split syntaxes:
2643 If the split is a string, that will be taken as a group name.
2644 @item (FIELD VALUE SPLIT)
2645 If the split is a list, and the first element is a string, then that
2646 means that if header FIELD (a regexp) contains VALUE (also a regexp),
2647 then store the message as specified by SPLIT.
2649 If the split is a list, and the first element is @code{|} (vertical
2650 bar), then process each SPLIT until one of them matches. A SPLIT is
2651 said to match if it will cause the mail message to be stored in one or
2654 If the split is a list, and the first element is @code{&}, then process
2655 all SPLITs in the list.
2658 In these splits, FIELD must match a complete field name. VALUE must
2659 match a complete word according to the fundamental mode syntax table.
2660 You can use @code{.*} in the regexps to match partial field names or
2663 @vindex nnmail-split-abbrev-alist
2664 FIELD and VALUE can also be lisp symbols, in that case they are expanded
2665 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
2666 an alist of cons cells, where the car of the cells contains the key, and
2667 the cdr contains a string.
2669 @node Mail & Procmail
2670 @subsubsection Mail & Procmail
2673 Many people use @code{procmail} to split incoming mail into groups. If
2674 you do that, you should set @code{nnmail-spool-file} to @code{procmail}
2675 to ensure that the mail backends never ever try to fetch mail by
2678 This also means that you probably don't want to set
2679 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
2682 When a mail backend is queried for what groups it carries, it replies
2683 with the contents of that variable, along with any groups it has figured
2684 out that it carries by other means. None of the backends (except
2685 @code{nnmh}) actually go out to the disk and check what groups actually
2686 exist. (It's not trivial to distinguish between what the user thinks is
2687 a basis for a newsgroup and what is just a plain old file or directory.)
2689 This means that you have to tell Gnus (and the backends) what groups
2692 Let's take the @code{nnmh} backend as an example.
2694 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
2695 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
2697 Go to the group buffer and type @kbd{G m}. When prompted, answer
2698 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
2699 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
2700 to include all your mail groups.
2702 That's it. You are now set to read your mail. An active file for this
2703 method will be created automatically.
2705 @vindex nnmail-procmail-suffix
2706 @vindex nnmail-procmail-directory
2707 If you use @code{nnfolder} or any other backend that store more than a
2708 single article in each file, you should never have procmail add mails to
2709 the file that Gnus sees. Instead, procmail should put all incoming mail
2710 in @code{nnmail-procmail-directory}. To arrive at the file name to put
2711 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
2712 name. The mail backends will read the mail from these files.
2714 @vindex nnmail-resplit-incoming
2715 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
2716 put in the @code{mail.misc}, as one would expect. However, if you want
2717 Gnus to split the mail the normal way, you could set
2718 @code{nnmail-resplit-incoming} to @code{t}.
2720 @vindex nnmail-keep-last-article
2721 If you use @code{procmail} to split things directory into an @code{nnmh}
2722 directory (which you shouldn't do), you should set
2723 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
2724 ever expiring the final article in a mail newsgroup. This is quite,
2728 @node Expiring Old Mail Articles
2729 @subsubsection Expiring Old Mail Articles
2730 @cindex article expiry
2732 Traditional mail readers have a tendency to remove mail articles when
2733 you mark them as read, in some way. Gnus takes a fundamentally
2734 different approach to mail reading.
2736 Gnus basically considers mail just to be news that has been received in
2737 a rather peculiar manner. It does not think that it has the power to
2738 actually change the mail, or delete any mail messages. If you enter a
2739 mail group, and mark articles as "read", or kill them in some other
2740 fashion, the mail articles will still exist on the system. I repeat:
2741 Gnus will not delete your old, read mail. Unless you ask it to, of
2744 To make Gnus get rid of your unwanted mail, you have to mark the
2745 articles as @dfn{expirable}. This does not mean that the articles will
2746 disappear right away, however. In general, a mail article will be
2747 deleted from your system if, 1) it is marked as expirable, AND 2) it is
2748 more than one week old. If you do not mark an article as expirable, it
2749 will remain on your system until hell freezes over. This bears
2750 repeating one more time, with some spurious capitalizations: IF you do
2751 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
2753 @vindex gnus-auto-expirable-newsgroups
2754 You do not have to mark articles as expirable by hand. Groups that
2755 match the regular expression @code{gnus-auto-expirable-newsgroups} will
2756 have all articles that you read marked as expirable automatically. All
2757 articles that are marked as expirable have an @samp{E} in the first
2758 column in the summary buffer.
2760 Let's say you subscribe to a couple of mailing lists, and you want the
2761 articles you have read to disappear after a while:
2764 (setq gnus-auto-expirable-newsgroups
2765 "mail.nonsense-list\\|mail.nice-list")
2768 Another way to have auto-expiry happen is to have the element
2769 @code{auto-expire} in the select method of the group.
2771 @vindex nnmail-expiry-wait
2772 The @code{nnmail-expiry-wait} variable supplies the default time an
2773 expirable article has to live. The default is seven days.
2775 Gnus also supplies a function that lets you fine-tune how long articles
2776 are to live, based on what group they are in. Let's say you want to
2777 have one month expiry period in the @samp{mail.private} group, a one day
2778 expiry period in the @samp{mail.junk} group, and a six day expiry period
2782 (setq nnmail-expiry-wait-function
2784 (cond ((string= group "mail.private")
2786 ((string= group "mail.junk")
2788 ((string= group "important")
2794 The group names that this function is fed are "unadorned" group
2795 names---no @samp{"nnml:"} prefixes and the like.
2797 The @code{nnmail-expiry-wait} variable and
2798 @code{nnmail-expiry-wait-function} function can be either a number (not
2799 necessarily an integer) or the symbols @code{immediate} or
2802 @vindex nnmail-keep-last-article
2803 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
2804 expire the final article in a mail newsgroup. This is to make life
2805 easier for procmail users.
2807 @vindex gnus-total-expirable-newsgroups
2808 By the way, that line up there about Gnus never expiring non-expirable
2809 articles is a lie. If you put @code{total-expire} in the group
2810 parameters, articles will not be marked as expirable, but all read
2811 articles will be put through the expiry process. Use with extreme
2812 caution. Even more dangerous is the
2813 @code{gnus-total-expirable-newsgroups} variable. All groups that match
2814 this regexp will have all read articles put through the expiry process,
2815 which means that @emph{all} old mail articles in the groups in question
2816 will be deleted after a while. Use with extreme caution, and don't come
2817 crying to me when you discover that the regexp you used matched the
2818 wrong group and all your important mail has disappeared. Be a
2819 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
2823 @node Not Reading Mail
2824 @subsubsection Not Reading Mail
2826 If you start using any of the mail backends, they have the annoying
2827 habit of assuming that you want to read mail with them. This might not
2828 be unreasonable, but it might not be what you want.
2830 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
2831 will ever attempt to read incoming mail, which should help.
2833 @vindex nnbabyl-get-new-mail
2834 @vindex nnmbox-get-new-mail
2835 @vindex nnml-get-new-mail
2836 @vindex nnmh-get-new-mail
2837 @vindex nnfolder-get-new-mail
2838 This might be too much, if, for instance, you are reading mail quite
2839 happily with @code{nnml} and just want to peek at some old @sc{rmail}
2840 file you have stashed away with @code{nnbabyl}. All backends have
2841 variables called backend-@code{get-new-mail}. If you want to disable
2842 the @code{nnbabyl} mail reading, you edit the virtual server for the
2843 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
2845 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
2846 narrowed to the article to be saved before saving it when reading
2850 @subsubsection nnmbox
2851 @cindex @code{nnmbox}
2852 @cindex unix mail box
2854 @vindex nnmbox-active-file
2855 @vindex nnmbox-mbox-file
2856 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
2857 mail. @code{nnmbox} will add extra headers to each mail article to say
2858 which group it belongs in.
2860 Virtual server settings:
2863 @item nnmbox-mbox-file
2864 @vindex nnmbox-mbox-file
2865 The name of the mail box in the user's home directory.
2867 @item nnmbox-active-file
2868 @vindex nnmbox-active-file
2869 The name of the active file for the mail box.
2871 @item nnmbox-get-new-mail
2872 @vindex nnmbox-get-new-mail
2873 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
2878 @subsubsection nnbabyl
2879 @cindex @code{nnbabyl}
2882 @vindex nnbabyl-active-file
2883 @vindex nnbabyl-mbox-file
2884 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
2885 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
2886 article to say which group it belongs in.
2888 Virtual server settings:
2891 @item nnbabyl-mbox-file
2892 @vindex nnbabyl-mbox-file
2893 The name of the rmail mbox file.
2895 @item nnbabyl-active-file
2896 @vindex nnbabyl-active-file
2897 The name of the active file for the rmail box.
2899 @item nnbabyl-get-new-mail
2900 @vindex nnbabyl-get-new-mail
2901 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
2907 @cindex mail @sc{nov} spool
2909 The @dfn{nnml} spool mail format isn't compatible with any other known
2910 format. It should be used with some caution.
2912 @vindex nnml-directory
2913 If you use this backend, Gnus will split all incoming mail into files;
2914 one file for each mail, and put the articles into the correct
2915 directories under the directory specified by the @code{nnml-directory}
2916 variable. The default value is @file{~/Mail/}.
2918 You do not have to create any directories beforehand; Gnus will take
2921 If you have a strict limit as to how many files you are allowed to store
2922 in your account, you should not use this backend. As each mail gets its
2923 own file, you might very well occupy thousands of inodes within a few
2924 weeks. If this is no problem for you, and it isn't a problem for you
2925 having your friendly systems administrator walking around, madly,
2926 shouting "Who is eating all my inodes?! Who? Who!?!", then you should
2927 know that this is probably the fastest format to use. You do not have
2928 to trudge through a big mbox file just to read your new mail.
2930 @code{nnml} is probably the slowest backend when it comes to article
2931 splitting. It has to create lots of files, and it also generates
2932 @sc{nov} databases for the incoming mails. This makes is the fastest
2933 backend when it comes to reading mail.
2935 Virtual server settings:
2938 @item nnml-directory
2939 @vindex nnml-directory
2940 All @code{nnml} directories will be placed under this directory.
2942 @item nnml-active-file
2943 @vindex nnml-active-file
2944 The active file for the @code{nnml} server.
2946 @item nnml-newsgroups-file
2947 @vindex nnml-newsgroups-file
2948 The @code{nnml} group descriptions file. @xref{Newsgroups File
2951 @item nnml-get-new-mail
2952 @vindex nnml-get-new-mail
2953 If non-@code{nil}, @code{nnml} will read incoming mail.
2955 @item nnml-nov-is-evil
2956 @vindex nnml-nov-is-evil
2957 If non-@code{nil}, this backend will ignore any @sc{nov} files.
2959 @item nnml-nov-file-name
2960 @vindex nnml-nov-file-name
2961 The name of the @sc{nov} files. The default is @file{.overview}.
2965 @findex nnml-generate-nov-databases
2966 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
2967 you can do a complete update by typing @kbd{M-x
2968 nnml-generate-nov-databases}. This command will trawl through the
2969 entire @code{nnml} hierarchy, looking at each and every article, so it
2970 might take a while to complete.
2975 @cindex mh-e mail spool
2977 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
2978 @sc{nov} databases and it doesn't keep an active file. This makes
2979 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
2980 makes it easier to write procmail scripts for.
2982 Virtual server settings:
2985 @item nnmh-directory
2986 @vindex nnmh-directory
2987 All @code{nnmh} directories will be located under this directory.
2989 @item nnmh-get-new-mail
2990 @vindex nnmh-get-new-mail
2991 If non-@code{nil}, @code{nnmh} will read incoming mail.
2994 @vindex nnmh-be-safe
2995 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
2996 sure that the articles in the folder is actually what Gnus think they
2997 are. It will check date stamps, and stat everything in sight, so
2998 setting this to @code{t} will mean a serious slow-down. If you never
2999 use anything by Gnus to read the @code{nnmh} articles, you do not have to set
3000 this variable to @code{t}.
3004 @subsubsection nnfolder
3005 @cindex @code{nnfolder}
3006 @cindex mbox folders
3008 @code{nnfolder} is a backend for storing each mail group in a separate
3009 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
3010 will add extra headers to keep track of article numbers and arrival
3013 Virtual server settings:
3016 @item nnfolder-directory
3017 @vindex nnfolder-directory
3018 All the @code{nnfolder} mail boxes will be stored under this directory.
3020 @item nnfolder-active-file
3021 @vindex nnfolder-active-file
3022 The name of the active file.
3024 @item nnfolder-newsgroups-file
3025 @vindex nnfolder-newsgroups-file
3026 The name of the group descriptions file. @xref{Newsgroups File Format}.
3028 @item nnfolder-get-new-mail
3029 @vindex nnfolder-get-new-mail
3030 If non-@code{nil}, @code{nnfolder} will read incoming mail.
3034 @node Group Parameters
3035 @section Group Parameters
3036 @cindex group parameters
3038 Gnus stores all information on a group in a list that is usually known
3039 as the @dfn{group info}. This list has from three to six elements.
3040 Here's an example info.
3043 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
3044 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
3047 The first element is the @dfn{group name}, as Gnus knows the group,
3048 anyway. The second element is the @dfn{subscription level}, which
3049 normally is a small integer. The third element is a list of ranges of
3050 read articles. The fourth element is a list of lists of article marks
3051 of various kinds. The fifth element is the select method (or virtual
3052 server, if you like). The sixth element is a list of @dfn{group
3053 parameters}, which is what this section is about.
3055 Any of the last three elements may be missing if they are not required.
3056 In fact, the vast majority of groups will normally only have the first
3057 three elements, which saves quite a lot of cons cells.
3059 The group parameters store information local to a particular group:
3064 If the group parameter list contains an element that looks like
3065 @samp{(to-address . "some@@where.com")}, that address will be used by
3066 the backend when doing followups and posts. This is primarily useful in
3067 mail groups that represent close mailing lists. You just set this
3068 address to whatever the list address is.
3070 This trick will actually work whether the group is foreign or not.
3071 Let's say there's a group on the server that is called @samp{fa.4ad-l}.
3072 This is a real newsgroup, but the server has gotten the articles from a
3073 mail-to-news gateway. Posting directly to this group is therefore
3074 impossible---you have to send mail to the mailing list address instead.
3075 Also @xref{Mail & Post}.
3079 If the group parameter list has an element that looks like
3080 @samp{(to-list . "some@@where.com")}, that address will be used when
3081 doing a @kbd{a} in any group. It is totally ignored when doing a
3082 followup---except that if it is present in a news group, you'll get mail
3083 group semantics when doing @kbd{f}.
3087 If the group parameter list contains an element like @code{(to-group
3088 . "some.group.name")}, all posts will be sent to that group.
3092 If this symbol is present in the group parameter list, all articles that
3093 are read will be marked as expirable. For an alternative approach,
3094 @xref{Expiring Old Mail Articles}.
3097 @cindex total-expire
3098 If this symbol is present, all read articles will be put through the
3099 expiry process, even if they are not marked as expirable. Use with
3104 If the group parameter has an element that looks like @samp{(expiry-wait
3105 . 10)}, this value will override any @code{nnmail-expiry-wait} and
3106 @code{nnmail-expiry-wait-functions} when expiring expirable messages.
3107 The value can either be a number of days (not necessarily an integer) or
3108 the symbols @code{never} or @code{immediate}.
3110 @item @var{(variable form)}
3111 You can use the group parameters to set variables local to the group you
3112 are entering. Say you want to turn threading off in
3113 @samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
3114 the group parameters of that group. @code{gnus-show-threads} will be
3115 made into a local variable in the summary buffer you enter, and the form
3116 @code{nil} will be @code{eval}ed there.
3118 This can also be used as a group-specific hook function, if you'd like.
3119 If you want to hear a beep when you enter the group
3120 @samp{alt.binaries.pictures.furniture}, you could put something like
3121 @code{(dummy-variable (ding))} in the parameters of that group.
3122 @code{dummy-variable} will be set to the result of the @code{(ding)}
3123 form, but who cares?
3127 If you want to change the group info you can use the @kbd{G E} command
3128 to enter a buffer where you can edit it.
3130 You usually don't want to edit the entire group info, so you'd be better
3131 off using the @kbd{G p} command to just edit the group parameters.
3133 @node Listing Groups
3134 @section Listing Groups
3135 @cindex group listing
3137 These commands all list various slices of the groups that are available.
3145 @findex gnus-group-list-groups
3146 List all groups that have unread articles
3147 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
3148 command will list only groups of level ARG and lower. By default, it
3149 only lists groups of level five or lower (i.e., just subscribed groups).
3155 @findex gnus-group-list-all-groups
3156 List all groups, whether they have unread articles or not
3157 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
3158 this command will list only groups of level ARG and lower. By default,
3159 it lists groups of level seven or lower (i.e., just subscribed and
3160 unsubscribed groups).
3164 @findex gnus-group-list-level
3165 List all unread groups on a specific level
3166 (@code{gnus-group-list-level}). If given a prefix, also list the groups
3167 with no unread articles.
3171 @findex gnus-group-list-killed
3172 List all killed groups (@code{gnus-group-list-killed}). If given a
3173 prefix argument, really list all groups that are available, but aren't
3174 currently (un)subscribed. This could entail reading the active file
3179 @findex gnus-group-list-zombies
3180 List all zombie groups (@code{gnus-group-list-zombies}).
3184 @findex gnus-group-list-matching
3185 List all subscribed groups with unread articles that match a regexp
3186 (@code{gnus-group-list-matching}).
3190 @findex gnus-group-list-all-matching
3191 List groups that match a regexp (@code{gnus-group-list-all-matching}).
3195 @findex gnus-group-list-active
3196 List absolutely all groups that are in the active file(s) of the
3197 server(s) you are connected to (@code{gnus-group-list-active}). This
3198 might very well take quite a while. It might actually be a better idea
3199 to do a @kbd{A m} to list all matching, and just give @samp{.} as the
3204 @vindex gnus-permanently-visible-groups
3205 @cindex visible group paramenter
3206 Groups that match the @code{gnus-permanently-visible-groups} regexp will
3207 always be shown, whether they have unread articles or not. You can also
3208 add the @code{visible} element to the group parameters in question to
3209 get the same effect.
3211 @node Sorting Groups
3212 @section Sorting Groups
3213 @cindex sorting groups
3215 @kindex C-c C-s (Group)
3216 @findex gnus-group-sort-groups
3217 @vindex gnus-group-sort-function
3218 The @kbd{C-c C-s} (@code{gnus-group-srot-groups}) command sorts the
3219 group buffer according to the function(s) given by the
3220 @code{gnus-group-sort-function} variable. Available sorting functions
3225 @item gnus-group-sort-by-alphabet
3226 @findex gnus-group-sort-by-alphabet
3227 Sort the group names alphabetically. This is the default.
3229 @item gnus-group-sort-by-level
3230 @findex gnus-group-sort-by-level
3231 Sort by group level.
3233 @item gnus-group-sort-by-score
3234 @findex gnus-group-sort-by-score
3235 Sort by group score.
3237 @item gnus-group-sort-by-rank
3238 @findex gnus-group-sort-by-rank
3239 Sort by group score and then the group level. The level and the score
3240 are, when taken together, the group's @dfn{rank}.
3242 @item gnus-group-sort-by-unread
3243 @findex gnus-group-sort-by-unread
3244 Sort by number of unread articles.
3246 @item gnus-group-sort-by-method
3247 @findex gnus-group-sort-by-method
3248 Sort by alphabetically on the select method.
3253 @code{gnus-group-sort-function} can also be a list of sorting
3254 functions. In that case, the most significant sort key function must be
3258 There are also a number of commands for sorting directly according to
3259 some sorting criteria:
3263 @kindex G S a (Group)
3264 @findex gnus-group-sort-groups-by-alphabet
3265 Sort the group buffer alphabetically by group name
3266 (@code{gnus-group-sort-groups-by-alphabet}).
3269 @kindex G S u (Group)
3270 @findex gnus-group-sort-groups-by-unread
3271 Sort the group buffer by the number of unread articles
3272 (@code{gnus-group-sort-groups-by-unread}).
3275 @kindex G S l (Group)
3276 @findex gnus-group-sort-groups-by-level
3277 Sort the group buffer by group level
3278 (@code{gnus-group-sort-groups-by-level}).
3281 @kindex G S v (Group)
3282 @findex gnus-group-sort-groups-by-score
3283 Sort the group buffer by group score
3284 (@code{gnus-group-sort-groups-by-score}).
3287 @kindex G S r (Group)
3288 @findex gnus-group-sort-groups-by-rank
3289 Sort the group buffer by group level
3290 (@code{gnus-group-sort-groups-by-rank}).
3293 @kindex G S m (Group)
3294 @findex gnus-group-sort-groups-by-method
3295 Sort the group buffer alphabetically by backend name
3296 (@code{gnus-group-sort-groups-by-method}).
3300 When given a prefix, all these commands will sort in reverse order.
3304 @node Group Maintenance
3305 @section Group Maintenance
3306 @cindex bogus groups
3311 @findex gnus-group-check-bogus-groups
3312 Find bogus groups and delete them
3313 (@code{gnus-group-check-bogus-groups}).
3317 @findex gnus-find-new-newsgroups
3318 Find new groups and process them (@code{gnus-find-new-newsgroups}).
3321 @kindex C-c C-x (Group)
3322 @findex gnus-group-expire-articles
3323 Run all expirable articles in the current group through the expiry
3324 process (if any) (@code{gnus-group-expire-articles}).
3327 @kindex C-c M-C-x (Group)
3328 @findex gnus-group-expire-all-groups
3329 Run all articles in all groups through the expiry process
3330 (@code{gnus-group-expire-all-groups}).
3335 @node Browse Foreign Server
3336 @section Browse Foreign Server
3337 @cindex foreign servers
3338 @cindex browsing servers
3343 @findex gnus-group-browse-foreign-server
3344 You will be queried for a select method and a server name. Gnus will
3345 then attempt to contact this server and let you browse the groups there
3346 (@code{gnus-group-browse-foreign-server}).
3349 @findex gnus-browse-server-mode
3350 A new buffer with a list of available groups will appear. This buffer
3351 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
3352 (well, a lot) like a normal group buffer, but with one major difference
3353 - you can't enter any of the groups. If you want to read any of the
3354 news available on that server, you have to subscribe to the groups you
3355 think may be interesting, and then you have to exit this buffer. The
3356 new groups will be added to the group buffer, and then you can read them
3357 as you would any other group.
3359 Future versions of Gnus may possibly permit reading groups straight from
3362 Here's a list of keystrokes available in the browse mode:
3367 @findex gnus-group-next-group
3368 Go to the next group (@code{gnus-group-next-group}).
3372 @findex gnus-group-prev-group
3373 Go to the previous group (@code{gnus-group-prev-group}).
3376 @kindex SPC (Browse)
3377 @findex gnus-browse-read-group
3378 Enter the current group and display the first article
3379 (@code{gnus-browse-read-group}).
3382 @kindex RET (Browse)
3383 @findex gnus-browse-select-group
3384 Enter the current group (@code{gnus-browse-select-group}).
3388 @findex gnus-browse-unsubscribe-current-group
3389 Unsubscribe to the current group, or, as will be the case here,
3390 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
3396 @findex gnus-browse-exit
3397 Exit browse mode (@code{gnus-browse-exit}).
3401 @findex gnus-browse-describe-briefly
3402 Describe browse mode briefly (well, there's not much to describe, is
3403 there) (@code{gnus-browse-describe-briefly}).
3407 @section Exiting Gnus
3408 @cindex exiting Gnus
3410 Yes, Gnus is ex(c)iting.
3415 @findex gnus-group-suspend
3416 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
3417 but it kills all buffers except the Group buffer. I'm not sure why this
3418 is a gain, but then who am I to judge?
3421 @findex gnus-group-exit
3422 Quit Gnus (@code{gnus-group-exit}).
3425 @findex gnus-group-quit
3426 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
3429 @vindex gnus-exit-gnus-hook
3430 @vindex gnus-suspend-gnus-hook
3431 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
3432 @code{gnus-exit-gnus-hook} is called when you quit Gnus.
3436 If you wish to completely unload Gnus and all its adherents, you can use
3437 the @code{gnus-unload} command. This command is also very handy when
3438 trying to custoize meta-variables.
3443 Miss Lisa Cannifax, while sitting in English class, feels her feet go
3444 numbly heavy and herself fall into a hazy trance as the boy sitting
3445 behind her drew repeated lines with his pencil across the back of her
3451 @section Group Topics
3454 If you read lots and lots of groups, it might be convenient to group
3455 them hierarchically according to topics. You put your Emacs groups over
3456 here, your sex groups over there, and the rest (what, two groups or so?)
3457 you put in some misc section that you never bother with anyway. You can
3458 even group the Emacs sex groups as a sub-topic to either the Emacs
3459 groups or the sex groups---or both! Go wild!
3461 @findex gnus-topic-mode
3463 To get this @emph{fab} functionality you simply turn on (ooh!) the
3464 @code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
3465 is a toggling command.)
3467 Go ahead, just try it. I'll still be here when you get back. La de
3468 dum... Nice tune, that... la la la... What, you're back? Yes, and now
3469 press @kbd{l}. There. All your groups are now listed under
3470 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
3473 If you want this permanently enabled, you should add that minor mode to
3474 the hook for the group mode:
3477 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
3480 There are, in general, two methods for dividing the groups into topics.
3481 You can either sniff around some variables, or you can use some handy
3485 * Topic Variables:: How to customize the topics the Lisp Way.
3486 * Topic Commands:: Interactive E-Z commands.
3487 * Topic Topology:: A map of the world.
3491 @node Topic Variables
3492 @subsection Topic Variables
3493 @cindex topic variables
3495 @vindex gnus-group-topics
3497 @code{gnus-group-topics} is the main variable that specifies what topics
3498 each group belong to. That is an alist where each entry looks like
3505 As you've already guessed (only geniï read manuals anyway), all
3506 groups that match @var{regexp} gets put into a section called
3507 @var{topic}. If @var{show} is non-@code{nil}, it overrides
3508 @code{gnus-group-topic-topics-only}. In specific, if @var{show} is
3509 @code{t}, all groups with this topic are always shown, and if it is a
3510 number, these groups are never shown.
3512 @vindex gnus-group-topic-topics-only
3513 Whoo, this is complicated. If @code{gnus-group-topic-topics-only} is
3514 @code{nil}, all groups and topics will be listed, as you would expect.
3515 If this variable is non-@code{nil}, only the topics will be listed, and
3516 the groups will not be listed. This makes the group buffer much shorter,
3517 I'm sure you'll agree. This is all modified on a topic-by-topic basis
3518 by the @var{show} parameter. It makes perfect sense, really.
3520 @vindex gnus-topic-unique
3521 If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
3522 of (tops) one topic each. If this is @code{nil}, each group might end
3523 up being a member of several topics.
3525 You can also put a @code{topic} in the group parameters (@pxref{Group
3528 Now, if you select a topic, if will fold/unfold that topic, which is
3529 really neat, I think.
3531 Here's an example @code{gnus-group-topics}:
3534 (("Emacs - the Spice of Life" "^gnu.emacs\\|comp.emacs" t)
3535 ("Alternativeness" "^alt" 0)
3536 ("Hard Stuff" "^comp" nil)
3537 ("The Rest" "." nil))
3540 @vindex gnus-topic-line-format
3541 The topic lines themselves are created according to the
3542 @code{gnus-topic-line-format} variable. @xref{Formatting Variables}.
3543 Elements allowed are:
3555 Number of groups in the topic.
3557 Number of unread articles in the topic.
3561 @node Topic Commands
3562 @subsection Topic Commands
3563 @cindex topic commands
3565 When the topic minor mode is turned on, a new @kbd{T} submap will be
3566 available. In addition, a few of the standard keys change their
3567 definitions slightly.
3573 @findex gnus-topic-create-topic
3574 Create a new topic (@code{gnus-topic-create-subtopic}). You will be
3575 prompted for a topic name and the name of the parent topic.
3579 @findex gnus-topic-move-group
3580 Move the current group to some other topic
3581 (@code{gnus-topic-move-group}). This command understands the
3582 process/prefix convention (@pxref{Process/Prefix}).
3586 @findex gnus-topic-copy-group
3587 Copy the current group to some other topic
3588 (@code{gnus-topic-copy-group}). This command understands the
3589 process/prefix convention (@pxref{Process/Prefix}).
3593 @findex gnus-topic-move-matching
3594 Move all groups that match some regular expression to a topic
3595 (@code{gnus-topic-move-matching}).
3599 @findex gnus-topic-copy-matching
3600 Copy all groups that match some regular expression to a topic
3601 (@code{gnus-topic-copy-matching}).
3605 @findex gnus-topic-select-group
3607 Either select a group or fold a topic (@code{gnus-topic-select-group}).
3608 When you perform this command on a group, you'll enter the group, as
3609 usual. When done on a topic line, the topic will be folded (if it was
3610 visible) or unfolded (if it was folded already). So it's basically a
3611 toggling command on topics. In addition, if you give a numerical
3612 prefix, group on that level (and lower) will be displayed.
3616 @findex gnus-topic-kill-group
3617 Kill a group or topic (@code{gnus-topic-kill-group}).
3621 @findex gnus-topic-yank-group
3622 Yank the previosuly killed group or topic (@code{gnus-topic-yank-group}).
3623 Note that all topics will be yanked before all groups.
3627 @findex gnus-topic-rename
3628 Rename a topic (@code{gnus-topic-rename}).
3631 @kindex T DEL (Group)
3632 @findex gnus-topic-delete
3633 Delete an empty topic (@code{gnus-topic-delete}).
3638 @node Topic Topology
3639 @subsection Topic Topology
3640 @cindex topic topology
3643 So, let's have a look at an example group buffer:
3649 2: alt.religion.emacs
3652 0: comp.talk.emacs.recovery
3654 8: comp.binaries.fractals
3655 13: comp.sources.unix
3658 So, here we have one top-level topic, two topics under that, and one
3659 sub-topic under one of the sub-topics. (There is always just one (1)
3660 top-level topic). This topology can be expressed as follows:
3664 (("Emacs -- I wuw it!" visible)
3665 (("Naughty Emacs" visible)))
3669 This is in fact how the variable @code{gnus-topic-topology} would look
3670 for the display above. That variable is saved in the @file{.newsrc.eld}
3671 file, and shouldn't be messed with manually---unless you really want
3672 to. Since this variable is read from the @file{.newsrc.eld} file,
3673 setting it in any other startup files will have no effect.
3675 This topology shows what topics are sub-topics of what topics (right),
3676 and which topics are visible. Two settings are currently
3677 allowed---@code{visible} and @code{invisible}.
3679 @vindex gnus-topic-hide-subtopics
3680 If @code{gnus-topic-hide-subtopics} is non-@code{nil} (which it is by
3681 default), sub-topics will be folded along with any groups that belong to
3682 the topic. If this variable is @code{nil}, all topics will always be
3683 visible, even though the parent topics are folded.
3686 @node Misc Group Stuff
3687 @section Misc Group Stuff
3693 @findex gnus-group-get-new-news
3694 Check the server(s) for new articles. If the numerical prefix is used,
3695 this command will check only groups of level @var{arg} and lower
3696 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
3697 command will force a total rereading of the active file(s) from the
3702 @findex gnus-group-get-new-news-this-group
3703 Check whether new articles have arrived in the current group
3704 (@code{gnus-group-get-new-news-this-group}).
3708 @findex gnus-group-enter-server-mode
3709 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
3714 @findex gnus-group-fetch-faq
3715 Try to fetch the FAQ for the current group
3716 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
3717 @code{gnus-group-faq-directory}, which is usually a directory on a
3718 remote machine. @code{ange-ftp} will be used for fetching the file.
3721 @findex gnus-group-restart
3722 Restart Gnus (@code{gnus-group-restart}).
3725 @findex gnus-group-read-init-file
3726 @vindex gnus-init-file
3727 Read the init file (@code{gnus-init-file}, which defaults to
3728 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
3731 @findex gnus-group-save-newsrc
3732 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
3733 (@code{gnus-group-save-newsrc}). If given a prefix, force saving the
3734 file(s) whether Gnus thinks it is necessary or not.
3737 @findex gnus-group-clear-dribble
3738 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
3741 @findex gnus-group-describe-group
3742 Describe the current group (@code{gnus-group-describe-group}). If given
3743 a prefix, force Gnus to re-read the description from the server.
3746 @findex gnus-group-apropos
3747 List all groups that have names that match a regexp
3748 (@code{gnus-group-apropos}).
3751 @findex gnus-group-description-apropos
3752 List all groups that have names or descriptions that match a regexp
3753 (@code{gnus-group-description-apropos}).
3756 @findex gnus-group-post-news
3757 Post an article to a group (@code{gnus-group-post-news}). The current
3758 group name will be used as the default.
3761 @findex gnus-group-mail
3762 Mail a message somewhere (@code{gnus-group-mail}).
3764 @kindex C-x C-t (Group)
3765 @findex gnus-group-transpose-groups
3766 Transpose two groups (@code{gnus-group-transpose-groups}).
3769 @findex gnus-version
3770 Display current Gnus version numbers (@code{gnus-version}).
3773 @findex gnus-group-describe-all-groups
3774 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
3775 prefix, force Gnus to re-read the description file from the server.
3778 @findex gnus-group-describe-briefly
3779 Give a very short help message (@code{gnus-group-describe-briefly}).
3781 @kindex C-c C-i (Group)
3782 @findex gnus-info-find-node
3783 Go to the Gnus info node (@code{gnus-info-find-node}).
3786 @vindex gnus-group-prepare-hook
3787 @code{gnus-group-prepare-hook} is called after the group buffer is
3788 generated. It may be used to modify the buffer in some strange,
3791 @node The Summary Buffer
3792 @chapter The Summary Buffer
3793 @cindex summary buffer
3795 A line for each article is displayed in the summary buffer. You can
3796 move around, read articles, post articles and reply to articles.
3799 * Summary Buffer Format:: Deciding how the summary buffer is to look.
3800 * Summary Maneuvering:: Moving around the summary buffer.
3801 * Choosing Articles:: Reading articles.
3802 * Paging the Article:: Scrolling the current article.
3803 * Reply Followup and Post:: Posting articles.
3804 * Canceling and Superseding:: "Whoops, I shouldn't have called him that."
3805 * Marking Articles:: Marking articles as read, expirable, etc.
3806 * Limiting:: You can limit the summary buffer.
3807 * Threading:: How threads are made.
3808 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
3809 * Article Caching:: You may store articles in a cache.
3810 * Article Backlog:: Having already read articles hang around.
3811 * Exiting the Summary Buffer:: Returning to the Group buffer.
3812 * Process/Prefix:: A convention used by many treatment commands.
3813 * Saving Articles:: Ways of customizing article saving.
3814 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
3815 * Article Treatment:: The article buffer can be mangled at will.
3816 * Summary Sorting:: You can sort the summary buffer four ways.
3817 * Finding the Parent:: No child support? Get the parent.
3818 * Mail Group Commands:: Some commands can only be used in mail groups.
3819 * Various Summary Stuff:: What didn't fit anywhere else.
3823 @node Summary Buffer Format
3824 @section Summary Buffer Format
3825 @cindex summary buffer format
3828 * Summary Buffer Lines:: You can specify how summary lines should look.
3829 * Summary Buffer Mode Line:: You can say how the mode line should look.
3832 @findex mail-extract-address-components
3833 @findex gnus-extract-address-components
3834 @vindex gnus-extract-address-components
3835 Gnus will use the value of the @code{gnus-extract-address-components}
3836 variable as a function for getting the name and address parts of a
3837 @code{From} header. Two pre-defined function exist:
3838 @code{gnus-extract-address-components}, which is the default, quite
3839 fast, and too simplistic solution; and
3840 @code{mail-extract-address-components}, which works very nicely, but is
3843 @vindex gnus-summary-same-subject
3844 @code{gnus-summary-same-subject} is a string indicating that the current
3845 article has the same subject as the previous. This string will be used
3846 with those specs that require it. The default is @samp{""}.
3848 @node Summary Buffer Lines
3849 @subsection Summary Buffer Lines
3851 @vindex gnus-summary-line-format
3852 You can change the format of the lines in the summary buffer by changing
3853 the @code{gnus-summary-line-format} variable. It works along the same
3854 lines a a normal @code{format} string, with some extensions.
3856 The default string is @samp{"%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n"}.
3858 The following format specification characters are understood:
3866 Subject if the article is the root, @code{gnus-summary-same-subject}
3869 Full @code{From} line.
3871 The name (from the @code{From} header).
3873 The name (from the @code{From} header). This differs from the @code{n}
3874 spec in that it uses @code{gnus-extract-address-components}, which is
3875 slower, but may be more thorough.
3877 The address (from the @code{From} header). This works the same way as
3880 Number of lines in the article.
3882 Number of characters in the article.
3884 Indentation based on thread level (@pxref{Customizing Threading}).
3886 Nothing if the article is a root and lots of spaces if it isn't (it
3887 pushes everything after it off the screen).
3889 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
3890 for adopted articles.
3892 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
3893 for adopted articles.
3895 One space for each thread level.
3897 Twenty minus thread level spaces.
3905 @vindex gnus-summary-zcore-fuzz
3906 Zcore, @samp{+} if above the default level and @samp{-} if below the
3907 default level. If the difference between
3908 @code{gnus-summary-default-level} and the score is less than
3909 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
3919 Number of articles in the current sub-thread. Using this spec will slow
3920 down summary buffer generation somewhat.
3922 A single character will be displayed if the article has any children.
3924 User defined specifier. The next character in the format string should
3925 be a letter. @sc{gnus} will call the function
3926 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
3927 following @samp{%u}. The function will be passed the current header as
3928 argument. The function should return a string, which will be inserted
3929 into the summary just like information from any other summary specifier.
3932 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
3933 have to be handled with care. For reasons of efficiency, Gnus will
3934 compute what column these characters will end up in, and "hard-code"
3935 that. This means that it is illegal to have these specs after a
3936 variable-length spec. Well, you might not be arrested, but your summary
3937 buffer will look strange, which is bad enough.
3939 The smart choice is to have these specs as far to the left as possible.
3940 (Isn't that the case with everything, though? But I digress.)
3942 This restriction may disappear in later versions of Gnus.
3944 @node Summary Buffer Mode Line
3945 @subsection Summary Buffer Mode Line
3947 @vindex gnus-summary-mode-line-format
3948 You can also change the format of the summary mode bar. Set
3949 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
3950 elements you can play with:
3956 Unprefixed group name.
3958 Current article number.
3962 Number of unread articles in this group.
3964 Number of unselected articles in this group.
3966 A string with the number of unread and unselected articles represented
3967 either as @samp{<%U(+%u) more>} if there are both unread and unselected
3968 articles, and just as @samp{<%U more>} if there are just unread articles
3969 and no unselected ones.
3971 Shortish group name. For instance, @samp{rec.arts.anime} will be
3972 shortened to @samp{r.a.anime}.
3974 Subject of the current article.
3978 Name of the current score file.
3980 Number of dormant articles.
3982 Number of ticked articles.
3984 Number of articles that have been marked as read in this session.
3986 Number of articles expunged by the score files.
3990 @node Summary Maneuvering
3991 @section Summary Maneuvering
3992 @cindex summary movement
3994 All the straight movement commands understand the numeric prefix and
3995 behave pretty much as you'd expect.
3997 None of these commands select articles.
4002 @kindex M-n (Summary)
4003 @kindex G M-n (Summary)
4004 @findex gnus-summary-next-unread-subject
4005 Go to the next summary line of an unread article
4006 (@code{gnus-summary-next-unread-subject}).
4009 @kindex M-p (Summary)
4010 @kindex G M-p (Summary)
4011 @findex gnus-summary-prev-unread-subject
4012 Go to the previous summary line of an unread article
4013 (@code{gnus-summary-prev-unread-subject}).
4017 @kindex G g (Summary)
4018 @findex gnus-summary-goto-subject
4019 Ask for an article number and then go to this summary line
4020 (@code{gnus-summary-goto-subject}).
4023 @vindex gnus-auto-select-next
4024 If you are at the end of the group and issue one of the movement
4025 commands, Gnus will offer to go to the next group. If
4026 @code{gnus-auto-select-next} is @code{t} and the next group is empty,
4027 Gnus will exit summary mode and return to the group buffer. If this
4028 variable is neither @code{t} nor @code{nil}, Gnus will select the next
4029 group, no matter whether it has any unread articles or not. As a
4030 special case, if this variable is @code{quietly}, Gnus will select the
4031 next group without asking for confirmation. If this variable is
4032 @code{almost-quietly}, the same will happen only if you are located on
4033 the last article in the group. Also @xref{Group Levels}.
4035 If Gnus asks you to press a key to confirm going to the next group, you
4036 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
4037 buffer, searching for the next group to read without actually returning
4038 to the group buffer.
4040 @vindex gnus-auto-select-same
4041 If @code{gnus-auto-select-same} is non-@code{nil}, all the movement
4042 commands will try to go to the next article with the same subject as the
4043 current. This variable is not particularly useful if you use a threaded
4046 @vindex gnus-summary-check-current
4047 If @code{gnus-summary-check-current} is non-@code{nil}, all the "unread"
4048 movement commands will not proceed to the next (or previous) article if
4049 the current article is unread. Instead, they will choose the current
4052 @vindex gnus-auto-center-summary
4053 If @code{gnus-auto-center-summary} is non-@code{nil}, Gnus will keep the
4054 point in the summary buffer centered at all times. This makes things
4055 quite tidy, but if you have a slow network connection, or simply do not
4056 like this un-Emacsism, you can set this variable to @code{nil} to get
4057 the normal Emacs scrolling action.
4059 @node Choosing Articles
4060 @section Choosing Articles
4061 @cindex selecting articles
4063 None of the following movement commands understand the numeric prefix,
4064 and they all select and display an article.
4068 @kindex SPACE (Summary)
4069 @findex gnus-summary-next-page
4070 Select the current article, or, if that one's read already, the next
4071 unread article (@code{gnus-summary-next-page}).
4075 @kindex G n (Summary)
4076 @findex gnus-summary-next-unread-article
4077 Go to next unread article (@code{gnus-summary-next-unread-article}).
4081 @findex gnus-summary-prev-unread-article
4082 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
4086 @kindex G N (Summary)
4087 @findex gnus-summary-next-article
4088 Go to the next article (@code{gnus-summary-next-article}).
4092 @kindex G P (Summary)
4093 @findex gnus-summary-prev-article
4094 Go to the previous article (@code{gnus-summary-prev-article}).
4096 @kindex G C-n (Summary)
4097 @findex gnus-summary-next-same-subject
4098 Go to the next article with the same subject
4099 (@code{gnus-summary-next-same-subject}).
4101 @kindex G C-p (Summary)
4102 @findex gnus-summary-prev-same-subject
4103 Go to the previous article with the same subject
4104 (@code{gnus-summary-prev-same-subject}).
4107 @kindex G f (Summary)
4109 @findex gnus-summary-first-unread-article
4110 Go to the first unread article
4111 (@code{gnus-summary-first-unread-article}).
4114 @kindex G b (Summary)
4116 Go to the article with the highest score
4117 (@code{gnus-summary-best-unread-article}).
4121 @kindex G l (Summary)
4122 @findex gnus-summary-goto-last-article
4123 Go to the previous article read (@code{gnus-summary-goto-last-article}).
4125 @kindex G p (Summary)
4126 @findex gnus-summary-pop-article
4127 Pop an article off the summary history and go to this article
4128 (@code{gnus-summary-pop-article}). This command differs from the
4129 command above in that you can pop as many previous articles off the
4130 history as you like.
4133 Some variables that are relevant for moving and selecting articles:
4136 @item gnus-auto-extend-newsgroup
4137 @vindex gnus-auto-extend-newsgroup
4138 All the movement commands will try to go to the previous (or next)
4139 article, even if that article isn't displayed in the Summary buffer if
4140 this variable is non-@code{nil}. Gnus will then fetch the article from
4141 the server and display it in the article buffer.
4142 @item gnus-select-article-hook
4143 @vindex gnus-select-article-hook
4144 This hook is called whenever an article is selected. By default it
4145 exposes any threads hidden under the selected article.
4146 @item gnus-mark-article-hook
4147 @vindex gnus-mark-article-hook
4148 This hook is called whenever an article is selected. It is intended to
4149 be used for marking articles as read.
4150 @item gnus-visual-mark-article-hook
4151 @vindex gnus-visual-mark-article-hook
4152 This hook is run after selecting an article. It is meant to be used for
4153 highlighting the article in some way. It is not run if
4154 @code{gnus-visual} is @code{nil}.
4155 @item gnus-summary-update-hook
4156 @vindex gnus-summary-update-hook
4157 This hook is called when a summary line is changed. It is not run if
4158 @code{gnus-visual} is @code{nil}.
4159 @item gnus-summary-selected-face
4160 @vindex gnus-summary-selected-face
4161 This is the face (or @dfn{font} as some people call it) that is used to
4162 highlight the current article in the summary buffer.
4163 @item gnus-summary-highlight
4164 @vindex gnus-summary-highlight
4165 Summary lines are highlighted according to this variable, which is a
4166 list where the elements are on the format @code{(FORM . FACE)}. If you
4167 would, for instance, like ticked articles to be italic and high-scored
4168 articles to be bold, you could set this variable to something like
4170 (((eq mark gnus-ticked-mark) . italic)
4171 ((> score default) . bold))
4173 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
4174 @var{FACE} will be applied to the line.
4177 @node Paging the Article
4178 @section Scrolling the Article
4179 @cindex article scrolling
4184 @kindex SPACE (Summary)
4185 @findex gnus-summary-next-page
4186 Pressing @kbd{SPACE} will scroll the current article forward one page,
4187 or, if you have come to the end of the current article, will choose the
4188 next article (@code{gnus-summary-next-page}).
4191 @kindex DEL (Summary)
4192 @findex gnus-summary-prev-page
4193 Scroll the current article back one page (@code{gnus-summary-prev-page}).
4195 @kindex RET (Summary)
4196 @findex gnus-summary-scroll-up
4197 Scroll the current article one line forward
4198 (@code{gnus-summary-scroll-up}).
4203 @kindex A < (Summary)
4204 @findex gnus-summary-beginning-of-article
4205 Scroll to the beginning of the article
4206 (@code{gnus-summary-beginning-of-article}).
4211 @kindex A > (Summary)
4212 @findex gnus-summary-end-of-article
4213 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
4216 @kindex A s (Summary)
4217 @findex gnus-summary-isearch-article
4218 Perform an isearch in the article buffer
4219 (@code{gnus-summary-isearch-article}).
4223 @node Reply Followup and Post
4224 @section Reply, Followup and Post
4229 @kindex C-c C-c (Post)
4230 All the commands for posting and mailing will put you in a post or mail
4231 buffer where you can edit the article all you like, before you send the
4232 article by pressing @kbd{C-c C-c}. If you are in a foreign news group,
4233 and you wish to post the article using the foreign server, you can give
4234 a prefix to @kbd{C-c C-c} to make Gnus try to post using the foreign
4238 * Mail:: Mailing & replying.
4239 * Post:: Posting and following up.
4240 * Posting Server:: What server should you post via?
4241 * Mail & Post:: Mailing and posting at the same time.
4242 * Posting Styles:: An easier way to configure some key elements.
4243 * Drafts:: Postponing messages and rejected messages.
4244 * Rejected Articles:: What happens if the server doesn't like your article?
4250 Commands for composing a mail message:
4256 @kindex S r (Summary)
4258 @findex gnus-summary-reply
4259 Mail a reply to the author of the current article
4260 (@code{gnus-summary-reply}).
4265 @kindex S R (Summary)
4266 @findex gnus-summary-reply-with-original
4267 Mail a reply to the author of the current article and include the
4268 original message (@code{gnus-summary-reply-with-original}). This
4269 command uses the process/prefix convention.
4272 @kindex S o m (Summary)
4273 @findex gnus-summary-mail-forward
4274 Forward the current article to some other person
4275 (@code{gnus-summary-mail-forward}).
4278 @kindex S o p (Summary)
4279 @findex gnus-summary-post-forward
4280 Forward the current article to a newsgroup
4281 (@code{gnus-summary-post-forward}).
4286 @kindex S m (Summary)
4287 @findex gnus-summary-mail-other-window
4288 Send a mail to some other person
4289 (@code{gnus-summary-mail-other-window}).
4292 @kindex S D b (Summary)
4293 @findex gnus-summary-resend-bounced-mail
4294 If you have sent a mail, but the mail was bounced back to you for some
4295 reason (wrong address, transient failure), you can use this command to
4296 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
4297 will be popped into a mail buffer where you can edit the headers before
4298 sending the mail off again. The headers that match the regexp
4299 @code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
4300 automatically deleted first. If you give a prefix to this command, and
4301 the bounced mail is a reply to some other mail, Gnus will try to fetch
4302 that mail and display it for easy perusal of its headers. This might
4303 very well fail, though.
4306 @kindex S D r (Summary)
4307 @findex gnus-summary-resend-message
4308 Not to be confused with the previous command,
4309 @code{gnus-summary-resend-message} will prompt you for an address to
4310 send the current message off to, and then send it to that place. The
4311 headers of the message won't be altered---but lots of headers that say
4312 @samp{Resent-To}, @samp{Resent-From} and so on will be added. This
4313 means that you actually send a mail to someone that has a @samp{To}
4314 header that (proabbly) points to yourself. This will confuse people.
4315 So, natcherly you'll only do that if you're really eVIl.
4317 This command is mainly used if you have several accounts and want to
4318 ship a mail to a different account of yours. (If you're both
4319 @samp{root} and @samp{postmaster} and get a mail for @samp{postmaster}
4320 to the @samp{root} account, you may want to resend it to
4321 @samp{postmaster}. Ordnung muss sein!
4324 @kindex S O m (Summary)
4325 @findex gnus-uu-digest-mail-forward
4326 Digest the current series and forward the result using mail
4327 (@code{gnus-uu-digest-mail-forward}). This command uses the
4328 process/prefix convention (@pxref{Process/Prefix}).
4331 @kindex S O p (Summary)
4332 @findex gnus-uu-digest-post-forward
4333 Digest the current series and forward the result to a newsgroup
4334 (@code{gnus-uu-digest-mail-forward}).
4337 Variables for customizing outgoing mail:
4340 @item gnus-reply-to-function
4341 @vindex gnus-reply-to-function
4342 Gnus uses the normal methods to determine where replies are to go, but
4343 you can change the behavior to suit your needs by fiddling with this
4346 If you want the replies to go to the @samp{Sender} instead of the
4347 @samp{From} in the group @samp{mail.stupid-list}, you could do something
4351 (setq gnus-reply-to-function
4353 (cond ((string= group "mail.stupid-list")
4354 (mail-fetch-field "sender"))
4359 This function will be called narrowed to the head of the article that is
4362 As you can see, this function should return a string if it has an
4363 opinion as to what the To header should be. If it does not, it should
4364 just return @code{nil}, and the normal methods for determining the To
4365 header will be used.
4367 This function can also return a list. In that case, each list element
4368 should be a cons, where the car should be the name of an header
4369 (eg. @samp{Cc}) and the cdr should be the header value
4370 (eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
4371 the head of the outgoing mail.
4373 @item gnus-mail-send-method
4374 @vindex gnus-mail-send-method
4375 This variable says how a mail should be mailed. It uses the function in
4376 the @code{send-mail-function} variable as the default.
4378 @item gnus-uu-digest-headers
4379 @vindex gnus-uu-digest-headers
4380 List of regexps to match headers included in digested messages. The
4381 headers will be included in the sequence they are matched.
4383 @item gnus-mail-hook
4384 @vindex gnus-mail-hook
4385 Hook called as the last thing after setting up a mail buffer.
4387 @item gnus-required-mail-headers
4388 @vindex gnus-required-mail-headers
4389 Gnus will generate headers in all outgoing mail instead of letting
4390 @code{sendmail} do it for us. This makes it possible to do more neat
4391 stuff, like putting mail without sending it, do hairy @code{Fcc}
4392 handling, and much more. This variable controls what headers Gnus will
4393 generate, and is of the exact same form as @code{gnus-required-headers},
4394 which does the same for news articles (@pxref{Post}).
4396 The @code{Newsgroups} header is illegal in this list, while @code{To} is
4397 required, and @code{X-Mailer} can be added if you so should want.
4399 @findex gnus-forward-start-separator
4400 @item gnus-forward-start-separator
4401 Delimiter inserted before forwarded messages.
4403 @findex gnus-forward-end-separator
4404 @item gnus-forward-end-separator
4405 Delimiter inserted after forwarded messages.
4407 @findex gnus-signature-before-forwarded-message
4408 @item gnus-signature-before-forwarded-message
4409 If this variable is @code{t}, which it is by default, your personal
4410 signature will be inserted before the forwarded message. If not, the
4411 forwarded message will be inserted first in the new mail.
4415 @kindex C-c C-c (Mail)
4416 @kindex C-c C-p (Mail)
4417 @findex gnus-put-message
4418 You normally send a mail message by pressing @kbd{C-c C-c}. However,
4419 you may wish to just put the mail message you have just written in your
4420 own local mail group instead of sending it. Sounds quite unlikely, but
4421 I found that useful, so you can now also press @kbd{C-c C-p} to
4422 @dfn{put} the article in the current mail group, or, if there is no such
4423 thing, you will be prompted for a mail group, and then the article will
4424 be put there. This means that the article is @dfn{not} mailed.
4426 There are three "methods" for handling all mail. The default is
4427 @code{sendmail}. Some people like what @code{mh} does better, and some
4428 people prefer @code{vm}.
4430 Three variables for customizing what to use when:
4434 @vindex gnus-mail-reply-method
4435 @item gnus-mail-reply-method
4436 This function is used to compose replies. The three functions avaibale
4439 @findex gnus-mail-reply-using-vm
4440 @findex gnus-mail-reply-using-mhe
4441 @findex gnus-mail-reply-using-mail
4444 @code{gnus-mail-reply-using-mail} (sendmail)
4446 @code{gnus-mail-reply-using-mhe} (mh)
4448 @code{gnus-mail-reply-using-vm} (vm)
4451 @vindex gnus-mail-forward-method
4452 @item gnus-mail-forward-method
4453 This function is used to forward messages. The three functions avaibale
4456 @findex gnus-mail-forward-using-vm
4457 @findex gnus-mail-forward-using-mhe
4458 @findex gnus-mail-forward-using-mail
4461 @code{gnus-mail-forward-using-mail} (sendmail)
4463 @code{gnus-mail-forward-using-mhe} (mh)
4465 @code{gnus-mail-forward-using-vm} (vm)
4468 @vindex gnus-mail-other-window-method
4469 @item gnus-mail-other-window-method
4470 This function is used to send mails. The three functions avaibale are:
4472 @findex gnus-mail-other-window-using-vm
4473 @findex gnus-mail-other-window-using-mhe
4474 @findex gnus-mail-other-window-using-mail
4477 @code{gnus-mail-other-window-using-mail} (sendmail)
4479 @code{gnus-mail-other-window-using-mhe} (mh)
4481 @code{gnus-mail-other-window-using-vm} (vm)
4490 Commands for posting an article:
4496 @kindex S p (Summary)
4497 @findex gnus-summary-post-news
4498 Post an article to the current group
4499 (@code{gnus-summary-post-news}).
4503 @kindex S f (Summary)
4504 @findex gnus-summary-followup
4505 Post a followup to the current article (@code{gnus-summary-followup}).
4508 @kindex S F (Summary)
4510 @findex gnus-summary-followup-with-original
4511 Post a followup to the current article and include the original message
4512 (@code{gnus-summary-followup-with-original}). This command uses the
4513 process/prefix convention.
4515 @kindex S u (Summary)
4516 @findex gnus-uu-post-news
4517 Uuencode a file, split it into parts, and post it as a series
4518 (@code{gnus-uu-post-news}).
4519 @c (@pxref{Uuencoding & Posting}).
4522 @vindex gnus-required-headers
4523 @code{gnus-required-headers} a list of header symbols. These headers
4524 will either be automatically generated, or, if that's impossible, they
4525 will be prompted for. The following symbols are legal:
4529 This required header will be filled out with the result of the
4530 @code{gnus-inews-user-name} function, which depends on the
4531 @code{gnus-user-from-line}, @code{gnus-user-login-name},
4532 @code{gnus-local-domain} and @code{user-mail-address} variables.
4534 This required header will be prompted for if not present already.
4536 This required header says which newsgroups the article is to be posted
4537 to. If it isn't present already, it will be prompted for.
4539 @cindex organization
4540 @vindex gnus-local-organization
4541 @vindex gnus-organization-file
4542 This optional header will be filled out depending on the
4543 @code{gnus-local-organization} variable. @code{gnus-organization-file}
4544 will be used if that variable is nil.
4546 This optional header will be computed by Gnus.
4549 This required header will be generated by Gnus. A unique ID will be
4550 created based on date, time, user name and system name.
4552 @cindex X-Newsreader
4553 This optional header will be filled out with the Gnus version numbers.
4555 @vindex gnus-article-expires
4557 This extremely optional header will be inserted according to the
4558 @code{gnus-article-expires} variable. It is highly deprecated and
4559 shouldn't be used unless you know what you're doing.
4561 This optional header is filled out according to the
4562 @code{gnus-distribution-function} variable. It is a deprecated and much
4563 misunderstood header.
4566 In addition, you can enter conses into this list. The car of this cons
4567 should be a symbol. This symbol's name is the name of the header, and
4568 the cdr can either be a string to be entered verbatim as the value of
4569 this header, or it can be a function to be called. This function should
4570 return a string to be inserted. For instance, if you want to insert
4571 @samp{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
4572 into the list. If you want to insert a funny quote, you could enter
4573 something like @code{(X-Yow . yow)} into the list. The function
4574 @code{yow} will then be called without any arguments.
4576 The list contains a cons where the car of the cons is @code{optional},
4577 the cdr of this cons will only be inserted if it is non-@code{nil}.
4579 Other variables for customizing outgoing articles:
4582 @item nntp-news-default-headers
4583 @vindex nntp-news-default-headers
4584 If non-@code{nil}, this variable will override
4585 @code{mail-default-headers} when posting. This variable should then be
4586 a string. This string will be inserted, as is, in the head of all
4589 @item gnus-use-followup-to
4590 @vindex gnus-use-followup-to
4591 If @code{nil}, always ignore the Followup-To header. If it is @code{t},
4592 use its value, but ignore the special value @samp{poster}, which will
4593 send the followup as a reply mail to the person you are responding to.
4594 If it is the symbol @code{ask}, query the user before posting.
4595 If it is the symbol @code{use}, always use the value.
4597 @item gnus-followup-to-function
4598 @vindex gnus-followup-to-function
4599 This variable is most useful in mail groups, where "following up" really
4600 means sending a mail to a list address. Gnus uses the normal methods to
4601 determine where follow-ups are to go, but you can change the behavior
4602 to suit your needs by fiddling with this variable.
4604 If you want the followups to go to the @samp{Sender} instead of the
4605 @samp{From} in the group @samp{mail.stupid-list}, you could do something
4609 (setq gnus-followup-to-function
4611 (cond ((string= group "mail.stupid-list")
4612 (mail-fetch-field "sender"))
4617 This function will be called narrowed to header of the article that is
4620 @item gnus-removable-headers
4621 @vindex gnus-removable-headers
4622 Some headers that are generated are toxic to the @sc{nntp} server.
4623 These include the @code{NNTP-Posting-Host}, @code{Bcc} and @code{Xref},
4624 so these headers are deleted if they are present in this list of
4627 @item gnus-deletable-headers
4628 @vindex gnus-deletable-headers
4629 Headers in this list that were previously generated by Gnus will be
4630 deleted before posting. Let's say you post an article. Then you decide
4631 to post it again to some other group, you naughty boy, so you jump back
4632 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
4633 ship it off again. By default, this variable makes sure that the old
4634 generated @code{Message-ID} is deleted, and a new one generated. If
4635 this isn't done, the entire empire would probably crumble, anarchy would
4636 prevail, and cats would start walking on two legs and rule the world.
4639 @item gnus-signature-function
4640 @vindex gnus-signature-function
4641 If non-@code{nil}, this variable should be a function that returns a
4642 signature file name. The function will be called with the name of the
4643 group being posted to. If the function returns a string that doesn't
4644 correspond to a file, the string itself is inserted. If the function
4645 returns @code{nil}, the @code{gnus-signature-file} variable will be used
4648 @item gnus-post-prepare-function
4649 @vindex gnus-post-prepare-function
4650 This function is called with the name of the current group after the
4651 post buffer has been initialized, and can be used for inserting a
4652 signature. Nice if you use different signatures in different groups.
4654 @item gnus-post-prepare-hook
4655 @vindex gnus-post-prepare-hook
4656 This hook is called after a post buffer has been prepared. If you want
4657 to insert a signature at this point, you could put
4658 @code{gnus-inews-insert-signature} into this hook.
4660 @item news-reply-header-hook
4661 @vindex news-reply-header-hook
4662 A related variable when following up and replying is this variable,
4663 which inserts the @dfn{quote line}. The default value is:
4666 (defvar news-reply-header-hook
4668 (insert "In article " news-reply-yank-message-id
4669 " " news-reply-yank-from " writes:\n\n")))
4672 This will create lines like:
4675 In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
4678 Having the @code{Message-ID} in this line is probably overkill, so I
4679 would suggest this hook instead:
4682 (setq news-reply-header-hook
4683 (lambda () (insert news-reply-yank-from " writes:\n\n")))
4686 @item gnus-prepare-article-hook
4687 @vindex gnus-prepare-article-hook
4688 This hook is called before the headers have been prepared.
4690 @item gnus-inews-article-function
4691 @vindex gnus-inews-article-function
4692 This function is used to do the actual article processing and header
4693 checking/generation.
4695 @item gnus-inews-article-hook
4696 @vindex gnus-inews-article-hook
4697 This hook is called right before the article is posted. By default it
4698 handles FCC processing (i.e., saving the article to a file.)
4700 @item gnus-inews-article-header-hook
4701 @vindex gnus-inews-article-header-hook
4702 This hook is called after inserting the required headers in an article
4703 to be posted. The hook is called from the @code{*post-news*} buffer,
4704 narrowed to the head, and is intended for people who would like to
4705 insert additional headers, or just change headers in some way or other.
4707 @item gnus-check-before-posting
4708 @vindex gnus-check-before-posting
4709 If non-@code{nil}, Gnus will attempt to check the legality of the
4710 headers, as well as some other stuff, before posting. You can control
4711 the granularity of the check by adding or removing elements from this
4712 list. Legal elemetents are:
4716 Check the subject for commands.
4718 Insert a new @code{Sender} header if the @code{From} header looks odd.
4719 @item multiple-headers
4720 Check for the existence of multiple equal headers.
4722 Check for the existence of version and sendsys commands.
4724 Check whether the @code{Message-ID} looks ok.
4726 Check whether the @code{From} header seems nice.
4728 Check for too long lines.
4730 Check for illegal characters.
4732 Check for excessive size.
4734 Check whether there is any new text in the messages.
4736 Check the length of the signature.
4738 Check whether the article has an @code{Approved} header, which is
4739 something only moderators should include.
4745 @node Posting Server
4746 @subsection Posting Server
4748 When you press those magical @kbd{C-c C-c} keys to ship off your latest
4749 (extremely intelligent, of course) article, where does it go?
4751 Thank you for asking. I hate you.
4753 @vindex gnus-post-method
4755 It can be quite complicated. Normally, Gnus will use the same native
4756 server. However. If your native server doesn't allow posting, just
4757 reading, you probably want to use some other server to post your
4758 (extremely intelligent and fabulously interesting) articles. You can
4759 then set the @code{gnus-post-method} to some other method:
4762 (setq gnus-post-method '(nnspool ""))
4765 Now, if you've done this, and then this server rejects your article, or
4766 this server is down, what do you do then? To override this variable you
4767 can use a prefix to the @kbd{C-c C-c} command to force using the
4768 "current" server for posting.
4772 @subsection Mail & Post
4774 Commands for sending mail and post at the same time:
4778 @kindex S b (Summary)
4779 @findex gnus-summary-followup-and-reply
4780 Post a followup and send a reply to the current article
4781 (@code{gnus-summary-followup-and-reply}).
4783 @kindex S B (Summary)
4784 @findex gnus-summary-followup-and-reply-with-original
4785 Post a followup and send a reply to the current article and include the
4786 original message (@code{gnus-summary-followup-and-reply-with-original}).
4787 This command uses the process/prefix convention.
4790 Here's a list of variables that are relevant to both mailing and
4794 @item gnus-signature-file
4795 @itemx mail-signature
4796 @vindex mail-signature
4797 @vindex gnus-signature-file
4798 @cindex double signature
4800 If @code{gnus-signature-file} is non-@code{nil}, it should be the name
4801 of a file containing a signature (@samp{~/.signature} by default). This
4802 signature will be appended to all outgoing post. Most people find it
4803 more convenient to use @code{mail-signature}, which (sort of) does the
4804 same, but inserts the signature into the buffer before you start editing
4805 the post (or mail). So---if you have both of these variables set, you
4806 will get two signatures. Note that @code{mail-signature} does not work
4807 the same way as @code{gnus-signature-file}, which is a bit confusing.
4808 If @code{mail-signature} is @code{t}, it will insert
4809 @file{~/.signature}. If it is a string, this string will be inserted.
4811 Note that RFC1036 says that a signature should be preceded by the three
4812 characters @samp{-- } on a line by themselves. This is to make it
4813 easier for the recipient to automatically recognize and process the
4814 signature. So don't remove those characters, even though you might feel
4815 that they ruin you beautiful design, like, totally.
4817 Also note that no signature should be more than four lines long.
4818 Including ASCII graphics is an efficient way to get everybody to believe
4819 that you are silly and have nothing important to say.
4821 @item mail-yank-prefix
4822 @vindex mail-yank-prefix
4825 When you are replying to or following up an article, you normally want
4826 to quote the person you are answering. Inserting quoted text is done by
4827 @dfn{yanking}, and each quoted line you yank will have
4828 @code{mail-yank-prefix} prepended to it. This is @samp{ } by default,
4829 which isn't very pretty. Most everybody prefers that lines are
4830 prepended with @samp{> }, so @code{(setq mail-yank-prefix "> ")} in your
4833 @item mail-yank-ignored-headers
4834 @vindex mail-yank-ignored-headers
4835 When you yank a message, you do not want to quote any headers, so
4836 @code{(setq mail-yank-ignored-headers "^")}.
4838 @item user-mail-address
4839 @vindex user-mail-address
4840 If all of @code{gnus-user-login-name}, @code{gnus-use-generic-from} and
4841 @code{gnus-local-domain} are @code{nil}, Gnus will use
4842 @code{user-mail-address} as the address part of the @code{From} header.
4844 @item gnus-local-domain
4845 @vindex gnus-local-domain
4847 The local doman name excluding the host name. If your host is called
4848 @samp{"narfi.ifi.uio.no"}, then this variable should be
4849 @samp{"ifi.uio.no"}.
4851 @item gnus-local-domain
4852 @vindex gnus-local-domain
4854 The local doman name excluding the host name. If your host is called
4855 @samp{"narfi.ifi.uio.no"}, then this variable should be
4856 @samp{"ifi.uio.no"}.
4858 @item gnus-user-from-line
4859 @vindex gnus-user-from-line
4860 Your full, complete e-mail address with name. This variable overrides
4861 the other Gnus variables if it is non-@code{nil}.
4863 Here are two example values of this variable: @samp{"larsi@@ifi.uio.no
4864 (Lars Magne Ingebrigtsen)"} and @samp{"Lars Magne Ingebrigtsen
4865 <larsi@@ifi.uio.no>"}. The latter version is recommended in news (and is
4866 probably illegal in mail), but the name has to be quoted if it contains
4867 non-alpha-numerical characters---@samp{"\"Lars M. Ingebrigtsen\"
4868 <larsi@@ifi.uio.no>"}.
4870 @item mail-default-headers
4871 @vindex mail-default-headers
4872 This is a string that will be inserted into the header of all outgoing
4873 mail messages and news articles. Convenient to use to insert standard
4874 headers. If @code{nntp-news-default-headers} is non-@code{nil}, that
4875 variable will override this one when posting articles.
4877 @item gnus-auto-mail-to-author
4878 @vindex gnus-auto-mail-to-author
4879 If @code{ask}, you will be prompted for whether you want to send a mail
4880 copy to the author of the article you are following up. If
4881 non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
4882 all follow-ups to the authors of the articles you follow up. It's nice
4883 in one way---you make sure that the person you are responding to gets
4884 your response. Other people loathe this method and will hate you dearly
4885 for it, because it means that they will first get a mail, and then have
4886 to read the same article later when they read the news. It is
4887 @code{nil} by default.
4889 @item gnus-mail-courtesy-message
4890 @vindex gnus-mail-courtesy-message
4891 This is a string that will be prepended to all mails that are the result
4892 of using the variable described above.
4894 @item gnus-outgoing-message-group
4895 @vindex gnus-outgoing-message-group
4896 All outgoing messages will be put in this group. If you want to store
4897 all your outgoing mail and articles in the group @samp{nnml:archive},
4898 you set this variable to that value. This variable can also be a list of
4901 If you want to have greater control over what group to put each
4902 message in, you can set this variable to a function that checks the
4903 current newsgroup name and then returns a suitable group name (or list
4906 @item gnus-mailing-list-groups
4907 @findex gnus-mailing-list-groups
4908 @cindex mailing lists
4910 If your newsserver offer groups that are really mailing lists that are
4911 gatewayed to the @sc{nntp} server, you can read those groups without
4912 problems, but you can't post/followup to them without some difficulty.
4913 One solution is to add a @code{to-address} to the group parameters
4914 (@pxref{Group Parameters}). An easier thing to do is set the
4915 @code{gnus-mailing-list-groups} to a regexp that match the groups that
4916 really are mailing lists. Then, at least, followups to the mailing
4917 lists will work most of the time. Posting to these groups (@kbd{a}) is
4918 still a pain, though.
4923 You may want to do spell-checking on messages that you send out. Or, if
4924 you don't want to spell-check by hand, you could add automatic
4925 spell-checking via the @code{ispell} package:
4927 @vindex news-inews-hook
4929 (add-hook 'news-inews-hook 'ispell-message) ;For news posts
4930 (add-hook 'mail-send-hook 'ispell-message) ;for mail posts via sendmail
4933 @findex gnus-inews-insert-mime-headers
4934 If you want to insert some @sc{mime} headers into the articles you post,
4935 without doing any actual encoding, you could add
4936 @code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
4939 @node Posting Styles
4940 @subsection Posting Styles
4941 @cindex posting styles
4944 All them variables, they make my head swim.
4946 So what if you want a different @code{Organization} and signature based
4947 on what groups you post to? And you post both from your home machine
4948 and your work machine, and you want different @code{From} lines, and so
4951 @vindex gnus-posting-styles
4952 One way to do stuff like that is to write clever hooks that change the
4953 variables you need to have changed. That's a bit boring, so somebody
4954 came up with the bright idea of letting the user specify these things in
4955 a handy alist. Here's an example of a @code{gnus-posting-styles}
4959 ((".*" (signature . "Peace and happiness") (organization . "What me?"))
4960 ("^comp" (signature . "Death to everybody"))
4961 ("comp.emacs.i-love-it" (organization . "Emacs is it")))
4964 As you might surmise from this example, this alist consists of several
4965 @dfn{styles}. Each style will be applicable if the first element
4966 "matches", in some form or other. The entire alist will be iterated
4967 over, from the beginning towards the end, and each match will be
4968 applied, which means that attributes in later styles that match override
4969 the same attributes in earlier matching styles. So
4970 @samp{comp.programming.literate} will have the @samp{Death to everybody}
4971 signature and the @samp{What me?} @code{Organization} header.
4973 The first element in each style is called the @code{match}. If it's a
4974 string, then Gnus will try to regexp match it against the group name.
4975 If it's a function symbol, that function will be called with no
4976 arguments. If it's a variable symbol, then the variable will be
4977 referenced. If it's a list, then that list will be @code{eval}ed. In
4978 any case, if this returns a non-@code{nil} value, then the style is said
4981 Each style may contain a random amount of @dfn{attributes}. Each
4982 attribute consists of a @var{(name . value)} pair. The attribute name
4983 can be one of @code{signature}, @code{organization} or @code{from}.
4984 The attribute name can also be a string. In that case, this will be
4985 used as a header name, and the value will be inserted in the headers of
4988 The attribute value can be a string (used verbatim), a function (the
4989 return value will be used), a variable (its value will be used) or a
4990 list (it will be @code{eval}ed and the return value will be used).
4992 So here's a new example:
4995 (setq gnus-posting-styles
4997 (signature . "~/.signature")
4998 (from . "user@@foo (user)")
4999 ("X-Home-Page" . (getenv "WWW_HOME"))
5000 (organization . "People's Front Against MWM"))
5002 (signature . my-funny-signature-randomizer))
5003 ((equal (system-name) "gnarly")
5004 (signature . my-quote-randomizer))
5005 (posting-from-work-p
5006 (signature . "~/.work-signature")
5007 (from . "user@@bar.foo (user)")
5008 (organization . "Important Work, Inc"))
5010 (signature . "~/.mail-signature"))))
5019 If you are writing a message (mail or news) and suddenly remember that
5020 you have a steak in the oven (or pesto in the food processor, you craazy
5021 vegetarians), you'll probably wish there was a method to save the
5022 message you are writing so that you can continue editing it some other
5023 day, and send it when you feel its finished.
5025 @kindex C-c C-d (Mail)
5026 @kindex C-c C-d (Post)
5027 @findex gnus-enter-into-draft-group
5028 @vindex gnus-draft-group-directory
5029 What you then do is simply push @kbd{C-c C-d}
5030 (@code{gnus-enter-into-draft-group}). This will put the current
5031 (unfinished) message in a special draft group (which is implemented as
5032 an @code{nndir} group, if you absolutely have to know) called
5033 @samp{nndir:drafts}. The variable @code{gnus-draft-group-directory}
5034 controls both the name of the group and the location---the leaf element
5035 in the path will be used as the name of the group.
5037 If the group doesn't exist, it will be created and you'll be subscribed
5040 @findex gnus-summary-send-draft
5041 @kindex S D c (Summary)
5042 When you want to continue editing the article, you simply enter the
5043 draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
5044 that. You will be placed in a buffer where you left off.
5046 Rejected articles will also be put in this draft group (@pxref{Rejected
5049 @findex gnus-summary-send-all-drafts
5050 If you have lots of rejected messages you want to post (or mail) without
5051 doing further editing, you can use the @kbd{S D a} command
5052 (@code{gnus-summary-send-all-drafts}). This command understands the
5053 process/prefix convention (@pxref{Process/Prefix}).
5056 @node Rejected Articles
5057 @subsection Rejected Articles
5058 @cindex rejected articles
5060 Sometimes a news server will reject an article. Perhaps the server
5061 doesn't like your face. Perhaps it just feels miserable. Perhaps
5062 @emph{there be demons}. Perhaps you have included too much cited text.
5063 Perhaps the disk is full. Perhaps the server is down.
5065 These situations are, of course, totally beyond the control of Gnus.
5066 (Gnus, of course, loves the way you look, always feels great, has angels
5067 fluttering around inside of it, doesn't care about how much cited text
5068 you include, never runs full and never goes down.) So Gnus saves these
5069 articles until some later time when the server feels better.
5071 The rejected articles will automatically be put in a special draft group
5072 (@pxref{Drafts}). When the server comes back up again, you'd then
5073 typically enter that group and send all the articles off.
5076 @node Canceling and Superseding
5077 @section Canceling Articles
5078 @cindex canceling articles
5079 @cindex superseding articles
5081 Have you ever written something, and then decided that you really,
5082 really, really wish you hadn't posted that?
5084 Well, you can't cancel mail, but you can cancel posts.
5086 @findex gnus-summary-cancel-article
5088 Find the article you wish to cancel (you can only cancel your own
5089 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
5090 c} (@code{gnus-summary-cancel-article}). Your article will be
5091 canceled---machines all over the world will be deleting your article.
5093 Be aware, however, that not all sites honor cancels, so your article may
5094 live on here and there, while most sites will delete the article in
5097 If you discover that you have made some mistakes and want to do some
5098 corrections, you can post a @dfn{superseding} article that will replace
5099 your original article.
5101 @findex gnus-summary-supersede-article
5103 Go to the original article and press @kbd{S s}
5104 (@code{gnus-summary-supersede-article}). You will be put in a buffer
5105 where you can edit the article all you want before sending it off the
5108 @vindex gnus-delete-supersedes-headers
5109 You probably want to delete some of the old headers before sending the
5110 superseding article---@code{Path} and @code{Date} are probably
5111 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
5112 match the lines you want removed. The default is
5113 @samp{"^Path:\\|^Date"}.
5115 The same goes for superseding as for canceling, only more so: Some
5116 sites do not honor superseding. On those sites, it will appear that you
5117 have posted almost the same article twice.
5119 If you have just posted the article, and change your mind right away,
5120 there is a trick you can use to cancel/supersede the article without
5121 waiting for the article to appear on your site first. You simply return
5122 to the post buffer (which is called @code{*post-buf*}). There you will
5123 find the article you just posted, with all the headers intact. Change
5124 the @samp{Message-ID} header to a @samp{Cancel} or @samp{Supersedes}
5125 header by substituting one of those words for @samp{Message-ID}. Then
5126 just press @kbd{C-c C-c} to send the article as you would do normally.
5127 The previous article will be canceled/superseded.
5129 Just remember, kids: There is no 'c' in 'supersede'.
5131 @node Marking Articles
5132 @section Marking Articles
5133 @cindex article marking
5134 @cindex article ticking
5137 There are several marks you can set on an article.
5139 You have marks that decide the @dfn{readed-ness} (whoo, neato-keano
5140 neologism ohoy!) of the article. Alphabetic marks generally mean
5141 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
5143 In addition, you also have marks that do not affect readedness.
5146 * Unread Articles:: Marks for unread articles.
5147 * Read Articles:: Marks for read articles.
5148 * Other Marks:: Marks that do not affect readedness.
5152 There's a plethora of commands for manipulating these marks:
5156 * Setting Marks:: How to set and remove marks.
5157 * Setting Process Marks:: How to mark articles for later processing.
5160 @node Unread Articles
5161 @subsection Unread Articles
5163 The following marks mark articles as unread, in one form or other.
5165 @vindex gnus-dormant-mark
5166 @vindex gnus-ticked-mark
5169 @dfn{Ticked articles} are articles that will remain visible always. If
5170 you see an article that you find interesting, or you want to put off
5171 reading it, or replying to it, until sometime later, you'd typically
5172 tick it. However, articles can be expired, so if you want to keep an
5173 article forever, you'll have to save it. Ticked articles have a
5174 @samp{!} (@code{gnus-ticked-mark}) in the first column.
5176 A @dfn{dormant} article is marked with a @samp{?}
5177 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
5178 if there are followups to it.
5180 An @dfn{unread} article is marked with a @samp{SPC}
5181 (@code{gnus-unread-mark}). These are articles that haven't been read at
5186 @subsection Read Articles
5187 @cindex expirable mark
5189 All the following marks mark articles as read.
5193 Articles that are marked as read. They have a @samp{r}
5194 (@code{gnus-del-mark}) in the first column. These are articles that the
5195 user has marked as read more or less manually.
5197 Articles that are actually read are marked with @samp{R}
5198 (@code{gnus-read-mark}).
5200 Articles that were marked as read in previous sessions are now
5201 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
5203 Marked as killed (@code{gnus-killed-mark}).
5205 Marked as killed by kill files (@code{gnus-kill-file-mark}).
5207 Marked as read by having a too low score (@code{gnus-low-score-mark}).
5209 Marked as read by a catchup (@code{gnus-catchup-mark}).
5211 Canceled article (@code{gnus-cancelled-mark})
5214 All these marks just mean that the article is marked as read, really.
5215 They are interpreted differently by the adaptive scoring scheme,
5218 One more special mark, though:
5222 You can also mark articles as @dfn{expirable} (or have them marked as
5223 such automatically). That doesn't make much sense in normal groups,
5224 because a user does not control the expiring of news articles, but in
5225 mail groups, for instance, articles that are marked as @dfn{expirable}
5226 can be deleted by Gnus at any time. Expirable articles are marked with
5227 @samp{E} (@code{gnus-expirable-mark}).
5231 @subsection Other Marks
5232 @cindex process mark
5235 There are some marks that have nothing to do with whether the article is
5238 You can set a bookmark in the current article. Say you are reading a
5239 long thesis on cat's urinary tracts, and have to go home for dinner
5240 before you've finished reading the thesis. You can then set a bookmark
5241 in the article, and Gnus will jump to this bookmark the next time it
5242 encounters the article.
5244 All articles that you have replied to or made a followup to (i.e., have
5245 answered) will be marked with an @samp{A} in the second column
5246 (@code{gnus-replied-mark}).
5248 @vindex gnus-not-empty-thread-mark
5249 @vindex gnus-empty-thread-mark
5250 It the @samp{%e} spec is used, the presence of threads or not will be
5251 marked with @code{gnus-not-empty-thread-mark} and
5252 @code{gnus-empty-thread-mark}, respectively.
5254 @vindex gnus-process-mark
5255 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
5256 variety of commands react to the presence of the process mark. For
5257 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
5258 all articles that have been marked with the process mark. Articles
5259 marked with the process mark have a @samp{#} in the second column.
5262 @subsection Setting Marks
5263 @cindex setting marks
5265 All the marking commands understand the numeric prefix.
5271 @kindex M t (Summary)
5272 @findex gnus-summary-tick-article-forward
5273 Tick the current article (@code{gnus-summary-tick-article-forward}).
5277 @kindex M ? (Summary)
5278 @findex gnus-summary-mark-as-dormant
5279 Mark the current article as dormant
5280 (@code{gnus-summary-mark-as-dormant}).
5283 @kindex M d (Summary)
5285 @findex gnus-summary-mark-as-read-forward
5286 Mark the current article as read
5287 (@code{gnus-summary-mark-as-read-forward}).
5291 @kindex M k (Summary)
5292 @findex gnus-summary-kill-same-subject-and-select
5293 Mark all articles that have the same subject as the current one as read,
5294 and then select the next unread article
5295 (@code{gnus-summary-kill-same-subject-and-select}).
5298 @kindex M K (Summary)
5299 @kindex C-k (Summary)
5300 @findex gnus-summary-kill-same-subject
5301 Mark all articles that have the same subject as the current one as read
5302 (@code{gnus-summary-kill-same-subject}).
5304 @kindex M C (Summary)
5305 @findex gnus-summary-catchup
5306 Mark all unread articles in the group as read
5307 (@code{gnus-summary-catchup}).
5309 @kindex M C-c (Summary)
5310 @findex gnus-summary-catchup-all
5311 Mark all articles in the group as read---even the ticked and dormant
5312 articles (@code{gnus-summary-catchup-all}).
5314 @kindex M H (Summary)
5315 @findex gnus-summary-catchup-to-here
5316 Catchup the current group to point
5317 (@code{gnus-summary-catchup-to-here}).
5319 @kindex C-w (Summary)
5320 @findex gnus-summary-mark-region-as-read
5321 Mark all articles between point and mark as read
5322 (@code{gnus-summary-mark-region-as-read}).
5324 @kindex M V k (Summary)
5325 @findex gnus-summary-kill-below
5326 Kill all articles with scores below the default score (or below the
5327 numeric prefix) (@code{gnus-summary-kill-below}).
5330 @kindex M c (Summary)
5331 @kindex M-u (Summary)
5332 @findex gnus-summary-clear-mark-forward
5333 Clear all readedness-marks from the current article
5334 (@code{gnus-summary-clear-mark-forward}).
5337 @kindex M e (Summary)
5339 @findex gnus-summary-mark-as-expirable
5340 Mark the current article as expirable
5341 (@code{gnus-summary-mark-as-expirable}).
5343 @kindex M b (Summary)
5344 @findex gnus-summary-set-bookmark
5345 Set a bookmark in the current article
5346 (@code{gnus-summary-set-bookmark}).
5348 @kindex M B (Summary)
5349 @findex gnus-summary-remove-bookmark
5350 Remove the bookmark from the current article
5351 (@code{gnus-summary-remove-bookmark}).
5353 @kindex M V c (Summary)
5354 @findex gnus-summary-clear-above
5355 Clear all marks from articles with scores over the default score (or
5356 over the numeric prefix) (@code{gnus-summary-clear-above}).
5358 @kindex M V u (Summary)
5359 @findex gnus-summary-tick-above
5360 Tick all articles with scores over the default score (or over the
5361 numeric prefix) (@code{gnus-summary-tick-above}).
5363 @kindex M V m (Summary)
5364 @findex gnus-summary-mark-above
5365 Prompt for a mark, and mark all articles with scores over the default
5366 score (or over the numeric prefix) with this mark
5367 (@code{gnus-summary-clear-above}).
5370 @code{gnus-summary-goto-unread}
5371 The @code{gnus-summary-goto-unread} variable controls what action should
5372 be taken after setting a mark. If non-@code{nil}, point will move to
5373 the next/previous unread article. If @code{nil}, point will just move
5374 one line up or down. The default is @code{t}.
5377 @node Setting Process Marks
5378 @subsection Setting Process Marks
5379 @cindex setting process marks
5385 @kindex M P p (Summary)
5386 @findex gnus-summary-mark-as-processable
5387 Mark the current article with the process mark
5388 (@code{gnus-summary-mark-as-processable}).
5389 @findex gnus-summary-unmark-as-processable
5392 @kindex M P u (Summary)
5393 @kindex M-# (Summary)
5394 Remove the process mark, if any, from the current article
5395 (@code{gnus-summary-unmark-as-processable}).
5397 @kindex M P U (Summary)
5398 @findex gnus-summary-unmark-all-processable
5399 Remove the process mark from all articles
5400 (@code{gnus-summary-unmark-all-processable}).
5402 @kindex M P R (Summary)
5403 @findex gnus-uu-mark-by-regexp
5404 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
5406 @kindex M P r (Summary)
5407 @findex gnus-uu-mark-region
5408 Mark articles in region (@code{gnus-uu-mark-region}).
5410 @kindex M P t (Summary)
5411 @findex gnus-uu-mark-thread
5412 Mark all articles in the current (sub)thread
5413 (@code{gnus-uu-mark-thread}).
5415 @kindex M P T (Summary)
5416 @findex gnus-uu-unmark-thread
5417 Unmark all articles in the current (sub)thread
5418 (@code{gnus-uu-unmark-thread}).
5420 @kindex M P s (Summary)
5421 @findex gnus-uu-mark-series
5422 Mark all articles in the current series (@code{gnus-uu-mark-series}).
5424 @kindex M P S (Summary)
5425 @findex gnus-uu-mark-sparse
5426 Mark all series that have already had some articles marked
5427 (@code{gnus-uu-mark-sparse}).
5429 @kindex M P a (Summary)
5430 @findex gnus-uu-mark-all
5431 Mark all articles in series order (@code{gnus-uu-mark-series}).
5433 @kindex M P b (Summary)
5434 @findex gnus-uu-mark-buffer
5435 Mark all articles in the buffer in the order they appear
5436 (@code{gnus-uu-mark-buffer}).
5444 It can be convenient to limit the summary buffer to just show some
5445 subset of the articles currently in the group. The effect most limit
5446 commands have is to remove a few (or many) articles from the summary
5452 @kindex / / (Summary)
5453 @findex gnus-summary-limit-to-subject
5454 Limit the summary buffer to articles that match some subject
5455 (@code{gnus-summary-limit-to-subject}).
5459 @kindex / u (Summary)
5461 @findex gnus-summary-limit-to-unread
5462 Limit the summary buffer to articles that are not marked as read
5463 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
5464 buffer to articles that are strictly unread. This means that ticked and
5465 dormant articles will also be excluded.
5468 @kindex / m (Summary)
5469 @findex gnus-summary-limit-to-marks
5470 Ask for a mark and then limit to all articles that have not been marked
5471 with that mark (@code{gnus-summary-limit-to-marks}).
5474 @kindex / n (Summary)
5475 @findex gnus-summary-limit-to-articles
5476 Limit the summary buffer to the current article
5477 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
5478 convention (@pxref{Process/Prefix}).
5481 @kindex / w (Summary)
5482 @findex gnus-summary-pop-limit
5483 Pop the previous limit off the stack and restore it
5484 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
5489 @kindex / s (Summary)
5491 @findex gnus-summary-limit-to-subject
5492 Limit the summary buffer to articles that have a subject that matches a
5493 regexp (@code{gnus-summary-limit-to-subject}).
5496 @kindex / v (Summary)
5497 @findex gnus-summary-limit-to-score
5498 Limit the summary buffer to articles that have a score at or above some
5499 score (@code{gnus-summary-limit-to-score}).
5503 @kindex M S (Summary)
5504 @kindex / E (Summary)
5505 @findex gnus-summary-limit-include-expunged
5506 Display all expunged articles
5507 (@code{gnus-summary-limit-include-expunged}).
5510 @kindex / D (Summary)
5511 @findex gnus-summary-limit-include-dormant
5512 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
5515 @kindex / d (Summary)
5516 @findex gnus-summary-limit-exclude-dormant
5517 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
5520 @kindex / c (Summary)
5521 @findex gnus-summary-limit-exclude-childless-dormant
5522 Hide all dormant articles that have no children
5523 (@code{gnus-summary-limit-exclude-childless-dormant}).
5531 @cindex article threading
5533 Gnus threads articles by default. @dfn{To thread} is to put replies to
5534 articles directly after the articles they reply to---in a hierarchical
5538 * Customizing Threading:: Variables you can change to affect the threading.
5539 * Thread Commands:: Thread based commands in the summary buffer.
5542 @node Customizing Threading
5543 @subsection Customizing Threading
5544 @cindex customizing threading
5549 @item gnus-show-threads
5550 @vindex gnus-show-threads
5551 If this variable is @code{nil}, no threading will be done, and all of
5552 the rest of the variables here will have no effect. Turning threading
5553 off will speed group selection up a bit, but it is sure to make reading
5554 slower and more awkward.
5556 @item gnus-fetch-old-headers
5557 @vindex gnus-fetch-old-headers
5558 If non-@code{nil}, Gnus will attempt to build old threads by fetching
5559 more old headers---headers to articles that are marked as read. If you
5560 would like to display as few summary lines as possible, but still
5561 connect as many loose threads as possible, you should set this variable
5562 to @code{some} or a number. If you set it to a number, no more than
5563 that number of extra old headers will be fetched. In either case,
5564 fetching old headers only works if the backend you are using carries
5565 overview files---this would normally be @code{nntp}, @code{nnspool} and
5566 @code{nnml}. Also remember that if the root of the thread has been
5567 expired by the server, there's not much Gnus can do about that.
5569 @item gnus-summary-gather-subject-limit
5570 Loose threads are gathered by comparing subjects of articles. If this
5571 variable is @code{nil}, Gnus requires an exact match between the
5572 subjects of the loose threads before gathering them into one big
5573 super-thread. This might be too strict a requirement, what with the
5574 presence of stupid newsreaders that chop off long subjects lines. If
5575 you think so, set this variable to, say, 20 to require that only the
5576 first 20 characters of the subjects have to match. If you set this
5577 variable to a real low number, you'll find that Gnus will gather
5578 everything in sight into one thread, which isn't very helpful.
5580 @cindex fuzzy article gathering
5581 If you set this variable to the special value @code{fuzzy}, Gnus will
5582 use a fuzzy string comparison algorithm on the subjects.
5584 @vindex gnus-summary-gather-exclude-subject
5585 Since loose thread gathering is done on subjects only, that might lead
5586 to many false hits, especially with certain common subjects like
5587 @samp{""} and @samp{"(none)"}. To make the situation slightly better,
5588 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
5589 what subjects should be excluded from the gathering process. The
5590 default is @samp{"^ *$\\|^(none)$"}.
5592 @item gnus-summary-make-false-root
5593 @vindex gnus-summary-make-false-root
5594 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
5595 and create a dummy root at the top. (Wait a minute. Root at the top?
5596 Yup.) Loose subtrees occur when the real root has expired, or you've
5597 read or killed the root in a previous session.
5599 When there is no real root of a thread, Gnus will have to fudge
5600 something. This variable says what fudging method Gnus should use.
5601 There are four possible values:
5603 @cindex adopting articles
5607 Gnus will make the first of the orphaned articles the parent. This
5608 parent will adopt all the other articles. The adopted articles will be
5609 marked as such by pointy brackets (@samp{<>}) instead of the standard
5610 square brackets (@samp{[]}). This is the default method.
5613 Gnus will create a dummy summary line that will pretend to be the
5614 parent. This dummy line does not correspond to any real article, so
5615 selecting it will just select the first real article after the dummy
5619 Gnus won't actually make any article the parent, but simply leave the
5620 subject field of all orphans except the first empty. (Actually, it will
5621 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
5625 Don't make any article parent at all. Just gather the threads and
5626 display them after one another.
5629 Don't gather loose threads.
5632 @item gnus-thread-hide-subtree
5633 @vindex gnus-thread-hide-subtree
5634 If non-@code{nil}, all threads will be hidden when the summary buffer is
5637 @item gnus-thread-hide-killed
5638 @vindex gnus-thread-hide-killed
5639 if you kill a thread and this variable is non-@code{nil}, the subtree
5642 @item gnus-thread-ignore-subject
5643 @vindex gnus-thread-ignore-subject
5644 Sometimes somebody changes the subject in the middle of a thread. If
5645 this variable is non-@code{nil}, the subject change is ignored. If it
5646 is @code{nil}, which is the default, a change in the subject will result
5649 @item gnus-thread-indent-level
5650 @vindex gnus-thread-indent-level
5651 This is a number that says how much each sub-thread should be indented.
5652 The default is @samp{4}.
5655 @node Thread Commands
5656 @subsection Thread Commands
5657 @cindex thread commands
5663 @kindex T k (Summary)
5664 @kindex M-C-k (Summary)
5665 @findex gnus-summary-kill-thread
5666 Mark all articles in the current sub-thread as read
5667 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
5668 remove all marks instead. If the prefix argument is negative, tick
5673 @kindex T l (Summary)
5674 @kindex M-C-l (Summary)
5675 @findex gnus-summary-lower-thread
5676 Lower the score of the current thread
5677 (@code{gnus-summary-lower-thread}).
5680 @kindex T i (Summary)
5681 @findex gnus-summary-raise-thread
5682 Increase the score of the current thread
5683 (@code{gnus-summary-raise-thread}).
5686 @kindex T # (Summary)
5687 @findex gnus-uu-mark-thread
5688 Set the process mark on the current thread
5689 (@code{gnus-uu-mark-thread}).
5692 @kindex T M-# (Summary)
5693 @findex gnus-uu-unmark-thread
5694 Remove the process mark from the current thread
5695 (@code{gnus-uu-unmark-thread}).
5698 @kindex T T (Summary)
5699 @findex gnus-summary-toggle-threads
5700 Toggle threading (@code{gnus-summary-toggle-threads}).
5703 @kindex T s (Summary)
5704 @findex gnus-summary-show-thread
5705 Expose the thread hidden under the current article, if any
5706 (@code{gnus-summary-show-thread}).
5709 @kindex T h (Summary)
5710 @findex gnus-summary-hide-thread
5711 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
5714 @kindex T S (Summary)
5715 @findex gnus-summary-show-all-threads
5716 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
5719 @kindex T H (Summary)
5720 @findex gnus-summary-hide-all-threads
5721 Hide all threads (@code{gnus-summary-hide-all-threads}).
5724 The following commands are thread movement commands. They all
5725 understand the numeric prefix.
5729 @kindex T n (Summary)
5730 @findex gnus-summary-next-thread
5731 Go to the next thread (@code{gnus-summary-next-thread}).
5733 @kindex T p (Summary)
5734 @findex gnus-summary-prev-thread
5735 Go to the previous thread (@code{gnus-summary-prev-thread}).
5737 @kindex T d (Summary)
5738 @findex gnus-summary-down-thread
5739 Descend the thread (@code{gnus-summary-down-thread}).
5741 @kindex T u (Summary)
5742 @findex gnus-summary-up-thread
5743 Ascend the thread (@code{gnus-summary-up-thread}).
5746 @vindex gnus-thread-operation-ignore-subject
5747 If you ignore subject while threading, you'll naturally end up with
5748 threads that have several different subjects in them. If you then issue
5749 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
5750 wish to kill the entire thread, but just those parts of the thread that
5751 have the same subject as the current article. If you like this idea,
5752 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
5753 is non-@code{nil} (which it is by default), subjects will be ignored
5754 when doing thread commands. If this variable is @code{nil}, articles in
5755 the same thread with different subjects will not be included in the
5756 operation in question. If this variable is @code{fuzzy}, only articles
5757 that have subjects that are fuzzily equal will be included.
5760 @node Asynchronous Fetching
5761 @section Asynchronous Article Fetching
5762 @cindex asynchronous article fetching
5764 If you read your news from an @sc{nntp} server that's far away, the
5765 network latencies may make reading articles a chore. You have to wait
5766 for a while after pressing @kbd{n} to go to the next article before the
5767 article appears. Why can't Gnus just go ahead and fetch the article
5768 while you are reading the previous one? Why not, indeed.
5770 First, some caveats. There are some pitfalls to using asynchronous
5771 article fetching, especially the way Gnus does it.
5773 Let's say you are reading article 1, which is short, and article 2 is
5774 quite long, and you are not interested in reading that. Gnus does not
5775 know this, so it goes ahead and fetches article 2. You decide to read
5776 article 3, but since Gnus is in the process of fetching article 2, the
5777 connection is blocked.
5779 To avoid these situations, Gnus will open two (count 'em two)
5780 connections to the server. Some people may think this isn't a very nice
5781 thing to do, but I don't see any real alternatives. Setting up that
5782 extra connection takes some time, so Gnus startup will be slower.
5784 Gnus will fetch more articles than you will read. This will mean that
5785 the link between your machine and the @sc{nntp} server will become more
5786 loaded than if you didn't use article pre-fetch. The server itself will
5787 also become more loaded---both with the extra article requests, and the
5790 Ok, so now you know that you shouldn't really use this thing... unless
5793 @vindex gnus-asynchronous
5794 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
5795 happen automatically.
5797 @vindex nntp-async-number
5798 You can control how many articles that are to be pre-fetched by setting
5799 @code{nntp-async-number}. This is five by default, which means that when
5800 you read an article in the group, @code{nntp} will pre-fetch the next
5801 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
5802 all the articles that it can without bound. If it is @code{nil}, no
5803 pre-fetching will be made.
5805 @vindex gnus-asynchronous-article-function
5806 You may wish to create some sort of scheme for choosing which articles
5807 that @code{nntp} should consider as candidates for pre-fetching. For
5808 instance, you may wish to pre-fetch all articles with high scores, and
5809 not pre-fetch low-scored articles. You can do that by setting the
5810 @code{gnus-asynchronous-article-function}, which will be called with an
5811 alist where the keys are the article numbers. Your function should
5812 return an alist where the articles you are not interested in have been
5813 removed. You could also do sorting on article score and the like.
5815 @node Article Caching
5816 @section Article Caching
5817 @cindex article caching
5820 If you have an @emph{extremely} slow @sc{nntp} connection, you may
5821 consider turning article caching on. Each article will then be stored
5822 locally under your home directory. As you may surmise, this could
5823 potentially use @emph{huge} amounts of disk space, as well as eat up all
5824 your inodes so fast it will make your head swim. In vodka.
5826 Used carefully, though, it could be just an easier way to save articles.
5828 @vindex gnus-use-long-file-name
5829 @vindex gnus-cache-directory
5830 @vindex gnus-use-cache
5831 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
5832 all articles that are ticked or marked as dormant will then be copied
5833 over to your local cache (@code{gnus-cache-directory}). Whether this
5834 cache is flat or hierarchal is controlled by the
5835 @code{gnus-use-long-file-name} variable, as usual.
5837 When re-select a ticked or dormant article, it will be fetched from the
5838 cache instead of from the server. As articles in your cache will never
5839 expire, this might serve as a method of saving articles while still
5840 keeping them where they belong. Just mark all articles you want to save
5841 as dormant, and don't worry.
5843 When an article is marked as read, is it removed from the cache.
5845 @vindex gnus-cache-remove-articles
5846 @vindex gnus-cache-enter-articles
5847 The entering/removal of articles from the cache is controlled by the
5848 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
5849 variables. Both are lists of symbols. The first is @code{(ticked
5850 dormant)} by default, meaning that ticked and dormant articles will be
5851 put in the cache. The latter is @code{(read)} by default, meaning that
5852 articles that are marked as read are removed from the cache. Possibly
5853 symbols in these two lists are @code{ticked}, @code{dormant},
5854 @code{unread} and @code{read}.
5856 @findex gnus-jog-cache
5857 So where does the massive article-fetching and storing come into the
5858 picture? The @code{gnus-jog-cache} command will go through all
5859 subscribed newsgroups, request all unread articles, and store them in
5860 the cache. You should only ever, ever ever ever, use this command if 1)
5861 your connection to the @sc{nntp} server is really, really, really slow
5862 and 2) you have a really, really, really huge disk. Seriously.
5864 @vindex gnus-uncacheable-groups
5865 It is likely that you do not want caching on some groups. For instance,
5866 if your @code{nnml} mail is located under your home directory, it makes no
5867 sense to cache it somewhere else under your home directory. Unless you
5868 feel that it's neat to use twice as much space. To limit the caching,
5869 you could set the @code{gnus-uncacheable-groups} regexp to
5870 @samp{"^nnml"}, for instance. This variable is @samp{"^nnvirtual"} by
5871 default, since caching doesn't really work in @code{nnvirtual} groups,
5872 since @code{nnvirtual} assigns random article numbers to its articles.
5875 @node Article Backlog
5876 @section Article Backlog
5878 @cindex article backlog
5880 If you have a slow connection, but the idea of using caching seems
5881 unappealing to you (and it is, really), you can help the situation some
5882 by switching on the @dfn{backlog}. This is where Gnus will buffer
5883 already read articles so that it doesn't have to re-fetch articles
5884 you've already read. This only helps if you are in the habit of
5885 re-selecting articles you've recently read, of course. If you never do
5886 that, turning the backlog on will slow Gnus down a little bit, and
5887 increase memory usage some.
5889 @vindex gnus-keep-backlog
5890 If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
5891 at most @var{n} old articles in a buffer for later re-fetching. If this
5892 variable is non-@code{nil} and is not a number, Gnus will store
5893 @emph{all} read articles, which means that your Emacs will group without
5894 bound before exploding and taking your machine down with you. I put
5895 that in there just to keep y'all on your toes.
5897 This variable is @code{nil} by default.
5900 @node Exiting the Summary Buffer
5901 @section Exiting the Summary Buffer
5902 @cindex summary exit
5904 Exiting from the summary buffer will normally update all info on the
5905 group and return you to the group buffer.
5910 @kindex Z Z (Summary)
5912 @findex gnus-summary-exit
5913 @vindex gnus-summary-exit-hook
5914 @vindex gnus-summary-prepare-exit-hook
5915 Exit the current group and update all information on the group
5916 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
5917 called before doing much of the exiting, and calls
5918 @code{gnus-summary-expire-articles} by default.
5919 @code{gnus-summary-exit-hook} is called after finishing the exiting
5923 @kindex Z E (Summary)
5925 @findex gnus-summary-exit-no-update
5926 Exit the current group without updating any information on the group
5927 (@code{gnus-summary-exit-no-update}).
5930 @kindex Z c (Summary)
5932 @findex gnus-summary-catchup-and-exit
5933 Mark all unticked articles in the group as read and then exit
5934 (@code{gnus-summary-catchup-and-exit}).
5936 @kindex Z C (Summary)
5937 @findex gnus-summary-catchup-all-and-exit
5938 Mark all articles, even the ticked ones, as read and then exit
5939 (@code{gnus-summary-catchup-all-and-exit}).
5941 @kindex Z n (Summary)
5942 @findex gnus-summary-catchup-and-goto-next-group
5943 Mark all articles as read and go to the next group
5944 (@code{gnus-summary-catchup-and-goto-next-group}).
5946 @kindex Z R (Summary)
5947 @findex gnus-summary-reselect-current-group
5948 Exit this group, and then enter it again
5949 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
5950 all articles, both read and unread.
5953 @kindex Z G (Summary)
5954 @kindex M-g (Summary)
5955 @findex gnus-summary-rescan-group
5956 Exit the group, check for new articles in the group, and select the
5957 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
5958 articles, both read and unread.
5960 @kindex Z N (Summary)
5961 @findex gnus-summary-next-group
5962 Exit the group and go to the next group
5963 (@code{gnus-summary-next-group}).
5965 @kindex Z P (Summary)
5966 @findex gnus-summary-prev-group
5967 Exit the group and go to the previous group
5968 (@code{gnus-summary-prev-group}).
5971 @vindex gnus-exit-group-hook
5972 @code{gnus-exit-group-hook} is called when you exit the current
5975 @vindex gnus-use-cross-reference
5976 The data on the current group will be updated (which articles you have
5977 read, which articles you have replied to, etc.) when you exit the
5978 summary buffer. If the @code{gnus-use-cross-reference} variable is
5979 @code{t} (which is the default), articles that are cross-referenced to
5980 this group and are marked as read, will also be marked as read in the
5981 other subscribed groups they were cross-posted to. If this variable is
5982 neither @code{nil} nor @code{t}, the article will be marked as read in
5983 both subscribed and unsubscribed groups.
5985 Marking cross-posted articles as read ensures that you'll never have to
5986 read the same article more than once. Unless, of course, somebody has
5987 posted it to several groups separately. Posting the same article to
5988 several groups (not cross-posting) is called @dfn{spamming}, and you are
5989 by law required to send nasty-grams to anyone who perpetrates such a
5992 Remember: Cross-posting is kinda ok, but posting the same article
5993 separately to several groups is not.
5995 One thing that may cause Gnus to not do the cross-posting thing
5996 correctly is if you use an @sc{nntp} server that supports @sc{xover}
5997 (which is very nice, because it speeds things up considerably) which
5998 does not include the @code{Xref} header in its @sc{nov} lines. This is
5999 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
6000 even with @sc{xover} by registering the @code{Xref} lines of all
6001 articles you actually read, but if you kill the articles, or just mark
6002 them as read without reading them, Gnus will not get a chance to snoop
6003 the @code{Xref} lines out of these articles, and will be unable to use
6004 the cross reference mechanism.
6006 @vindex gnus-nov-is-evil
6007 If you want Gnus to get the @code{Xref}s right all the time, you have to
6008 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
6014 @node Process/Prefix
6015 @section Process/Prefix
6016 @cindex process/prefix convention
6018 Many functions, among them functions for moving, decoding and saving
6019 articles, use what is known as the @dfn{Process/Prefix convention}.
6021 This is a method for figuring out what articles that the user wants the
6022 command to be performed on.
6026 If the numeric prefix is N, perform the operation on the next N
6027 articles, starting with the current one. If the numeric prefix is
6028 negative, perform the operation on the previous N articles, starting
6029 with the current one.
6031 If @code{transient-mark-mode} in non-@code{nil} and the region is
6032 active, all articles in the region will be worked upon.
6034 If there is no numeric prefix, but some articles are marked with the
6035 process mark, perform the operation on the articles that are marked with
6038 If there is neither a numeric prefix nor any articles marked with the
6039 process mark, just perform the operation on the current article.
6041 Quite simple, really, but it needs to be made clear so that surprises
6044 @vindex gnus-summary-goto-unread
6045 One thing that seems to shock & horrify lots of people is that, for
6046 instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
6047 Since each @kbd{d} (which marks the current article as read) by default
6048 goes to the next unread article after marking, this means that @kbd{3 d}
6049 will mark the next three unread articles as read, no matter what the
6050 summary buffer looks like. Set @code{gnus-summary-goto-unread} to
6051 @code{nil} for a more straightforward action.
6053 @node Saving Articles
6054 @section Saving Articles
6055 @cindex saving articles
6057 Gnus can save articles in a number of ways. Below is the documentation
6058 for saving articles in a fairly straight-forward fashion (i.e., little
6059 processing of the article is done before it is saved). For a different
6060 approach (uudecoding, unsharing) you should use @code{gnus-uu}
6061 (@pxref{Decoding Articles}).
6063 @vindex gnus-save-all-headers
6064 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
6065 unwanted headers before saving the article.
6067 @vindex gnus-saved-headers
6068 If the preceeding variable is @code{nil}, all headers that match the
6069 @code{gnus-saved-headers} regexp will be kept, while the rest will be
6070 deleted before saving.
6076 @kindex O o (Summary)
6078 @findex gnus-summary-save-article
6079 Save the current article using the default article saver
6080 (@code{gnus-summary-save-article}).
6083 @kindex O m (Summary)
6084 @findex gnus-summary-save-article-mail
6085 Save the current article in mail format
6086 (@code{gnus-summary-save-article-mail}).
6089 @kindex O r (Summary)
6090 @findex gnus-summary-save-article-mail
6091 Save the current article in rmail format
6092 (@code{gnus-summary-save-article-rmail}).
6095 @kindex O f (Summary)
6096 @findex gnus-summary-save-article-file
6097 Save the current article in plain file format
6098 (@code{gnus-summary-save-article-file}).
6101 @kindex O b (Summary)
6102 @findex gnus-summary-save-article-body-file
6103 Save the current article body in plain file format
6104 (@code{gnus-summary-save-article-body-file}).
6107 @kindex O h (Summary)
6108 @findex gnus-summary-save-article-folder
6109 Save the current article in mh folder format
6110 (@code{gnus-summary-save-article-folder}).
6113 @kindex O p (Summary)
6114 @findex gnus-summary-pipe-output
6115 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
6116 the current article to a process (@code{gnus-summary-pipe-output}).
6119 @vindex gnus-prompt-before-saving
6120 All these commands use the process/prefix convention
6121 (@pxref{Process/Prefix}). If you save bunches of articles using these
6122 functions, you might get tired of being prompted for files to save each
6123 and every article in. The prompting action is controlled by
6124 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
6125 default, giving you that excessive prompting action you know and
6126 loathe. If you set this variable to @code{t} instead, you'll be promted
6127 just once for each series of articles you save. If you like to really
6128 have Gnus do all your thinking for you, you can even set this variable
6129 to @code{nil}, which means that you will never be prompted for files to
6130 save articles in. Gnus will simply save all the articles in the default
6134 @vindex gnus-default-article-saver
6135 You can customize the @code{gnus-default-article-saver} variable to make
6136 Gnus do what you want it to. You can use any of the four ready-made
6137 functions below, or you can create your own.
6141 @item gnus-summary-save-in-rmail
6142 @findex gnus-summary-save-in-rmail
6143 This is the default format, @dfn{babyl}. Uses the function in the
6144 @code{gnus-rmail-save-name} variable to get a file name to save the
6145 article in. The default is @code{gnus-plain-save-name}.
6147 @item gnus-summary-save-in-mail
6148 @findex gnus-summary-save-in-mail
6149 Save in a Unix mail (mbox) file. Uses the function in the
6150 @code{gnus-mail-save-name} variable to get a file name to save the
6151 article in. The default is @code{gnus-plain-save-name}.
6153 @item gnus-summary-save-in-file
6154 @findex gnus-summary-save-in-file
6155 Append the article straight to an ordinary file. Uses the function in
6156 the @code{gnus-file-save-name} variable to get a file name to save the
6157 article in. The default is @code{gnus-numeric-save-name}.
6159 @item gnus-summary-save-body-in-file
6160 @findex gnus-summary-save-body-in-file
6161 Append the article body to an ordinary file. Uses the function in the
6162 @code{gnus-file-save-name} variable to get a file name to save the
6163 article in. The default is @code{gnus-numeric-save-name}.
6165 @item gnus-summary-save-in-folder
6166 @findex gnus-summary-save-in-folder
6167 Save the article to an MH folder using @code{rcvstore} from the MH
6170 @item gnus-summary-save-in-vm
6171 @findex gnus-summary-save-in-vm
6172 Save the article in a VM folder. You have to have the VM mail
6173 reader to use this setting.
6176 All of these functions, except for the last one, will save the article
6177 in the @code{gnus-article-save-directory}, which is initialized from the
6178 @samp{SAVEDIR} environment variable. This is @file{~/News/} by
6181 As you can see above, the functions use different functions to find a
6182 suitable name of a file to save the article in. Below is a list of
6183 available functions that generate names:
6186 @item gnus-Numeric-save-name
6187 @findex gnus-Numeric-save-name
6188 Generates file names that look like @samp{~/News/Alt.andrea-dworkin/45}.
6189 @item gnus-numeric-save-name
6190 @findex gnus-numeric-save-name
6191 Generates file names that look like @samp{~/News/alt.andrea-dworkin/45}.
6192 @item gnus-Plain-save-name
6193 @findex gnus-Plain-save-name
6194 Generates file names that look like @samp{~/News/Alt.andrea-dworkin}.
6195 @item gnus-plain-save-name
6196 @findex gnus-plain-save-name
6197 Generates file names that look like @samp{~/News/alt.andrea-dworkin}.
6200 @vindex gnus-split-methods
6201 You can have Gnus suggest where to save articles by plonking regexp into
6202 the @code{gnus-split-methods} alist. For instance, if you would like to
6203 save articles related to Gnus in the file @file{gnus-stuff}, and articles
6204 related to VM in @code{vm-stuff}, you could set this variable to something
6208 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
6209 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
6210 (my-choosing-function "../other-dir/my-stuff")
6211 ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
6214 We see that this is a list where each element is a list that has two
6215 elements---the @dfn{match} and the @dfn{file}. The match can either be
6216 a string (in which case it is used as a regexp to match on the article
6217 head); it can be a symbol (which will be called as a function); or it
6218 can be a list (which will be @code{eval}ed). If any of these actions
6219 have a non-@code{nil} result, the @dfn{file} will be used as a default
6222 @vindex gnus-use-long-file-name
6223 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
6224 @code{nil}, all the preceding functions will replace all periods
6225 (@samp{.}) in the group names with slashes (@samp{/})---which means that
6226 the functions will generate hierarchies of directories instead of having
6227 all the files in the toplevel directory
6228 (@samp{~/News/alt/andrea-dworkin} instead of
6229 @samp{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
6230 on most systems. However, for historical reasons, this is @code{nil} on
6231 Xenix and usg-unix-v machines by default.
6233 This function also affects kill and score file names. If this variable
6234 is a list, and the list contains the element @code{not-score}, long file
6235 names will not be used for score files, if it contains the element
6236 @code{not-save}, long file names will not be used for saving, and if it
6237 contains the element @code{not-kill}, long file names will not be used
6240 If you'd like to save articles in a hierarchy that looks something like
6244 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
6245 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
6248 Then just save with @kbd{o}. You'd then read this hierarchy with
6249 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
6250 the toplevel directory as the argument (@file{~/News/}). Then just walk
6251 around to the groups/directories with @code{nneething}.
6254 @node Decoding Articles
6255 @section Decoding Articles
6256 @cindex decoding articles
6258 Sometime users post articles (or series of articles) that have been
6259 encoded in some way or other. Gnus can decode them for you.
6262 * Uuencoded Articles:: Uudecode articles.
6263 * Shared Articles:: Unshar articles.
6264 * PostScript Files:: Split PostScript.
6265 * Decoding Variables:: Variables for a happy decoding.
6266 * Viewing Files:: You want to look at the result of the decoding?
6269 All these functions use the process/prefix convention
6270 (@pxref{Process/Prefix}) for finding out what articles to work on, with
6271 the extension that a "single article" means "a single series". Gnus can
6272 find out by itself what articles belong to a series, decode all the
6273 articles and unpack/view/save the resulting file(s).
6275 Gnus guesses what articles are in the series according to the following
6276 simplish rule: The subjects must be (nearly) identical, except for the
6277 last two numbers of the line. (Spaces are largely ignored, however.)
6279 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
6280 will find all the articles that match the regexp @samp{^cat.gif
6281 ([0-9]+/[0-9]+).*$}.
6283 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
6284 series}, will not be properly recognized by any of the automatic viewing
6285 commands, and you have to mark the articles manually with @key{#}.
6287 @node Uuencoded Articles
6288 @subsection Uuencoded Articles
6290 @cindex uuencoded articles
6294 @kindex X u (Summary)
6295 @findex gnus-uu-decode-uu
6296 Uudecodes the current series (@code{gnus-uu-decode-uu}).
6298 @kindex X U (Summary)
6299 @findex gnus-uu-decode-uu-and-save
6300 Uudecodes and saves the current series
6301 (@code{gnus-uu-decode-uu-and-save}).
6303 @kindex X v u (Summary)
6304 @findex gnus-uu-decode-uu-view
6305 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
6307 @kindex X v U (Summary)
6308 @findex gnus-uu-decode-uu-and-save-view
6309 Uudecodes, views and saves the current series
6310 (@code{gnus-uu-decode-uu-and-save-view}).
6313 Remember that these all react to the presence of articles marked with
6314 the process mark. If, for instance, you'd like to uncode and save an
6315 entire newsgroup, you'd typically do @kbd{M P a}
6316 (@code{gnus-uu-mark-all}) and then @kbd{X U}
6317 (@code{gnus-uu-decode-uu-and-save}).
6319 All this is very much different from how @code{gnus-uu} worked with
6320 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
6321 the sun. This version of @code{gnus-uu} generally assumes that you mark
6322 articles in some way (@pxref{Setting Process Marks}) and then press
6325 Note: When trying to decode articles that have names matching
6326 @code{gnus-uu-notify-files}, which is hard-coded to
6327 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
6328 automatically post an article on @samp{comp.unix.wizards} saying that
6329 you have just viewed the file in question. This feature can't be turned
6332 @node Shared Articles
6333 @subsection Shared Articles
6335 @cindex shared articles
6339 @kindex X s (Summary)
6340 @findex gnus-uu-decode-unshar
6341 Unshars the current series (@code{gnus-uu-decode-unshar}).
6343 @kindex X S (Summary)
6344 @findex gnus-uu-decode-unshar-and-save
6345 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
6347 @kindex X v s (Summary)
6348 @findex gnus-uu-decode-unshar-view
6349 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
6351 @kindex X v S (Summary)
6352 @findex gnus-uu-decode-unshar-and-save-view
6353 Unshars, views and saves the current series
6354 (@code{gnus-uu-decode-unshar-and-save-view}).
6357 @node PostScript Files
6358 @subsection PostScript Files
6363 @kindex X p (Summary)
6364 @findex gnus-uu-decode-postscript
6365 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
6367 @kindex X P (Summary)
6368 @findex gnus-uu-decode-postscript-and-save
6369 Unpack and save the current PostScript series
6370 (@code{gnus-uu-decode-postscript-and-save}).
6372 @kindex X v p (Summary)
6373 @findex gnus-uu-decode-postscript-view
6374 View the current PostScript series
6375 (@code{gnus-uu-decode-postscript-view}).
6377 @kindex X v P (Summary)
6378 @findex gnus-uu-decode-postscript-and-save-view
6379 View and save the current PostScript series
6380 (@code{gnus-uu-decode-postscript-and-save-view}).
6383 @node Decoding Variables
6384 @subsection Decoding Variables
6386 Adjective, not verb.
6389 * Rule Variables:: Variables that say how a file is to be viewed.
6390 * Other Decode Variables:: Other decode variables.
6391 * Uuencoding & Posting:: Variables for customizing uuencoding.
6394 @node Rule Variables
6395 @subsubsection Rule Variables
6396 @cindex rule variables
6398 Gnus uses @dfn{rule variables} to decide how to view a file. All these
6399 variables are on the form
6402 (list '(regexp1 command2)
6408 @item gnus-uu-user-view-rules
6409 @vindex gnus-uu-user-view-rules
6410 This variable is consulted first when viewing files. If you wish to use,
6411 for instance, @code{sox} to convert an @samp{.au} sound file, you could
6414 (setq gnus-uu-user-view-rules
6415 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
6417 @item gnus-uu-user-view-rules-end
6418 @vindex gnus-uu-user-view-rules-end
6419 This variable is consulted if Gnus couldn't make any matches from the
6420 user and default view rules.
6421 @item gnus-uu-user-archive-rules
6422 @vindex gnus-uu-user-archive-rules
6423 This variable can be used to say what commands should be used to unpack
6427 @node Other Decode Variables
6428 @subsubsection Other Decode Variables
6431 @item gnus-uu-ignore-files-by-name
6432 @vindex gnus-uu-ignore-files-by-name
6433 Files with name matching this regular expression won't be viewed.
6435 @item gnus-uu-ignore-files-by-type
6436 @vindex gnus-uu-ignore-files-by-type
6437 Files with a @sc{mime} type matching this variable won't be viewed.
6438 Note that Gnus tries to guess what type the file is based on the name.
6439 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
6442 @item gnus-uu-tmp-dir
6443 @vindex gnus-uu-tmp-dir
6444 Where @code{gnus-uu} does its work.
6446 @item gnus-uu-do-not-unpack-archives
6447 @vindex gnus-uu-do-not-unpack-archives
6448 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
6449 looking for files to display.
6451 @item gnus-uu-view-and-save
6452 @vindex gnus-uu-view-and-save
6453 Non-@code{nil} means that the user will always be asked to save a file
6456 @item gnus-uu-ignore-default-view-rules
6457 @vindex gnus-uu-ignore-default-view-rules
6458 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
6461 @item gnus-uu-ignore-default-archive-rules
6462 @vindex gnus-uu-ignore-default-archive-rules
6463 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
6466 @item gnus-uu-kill-carriage-return
6467 @vindex gnus-uu-kill-carriage-return
6468 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
6471 @item gnus-uu-unmark-articles-not-decoded
6472 @vindex gnus-uu-unmark-articles-not-decoded
6473 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
6474 unsuccessfully decoded as unread.
6476 @item gnus-uu-correct-stripped-uucode
6477 @vindex gnus-uu-correct-stripped-uucode
6478 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
6479 uuencoded files that have had trailing spaces deleted.
6481 @item gnus-uu-view-with-metamail
6482 @vindex gnus-uu-view-with-metamail
6483 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
6484 commands defined by the rule variables and just fudge a @sc{mime}
6485 content type based on the file name. The result will be fed to
6486 @code{metamail} for viewing.
6488 @item gnus-uu-save-in-digest
6489 @vindex gnus-uu-save-in-digest
6490 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
6491 decoding, will save in digests. If this variable is @code{nil},
6492 @code{gnus-uu} will just save everything in a file without any
6493 embellishments. The digesting almost conforms to RFC1153---no easy way
6494 to specify any meaningful volume and issue numbers were found, so I
6495 simply dropped them.
6499 @node Uuencoding & Posting
6500 @subsubsection Uuencoding & Posting
6504 @item gnus-uu-post-include-before-composing
6505 @vindex gnus-uu-post-include-before-composing
6506 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
6507 before you compose the article. If this variable is @code{t}, you can
6508 either include an encoded file with @key{C-c C-i} or have one included
6509 for you when you post the article.
6511 @item gnus-uu-post-length
6512 @vindex gnus-uu-post-length
6513 Maximum length of an article. The encoded file will be split into how
6514 many articles it takes to post the entire file.
6516 @item gnus-uu-post-threaded
6517 @vindex gnus-uu-post-threaded
6518 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
6519 thread. This may not be smart, as no other decoder I have seen are able
6520 to follow threads when collecting uuencoded articles. (Well, I have
6521 seen one package that does that---@code{gnus-uu}, but somehow, I don't
6522 think that counts...) Default is @code{nil}.
6524 @item gnus-uu-post-separate-description
6525 @vindex gnus-uu-post-separate-description
6526 Non-@code{nil} means that the description will be posted in a separate
6527 article. The first article will typically be numbered (0/x). If this
6528 variable is @code{nil}, the description the user enters will be included
6529 at the beginning of the first article, which will be numbered (1/x).
6530 Default is @code{t}.
6535 @subsection Viewing Files
6536 @cindex viewing files
6537 @cindex pseudo-articles
6539 After decoding, if the file is some sort of archive, Gnus will attempt
6540 to unpack the archive and see if any of the files in the archive can be
6541 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
6542 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
6543 uncompress and detar the main file, and then view the two pictures.
6544 This unpacking process is recursive, so if the archive contains archives
6545 of archives, it'll all be unpacked.
6547 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
6548 extracted file into the summary buffer. If you go to these "articles",
6549 you will be prompted for a command to run (usually Gnus will make a
6550 suggestion), and then the command will be run.
6552 @vindex gnus-view-pseudo-asynchronously
6553 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
6554 until the viewing is done before proceeding.
6556 @vindex gnus-view-pseudos
6557 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
6558 the pseudo-articles into the summary buffer, but view them
6559 immediately. If this variable is @code{not-confirm}, the user won't even
6560 be asked for a confirmation before viewing is done.
6562 @vindex gnus-view-pseudos-separately
6563 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
6564 pseudo-article will be created for each file to be viewed. If
6565 @code{nil}, all files that use the same viewing command will be given as
6566 a list of parameters to that command.
6568 So; there you are, reading your @emph{pseudo-articles} in your
6569 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
6570 Why isn't anything real anymore? How did we get here?
6573 @node Article Treatment
6574 @section Article Treatment
6576 Reading through this huge manual, you may have quite forgotten that the
6577 object of newsreaders are to actually, like, read what people have
6578 written. Reading articles. Unfortunately, people are quite bad at
6579 writing, so there are tons of functions and variables to make reading
6580 these articles easier.
6583 * Article Highlighting:: You want to make the article look like fruit salad.
6584 * Article Hiding:: You also want to make certain info go away.
6585 * Article Washing:: Lots of way-neat functions to make life better.
6586 * Article Buttons:: Clcik on URLs, Message-IDs, addresses and the like.
6587 * Article Date:: Grumble, UT!
6591 @node Article Highlighting
6592 @subsection Article Highlighting
6595 Not only do you want your article buffer to look like fruit salad, but
6596 you want it to look like technicolor fruit salad.
6601 @kindex W H a (Summary)
6602 @findex gnus-article-highlight
6603 Highlight the current article (@code{gnus-article-highlight}).
6606 @kindex W H h (Summary)
6607 @findex gnus-article-highlight-headers
6608 @vindex gnus-header-face-alist
6609 Highlight the headers (@code{gnus-article-highlight-headers}). The
6610 highlighting will be done according to the @code{gnus-header-face-alist}
6611 variable, which is a list where each element has the form @var{(regexp
6612 name content)}. @var{regexp} is a regular expression for matching the
6613 header, @var{name} is the face used for highling the header name and
6614 @var{content} is the face for highlighting the header value. The first
6615 match made will be used.
6618 @kindex W H c (Summary)
6619 @findex gnus-article-highlight-citation
6620 Highlight cited text (@code{gnus-article-highlight-citation}).
6622 Some variables to customize the citation highlights:
6625 @vindex gnus-cite-parse-max-size
6626 @item gnus-cite-parse-max-size
6627 If the article size if bigger than this variable (which is 25000 by
6628 default), no citation highlighting will be performed.
6630 @item gnus-cite-prefix-regexp
6631 @vindex gnus-cite-prefix-regexp
6632 Regexp mathcing the longest possible citation prefix on a line.
6634 @item gnus-cite-max-prefix
6635 @vindex gnus-cite-max-prefix
6636 Maximum possible length for a citation prefix (default 20).
6638 @item gnus-supercite-regexp
6639 @vindex gnus-supercite-regexp
6640 Regexp matching normal SuperCite attribution lines.
6642 @item gnus-supercite-secondary-regexp
6643 @vindex gnus-supercite-secondary-regexp
6644 Regexp matching mangled SuperCite attribution lines.
6646 @item gnus-cite-minimum-match-count
6647 @vindex gnus-cite-minimum-match-count
6648 Minimum number of identical prefixes we have to see before we believe
6649 that it's a citation.
6651 @item gnus-cite-attribution-prefix
6652 @vindex gnus-cite-attribution-prefix
6653 Regexp matching the beginning of an attribution line.
6655 @item gnus-cite-addtribution-suffix
6656 @vindex gnus-cite-addtribution-suffix
6657 Regexp matching the end of an attribution line.
6659 @item gnus-cite-attribution-face
6660 @vindex gnus-cite-attribution-face
6661 Face used for attribution lines. It is merged with the face for the
6662 cited text belonging to the attribution.
6668 @kindex W H s (Summary)
6669 @vindex gnus-signature-separator
6670 @findex gnus-article-highlight-signature
6671 Highlight the signature (@code{gnus-article-highlight-signature}).
6672 Everything after @code{gnus-signature-separator} in an article will be
6673 considered a signature.
6678 @node Article Hiding
6679 @subsection Article Hiding
6680 @cindex article hiding
6682 Or rather, hiding certain things in each article. There usually is much
6683 to much gruft in most articles.
6688 @kindex W W a (Summary)
6689 @findex gnus-article-hide
6690 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
6693 @kindex W W h (Summary)
6694 @findex gnus-article-hide-headers
6695 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
6699 @kindex W W s (Summary)
6700 @findex gnus-article-hide-signature
6701 Hide signature (@code{gnus-article-hide-signature}).
6704 @kindex W W p (Summary)
6705 @findex gnus-article-hide-pgp
6706 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}).
6709 @kindex W W c (Summary)
6710 @findex gnus-article-hide-citation
6711 Hide citation (@code{gnus-article-hide-citation}). Two variables for
6712 customizing the hiding:
6716 @item gnus-cite-hide-percentage
6717 @vindex gnus-cite-hide-percentage
6718 If the cited text is of a bigger percentage than this variable (default
6719 50), hide the cited text.
6721 @item gnus-cite-hide-absolute
6722 @vindex gnus-cite-hide-absolute
6723 The cited text must be have at least this length (default 10) before it
6728 Also see @xref{Article Highlighting} for further variables for
6729 citation customization.
6734 @node Article Washing
6735 @subsection Article Washing
6737 @cindex article washing
6739 We call this "article washing" for a really good reason. Namely, the
6740 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
6742 @dfn{Washing} is defined by us as "changing something from something to
6743 something else", but normally results in something looking better.
6749 @kindex W l (Summary)
6750 @findex gnus-summary-stop-page-breaking
6751 Remove page breaks from the current article
6752 (@code{gnus-summary-stop-page-breaking}).
6755 @kindex W r (Summary)
6756 @findex gnus-summary-caesar-message
6757 Do a Caesar rotate (rot13) on the article buffer
6758 (@code{gnus-summary-caesar-message}).
6761 @kindex A g (Summary)
6762 @findex gnus-summary-show-article
6763 (Re)fetch the current article (@code{gnus-summary-show-article}). If
6764 given a prefix, fetch the current article, but don't run any of the
6765 article treatment functions. This will give you a "raw" article, just
6766 the way it came from the server.
6769 @kindex W t (Summary)
6770 @findex gnus-summary-toggle-header
6771 Toggle whether to display all headers in the article buffer
6772 (@code{gnus-summary-toggle-header}).
6775 @kindex W m (Summary)
6776 @findex gnus-summary-toggle-mime
6777 Toggle whether to run the article through @sc{mime} before displaying
6778 (@code{gnus-summary-toggle-mime}).
6781 @kindex W o (Summary)
6782 @findex gnus-article-treat-overstrike
6783 Treat overstrike (@code{gnus-article-treat-overstrike}).
6786 @kindex W w (Summary)
6787 @findex gnus-article-word-wrap
6788 Do word wrap (@code{gnus-article-word-wrap}).
6791 @kindex W c (Summary)
6792 @findex gnus-article-remove-cr
6793 Remove CR (@code{gnus-article-remove-cr}).
6796 @kindex W q (Summary)
6797 @findex gnus-article-de-quoted-unreadable
6798 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
6801 @kindex W f (Summary)
6803 @findex gnus-article-display-x-face
6804 @findex gnus-article-x-face-command
6805 @vindex gnus-article-x-face-command
6806 @vindex gnus-article-x-face-too-ugly
6807 Look for and display any X-Face headers
6808 (@code{gnus-article-display-x-face}). The command executed by this
6809 function is given by the @code{gnus-article-x-face-command} variable. If
6810 this variable is a string, this string will be executed in a sub-shell.
6811 If it is a function, this function will be called with the face as the
6812 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
6813 matches the @code{From} header, the face will not be shown.
6816 @kindex W b (Summary)
6817 @findex gnus-article-add-buttons
6818 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
6821 @kindex W B (Summary)
6822 @findex gnus-article-add-buttons-to-head
6823 Add clickable buttons to the article headers
6824 (@code{gnus-article-add-buttons-to-head}).
6829 @node Article Buttons
6830 @subsection Article Buttons
6833 People often include references to other stuff in articles, and it would
6834 be nice if Gnus could just fetch whatever it is that people talk about
6835 with the minimum of fuzz.
6837 Gnus adds @dfn{buttons} to certain standard references by default:
6838 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
6839 two variables, one that handles article bodies and one that handles
6844 @item gnus-button-alist
6845 @vindex gnus-header-button-alist
6846 This is an alist where each entry has this form:
6849 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
6855 All text that match this regular expression will be considered an
6856 external reference. Here's a typical regexp that match embedded URLs:
6857 @samp{"<URL:\\([^\n\r>]*\\)>"}.
6860 Gnus has to know which parts of the match is to be highlighted. This is
6861 a number that says what sub-expression of the regexp that is to be
6862 highlighted. If you want it all highlighted, you use @samp{0} here.
6865 This form will be @code{eval}ed, and if the result is non-@code{nil},
6866 this is considered a match. This is useful if you want extra sifting to
6867 avoid false matches.
6870 This function will be called when you click on this button.
6873 As with @var{button-par}, this is a sub-expression number, but this one
6874 says which part of the match is to be sent as data to @var{function}.
6878 So the full entry for buttonizing URLs is then
6881 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
6884 @item gnus-header-button-alist
6885 @vindex gnus-header-button-alist
6886 This is just like the other alist, except that it is applied to the
6887 article head only, and that each entry has an additional element that is
6888 used to say what headers to apply the buttonize coding to:
6891 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
6894 @var{header} is a regular expression.
6898 @vindex gnus-article-button-face
6899 @vindex gnus-article-mouse-face
6900 Buttons are highlighted with @code{gnus-article-button-face}, while
6901 @code{gnus-article-mouse-face} is used when the mouse cursor is over the
6906 @subsection Article Date
6908 The date is most likely generated in some obscure timezone you've never
6909 heard of, so it's quite nice to be able to find out what the time was
6910 when the article was sent.
6915 @kindex W T u (Summary)
6916 @findex gnus-article-date-ut
6917 Display the date in UT (aka. GMT, aka ZULU)
6918 (@code{gnus-article-date-ut}).
6921 @kindex W T l (Summary)
6922 @findex gnus-article-date-local
6923 Display the date in the local timezone (@code{gnus-article-date-local}).
6926 @kindex W T e (Summary)
6927 @findex gnus-article-date-lapsed
6928 Say how much time has (e)lapsed between the article was posted and now
6929 (@code{gnus-article-date-lapsed}).
6932 @kindex W T o (Summary)
6933 @findex gnus-article-date-original
6934 Display the original date (@code{gnus-article-date-original}). This can
6935 be useful if you normally use some other conversion function and is
6936 worried that it might be doing something totally wrong. Say, claiming
6937 that the article was posted in 1854. Although something like that is
6938 @emph{totally} impossible. Don't you trust me? *titter*
6943 @node Summary Sorting
6944 @section Summary Sorting
6945 @cindex summary sorting
6947 You can have the summary buffer sorted in various ways, even though I
6948 can't really see why you'd want that.
6952 @kindex C-c C-s C-n (Summary)
6953 @findex gnus-summary-sort-by-number
6954 Sort by article number (@code{gnus-summary-sort-by-number}).
6956 @kindex C-c C-s C-a (Summary)
6957 @findex gnus-summary-sort-by-author
6958 Sort by author (@code{gnus-summary-sort-by-author}).
6960 @kindex C-c C-s C-s (Summary)
6961 @findex gnus-summary-sort-by-subject
6962 Sort by subject (@code{gnus-summary-sort-by-subject}).
6964 @kindex C-c C-s C-d (Summary)
6965 @findex gnus-summary-sort-by-date
6966 Sort by date (@code{gnus-summary-sort-by-date}).
6968 @kindex C-c C-s C-i (Summary)
6969 @findex gnus-summary-sort-by-score
6970 Sort by score (@code{gnus-summary-sort-by-score}).
6973 These functions will work both when you use threading and when you don't
6974 use threading. In the latter case, all summary lines will be sorted,
6975 line by line. In the former case, sorting will be done on a
6976 root-by-root basis, which might not be what you were looking for. To
6977 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
6981 @node Finding the Parent
6982 @section Finding the Parent
6983 @cindex parent articles
6984 @cindex referring articles
6986 @findex gnus-summary-refer-parent-article
6988 If you'd like to read the parent of the current article, and it is not
6989 displayed in the article buffer, you might still be able to. That is,
6990 if the current group is fetched by @sc{nntp}, the parent hasn't expired
6991 and the @code{References} in the current article are not mangled, you
6992 can just press @kbd{^} or @kbd{A r}
6993 (@code{gnus-summary-refer-parent-article}). If everything goes well,
6994 you'll get the parent. If the parent is already displayed in the
6995 summary buffer, point will just move to this article.
6997 @findex gnus-summary-refer-references
6998 @kindex A R (Summary)
6999 You can have Gnus fetch all articles mentioned in the @code{References}
7000 header of the article by pushing @kbd{A R}
7001 (@code{gnus-summary-refer-references}).
7003 @findex gnus-summary-refer-article
7004 @kindex M-^ (Summary)
7005 You can also ask the @sc{nntp} server for an arbitrary article, no
7006 matter what group it belongs to. @kbd{M-^}
7007 (@code{gnus-summary-refer-article}) will ask you for a
7008 @code{Message-ID}, which is one of those long thingies that look
7009 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
7010 it all exactly right. No fuzzy searches, I'm afraid.
7012 @vindex gnus-refer-article-method
7013 If the group you are reading is located on a backend that does not
7014 support fetching by @code{Message-ID} very well (like @code{nnspool}),
7015 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
7016 would, perhaps, be best if the @sc{nntp} server you consult is the same
7017 as the one that keeps the spool you are reading from updated, but that's
7018 not really necessary.
7020 Most of the mail backends support fetching by @code{Message-ID}, but do
7021 not do a particularly excellent job of it. That is, @code{nnmbox} and
7022 @code{nnbabyl} are able to locate articles from any groups, while
7023 @code{nnml} and @code{nnfolder} are only able to locate articles that
7024 have been posted to the current group. (Anything else would be too time
7025 consuming.) @code{nnmh} does not support this at all.
7028 @node Mail Group Commands
7029 @section Mail Group Commands
7030 @cindex mail group commands
7032 Some commands only make sense in mail groups. If these commands are
7033 illegal in the current group, they will raise a hell and let you know.
7035 All these commands (except the expiry and edit commands) use the
7036 process/prefix convention (@pxref{Process/Prefix}).
7040 @kindex B e (Summary)
7041 @findex gnus-summary-expire-articles
7042 Expire all expirable articles in the group
7043 (@code{gnus-summary-expire-articles}).
7046 @kindex B M-C-e (Summary)
7047 @findex gnus-summary-expire-articles-now
7048 Expunge all the expirable articles in the group
7049 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
7050 articles that are eligeble for expiry in the current group will
7051 disappear forever into that big @file{/dev/null} in the sky.
7054 @kindex B DEL (Summary)
7055 @findex gnus-summary-delete-articles
7056 Delete the mail article. This is "delete" as in "delete it from your
7057 disk forever and ever, never to return again." Use with caution.
7058 (@code{gnus-summary-delete-article}).
7061 @kindex B m (Summary)
7063 @findex gnus-summary-move-article
7064 Move the article from one mail group to another
7065 (@code{gnus-summary-move-article}).
7068 @kindex B c (Summary)
7070 @findex gnus-summary-copy-article
7071 Copy the article from one group (mail group or not) to a mail group
7072 (@code{gnus-summary-copy-article}).
7075 @kindex B i (Summary)
7076 @findex gnus-summary-import-article
7077 Import a random file into the current mail newsgroup
7078 (@code{gnus-summary-import-article}). You will be prompted for a file
7079 name, a @code{From} header and a @code{Subject} header.
7081 Something similar can be done by just starting to compose a mail
7082 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
7083 @kbd{C-c C-p} instead. This will put the message you have just created
7084 into the current mail group.
7087 @kindex B r (Summary)
7088 @findex gnus-summary-respool-article
7089 Respool the mail article (@code{gnus-summary-move-article}).
7093 @kindex B w (Summary)
7095 @findex gnus-summary-edit-article
7096 @kindex C-c C-c (Article)
7097 Edit the current article (@code{gnus-summary-edit-article}). To finish
7098 editing and make the changes permanent, type @kbd{C-c C-c}
7099 (@kbd{gnus-summary-edit-article-done}).
7102 @kindex B q (Summary)
7103 @findex gnus-summary-respool-query
7104 If you want to respool an article, you might be curious as to what group
7105 the article will end up in before you do the respooling. This command
7106 will tell you (@code{gnus-summary-fancy-query}).
7109 @node Various Summary Stuff
7110 @section Various Summary Stuff
7113 * Group Information:: Information oriented commands.
7114 * Searching for Articles:: Multiple article commands.
7115 * Really Various Summary Commands:: Those pesky non-conformant commands.
7118 @vindex gnus-summary-generate-hook
7119 @code{gnus-summary-generate-hook} is called as the last thing before
7120 doing the threading and the generation of the summary buffer. It's
7121 quite convenient for customizing the threading variables based on what
7122 data the newsgroup has. This hook is called from the summary buffer
7123 after most summary buffer variables has been set.
7125 @vindex gnus-summary-prepare-hook
7126 @code{gnus-summary-prepare-hook} is called after the summary buffer has
7127 been generated. You might use it to, for instance, highlight lines or
7128 modify the look of the buffer in some other ungodly manner. I don't
7131 @node Group Information
7132 @subsection Group Information
7136 @kindex H f (Summary)
7137 @findex gnus-summary-fetch-faq
7138 @vindex gnus-group-faq-directory
7139 Try to fetch the FAQ (list of frequently asked questions) for the
7140 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
7141 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
7142 on a remote machine. This variable can also be a list of directories.
7143 In that case, giving a prefix to this command will allow you to choose
7144 between the various sites. @code{ange-ftp} probably will be used for
7147 @kindex H d (Summary)
7148 @findex gnus-summary-describe-group
7149 Give a brief description of the current group
7150 (@code{gnus-summary-describe-group}). If given a prefix, force
7151 rereading the description from the server.
7153 @kindex H h (Summary)
7154 @findex gnus-summary-describe-briefly
7155 Give a very brief description of the most important summary keystrokes
7156 (@code{gnus-summary-describe-briefly}).
7158 @kindex H i (Summary)
7159 @findex gnus-info-find-node
7160 Go to the Gnus info node (@code{gnus-info-find-node}).
7163 @node Searching for Articles
7164 @subsection Searching for Articles
7168 @kindex M-s (Summary)
7169 @findex gnus-summary-search-article-forward
7170 Search through all subsequent articles for a regexp
7171 (@code{gnus-summary-search-article-forward}).
7173 @kindex M-r (Summary)
7174 @findex gnus-summary-search-article-backward
7175 Search through all previous articles for a regexp
7176 (@code{gnus-summary-search-article-backward}).
7179 @findex gnus-summary-execute-command
7180 This command will prompt you for a header field, a regular expression to
7181 match on this field, and a command to be executed if the match is made
7182 (@code{gnus-summary-execute-command}).
7184 @kindex M-& (Summary)
7185 @findex gnus-summary-universal-argument
7186 Perform any operation on all articles that have been marked with
7187 the process mark (@code{gnus-summary-universal-argument}).
7190 @node Really Various Summary Commands
7191 @subsection Really Various Summary Commands
7195 @kindex A D (Summary)
7196 @findex gnus-summary-enter-digest-group
7197 If the current article is a digest, you might use this command to enter
7198 a group based on the current digest
7199 (@code{gnus-summary-enter-digest-group}). Gnus will try to guess what
7200 article type is currently displayed unless you give a prefix to this
7201 command, which forces a "digest" interpretation.
7204 @kindex C-t (Summary)
7205 @findex gnus-summary-toggle-truncation
7206 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
7210 @findex gnus-summary-expand-window
7211 Expand the summary buffer window (@code{gnus-summary-expand-window}).
7212 If given a prefix, force an @code{article} window configuration.
7216 @node The Article Buffer
7217 @chapter The Article Buffer
7218 @cindex article buffer
7220 The articles are displayed in the article buffer, of which there is only
7221 one. All the summary buffer share the same article buffer.
7224 * Hiding Headers:: Deciding what headers should be displayed.
7225 * Using Mime:: Pushing articles through @sc{mime} before reading them.
7226 * Customizing Articles:: Tailoring the look of the articles.
7227 * Article Keymap:: Keystrokes available in the article buffer
7228 * Misc Article:: Other stuff.
7231 @node Hiding Headers
7232 @section Hiding Headers
7233 @cindex hiding headers
7234 @cindex deleting headers
7236 The top section of each article is the @dfn{head}. (The rest is the
7237 @dfn{body}, but you may have guessed that already.)
7239 @vindex gnus-show-all-headers
7240 There is a lot of useful information in the head: the name of the person
7241 who wrote the article, the date it was written and the subject of the
7242 article. That's well and nice, but there's also lots of information
7243 most people do not want to see---what systems the article has passed
7244 through before reaching you, the @code{Message-ID}, the
7245 @code{References}, etc. ad nauseum---and you'll probably want to get rid
7246 of some of those lines. If you want to keep all those lines in the
7247 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
7249 Gnus provides you with two variables for sifting headers:
7252 @item gnus-visible-headers
7253 @vindex gnus-visible-headers
7254 If this variable is non-@code{nil}, it should be a regular expression
7255 that says what headers you wish to keep in the article buffer. All
7256 headers that do not match this variable will be hidden.
7258 For instance, if you only want to see the name of the person who wrote
7259 the article and the subject, you'd say:
7262 (setq gnus-visible-headers "^From:\\|^Subject:")
7265 @item gnus-ignored-headers
7266 @vindex gnus-ignored-headers
7267 This variable is the reverse of @code{gnus-visible-headers}. If this
7268 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
7269 should be a regular expression that matches all lines that you want to
7270 hide. All lines that do not match this variable will remain visible.
7272 For instance, if you just want to get rid of the @code{References} line
7273 and the @code{Xref} line, you might say:
7276 (setq gnus-ignored-headers "^References:\\|^Xref:")
7279 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
7280 variable will have no effect.
7283 @vindex gnus-sorted-header-list
7284 Gnus can also sort the headers for you. (It does this by default.) You
7285 can control the sorting by setting the @code{gnus-sorted-header-list}
7286 variable. It is a list of regular expressions that says in what order
7287 the headers are to be displayed.
7289 For instance, if you want the name of the author of the article first,
7290 and then the subject, you might say something like:
7293 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
7296 Any headers that are to remain visible, but are not listed in this
7297 variable, will be displayed in random order after all the headers that
7298 are listed in this variable.
7304 Mime is a standard for waving your hands through the air, aimlessly,
7305 while people stand around yawning.
7307 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
7308 while all newsreaders die of fear.
7310 @sc{mime} may specify what character set the article uses, the encoding
7311 of the characters, and it also makes it possible to embed pictures and
7312 other naughty stuff in innocent-looking articles.
7314 @vindex gnus-show-mime
7315 @vindex gnus-show-mime-method
7316 Gnus handles @sc{mime} by shoving the articles through
7317 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
7318 default. If @code{gnus-strict-mime} is non-@code{nil}, the @sc{mime}
7319 method will only be used it there are @sc{mime} headers in the article.
7320 Set @code{gnus-show-mime} to @code{t} if you want to use @sc{mime} all
7321 the time; it might be best to just use the toggling functions from the
7322 summary buffer to avoid getting nasty surprises. (For instance, you
7323 enter the group @samp{alt.sing-a-long} and, before you know it,
7324 @sc{mime} has decoded the sound file in the article and some horrible
7325 sing-a-long song comes streaming out out your speakers, and you can't
7326 find the volume button, because there isn't one, and people are starting
7327 to look at you, and you try to stop the program, but you can't, and you
7328 can't find the program to control the volume, and everybody else in the
7329 room suddenly decides to look at you disdainfully, and you'll feel
7332 Any similarity to real events and people is purely coincidental. Ahem.
7335 @node Customizing Articles
7336 @section Customizing Articles
7337 @cindex article customization
7339 @vindex gnus-article-display-hook
7340 The @code{gnus-article-display-hook} is called after the article has
7341 been inserted into the article buffer. It is meant to handle all
7342 treatment of the article before it is displayed.
7344 By default it contains @code{gnus-article-hide-headers},
7345 @code{gnus-article-treat-overstrike}, and
7346 @code{gnus-article-maybe-highlight}, but there are thousands, nay
7347 millions, of functions you can put in this hook. For an overview of
7348 functions @xref{Article Highlighting}, @xref{Article Hiding},
7349 @xref{Article Washing}, @xref{Article Buttons} and @xref{Article Date}.
7351 You can, of course, write your own functions. The functions are called
7352 from the article buffer, and you can do anything you like, pretty much.
7353 There is no information that you have to keep in the buffer---you can
7354 change everything. However, you shouldn't delete any headers. Instead
7355 make them invisible if you want to make them go away.
7358 @node Article Keymap
7359 @section Article Keymap
7361 @c Most of the keystrokes in the summary buffer can also be used in the
7362 @c article buffer. They should behave as if you typed them in the summary
7363 @c buffer, which means that you don't actually have to have a summary
7364 @c buffer displayed while reading. You can do it all from the article
7367 A few additional keystrokes are available:
7371 @kindex SPACE (Article)
7372 @findex gnus-article-next-page
7373 Scroll forwards one page (@code{gnus-article-next-page}).
7375 @kindex DEL (Article)
7376 @findex gnus-article-prev-page
7377 Scroll backwards one page (@code{gnus-article-prev-page}).
7379 @kindex C-c ^ (Article)
7380 @findex gnus-article-refer-article
7381 If point is in the neighborhood of a @code{Message-ID} and you press
7382 @kbd{r}, Gnus will try to get that article from the server
7383 (@code{gnus-article-refer-article}).
7385 @kindex C-c C-m (Article)
7386 @findex gnus-article-mail
7387 Send a reply to the address near point (@code{gnus-article-mail}). If
7388 given a prefix, include the mail.
7391 @findex gnus-article-show-summary
7392 Reconfigure the buffers so that the summary buffer becomes visible
7393 (@code{gnus-article-show-summary}).
7396 @findex gnus-article-describe-briefly
7397 Give a very brief description of the available keystrokes
7398 (@code{gnus-article-describe-briefly}).
7402 @section Misc Article
7405 @vindex gnus-article-prepare-hook
7406 @item gnus-article-prepare-hook
7407 This hook is called right after the article has been inserted into the
7408 article buffer. It is mainly intended for functions that do something
7409 depending on the contents; it should probably not be used for changing
7410 the contents of the article buffer.
7411 @vindex gnus-article-display-hook
7412 @item gnus-article-display-hook
7413 This hook is called as the last thing when displaying an article, and is
7414 intended for modifying the contents of the buffer, doing highlights,
7415 hiding headers, and the like.
7416 @vindex gnus-article-mode-line-format
7417 @item gnus-article-mode-line-format
7418 This variable is a format string along the same lines as
7419 @code{gnus-summary-mode-line-format}. It accepts exactly the same
7420 format specifications as that variable.
7421 @vindex gnus-break-pages
7422 @item gnus-break-pages
7423 Controls whether @dfn{page breaking} is to take place. If this variable
7424 is non-@code{nil}, the articles will be divided into pages whenever a
7425 page delimiter appears in the article. If this variable is @code{nil},
7426 paging will not be done.
7427 @item gnus-page-delimiter
7428 @vindex gnus-page-delimiter
7429 This is the delimiter mentioned above. By default, it is @samp{^L}
7433 @node The Server Buffer
7434 @chapter The Server Buffer
7436 Traditionally, a @dfn{server} is a machine or a piece of software that
7437 one connects to, and then requests information from. Gnus does not
7438 connect directly to any real servers, but does all transactions through
7439 one backend or other. But that's just putting one layer more between
7440 the actual media and Gnus, so we might just as well say that each
7441 backend represents a virtual server.
7443 For instance, the @code{nntp} backend may be used to connect to several
7444 different actual @sc{nntp} servers, or, perhaps, to many different ports
7445 on the same actual @sc{nntp} server. You tell Gnus which backend to
7446 use, and what parameters to set by specifying a @dfn{select method}.
7448 These select methods specifications can sometimes become quite
7449 complicated---say, for instance, that you want to read from the
7450 @sc{nntp} server @samp{news.funet.fi} on port number @samp{13}, which
7451 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
7452 Anyways, if you had to specify that for each group that used this
7453 server, that would be too much work, so Gnus offers a way of putting
7454 names to methods, which is what you do in the server buffer.
7456 To enter the server buffer, user the @kbd{^}
7457 (@code{gnus-group-enter-server-mode}) command in the group buffer.
7460 * Server Buffer Format:: You can customize the look of this buffer.
7461 * Server Commands:: Commands to manipulate servers.
7462 * Example Methods:: Examples server specifications.
7463 * Servers & Methods:: You can use server names as select methods.
7464 * Unavailable Servers:: Some servers you try to contact may be down.
7467 @node Server Buffer Format
7468 @section Server Buffer Format
7469 @cindex server buffer format
7471 @vindex gnus-server-line-format
7472 You can change the look of the server buffer lines by changing the
7473 @code{gnus-server-line-format} variable. This is a @code{format}-like
7474 variable, with some simple extensions:
7478 How the news is fetched---the backend name.
7480 The name of this server.
7482 Where the news is to be fetched from---the address.
7485 @node Server Commands
7486 @section Server Commands
7487 @cindex server commands
7491 Browse the current server (@code{gnus-server-read-server}).
7493 Return to the group buffer (@code{gnus-server-exit}).
7495 List all servers (@code{gnus-server-list-servers}).
7497 Kill the current server (@code{gnus-server-kill-server}).
7499 Yank the previously killed server (@code{gnus-server-yank-server}).
7501 Copy the current server (@code{gnus-server-copy-server}).
7503 Add a new server (@code{gnus-server-add-server}).
7505 Edit a server (@code{gnus-server-edit-server}).
7508 @node Example Methods
7509 @section Example Methods
7511 Most select methods are pretty simple and self-explanatory:
7514 (nntp "news.funet.fi")
7517 Reading directly from the spool is even simpler:
7523 As you can see, the first element in a select method is the name of the
7524 backend, and the second is the @dfn{address}, or @dfn{name}, if you
7527 After these two elements, there may be a random number of @var{(variable
7530 To go back to the first example---imagine that you want to read from
7531 port @code{15} from that machine. This is what the select method should
7535 (nntp "news.funet.fi" (nntp-port-number 15))
7538 You should read the documentation to each backend to find out what
7539 variables are relevant, but here's an @code{nnmh} example.
7541 @code{nnmh} is a mail backend that reads a spool-like structure. Say
7542 you have two structures that you wish to access: One is your private
7543 mail spool, and the other is a public one. Here's the possible spec for
7547 (nnmh "private" (nnmh-directory "~/private/mail/"))
7550 (This server is then called @samp{private}, but you may have guessed
7553 Here's the method for the public spool:
7557 (nnmh-directory "/usr/information/spool/")
7558 (nnmh-get-new-mail nil))
7561 @node Servers & Methods
7562 @section Servers & Methods
7564 Wherever you would normally use a select method
7565 (eg. @code{gnus-secondary-select-method}, in the group select method,
7566 when browsing a foreign server) you can use a virtual server name
7567 instead. This could potentially save lots of typing. And it's nice all
7571 @node Unavailable Servers
7572 @section Unavailable Servers
7574 If a server seems to be unreachable, Gnus will mark that server as
7575 @code{denied}. That means that any subsequent attempt to make contact
7576 with that server will just be ignored. "It can't be opened," Gnus will
7577 tell you, without making the least effort to see whether that is
7578 actually the case or not.
7580 That might seem quite naughty, but it does make sense most of the time.
7581 Let's say you have 10 groups subscribed to the server
7582 @samp{nepholococcygia.com}. This server is located somewhere quite far
7583 away from you, the machine is quite, so it takes 1 minute just to find
7584 out that it refuses connection from you today. If Gnus were to attempt
7585 to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
7586 that. Once it has gotten a single "connection refused", it will regard
7587 that server as "down".
7589 So, what happens if the machine was only feeling unwell temporarily?
7590 How do you test to see whether the machine has come up again?
7592 You jump to the server buffer (@pxref{The Server Buffer}) and poke ut
7593 with the following commands:
7599 @findex gnus-server-open-server
7600 Try to establish connection to the server on the current line
7601 (@code{gnus-server-open-server}).
7605 @findex gnus-server-close-server
7606 Close the connection (if any) to the server
7607 (@code{gnus-server-close-server}).
7611 @findex gnus-server-deny-server
7612 Mark the current server as unreachable
7613 (@code{gnus-server-deny-server}).
7617 @findex gnus-server-remove-denials
7618 Remove all marks to whether Gnus was denied connection from all servers
7619 (@code{gnus-server-remove-denials}).
7628 Other people use @dfn{kill files}, but we here at Gnus Towers like
7629 scoring better than killing, so we'd rather switch than fight. They do
7630 something completely different as well, so sit up straight and pay
7633 @vindex gnus-summary-mark-below
7634 All articles have a default score (@code{gnus-summary-default-score}),
7635 which is 0 by default. This score may be raised or lowered either
7636 interactively or by score files. Articles that have a score lower than
7637 @code{gnus-summary-mark-below} are marked as read.
7639 Gnus will read any @dfn{score files} that apply to the current group
7640 before generating the summary buffer.
7642 There are several commands in the summary buffer that insert score
7643 entries based on the current article. You can, for instance, ask Gnus to
7644 lower or increase the score of all articles with a certain subject.
7646 There are two sorts of scoring entries: Permanent and temporary.
7647 Temporary score entries are self-expiring entries. Any entries that are
7648 temporary and have not been used for, say, a week, will be removed
7649 silently to help keep the sizes of the score files down.
7652 * Summary Score Commands:: Adding score entries for the current group.
7653 * Group Score Commands:: General score commands.
7654 * Score Variables:: Customize your scoring. (My, what terminology).
7655 * Score File Format:: What a score file may contain.
7656 * Score File Editing:: You can edit score files by hand as well.
7657 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
7658 * Scoring Tips:: How to score effectively.
7659 * Reverse Scoring:: That problem child of old is not problem.
7660 * Global Score Files:: Earth-spanning, ear-splitting score files.
7661 * Kill Files:: They are still here, but they can be ignored.
7664 @node Summary Score Commands
7665 @section Summary Score Commands
7666 @cindex score commands
7668 The score commands that alter score entries do not actually modify real
7669 score files. That would be too inefficient. Gnus maintains a cache of
7670 previously loaded score files, one of which is considered the
7671 @dfn{current score file alist}. The score commands simply insert
7672 entries into this list, and upon group exit, this list is saved.
7674 The current score file is by default the group's local score file, even
7675 if no such score file actually exists. To insert score commands into
7676 some other score file (eg. @file{all.SCORE}), you must first make this
7677 score file the current one.
7679 General score commands that don't actually change the score file:
7683 @kindex V s (Summary)
7684 @findex gnus-summary-set-score
7685 Set the score of the current article (@code{gnus-summary-set-score}).
7688 @kindex V S (Summary)
7689 @findex gnus-summary-current-score
7690 Display the score of the current article
7691 (@code{gnus-summary-current-score}).
7694 @kindex V t (Summary)
7695 @findex gnus-score-find-trace
7696 Display all score rules that have been used on the current article
7697 (@code{gnus-score-find-trace}).
7700 @kindex V a (Summary)
7701 @findex gnus-summary-score-entry
7702 Add a new score entry, and allow specifying all elements
7703 (@code{gnus-summary-score-entry}).
7706 @kindex V c (Summary)
7707 @findex gnus-score-change-score-file
7708 Make a different score file the current
7709 (@code{gnus-score-change-score-file}).
7712 @kindex V e (Summary)
7713 @findex gnus-score-edit-alist
7714 Edit the current score file (@code{gnus-score-edit-alist}). You will be
7715 popped into a @code{gnus-score-mode} buffer (@pxref{Score File
7719 @kindex V f (Summary)
7720 @findex gnus-score-edit-file
7721 Edit a score file and make this score file the current one
7722 (@code{gnus-score-edit-file}).
7725 @kindex V C (Summary)
7726 @findex gnus-score-customize
7727 Customize a score file in a visually pleasing manner
7728 (@code{gnus-score-customize}).
7731 @kindex I C-i (Summary)
7732 @findex gnus-summary-raise-score
7733 Increase the score of the current article
7734 (@code{gnus-summary-raise-score}).
7737 @kindex L C-l (Summary)
7738 @findex gnus-summary-lower-score
7739 Lower the score of the current article
7740 (@code{gnus-summary-lower-score}).
7743 The rest of these commands modify the local score file.
7747 @kindex V m (Summary)
7748 @findex gnus-score-set-mark-below
7749 Prompt for a score, and mark all articles with a score below this as
7750 read (@code{gnus-score-set-mark-below}).
7752 @kindex V E (Summary)
7753 @findex gnus-score-set-expunge-below
7754 Expunge all articles with a score below the default score (or the
7755 numeric prefix) (@code{gnus-score-set-expunge-below}).
7758 The keystrokes for actually making score entries follow a very regular
7759 pattern, so there's no need to list all the commands. (Hundreds of
7764 The first key is either @kbd{I} (upper case i) for increasing the score
7765 or @kbd{L} for lowering the score.
7767 The second key says what header you want to score on. The following
7771 Score on the author name.
7773 Score on the subject line.
7775 Score on the Xref line---i.e., the cross-posting line.
7777 Score on thread---the References line.
7781 Score on the number of lines.
7783 Score on the Message-ID.
7793 The third key is the match type. Which match types are legal depends on
7794 what headers you are scoring on.
7827 Greater than number.
7832 The fourth and final key says whether this is a temporary (i.e., expiring)
7833 score entry, or a permanent (i.e., non-expiring) score entry, or whether
7834 it is to be done immediately, without adding to the score file.
7837 Temporary score entry.
7839 Permanent score entry.
7841 Immediately scoring.
7846 So, let's say you want to increase the score on the current author with
7847 exact matching permanently: @kbd{I a e p}. If you want to lower the
7848 score based on the subject line, using substring matching, and make a
7849 temporary score entry: @kbd{L s s t}. Pretty easy.
7851 To make things a bit more complicated, there are shortcuts. If you use
7852 a capital letter on either the second or third keys, Gnus will use
7853 defaults for the remaining one or two keystrokes. The defaults are
7854 "substring" and "temporary". So @kbd{I A} is the same as @kbd{I a s t},
7855 and @kbd{I a R} is the same as @kbd{I a r t}.
7857 @vindex gnus-score-mimic-keymap
7858 The @code{gnus-score-mimic-keymap} says whether these commands will
7859 pretend they are keymaps or not.
7862 @node Group Score Commands
7863 @section Group Score Commands
7864 @cindex group score commands
7866 There aren't many of these as yet, I'm afraid.
7872 @findex gnus-score-flush-cache
7873 Gnus maintains a cache of score alists to avoid having to reload them
7874 all the time. This command will flush the cache
7875 (@code{gnus-score-flush-cache}).
7880 @node Score Variables
7881 @section Score Variables
7882 @cindex score variables
7885 @item gnus-use-scoring
7886 @vindex gnus-use-scoring
7887 If @code{nil}, Gnus will not check for score files, and will not, in
7888 general, do any score-related work. This is @code{t} by default.
7890 @item gnus-kill-killed
7891 @vindex gnus-kill-killed
7892 If this variable is @code{nil}, Gnus will never apply score files to
7893 articles that have already been through the kill process. While this
7894 may save you lots of time, it also means that if you apply a kill file
7895 to a group, and then change the kill file and want to run it over you
7896 group again to kill more articles, it won't work. You have to set this
7897 variable to @code{t} to do that. (It is @code{t} by default.)
7899 @item gnus-kill-files-directory
7900 @vindex gnus-kill-files-directory
7901 All kill and score files will be stored in this directory, which is
7902 initialized from the @samp{SAVEDIR} environment variable by default.
7903 This is @file{~/News/} by default.
7905 @item gnus-score-file-suffix
7906 @vindex gnus-score-file-suffix
7907 Suffix to add to the group name to arrive at the score file name
7908 (@samp{SCORE} by default.)
7910 @item gnus-score-uncacheable-files
7911 @vindex gnus-score-uncacheable-files
7913 All score files are normally cached to avoid excessive re-loading of
7914 score files. However, if this might make you Emacs grow big and
7915 bloated, so this regexp can be used to weed out score files that are
7916 unlikely to be needed again. It would be a bad idea to deny caching of
7917 @file{all.SCORE}, while it might be a good idea to not cache
7918 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
7919 variable is @samp{"ADAPT$"} by default, so no adaptive score files will
7922 @item gnus-save-score
7923 @vindex gnus-save-score
7924 If you have really complicated score files, and do lots of batch
7925 scoring, then you might set this variable to @code{t}. This will make
7926 Gnus save the scores into the @file{.newsrc.eld} file.
7928 @item gnus-save-score
7929 @vindex gnus-save-score
7930 If you have really complicated score files, and do lots of batch
7931 scoring, then you might set this variable to @code{t}. This will make
7932 Gnus save the scores into the @file{.newsrc.eld} file.
7934 @item gnus-score-interactive-default-score
7935 @vindex gnus-score-interactive-default-score
7936 Score used by all the interactive raise/lower commands to raise/lower
7937 score with. Default is 1000, which may seem excessive, but this is to
7938 ensure that the adaptive scoring scheme gets enough room to play with.
7939 We don't want the small changes from the adaptive scoring to overwrite
7940 manually entered data.
7942 @item gnus-summary-default-score
7943 @vindex gnus-summary-default-score
7944 Default score of an article, which is 0 by default.
7946 @item gnus-score-over-mark
7947 @vindex gnus-score-over-mark
7948 Mark (in the third column) used for articles with a score over the
7949 default. Default is @samp{+}.
7951 @item gnus-score-below-mark
7952 @vindex gnus-score-below-mark
7953 Mark (in the third column) used for articles with a score below the
7954 default. Default is @samp{-}.
7956 @item gnus-score-find-score-files-function
7957 @vindex gnus-score-find-score-files-function
7958 Function used to find score files for the current group. This function
7959 is called with the name of the group as the argument.
7961 Predefined functions available are:
7964 @item gnus-score-find-single
7965 @findex gnus-score-find-single
7966 Only apply the group's own score file.
7968 @item gnus-score-find-bnews
7969 @findex gnus-score-find-bnews
7970 Apply all score files that match, using bnews syntax. This is the
7971 default. For instance, if the current group is @samp{gnu.emacs.gnus},
7972 @samp{all.emacs.all.SCORE}, @samp{not.alt.all.SCORE} and
7973 @samp{gnu.all.SCORE} would all apply. In short, the instances of
7974 @samp{all} in the score file names are translated into @samp{.*}, and
7975 then a regexp match is done.
7977 This means that if you have some score entries that you want to apply to
7978 all groups, then you put those entries in the @file{all.SCORE} file.
7980 If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
7981 very will. It will find stuff like @file{gnu/all/SCORE}, but will not
7982 find files like @file{not/gnu/all/SCORE}.
7984 @item gnus-score-find-hierarchical
7985 @findex gnus-score-find-hierarchical
7986 Apply all score files from all the parent groups. This means that you
7987 can't have score files like @file{all.SCORE} or @file{all.emacs.SCORE},
7988 but you can have @file{SCORE}, @file{comp.SCORE} and
7989 @file{comp.emacs.SCORE}.
7992 This variable can also be a list of functions. In that case, all these
7993 functions will be called, and all the returned lists of score files will
7994 be applied. These functions can also return lists of score alists
7995 directly. In that case, the functions that return these non-file score
7996 alists should probably be placed before the "real" score file functions,
7997 to ensure that the last score file returned is the local score file.
7999 @item gnus-score-expiry-days
8000 @vindex gnus-score-expiry-days
8001 This variable says how many days should pass before an unused score file
8002 entry is expired. The default is 7.
8005 @node Score File Format
8006 @section Score File Format
8007 @cindex score file format
8009 A score file is an @code{emacs-lisp} file that normally contains just a
8010 single form. Casual users are not expected to edit these files;
8011 everything can be changed from the summary buffer.
8013 Anyway, if you'd like to dig into it yourself, here's an example:
8017 ("Lars Ingebrigtsen" -10000)
8019 ("larsi\\|lmi" -50000 nil R))
8021 ("Ding is Badd" nil 728373))
8023 ("alt.politics" -1000 728372 s))
8028 (mark-and-expunge -10)
8032 (files "/hom/larsi/News/gnu.SCORE")
8033 (exclude-files "all.SCORE")
8034 (local (gnus-newsgroup-auto-expire t)
8035 (gnus-summary-make-false-root 'empty))
8039 This example demonstrates absolutely everything about a score file.
8041 Even though this looks much like lisp code, nothing here is actually
8042 @code{eval}ed. The lisp reader is used to read this form, though, so it
8043 has to be legal syntactically, if not semantically.
8045 Six keys are supported by this alist:
8049 If the key is a string, it is the name of the header to perform the
8050 match on. Scoring can only be performed on these eight headers:
8051 @samp{From}, @samp{Subject}, @samp{References}, @samp{Message-ID},
8052 @samp{Xref}, @samp{Lines}, @samp{Chars} and @samp{Date}. In addition to
8053 these headers, there are three strings to tell Gnus to fetch the entire
8054 article and do the match on larger parts of the article: @samp{Body}
8055 will perform the match on the body of the article, @samp{Head} will
8056 perform the match on the head of the article, and @samp{All} will
8057 perform the match on the entire article. Note that using any of these
8058 last three keys will slow down group entry @emph{considerably}. The
8059 final "header" you can score on is @samp{Followup}. These score entries
8060 will result in new score entries being added for all follow-ups to
8061 articles that matches these score entries.
8063 Following this key is a random number of score entries, where each score
8064 entry has one to four elements.
8067 The first element is the @dfn{match element}. On most headers this will
8068 be a string, but on the Lines and Chars headers, this must be an
8071 If the second element is present, it should be a number---the @dfn{score
8072 element}. This number should be an integer in the neginf to posinf
8073 interval. This number is added to the score of the article if the match
8074 is successful. If this element is not present, the
8075 @code{gnus-score-interactive-default-score} number will be used
8076 instead. This is 1000 by default.
8078 If the third element is present, it should be a number---the @dfn{date
8079 element}. This date says when the last time this score entry matched,
8080 which provides a mechanism for expiring the score entries. It this
8081 element is not present, the score entry is permanent. The date is
8082 represented by the number of days since December 31, 1 ce.
8084 If the fourth element is present, it should be a symbol---the @dfn{type
8085 element}. This element specifies what function should be used to see
8086 whether this score entry matches the article. What match types that can
8087 be used depends on what header you wish to perform the match on.
8089 @item From, Subject, References, Xref, Message-ID
8090 For most header types, there are the @code{r} and @code{R} (regexp) as
8091 well as @code{s} and @code{S} (substring) types and @code{e} and
8092 @code{E} (exact match) types. If this element is not present, Gnus will
8093 assume that substring matching should be used. @code{R} and @code{S}
8094 differ from the other two in that the matches will be done in a
8095 case-sensitive manner. All these one-letter types are really just
8096 abbreviations for the @code{regexp}, @code{string} and @code{exact}
8097 types, which you can use instead, if you feel like.
8099 These two headers use different match types: @code{<}, @code{>},
8100 @code{=}, @code{>=} and @code{<=}.
8102 For the Date header we have three match types: @code{before}, @code{at}
8103 and @code{after}. I can't really imagine this ever being useful, but,
8104 like, it would feel kinda silly not to provide this function. Just in
8105 case. You never know. Better safe than sorry. Once burnt, twice shy.
8106 Don't judge a book by its cover. Never not have sex on a first date.
8107 @item Head, Body, All
8108 These three match keys use the same match types as the @code{From} (etc)
8111 This match key will add a score entry on all articles that followup to
8112 some author. Uses the same match types as the @code{From} header uses.
8117 The value of this entry should be a number. Any articles with a score
8118 lower than this number will be marked as read.
8120 The value of this entry should be a number. Any articles with a score
8121 lower than this number will be removed from the summary buffer.
8122 @item mark-and-expunge
8123 The value of this entry should be a number. Any articles with a score
8124 lower than this number will be marked as read and removed from the
8127 The value of this entry should be any number of file names. These files
8128 are assumed to be score files as well, and will be loaded the same way
8131 The clue of this entry should be any number of files. This files will
8132 not be loaded, even though they would normally be so, for some reason or
8135 The value of this entry will be @code{eval}el. This element will be
8136 ignored when handling global score files.
8138 Read-only score files will not be updated or saved. Global score files
8139 should feature this atom (@pxref{Global Score Files}).
8141 The value of this entry should be a number. Articles that do not have
8142 parents will get this number added to their scores.
8144 This entry controls the adaptive scoring. If it is @code{t}, the
8145 default adaptive scoring rules will be used. If it is @code{ignore}, no
8146 adaptive scoring will be performed on this group. If it is a list, this
8147 list will be used as the adaptive scoring rules. If it isn't present,
8148 or is something other than @code{t} or @code{ignore}, the default
8149 adaptive scoring rules will be used. If you want to use adaptive
8150 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
8151 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
8152 not want adaptive scoring. If you only want adaptive scoring in a few
8153 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
8154 insert @code{(adapt t)} in the score files of the groups where you want
8157 @cindex local variables
8158 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
8159 Each @var{var} will be made buffer-local to the current summary buffer,
8160 and set to the value specified. This is a convenient, if somewhat
8161 strange, way of setting variables in some groups if you don't like hooks
8165 @node Score File Editing
8166 @section Score File Editing
8168 You normally enter all scoring commands from the summary buffer, but you
8169 might feel the urge to edit them by hand as well, so we've supplied you
8170 with a mode for that.
8172 It's simply a slightly customized @code{emacs-lisp} mode, with these
8173 additional commands:
8177 @kindex C-c C-c (Score)
8178 @findex gnus-score-edit-done
8179 Save the changes you have made and return to the summary buffer
8180 (@code{gnus-score-edit-done}).
8182 @kindex C-c C-d (Score)
8183 @findex gnus-score-edit-insert-date
8184 Insert the current date in numerical format
8185 (@code{gnus-score-edit-insert-date}). This is really the day number, if
8189 @node Adaptive Scoring
8190 @section Adaptive Scoring
8191 @cindex adaptive scoring
8193 If all this scoring is getting you down, Gnus has a way of making it all
8194 happen automatically---as if by magic. Or rather, as if by artificial
8195 stupidity, to be precise.
8197 @vindex gnus-use-adaptive-scoring
8198 When you read an article, or mark an article as read, or kill an
8199 article, you leave marks behind. On exit from the group, Gnus can sniff
8200 these marks and add score elements depending on what marks it finds.
8201 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
8204 @vindex gnus-default-adaptive-score-alist
8205 To give you complete control over the scoring process, you can customize
8206 the @code{gnus-default-adaptive-score-alist} variable. By default, it
8207 looks something like this:
8210 (defvar gnus-default-adaptive-score-alist
8211 '((gnus-unread-mark)
8212 (gnus-ticked-mark (from 4))
8213 (gnus-dormant-mark (from 5))
8214 (gnus-del-mark (from -4) (subject -1))
8215 (gnus-read-mark (from 4) (subject 2))
8216 (gnus-expirable-mark (from -1) (subject -1))
8217 (gnus-killed-mark (from -1) (subject -3))
8218 (gnus-kill-file-mark)
8219 (gnus-catchup-mark (from -1) (subject -1))))
8222 As you see, each element in this alist has a mark as a key (either a
8223 variable name or a "real" mark---a character). Following this key is a
8224 random number of header/score pairs.
8226 To take @code{gnus-del-mark} as an example---this alist says that all
8227 articles that have that mark (i.e., are marked with @samp{D}) will have a
8228 score entry added to lower based on the @code{From} header by -4, and
8229 lowered by @code{Subject} by -1. Change this to fit your prejudices.
8231 The headers you can score on are @code{from}, @code{subject},
8232 @code{message-id}, @code{references}, @code{xref}, @code{lines},
8233 @code{chars} and @code{date}. In addition, you can score on
8234 @code{followup}, which will create an adaptive score entry that matches
8235 on the @code{References} header using the @code{Message-ID} of the
8236 current article, thereby matching the following thread.
8238 If you use this scheme, you should set @code{mark-below} to something
8239 small---like -300, perhaps, to avoid having small random changes result
8240 in articles getting marked as read.
8242 After using adaptive scoring for a week or so, Gnus should start to
8243 become properly trained and enhance the authors you like best, and kill
8244 the authors you like least, without you having to say so explicitly.
8246 You can control what groups the adaptive scoring is to be performed on
8247 by using the score files (@pxref{Score File Format}). This will also
8248 let you use different rules in different groups.
8250 @vindex gnus-adaptive-file-suffix
8251 The adaptive score entries will be put into a file where the name is the
8252 group name with @code{gnus-adaptive-file-suffix} appended. The default
8255 @vindex gnus-score-exact-adapt-limit
8256 When doing adaptive scoring, substring or fuzzy matching would probably
8257 give you the best results in most cases. However, if the header one
8258 matches is short, the possibility for false positives is great, so if
8259 the length of the match is less than
8260 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
8261 this variable is @code{nil}, exact matching will always be used to avoid
8265 @section Scoring Tips
8266 @cindex scoring tips
8270 If you want to lower the score of crossposts, the line to match on is
8271 the @code{Xref} header.
8273 ("xref" (" talk.politics.misc:" -1000))
8275 @item Multiple crossposts
8276 If you want to lower the score of articles that have been crossposted to
8277 more than, say, 3 groups:
8279 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
8281 @item Matching on the body
8282 This is generally not a very good idea---it takes a very long time.
8283 Gnus actually has to fetch each individual article from the server. But
8284 you might want to anyway, I guess. Even though there are three match
8285 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
8286 and stick with it in each score file. If you use any two, each article
8287 will be fetched @emph{twice}. If you want to match a bit on the
8288 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
8290 @item Marking as read
8291 You will probably want to mark articles that has a score below a certain
8292 number as read. This is most easily achieved by putting the following
8293 in your @file{all.SCORE} file:
8297 You may also consider doing something similar with @code{expunge}.
8299 @item Negated charater classes
8300 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
8301 That will match newlines, which might lead to, well, The Unknown. Say
8302 @code{[^abcd\n]*} instead.
8305 @node Reverse Scoring
8306 @section Reverse Scoring
8307 @cindex reverse scoring
8309 If you want to keep just articles that have @samp{Sex with Emacs} in the
8310 subject header, and expunge all other articles, you could put something
8311 like this in your score file:
8315 ("Sex with Emacs" 2))
8320 So, you raise all articles that match @samp{Sex with Emacs} and mark the
8321 rest as read, and expunge them to boot.
8323 @node Global Score Files
8324 @section Global Score Files
8325 @cindex global score files
8327 Sure, other newsreaders have "global kill files". These are usually
8328 nothing more than a single kill file that applies to all groups, stored
8329 in the user's home directory. Bah! Puny, weak newsreaders!
8331 What I'm talking about here are Global Score Files. Score files from
8332 all over the world, from users everywhere, uniting all nations in one
8333 big, happy score file union! Ange-score! New and untested!
8335 @vindex gnus-global-score-files
8336 All you have to do to use other people's score files is to set the
8337 @code{gnus-global-score-files} variable. One entry for each score file,
8338 or each score file directory. Gnus will decide by itself what score
8339 files are applicable to which group.
8341 Say you want to use all score files in the
8342 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
8343 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
8346 (setq gnus-global-score-files
8347 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
8348 "/ftp@@ftp.some-where:/pub/score/"))
8351 @findex gnus-score-search-global-directories
8352 Simple, eh? Directory names must end with a @samp{/}. These
8353 directories are typically scanned only once during each Gnus session.
8354 If you feel the need to manually re-scan the remote directories, you can
8355 use the @code{gnus-score-search-global-directories} command.
8357 Note that, at present, using this option will slow down group entry
8358 somewhat. (That is---a lot.)
8360 If you want to start maintaining score files for other people to use,
8361 just put your score file up for anonymous ftp and announce it to the
8362 world. Become a retro-moderator! Participate in the retro-moderator
8363 wars sure to ensue, where retro-moderators battle it out for the
8364 sympathy of the people, luring them to use their score files on false
8365 premises! Yay! The net is saved!
8367 Here are some tips for the would-be retro-moderator, off the top of my
8372 Articles that are heavily crossposted are probably junk.
8374 To lower a single inappropriate article, lower by @code{Message-ID}.
8376 Particularly brilliant authors can be raised on a permanent basis.
8378 Authors that repeatedly post off-charter for the group can safely be
8379 lowered out of existence.
8381 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
8382 articles completely.
8384 Use expiring score entries to keep the size of the file down. You
8385 should probably have a long expiry period, though, as some sites keep
8386 old articles for a long time.
8389 ... I wonder whether other newsreaders will support global score files
8390 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
8391 Wave, xrn and 1stReader are bound to implement scoring. Should we start
8392 holding our breath yet?
8399 Gnus still supports those pesky old kill files. In fact, the kill file
8400 entries can now be expiring, which is something I wrote before Daniel
8401 Quinlan thought of doing score files, so I've left the code in there.
8403 In short, kill processing is a lot slower (and I do mean @emph{a lot})
8404 than score processing, so it might be a good idea to rewrite your kill
8405 files into score files.
8407 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
8408 forms into this file, which means that you can use kill files as some
8409 sort of primitive hook function to be run on group entry, even though
8410 that isn't a very good idea.
8412 XCNormal kill files look like this:
8415 (gnus-kill "From" "Lars Ingebrigtsen")
8416 (gnus-kill "Subject" "ding")
8420 This will mark every article written by me as read, and remove them from
8421 the summary buffer. Very useful, you'll agree.
8423 Other programs use a totally different kill file syntax. If Gnus
8424 encounters what looks like a @code{rn} kill file, it will take a stab at
8427 Two functions for editing a GNUS kill file:
8431 @kindex M-k (Summary)
8432 @findex gnus-summary-edit-local-kill
8433 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
8436 @kindex M-K (Summary)
8437 @findex gnus-summary-edit-global-kill
8438 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
8441 @vindex gnus-kill-file-name
8442 A kill file for the group @samp{soc.motss} is normally called
8443 @file{soc.motss.KILL}. The suffix appended to the group name to get
8444 this file name is detailed by the @code{gnus-kill-file-name} variable.
8445 The "global" kill file (not in the score file sense of "global", of
8446 course) is called just @file{KILL}.
8448 @vindex gnus-kill-save-kill-file
8449 If @code{gnus-kill-save-kill-file} is non-@code{nil}, Gnus will save the
8450 kill file after processing, which is necessary if you use expiring
8460 * Interactive:: Making Gnus ask you many questions.
8461 * Formatting Variables:: How to control the look of the buffers.
8462 * Windows Configuration:: Configuring the Gnus buffer windows.
8463 * Buttons:: Get tendonitis in ten easy steps!
8464 * Compilation & Init File:: How to speed Gnus up.
8465 * Daemons:: Gnus can do things behind your back.
8466 * NoCeM:: How to avoid spam and other fatty foods.
8467 * Various Various:: Things that are really various.
8471 @section Interactive
8475 @item gnus-novice-user
8476 @vindex gnus-novice-user
8477 If this variable is non-@code{nil}, you are either a newcomer to the
8478 World of Usenet, or you are very cautious, which is a nice thing to be,
8479 really. You will be given questions of the type "Are you sure you want
8480 to do this?" before doing anything dangerous. This is @code{t} by
8483 @item gnus-expert-user
8484 @vindex gnus-expert-user
8485 If this variable is non-@code{nil}, you will never ever be asked any
8486 questions by Gnus. It will simply assume you know what your are doing,
8487 no matter how strange.
8489 @item gnus-interactive-catchup
8490 @vindex gnus-interactive-catchup
8491 Require confirmation before catching up a group if non-@code{nil}. It
8492 is @code{t} by default.
8494 @item gnus-interactive-post
8495 @vindex gnus-interactive-post
8496 If non-@code{nil}, the user will be prompted for a group name when
8497 posting an article. It is @code{t} by default.
8499 @item gnus-interactive-exit
8500 @vindex gnus-interactive-exit
8501 Require confirmation before exiting Gnus. This variable is @code{t} by
8506 @node Formatting Variables
8507 @section Formatting Variables
8508 @cindex formatting variables
8510 Throughout this manual you've probably noticed lots of variables that
8511 are called things like @code{gnus-group-line-format} and
8512 @code{gnus-summary-mode-line-format}. These control how Gnus is to
8513 output lines in the various buffers. There's quite a lot of them.
8514 Fortunately, they all use the same syntax, so there's not that much to
8517 Here's an example format spec (from the group buffer): @samp{"%M%S%5y:
8518 %(%g%)\n"}. We see that it is indeed extremely ugly, and that there are
8519 lots of percentages everywhere.
8521 Each @samp{%} element will be replaced by some string or other when the
8522 buffer in question is generated. @samp{%5y} means "insert the @samp{y}
8523 spec, and pad with spaces to get a 5-character field". Just like a
8524 normal format spec, almost.
8526 You can also say @samp{%6,4y}, which means that the field will never be
8527 more than 6 characters wide and never less than 4 characters wide.
8529 There are also specs for highlighting, and these are shared by all the
8530 format variables. Text inside the @samp{%(} and @samp{%)} specifiers
8531 will get the special @code{mouse-face} property set, which means that it
8532 will be highlighted (with @code{gnus-mouse-face}) when you put the mouse
8535 Text inside the @samp{%@{} and @samp{%@}} specifiers will have their
8536 normal faces set using @code{gnus-face-0}, which is @code{bold} by
8537 default. If you say @samp{%1@{} instead, you'll get @code{gnus-face-1}
8538 instead, and so on. Create as many faces as you wish. The same goes
8539 for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
8540 @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
8542 Here's an alternative recipe for the group buffer:
8545 ;; Create three face types.
8546 (setq gnus-face-1 'bold)
8547 (setq gnus-face-3 'italic)
8549 ;; We want the article count to be in
8550 ;; a bold and green face. So we create
8551 ;; a new face called `my-green-bold'.
8552 (copy-face 'bold 'my-green-bold)
8554 (set-face-foreground 'my-green-bold "ForestGreen")
8555 (setq gnus-face-2 'my-green-bold)
8557 ;; Set the new & fancy format.
8558 (setq gnus-group-line-format
8559 "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
8562 I'm sure you'll be able to use this scheme to create totally unreadable
8563 and extremely vulgar displays. Have fun!
8565 Currently Gnus uses the following formatting variables:
8566 @code{gnus-group-line-format}, @code{gnus-summary-line-format},
8567 @code{gnus-server-line-format}, @code{gnus-topic-line-format},
8568 @code{gnus-group-mode-line-format},
8569 @code{gnus-summary-mode-line-format},
8570 @code{gnus-article-mode-line-format},
8571 @code{gnus-server-mode-line-format}.
8573 Note that the @samp{%(} specs (and friends) do not make any sense on the
8574 mode-line variables.
8576 All these format variables can also be random elisp forms. In that
8577 case, they will be @code{eval}ed to insert the required lines.
8579 @kindex M-x gnus-update-format
8580 @findex gnus-update-format
8581 Gnus includes a command to help you while creating your own format
8582 specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
8583 update the spec in question and pop you to a buffer where you can
8584 examine the resulting lisp code to be run to generate the line.
8587 @node Windows Configuration
8588 @section Windows Configuration
8589 @cindex windows configuration
8591 No, there's nothing here about X, so be quiet.
8594 @item gnus-use-full-window
8595 @vindex gnus-use-full-window
8596 If non-@code{nil}, Gnus will delete all other windows and occupy the
8597 entire Emacs screen by itself. It is @code{t} by default.
8599 @item gnus-buffer-configuration
8600 @vindex gnus-buffer-configuration
8601 This variable describes how much space each Gnus buffer should be given.
8602 Here's an excerpt of this variable:
8605 ((group ([group 1.0 point]
8606 (if gnus-carpal [group-carpal 4])))
8607 (article ([summary 0.25 point]
8611 This is an alist. The @dfn{key} is a symbol that names some action or
8612 other. For instance, when displaying the group buffer, the window
8613 configuration function will use @code{group} as the key. A full list of
8614 possible names is listed below.
8616 The @dfn{value} is a @dfn{rule} that says how much space each buffer
8617 should occupy. To take the @code{article} rule as an example -
8620 (article ([summary 0.25 point]
8624 This rule says that the summary buffer should occupy 25% of the screen,
8625 and that it is placed over the article buffer. As you may have noticed,
8626 100% + 25% is actually 125% (yup, I saw y'all reaching for that
8627 calculator there). However, the special number @code{1.0} is used to
8628 signal that this buffer should soak up all the rest of the space
8629 avaiable after the rest of the buffers have taken whatever they need.
8630 There should be only one buffer with the @code{1.0} size spec.
8632 Point will be put in the buffer that has the optional third element
8635 Here's a more complicated example:
8639 [summary 0.25 point]
8640 (if gnus-carpal [summary-carpal 4])
8644 If the size spec is an integer instead of a floating point number,
8645 then that number will be used to say how many lines a buffer should
8646 occupy, not a percentage.
8648 If an element is a list instead of a vector, this list will be
8649 @code{eval}ed. If the result is non-@code{nil}, it will be used. This
8650 means that there will be three buffers if @code{gnus-carpal} is
8651 @code{nil}, and four buffers if @code{gnus-carpal} is non-@code{nil}.
8653 Not complicated enough for you? Well, try this on for size:
8656 (article ([group 1.0]
8659 [summary 0.25 point]
8664 Whoops. Two buffers with the mystery 100% tag. And what's that
8665 @code{horizontal} thingie?
8667 If the first element in one of the rule lists is a list with
8668 @code{horizontal} as the first element, Gnus will split the window
8669 horizontally, giving you two windows side-by-side. Inside each of these
8670 strips you may carry on all you like in the normal fashion. The number
8671 following @code{horizontal} says what percentage of the screen is to be
8672 given to this strip.
8674 For each horizontal split, there @emph{must} be one element that has the
8675 100% tag. The splitting is never accurate, and this buffer will eat any
8676 leftover lines from the splits.
8678 Here's a list of all possible keys:
8680 @code{group}, @code{summary}, @code{article}, @code{server},
8681 @code{browse}, @code{group-mail}, @code{summary-mail},
8682 @code{summary-reply}, @code{info}, @code{summary-faq},
8683 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
8684 @code{followup}, @code{followup-yank}, @code{edit-score}.
8686 @findex gnus-add-configuration
8687 Since this variable is so long and complicated, there's a function you
8688 can use to ease changing the config of a single setting:
8689 @code{gnus-add-configuration}. If, for instance, you want to change the
8690 @code{article} setting, you could say:
8693 (gnus-add-configuration
8694 '(article ([group 4]
8707 Those new-fangled @dfn{mouse} contraptions is very popular with the
8708 young, hep kids who don't want to learn the proper way to do things
8709 these days. Why, I remember way back in the summer of '89, when I was
8710 using Emacs on a Tops 20 system. Three hundred users on one single
8711 machine, and every user was running Simula compilers. Bah!
8716 Well, you can make Gnus display bufferfuls of buttons you can click to
8717 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
8718 really. Tell the chiropractor I sent you.
8722 @item gnus-carpal-mode-hook
8723 @vindex gnus-carpal-mode-hook
8724 Hook run in all carpal mode buffers.
8725 @item gnus-carpal-button-face
8726 @vindex gnus-carpal-button-face
8727 Face used on buttons.
8728 @item gnus-carpal-group-buffer-buttons
8729 @vindex gnus-carpal-group-buffer-buttons
8730 Buttons in the group buffer.
8731 @item gnus-carpal-summary-buffer-buttons
8732 @vindex gnus-carpal-summary-buffer-buttons
8733 Buttons in the summary buffer.
8734 @item gnus-carpal-server-buffer-buttons
8735 @vindex gnus-carpal-server-buffer-buttons
8736 Buttons in the server buffer.
8737 @item gnus-carpal-browse-buffer-buttons
8738 @vindex gnus-carpal-browse-buffer-buttons
8739 Buttons in the browse buffer.
8742 All the @code{buttons} variables are lists. The elements in these list
8743 is either a cons cell where the car contains a text to be displayed and
8744 the cdr contains a function symbol, or a simple string.
8747 @node Compilation & Init File
8748 @section Compilation & Init File
8751 @cindex byte-compilation
8753 @vindex gnus-init-file
8754 @findex gnus-compile
8755 When Gnus starts up, it will read the Gnus init file
8756 @code{gnus-init-file}, which is @file{.gnus} by default. It is
8757 recommended that you keep any Gnus-related functions that you have
8758 written in that file. If you want to byte-compile the file, Gnus offers
8759 the handy @kbd{M-x gnus-compile} function that will do that for you.
8761 That's not really why that function was written, though.
8763 Remember all those line format specification variables?
8764 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
8765 on. Now, Gnus will of course heed whatever these variables are, but,
8766 unfortunately, changing them will mean a quite significant slow-down.
8767 (The default values of these variables have byte-compiled functions
8768 associated with them, while the user-generated versions do not, of
8771 To help with this, you can run @code{gnus-compile} after you've fiddled
8772 around with the variables and feel that you're (kind of) satisfied.
8773 This will result in the new specs being byte-compiled, and you'll get
8776 The result of these byte-compilations will be written to
8777 @file{.gnus.elc} by default.
8779 Note that Gnus will read @file{.gnus.elc} instead of @file{.gnus} if
8780 @file{.gnus.elc} exists, so if you change @file{.gnus}, you should
8781 remove @file{.gnus.elc}.
8789 Gnus, being larger than any program ever written (allegedly), does lots
8790 of strange stuff that you may wish to have done while you're not
8791 present. For instance, you may want it to check for new mail once in a
8792 while. Or you may want it to close down all connections to all servers
8793 when you leave Emacs idle. And stuff like that.
8795 Gnus will let you do stuff like that by defining various
8796 @dfn{handlers}. Each handler consists of three elements: A
8797 @var{function}, a @var{time}, and an @var{idle} parameter.
8799 Here's an example of a handler that closes connections when Emacs has
8800 been idle for thirty minutes:
8803 (gnus-demon-close-connections nil 30)
8806 Here's a handler that scans for PGP headers every hour when Emacs is
8810 (gnus-demon-scan-pgp 60 t)
8813 This @var{time} parameter and than @var{idle} parameter works together
8814 in a strange, but wonderful fashion. Basically, if @var{idle} is
8815 @code{nil}, then the function will be called every @var{time} minutes.
8817 If @var{idle} is @code{t}, then the function will be called after
8818 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
8819 the function will never be called. But once Emacs goes idle, the
8820 function will be called every @var{time} minutes.
8822 If @var{idle} is a number and @var{time} is a number, the function will
8823 be called every @var{time} minutes only when Emacs has been idle for
8826 If @var{idle} is a number and @var{time} is @code{nil}, the function
8827 will be called once every time Emacs has been idle for @var{idle}
8830 And if @var{time} is a string, it should look like @samp{"07:31"}, and
8831 the function will then be called once every day somewhere near that
8832 time. Modified by the @var{idle} parameter, of course.
8834 @vindex gnus-demon-timestep
8835 (When I say "minute" here, I really mean @code{gnus-demon-timestep}
8836 seconds. This is @samp{60} by default. If you change that variable,
8837 all the timings in the handlers will be affected.)
8839 @vindex gnus-use-demon
8840 To set the whole thing in motion, though, you have to set
8841 @code{gnus-use-demon} to @code{t}.
8843 @vindex gnus-use-demon
8844 To set the whole thing in motion, though, you have to set
8845 @code{gnus-use-demon} to @code{t}.
8847 So, if you want to add a handler, you could put something like this in
8848 your @file{.gnus} file:
8850 @findex gnus-demon-add-handler
8852 (gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
8855 @findex gnus-demon-add-nocem
8856 @findex gnus-demon-add-scanmail
8857 @findex gnus-demon-add-disconnection
8858 Some ready-made functions to do this has been created:
8859 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
8860 @code{gnus-demon-add-scanmail}. Just put those functions in your
8861 @file{.gnus} if you want those abilities.
8863 @findex gnus-demon-init
8864 @findex gnus-demon-cancel
8865 @vindex gnus-demon-handlers
8866 If you add handlers to @code{gnus-demon-handlers} directly, you should
8867 run @code{gnus-demon-init} to make the changes take hold. To cancel all
8868 daemons, you can use the @code{gnus-demon-cancel} function.
8870 Note that adding daemons can be pretty naughty if you overdo it. Adding
8871 functions that scan all news and mail from all servers every two seconds
8872 is a sure-fire way of getting booted off any respectable system. So
8883 @node Various Various
8884 @section Various Various
8890 @vindex gnus-verbose
8891 This variable is an integer between zero and ten. The higher the value,
8892 the more messages will be displayed. If this variable is zero, Gnus
8893 will never flash any messages, if it is seven (which is the default),
8894 most important messages will be shown, and if it is ten, Gnus won't ever
8895 shut up, but will flash so many messages it will make your head swim.
8897 @item gnus-updated-mode-lines
8898 @vindex gnus-updated-mode-lines
8899 This is a list of buffers that should keep their mode lines updated.
8900 The list may contain the symbols @code{group}, @code{article} and
8901 @code{summary}. If the corresponding symbol is present, Gnus will keep
8902 that mode line updated with information that may be pertinent. If this
8903 variable is @code{nil}, screen refresh may be quicker.
8905 @cindex display-time
8906 @item gnus-mode-non-string-length
8907 @vindex gnus-mode-non-string-length
8908 By default, Gnus displays information on the current article in the mode
8909 lines of the summary and article buffers. The information Gnus wishes
8910 to display (eg. the subject of the article) is often longer than the
8911 mode lines, and therefore have to be cut off at some point. This
8912 variable says how long the other elements on the line is (i.e., the
8913 non-info part). If you put additional elements on the mode line (eg. a
8914 clock), you should modify this variable:
8915 @c Hook written by Keinonen Kari <kk85613@cs.tut.fi>.
8917 (add-hook 'display-time-hook
8919 (setq gnus-mode-non-string-length
8920 (+ 21 (length display-time-string)))))
8926 @cindex highlighting
8929 If @code{nil}, Gnus won't attempt to create menus or use fancy colors
8930 or fonts. This will also inhibit loading the @file{gnus-visual.el}
8933 This variable can also be a list of visual properties that are enabled.
8934 The following elements are legal, and are all set by default:
8938 @item summary-highlight
8939 Perform various highlighting in the summary buffer.
8941 @item article-highlight
8942 Perform various highlighting in the article buffer.
8945 Turn on highlighting in all buffers.
8948 Create menus in the group buffer.
8951 Create menus in the summary buffer.
8954 Create menus in the article buffer.
8957 Create menus in the browse buffer.
8960 Create menus in the server buffer.
8963 Create menus in all buffers.
8967 So if you only want highlighting in the article buffer and menus in all
8968 buffers, you couls say something like:
8971 (setq gnus-visual '(article-highlight menu))
8974 If you want only highlighting and no menus whatsoever, you'd say:
8977 (setq gnus-visual '(highlight))
8980 @item gnus-mouse-face
8981 @vindex gnus-mouse-face
8982 This is the face (i.e., font) used for mouse highlighting in Gnus. No
8983 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
8985 @item gnus-display-type
8986 @vindex gnus-display-type
8987 This variable is symbol indicating the display Emacs is running under.
8988 The symbol should be one of @code{color}, @code{grayscale} or
8989 @code{mono}. If Gnus guesses this display attribute wrongly, either set
8990 this variable in your @file{~/.emacs} or set the resource
8991 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
8993 @item gnus-background-mode
8994 @vindex gnus-background-mode
8995 This is a symbol indicating the Emacs background brightness. The symbol
8996 should be one of @code{light} or @code{dark}. If Gnus guesses this
8997 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
8998 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
8999 `gnus-display-type'.
9001 @item nnheader-max-head-length
9002 @vindex nnheader-max-head-length
9003 When the backends read straight heads of articles, they all try to read
9004 as little as possible. This variable (default @code{4096}) specifies
9005 the absolute max length the backends will try to read before giving up
9006 on finding a separator line between the head and the body. If this
9007 variable is @code{nil}, there is no upper read bound. If it is
9008 @code{t}, the backends won't try to read the articles piece by piece,
9009 but read the entire articles. This makes sense with some versions of
9016 @chapter Customization
9017 @cindex general customization
9019 All variables are properly documented elsewhere in this manual. This
9020 section is designed to give general pointers on how to customize Gnus
9021 for some quite common situations.
9024 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
9025 * Slow Terminal Connection:: You run a remote Emacs.
9026 * Little Disk Space:: You feel that having large setup files is icky.
9027 * Slow Machine:: You feel like buying a faster machine.
9030 @node Slow/Expensive Connection
9031 @section Slow/Expensive @sc{nntp} Connection
9033 If you run Emacs on a machine locally, and get your news from a machine
9034 over some very thin strings, you want to cut down on the amount of data
9035 Gnus has to get from the @sc{nntp} server.
9038 @item gnus-read-active-file
9039 Set this to @code{nil}, which will inhibit Gnus from requesting the
9040 entire active file from the server. This file is often v. large. You
9041 also have to set @code{gnus-check-new-news} and
9042 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
9043 doesn't suddenly decide to fetch the active file anyway.
9044 @item gnus-nov-is-evil
9045 This one has to be @code{nil}. If not, grabbing article headers from
9046 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
9047 support @sc{xover}; Gnus will detect this by itself.
9050 @node Slow Terminal Connection
9051 @section Slow Terminal Connection
9053 Let's say you use your home computer for dialing up the system that
9054 runs Emacs and Gnus. If your modem is slow, you want to reduce the
9055 amount of data that is sent over the wires as much as possible.
9058 @item gnus-auto-center-summary
9059 Set this to @code{nil} to inhibit Gnus from recentering the summary
9060 buffer all the time.
9061 @item gnus-visible-headers
9062 Cut down on the headers that are included in the articles to the
9063 minimum. You can, in fact, make do without them altogether---most of the
9064 useful data is in the summary buffer, anyway. Set this variable to
9065 @samp{"^NEVVVVER"} or @samp{"From:"}, or whatever you feel you need.
9066 @item gnus-article-display-hook
9067 Set this hook to all the available hiding commands:
9069 (setq gnus-article-display-hook
9070 '(gnus-article-hide-headers gnus-article-hide-signature
9071 gnus-article-hide-citation))
9073 @item gnus-use-full-window
9074 By setting this to @code{nil}, you can make all the windows smaller.
9075 While this doesn't really cut down much generally, it means that you
9076 have to see smaller portions of articles before deciding that you didn't
9077 want to read them anyway.
9078 @item gnus-thread-hide-subtree
9079 If this is non-@code{nil}, all threads in the summary buffer will be
9081 @item gnus-updated-mode-lines
9082 If this is @code{nil}, Gnus will not put information in the buffer mode
9083 lines, which might save some time.
9086 @node Little Disk Space
9087 @section Little Disk Space
9089 The startup files can get rather large, so you may want to cut their
9090 sizes a bit if you are running out of space.
9093 @item gnus-save-newsrc-file
9094 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
9095 only save @file{.newsrc.eld}. This means that you will not be able to
9096 use any other newsreaders than Gnus. This variable is @code{t} by
9099 @item gnus-save-killed-list
9100 If this is @code{nil}, Gnus will not save the list of dead groups. You
9101 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
9102 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
9103 variable to @code{nil}. This variable is @code{t} by default.
9109 @section Slow Machine
9111 If you have a slow machine, or are just really impatient, there are a
9112 few things you can do to make Gnus run faster.
9114 Set@code{gnus-check-new-newsgroups} and
9115 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
9117 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
9118 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
9119 summary buffer faster.
9121 Set @code{gnus-article-display-hook} to @code{nil} to make article
9122 processing a bit faster.
9125 @node Troubleshooting
9126 @chapter Troubleshooting
9127 @cindex troubleshooting
9129 Gnus works @emph{so} well straight out of the box---I can't imagine any
9137 Make sure your computer is switched on.
9140 Make sure that you really load the current Gnus version. If you have
9141 been running @sc{gnus}, you need to exit Emacs and start it up again before
9145 Try doing an @kbd{M-x gnus-version}. If you get something that looks
9146 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
9147 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
9148 flee}, you have some old @file{.el} files lying around. Delete these.
9151 Read the help group (@kbd{M h} in the group buffer) for a FAQ and a
9155 If all else fails, report the problem as a bug.
9158 @cindex reporting bugs
9160 @kindex M-x gnus-bug
9162 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
9163 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
9164 me the backtrace. I will fix bugs, but I can only fix them if you send
9165 me a precise description as to how to reproduce the bug.
9167 You really can never be too detailed in a bug report. Always use the
9168 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
9169 a 10Kb mail each time you use it, and even if you have sent me your
9170 environment 500 times before. I don't care. I want the full info each
9173 It is also important to remember that I have no memory whatsoever. If
9174 you send a bug report, and I send you a reply, and then you send back
9175 just "No, it's not! Moron!", I will have no idea what you are insulting
9176 me about. Always overexplain everything. It's much easier for all of
9177 us---if I don't have all the information I need, I will just mail you
9178 and ask for more info, and everything takes more time.
9180 If you just need help, you are better off asking on
9181 @samp{gnu.emacs.gnus}. I'm not very helpful.
9183 @cindex gnu.emacs.gnus
9184 @cindex ding mailing list
9185 You can also ask on the ding mailing list---@samp{ding@@ifi.uio.no}.
9186 Write to @samp{ding-request@@ifi.uio.no} to subscribe.
9192 Well, that's the manual---you can get on with your life now. Keep in
9193 touch. Say hello to your cats from me.
9195 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
9197 Ol' Chuck Reznikoff said it pretty well, so I leave the floor to him:
9202 Not because of victories @*
9205 but for the common sunshine,@*
9207 the largess of the spring.
9210 but for the day's work done@*
9211 as well as I was able;@*
9212 not for a seat upon the dais@*
9213 but at the common table.@*
9220 * A Programmer@'s Guide to Gnus:: Rilly, rilly technical stuff.
9221 * Emacs for Heathens:: A short intruduction to Emacsian terms.
9222 * Frequently Asked Questions:: A question-and-answer session.
9226 @node A Programmer@'s Guide to Gnus
9227 @section A Programmer@'s Guide to Gnus
9229 It is my hope that other people will figure out smart stuff that Gnus
9230 can do, and that other people will write those smart things as well. To
9231 facilitate that I thought it would be a good idea to describe the inner
9232 workings of Gnus. And some of the not-so-inner workings, while I'm at
9235 You can never expect the internals of a program not to change, but I
9236 will be defining (in some details) the interface between Gnus and its
9237 backends (this is written in stone), the format of the score files
9238 (ditto), data structures (some are less likely to change than others)
9239 and general method of operations.
9242 * Backend Interface:: How Gnus communicates with the servers.
9243 * Score File Syntax:: A BNF definition of the score file standard.
9244 * Headers:: How Gnus stores headers internally.
9245 * Ranges:: A handy format for storing mucho numbers.
9246 * Group Info:: The group info format.
9247 * Various File Formats:: Formats of files that Gnus use.
9251 @node Backend Interface
9252 @subsection Backend Interface
9254 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
9255 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
9256 server is a @dfn{backend} and some @dfn{backend variables}. As examples
9257 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
9258 examples of the latter we have @code{nntp-port-number} and
9259 @code{nnmbox-directory}.
9261 When Gnus asks for information from a backend---say @code{nntp}---on
9262 something, it will normally include a virtual server name in the
9263 function parameters. (If not, the backend should use the "current"
9264 virtual server.) For instance, @code{nntp-request-list} takes a virtual
9265 server as its only (optional) parameter. If this virtual server hasn't
9266 been opened, the function should fail.
9268 Note that a virtual server name has no relation to some physical server
9269 name. Take this example:
9273 (nntp-address "ifi.uio.no")
9274 (nntp-port-number 4324))
9277 Here the virtual server name is @samp{"odd-one"} while the name of
9278 the physical server is @samp{"ifi.uio.no"}.
9280 The backends should be able to switch between several virtual servers.
9281 The standard backends implement this by keeping an alist of virtual
9282 server environments that it pulls down/pushes up when needed.
9284 There are two groups of interface functions: @dfn{required functions},
9285 which must be present, and @dfn{optional functions}, which Gnus will
9286 always check whether are present before attempting to call.
9288 All these functions are expected to return data in the buffer
9289 @code{nntp-server-buffer} (@samp{" *nntpd*"}), which is somewhat
9290 unfortunately named, but we'll have to live with it. When I talk about
9291 "resulting data", I always refer to the data in that buffer. When I
9292 talk about "return value", I talk about the function value returned by
9295 Some backends could be said to be @dfn{server-forming} backends, and
9296 some might be said to not be. The latter are backends that generally
9297 only operate on one group at a time, and have no concept of "server" --
9298 they have a group, and they deliver info on that group and nothing more.
9300 In the examples and definitions I will refer to the imaginary backend
9303 @cindex @code{nnchoke}
9306 * Required Backend Functions:: Functions that must be implemented.
9307 * Optional Backend Functions:: Functions that need not be implemented.
9311 @node Required Backend Functions
9312 @subsubsection Required Backend Functions
9316 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
9318 @var{articles} is either a range of article numbers or a list of
9319 @code{Message-ID}s. Current backends do not fully support either---only
9320 sequences (lists) of article numbers, and most backends do not support
9321 retrieval of @code{Message-ID}s. But they should try for both.
9323 The result data should either be HEADs or NOV lines, and the result
9324 value should either be @code{headers} or @code{nov} to reflect this.
9325 This might later be expanded to @code{various}, which will be a mixture
9326 of HEADs and NOV lines, but this is currently not supported by Gnus.
9328 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
9329 headers, in some meaning of the word. This is generally done by
9330 fetching (at most) @var{fetch-old} extra headers less than the smallest
9331 article number in @code{articles}, and fill in the gaps as well. The
9332 presence of this parameter can be ignored if the backend finds it
9333 cumbersome to follow the request. If this is non-@code{nil} and not a
9334 number, do maximum fetches.
9336 Here's an example HEAD:
9339 221 1056 Article retrieved.
9340 Path: ifi.uio.no!sturles
9341 From: sturles@@ifi.uio.no (Sturle Sunde)
9342 Newsgroups: ifi.discussion
9343 Subject: Re: Something very droll
9344 Date: 27 Oct 1994 14:02:57 +0100
9345 Organization: Dept. of Informatics, University of Oslo, Norway
9347 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
9348 References: <38jdmq$4qu@@visbur.ifi.uio.no>
9349 NNTP-Posting-Host: holmenkollen.ifi.uio.no
9353 So a @code{headers} return value would imply that there's a number of
9354 these in the data buffer.
9356 Here's a BNF definition of such a buffer:
9360 head = error / valid-head
9361 error-message = [ "4" / "5" ] 2number " " <error message> eol
9362 valid-head = valid-message *header "." eol
9363 valid-message = "221 " <number> " Article retrieved." eol
9367 If the return value is @code{nov}, the data buffer should contain
9368 @dfn{network overview database} lines. These are basically fields
9372 nov-buffer = *nov-line
9373 nov-line = 8*9 [ field <TAB> ] eol
9374 field = <text except TAB>
9377 For a closer explanation what should be in those fields,
9381 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
9383 @var{server} is here the virtual server name. @var{definitions} is a
9384 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
9386 If the server can't be opened, no error should be signaled. The backend
9387 may then choose to refuse further attempts at connecting to this
9388 server. In fact, it should do so.
9390 If the server is opened already, this function should return a
9391 non-@code{nil} value. There should be no data returned.
9394 @item (nnchoke-close-server &optional SERVER)
9396 Close connection to @var{server} and free all resources connected
9399 There should be no data returned.
9402 @item (nnchoke-request-close)
9404 Close connection to all servers and free all resources that the backend
9405 have reserved. All buffers that have been created by that backend
9406 should be killed. (Not the @code{nntp-server-buffer}, though.)
9408 There should be no data returned.
9411 @item (nnchoke-server-opened &optional SERVER)
9413 This function should return whether @var{server} is opened, and that the
9414 connection to it is still alive. This function should under no
9415 circumstances attempt to reconnect to a server that is has lost
9418 There should be no data returned.
9421 @item (nnchoke-status-message &optional SERVER)
9423 This function should return the last error message from @var{server}.
9425 There should be no data returned.
9428 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
9430 The result data from this function should be the article specified by
9431 @var{article}. This might either be a @code{Message-ID} or a number.
9432 It is optional whether to implement retrieval by @code{Message-ID}, but
9433 it would be nice if that were possible.
9435 If @var{to-buffer} is non-@code{nil}, the result data should be returned
9436 in this buffer instead of the normal data buffer. This is to make it
9437 possible to avoid copying large amounts of data from one buffer to
9438 another, and Gnus mainly request articles to be inserted directly into
9442 @item (nnchoke-open-group GROUP &optional SERVER)
9444 Make @var{group} the current group.
9446 There should be no data returned by this function.
9449 @item (nnchoke-request-group GROUP &optional SERVER)
9451 Get data on @var{group}. This function also has the side effect of
9452 making @var{group} the current group.
9454 Here's an example of some result data and a definition of the same:
9457 211 56 1000 1059 ifi.discussion
9460 The first number is the status, which should be @samp{211}. Next is the
9461 total number of articles in the group, the lowest article number, the
9462 highest article number, and finally the group name. Note that the total
9463 number of articles may be less than one might think while just
9464 considering the highest and lowest article numbers, but some articles
9465 may have been cancelled. Gnus just discards the total-number, so
9466 whether one should take the bother to generate it properly (if that is a
9467 problem) is left as an excercise to the reader.
9470 group-status = [ error / info ] eol
9471 error = [ "4" / "5" ] 2<number> " " <Error message>
9472 info = "211 " 3* [ <number> " " ] <string>
9476 @item (nnchoke-close-group GROUP &optional SERVER)
9478 Close @var{group} and free any resources connected to it. This will be
9479 a no-op on most backends.
9481 There should be no data returned.
9484 @item (nnchoke-request-list &optional SERVER)
9486 Return a list of all groups available on @var{server}. And that means
9489 Here's an example from a server that only carries two groups:
9492 ifi.test 0000002200 0000002000 y
9493 ifi.discussion 3324 3300 n
9496 On each line we have a group name, then the highest article number in
9497 that group, the lowest article number, and finally a flag.
9500 active-file = *active-line
9501 active-line = name " " <number> " " <number> " " flags eol
9503 flags = "n" / "y" / "m" / "x" / "j" / "=" name
9506 The flag says whether the group is read-only (@samp{n}), is moderated
9507 (@samp{m}), is dead (@samp{x}), is aliased to some other group
9508 (@samp{=other-group} or none of the above (@samp{y}).
9511 @item (nnchoke-request-post &optional SERVER)
9513 This function should post the current buffer. It might return whether
9514 the posting was successful or not, but that's not required. If, for
9515 instance, the posting is done asynchronously, it has generally not been
9516 completed by the time this function concludes. In that case, this
9517 function should set up some kind of sentinel to beep the user loud and
9518 clear if the posting could not be completed.
9520 There should be no result data from this function.
9523 @item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
9525 This function should return a buffer suitable for composing an article
9526 to be posted by @code{nnchoke-request-post}. If @var{post} is
9527 non-@code{nil}, this is not a followup, but a totally new article.
9528 @var{group} is the name of the group to be posted to. @var{subject} is
9529 the subject of the message. @var{article-buffer} is the buffer being
9530 followed up, if that is the case. @var{info} is the group info.
9531 @var{follow-to} is the group that one is supposed to re-direct the
9532 article ot. If @var{respect-poster} is non-@code{nil}, the special
9533 @samp{"poster"} value of a @code{Followup-To} header is to be respected.
9535 There should be no result data returned.
9539 @node Optional Backend Functions
9540 @subsubsection Optional Backend Functions
9544 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
9546 @var{groups} is a list of groups, and this function should request data
9547 on all those groups. How it does it is of no concern to Gnus, but it
9548 should attempt to do this in a speedy fashion.
9550 The return value of this function can be either @code{active} or
9551 @code{group}, which says what the format of the result data is. The
9552 former is in the same format as the data from
9553 @code{nnchoke-request-list}, while the latter is a buffer full of lines
9554 in the same format as @code{nnchoke-request-group} gives.
9557 group-buffer = *active-line / *group-status
9561 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
9563 A Gnus group info (@pxref{Group Info}) is handed to the backend for
9564 alterations. This comes in handy if the backend really carries all the
9565 information (as is the case with virtual an imap groups). This function
9566 may alter the info in any manner it sees fit, and should return the
9567 (altered) group info. This function may alter the group info
9568 destructively, so no copying is needed before boogying.
9570 There should be no result data from this function.
9573 @item (nnchoke-request-scan &optional GROUP SERVER)
9575 This function may be called at any time (by Gnus or anything else) to
9576 request that the backend check for incoming articles, in one way or
9577 another. A mail backend will typically read the spool file or query the
9578 POP server when this function is invoked. The @var{group} doesn't have
9579 to be heeded---if the backend decides that it is too much work just
9580 scanning for a single group, it may do a total scan of all groups. It
9581 would be nice, however, to keep things local if that's practical.
9583 There should be no result data from this function.
9586 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
9588 This is a request to fetch articles asynchronously later.
9589 @var{articles} is an alist of @var{(article-number line-number)}. One
9590 would generally expect that if one later fetches article number 4, for
9591 instance, some sort of asynchronous fetching of the articles after 4
9592 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
9593 alist) would be fetched asynchronouly, but that is left up to the
9594 backend. Gnus doesn't care.
9596 There should be no result data from this function.
9599 @item (nnchoke-request-group-description GROUP &optional SERVER)
9601 The result data from this function should be a description of
9605 description-line = name <TAB> description eol
9607 description = <text>
9610 @item (nnchoke-request-list-newsgroups &optional SERVER)
9612 The result data from this function should be the description of all
9613 groups available on the server.
9616 description-buffer = *description-line
9620 @item (nnchoke-request-newgroups DATE &optional SERVER)
9622 The result data from this function should be all groups that were
9623 created after @samp{date}, which is in normal human-readable date
9624 format. The data should be in the active buffer format.
9627 @item (nnchoke-request-create-groups GROUP &optional SERVER)
9629 This function should create an empty group with name @var{group}.
9631 There should be no return data.
9634 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
9636 This function should run the expiry process on all articles in the
9637 @var{articles} range (which is currently a simple list of article
9638 numbers.) It is left up to the backend to decide how old articles
9639 should be before they are removed by this function. If @var{force} is
9640 non-@code{nil}, all @var{articles} should be deleted, no matter how new
9643 This function should return a list of articles that it did not/was not
9646 There should be no result data returned.
9649 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
9652 This function should move @var{article} (which is a number) from
9653 @var{group} by calling @var{accept-form}.
9655 This function should ready the article in question for moving by
9656 removing any header lines it has added to the article, and generally
9657 should "tidy up" the article. Then it should @code{eval}
9658 @var{accept-form} in the buffer where the "tidy" article is. This will
9659 do the actual copying. If this @code{eval} returns a non-@code{nil}
9660 value, the article should be removed.
9662 If @var{last} is @code{nil}, that means that there is a high likelihood
9663 that there will be more requests issued shortly, so that allows some
9666 There should be no data returned.
9669 @item (nnchoke-request-accept-article GROUP &optional LAST)
9671 This function takes the current buffer and inserts it into @var{group}.
9672 If @var{last} in @code{nil}, that means that there will be more calls to
9673 this function in short order.
9675 There should be no data returned.
9678 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
9680 This function should remove @var{article} (which is a number) from
9681 @var{group} and insert @var{buffer} there instead.
9683 There should be no data returned.
9686 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
9688 This function should delete @var{group}. If @var{force}, it should
9689 really delete all the articles in the group, and then delete the group
9690 itself. (If there is such a thing as "the group itself".)
9692 There should be no data returned.
9695 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
9697 This function should rename @var{group} into @var{new-name}. All
9698 articles that are in @var{group} should move to @var{new-name}.
9700 There should be no data returned.
9706 @node Score File Syntax
9707 @subsection Score File Syntax
9709 Score files are meant to be easily parsable, but yet extremely
9710 mallable. It was decided that something that had the same read syntax
9711 as an Emacs Lisp list would fit that spec.
9713 Here's a typical score file:
9717 ("win95" -10000 nil s)
9724 BNF definition of a score file:
9727 score-file = "" / "(" *element ")"
9728 element = rule / atom
9729 rule = string-rule / number-rule / date-rule
9730 string-rule = "(" quote string-header quote space *string-match ")"
9731 number-rule = "(" quote number-header quote space *number-match ")"
9732 date-rule = "(" quote date-header quote space *date-match ")"
9734 string-header = "subject" / "from" / "references" / "message-id" /
9735 "xref" / "body" / "head" / "all" / "followup"
9736 number-header = "lines" / "chars"
9737 date-header = "date"
9738 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
9739 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
9740 score = "nil" / <integer>
9741 date = "nil" / <natural number>
9742 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
9743 "r" / "regex" / "R" / "Regex" /
9744 "e" / "exact" / "E" / "Exact" /
9745 "f" / "fuzzy" / "F" / "Fuzzy"
9746 number-match = "(" <integer> [ "" / [ space score [ "" /
9747 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
9748 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
9749 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
9750 space date [ "" / [ space date-match-t ] ] ] ] ")"
9751 date-match-t = "nil" / "at" / "before" / "after"
9752 atom = "(" [ required-atom / optional-atom ] ")"
9753 required-atom = mark / expunge / mark-and-expunge / files /
9754 exclude-files / read-only / touched
9755 optional-atom = adapt / local / eval
9756 mark = "mark" space nil-or-number
9757 nil-or-number = "nil" / <integer>
9758 expunge = "expunge" space nil-or-number
9759 mark-and-expunge = "mark-and-expunge" space nil-or-number
9760 files = "files" *[ space <string> ]
9761 exclude-files = "exclude-files" *[ space <string> ]
9762 read-only = "read-only" [ space "nil" / space "t" ]
9763 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
9764 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
9765 local = "local" *[ space "(" <string> space <form> ")" ]
9766 eval = "eval" space <form>
9767 space = *[ " " / <TAB> / <NEWLINE> ]
9770 Any unrecognized elements in a score file should be ignored, but not
9773 As you can see, white space is needed, but the type and amount of white
9774 space is irrelevant. This means that formatting of the score file is
9775 left up to the programmer---if it's simpler to just spew it all out on
9776 one looong line, then that's ok.
9778 The meaning of the various atoms are explained elsewhere in this
9784 Gnus uses internally a format for storing article headers that
9785 corresponds to the @sc{nov} format in a mysterious fashion. One could
9786 almost suspect that the author looked at the @sc{nov} specification and
9787 just shamelessly @emph{stole} the entire thing, and one would be right.
9789 @dfn{Header} is a severly overloaded term. "Header" is used in RFC1036
9790 to talk about lines in the head of an article (eg., @code{From}). It is
9791 used by many people as a synonym for "head"---"the header and the
9792 body". (That should be avoided, in my opinion.) And Gnus uses a format
9793 interanally that it calls "header", which is what I'm talking about
9794 here. This is a 9-element vector, basically, with each header (ouch)
9797 These slots are, in order: @code{number}, @code{subject}, @code{from},
9798 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
9799 @code{xref}. There are macros for accessing and setting these slots --
9800 they all have predicatable names beginning with @code{mail-header-} and
9801 @code{mail-header-set-}, respectively.
9803 The @code{xref} slot is really a @code{misc} slot. Any extra info will
9809 @sc{gnus} introduced a concept that I found so useful that I've started
9810 using it a lot and have elaborated on it greatly.
9812 The question is simple: If you have a large amount of objects that are
9813 identified by numbers (say, articles, to take a @emph{wild} example)
9814 that you want to callify as being "included", a normal sequence isn't
9815 very useful. (A 200,000 length sequence is a bit long-winded.)
9817 The solution is as simple as the question: You just collapse the
9821 (1 2 3 4 5 6 10 11 12)
9830 To avoid having those nasty @samp{(13 . 13)} elements to denote a
9831 lonesome object, a @samp{13} is a valid element:
9834 ((1 . 6) 7 (10 . 12))
9837 This means that comparing two ranges to find out whether they are equal
9841 ((1 . 6) 7 8 (10 . 12))
9847 ((1 . 5) (7 . 8) (10 . 12))
9850 are equal. In fact, any non-descending list is a range:
9856 is a perfectly valid range, although a pretty longwinded one. This is
9863 and is equal to the previous range.
9865 Here's a BNF definition of ranges. Of course, one must remember the
9866 semantic requirement that the numbers are non-descending. (Any number
9867 of repetition of the same number is allowed, but apt to disappear in
9871 range = simple-range / normal-range
9872 simple-range = "(" number " . " number ")"
9873 normal-range = "(" start-contents ")"
9874 contents = "" / simple-range *[ " " contents ] /
9875 number *[ " " contents ]
9878 Gnus currently uses ranges to keep track of read articles and article
9879 marks. I plan on implementing a number of range operators in C if The
9880 Powers That Be are willing to let me. (I haven't asked yet, because I
9881 need to do some more thinking on what operators I need to make life
9882 totally range-based without ever having to convert back to normal
9887 @subsection Group Info
9889 Gnus stores all permanent info on groups in a @dfn{group info} list.
9890 This list is from three to six elements (or more) long and exhaustively
9891 describes the group.
9893 Here are two example group infos; one is a very simple group while the
9894 second is a more complex one:
9897 ("no.group" 5 (1 . 54324))
9899 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
9900 ((tick (15 . 19)) (replied 3 6 (19 . 3)))
9902 (auto-expire (to-address "ding@@ifi.uio.no")))
9905 The first element is the group name as Gnus knows the group; the second
9906 is the group level; the third is the read articles in range format; the
9907 fourth is a list of article marks lists; the fifth is the select method;
9908 and the sixth contains the group parameters.
9910 Here's a BNF definition of the group info format:
9913 info = "(" group space level space read
9914 [ "" / [ space marks-list [ "" / [ space method [ "" /
9915 space parameters ] ] ] ] ] ")"
9916 group = quote <string> quote
9917 level = <integer in the range of 1 to inf>
9919 marks-lists = nil / "(" *marks ")"
9920 marks = "(" <string> range ")"
9921 method = "(" <string> *elisp-forms ")"
9922 parameters = "(" *elisp-forms ")"
9925 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
9926 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
9930 @node Various File Formats
9931 @subsection Various File Formats
9934 * Active File Format:: Information on articles and groups available.
9935 * Newsgroups File Format:: Group descriptions.
9939 @node Active File Format
9940 @subsubsection Active File Format
9942 The active file lists all groups that are available on the server in
9943 question. It also lists the highest and lowest current article numbers
9946 Here's an exceprt from a typical active file:
9949 soc.motss 296030 293865 y
9950 alt.binaries.pictures.fractals 3922 3913 n
9951 comp.sources.unix 1605 1593 m
9952 comp.binaries.ibm.pc 5097 5089 y
9953 no.general 1000 900 y
9956 Here's a pseudo-BNF definition of this file:
9959 active = *group-line
9960 group-line = group space high-number space low-number space flag <NEWLINE>
9961 group = <non-white-space string>
9963 high-number = <non-negative integer>
9964 low-number = <positive integer>
9965 flag = "y" / "n" / "m" / "j" / "x" / "=" group
9969 @node Newsgroups File Format
9970 @subsubsection Newsgroups File Format
9972 The newsgroups file lists groups along with their descriptions. Not all
9973 groups on the server have to be listed, and not all groups in the file
9974 have to exist on the server. The file is meant purely as information to
9977 The format is quite simple; a group name, a tab, and the description.
9978 Here's the definition:
9982 line = group tab description <NEWLINE>
9983 group = <non-white-space string>
9985 description = <string>
9989 @node Emacs for Heathens
9990 @section Emacs for Heathens
9992 Believe it or not, but some people who use Gnus haven't really used
9993 Emacs much before they embarked on their journey on the Gnus Love Boat.
9994 If you are one of those unfortunates whom "@kbd{M-C-a}", "kill the
9995 region", and "set @code{gnus-flargblossen} to an alist where the key is
9996 a regexp that is used for matching on the group name" are magical
9997 phrases with little or no meaning, then this appendix is for you. If
9998 you are already familiar with Emacs, just ignore this and go fondle your
10002 * Keystrokes:: Entering text and executing commands.
10003 * Emacs Lisp:: The built-in Emacs programming language.
10008 @subsection Keystrokes
10012 Q: What is an experienced Emacs user?
10014 A: A person who wishes that the terminal had pedals.
10017 Yes, when you use Emacs, you are apt to use the control key, the shift
10018 key and the meta key a lot. This is very annoying to some people
10019 (notably @code{vi}le users), and the rest of us just love the hell out
10020 of it. Just give up and submit. Emacs really does stand for
10021 "Escape-Meta-Alt-Control-Shift", and not "Editin Macros", as you may
10022 have heard from other disreputable sources (like the Emacs author).
10024 The shift key is normally located near your pinky fingers, and are
10025 normally used to get capital letters and stuff. You probably use it all
10026 the time. The control key is normally marked "CTRL" or something like
10027 that. The meta key is, funnily enough, never marked as such on any
10028 keyboards. The one I'm curretly at has a key that's marked "Alt", which
10029 is the meta key on this keyboard. It's usually located somewhere to the
10030 left hand side of the keyboard, usually on the bottom row.
10032 Now, us Emacs people doesn't say "press the meta-control-m key", because
10033 that's just too inconvenient. We say "press the @kbd{M-C-m} key".
10034 @kbd{M-} is the prefix that means "meta" and "C-" is the prefix that
10035 means "control". So "press @kbd{C-k}" means "press down the control
10036 key, and hold it down while you press @kbd{k}". "Press @kbd{M-C-k}"
10037 means "press down and hold down the meta key and the control key and
10038 then press @kbd{k}". Simple, ay?
10040 This is somewhat complicated by the fact that not all keyboards have a
10041 meta key. In that case you can use the "escape" key. Then @kbd{M-k}
10042 means "press escape, release escape, press @kbd{k}". That's much more
10043 work than if you have a meta key, so if that's the case, I respectfully
10044 suggest you get a real keyboard with a meta key. You can't live without
10050 @subsection Emacs Lisp
10052 Emacs is the King of Editors because it's really a Lisp interpreter.
10053 Each and every key you tap runs some Emacs Lisp code snippet, and since
10054 Emacs Lisp is an interpreted language, that means that you can configure
10055 any key to run any random code. You just, like, do it.
10057 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
10058 functions. (These are byte-compiled for speed, but it's still
10059 interpreted.) If you decide that you don't like the way Gnus does
10060 certain things, it's trivial to have it do something a different way.
10061 (Well, at least if you know how to write Lisp code.) However, that's
10062 beyond the scope of this manual, so we are simply going to talk about
10063 some common constructs that you normally use in your @file{.emacs} file
10066 If you want to set the variable @code{gnus-florgbnize} to four (4), you
10067 write the following:
10070 (setq gnus-florgbnize 4)
10073 This function (really "special form") @code{setq} is the one that can
10074 set a variable to some value. This is really all you need to know. Now
10075 you can go and fill your @code{.emacs} file with lots of these to change
10078 If you have put that thing in your @code{.emacs} file, it will be read
10079 and @code{eval}ed (which is lispese for "run") the next time you start
10080 Emacs. If you want to change the variable right away, simply say
10081 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
10082 previous "form", which here is a simple @code{setq} statement.
10084 Go ahead---just try it, if you're located at your Emacs. After you
10085 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
10086 is the return value of the form you @code{eval}ed.
10090 If the manual says "set @code{gnus-read-active-file} to @code{some}",
10094 (setq gnus-read-active-file 'some)
10097 On the other hand, if the manual says "set @code{gnus-nntp-server} to
10098 @samp{"nntp.ifi.uio.no"}", that means:
10101 (setq gnus-nntp-server "nntp.ifi.uio.no")
10104 So be careful not to mix up strings (the latter) with symbols (the
10105 former). The manual is unambiguous, but it can be confusing.
10108 @include gnus-faq.texi
10123 @c Local Variables:
10124 @c outline-regexp: "@chap\\|@\\(sub\\)*section\\|@appendix \\|@appendix\\(sub\\)*sec\\|\^L"