1 \input texinfo @c -*-texinfo-*-
4 @settitle September Gnus Manual
11 @setchapternewpage odd
15 \documentclass[twoside,a4paper,openright]{book}
16 \usepackage[latin1]{inputenc}
17 % \usepackage{fontenc}
19 \usepackage{pagestyle}
21 \fontfamily{bembo}\selectfont
26 \newcommand{\gnuschaptername}{}
27 \newcommand{\gnussectionname}{}
29 \newcommand{\gnusbackslash}{/}
31 \newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}}
32 \newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}}
34 \newcommand{\gnuskindex}[1]{\index{#1}}
35 \newcommand{\gnusindex}[1]{\index{#1}}
37 \newcommand{\gnustt}[1]{{\textbf{\textsf{#1}}}}
38 \newcommand{\gnuscode}[1]{\gnustt{#1}}
39 \newcommand{\gnussamp}[1]{`\gnustt{#1}'}
40 \newcommand{\gnuslisp}[1]{\gnustt{#1}}
41 \newcommand{\gnuskbd}[1]{`\gnustt{#1}'}
42 \newcommand{\gnusfile}[1]{`\gnustt{#1}'}
43 \newcommand{\gnusdfn}[1]{\textit{#1}}
44 \newcommand{\gnusi}[1]{\textit{#1}}
45 \newcommand{\gnusstrong}[1]{\textbf{#1}}
46 \newcommand{\gnusemph}[1]{\textit{#1}}
47 \newcommand{\gnusvar}[1]{\textsl{\textsf{#1}}}
48 \newcommand{\gnussc}[1]{\textsc{#1}}
49 \newcommand{\gnustitle}[1]{{\huge\textbf{#1}}}
50 \newcommand{\gnusauthor}[1]{{\large\textbf{#1}}}
52 \newcommand{\gnusbullet}{{${\bullet}$}}
53 \newcommand{\gnusdollar}{\$}
54 \newcommand{\gnusampersand}{\&}
55 \newcommand{\gnuspercent}{\%}
56 \newcommand{\gnushash}{\#}
57 \newcommand{\gnushat}{\symbol{"5E}}
58 \newcommand{\gnustilde}{\symbol{"7E}}
59 \newcommand{\gnusless}{{$<$}}
60 \newcommand{\gnusgreater}{{$>$}}
62 \newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=gnus-head.eps,height=1cm}}}
63 \newcommand{\gnusinteresting}{
64 \marginpar[\hspace{2.5cm}\gnushead]{\gnushead}
67 \newcommand{\gnuschapter}[1]{
68 \renewcommand{\gnussectionname}{}
70 \renewcommand{\gnuschaptername}{#1}
72 % \epsfig{figure=gnus-herd-\arabic{chapter}.eps,height=15cm}
76 \newcommand{\gnusitemx}[1]{{\itemsep=0pt\item#1}}
78 \newcommand{\gnussection}[1]{
79 \renewcommand{\gnussectionname}{#1}
83 \newenvironment{codelist}%
88 \newenvironment{kbdlist}%
94 \newenvironment{dfnlist}%
99 \newenvironment{stronglist}%
104 \newenvironment{samplist}%
109 \newenvironment{varlist}%
114 \newenvironment{emphlist}%
126 \makebox[\headtextwidth]{
128 \textbf{\arabic{chapter}.\arabic{section}}
129 \textbf{\gnussectionname\hfill\arabic{page}}
137 \makebox[\headtextwidth]{
138 \textbf{\arabic{page}\hfill\gnuschaptername}
147 \raisebox{-0.5cm}{\epsfig{figure=gnus-big-logo.eps,height=1cm}}
149 \raisebox{-0.5cm}{\epsfig{figure=gnus-big-logo.eps,height=1cm}}
163 %\addtolength{\oddsidemargin}{-5cm}
164 %\addtolength{\evensidemargin}{-5cm}
166 \addtolength{\textheight}{2cm}
168 \gnustitle{\gnustitlename}\\
171 \hspace*{-1cm}\epsfig{figure=gnus-big-logo.eps,height=15cm}
174 \gnusauthor{by Lars Magne Ingebrigtsen}
181 \thispagestyle{empty}
183 Copyright \copyright{} 1995 Free Software Foundation, Inc.
185 Permission is granted to make and distribute verbatim copies of
186 this manual provided the copyright notice and this permission notice
187 are preserved on all copies.
189 Permission is granted to copy and distribute modified versions of this
190 manual under the conditions for verbatim copying, provided that the
191 entire resulting derived work is distributed under the terms of a
192 permission notice identical to this one.
194 Permission is granted to copy and distribute translations of this manual
195 into another language, under the above conditions for modified versions.
204 This file documents Gnus, the GNU Emacs newsreader.
206 Copyright (C) 1995 Free Software Foundation, Inc.
208 Permission is granted to make and distribute verbatim copies of
209 this manual provided the copyright notice and this permission notice
210 are preserved on all copies.
213 Permission is granted to process this file through Tex and print the
214 results, provided the printed document carries copying permission
215 notice identical to this one except for the removal of this paragraph
216 (this paragraph not being relevant to the printed manual).
219 Permission is granted to copy and distribute modified versions of this
220 manual under the conditions for verbatim copying, provided also that the
221 entire resulting derived work is distributed under the terms of a
222 permission notice identical to this one.
224 Permission is granted to copy and distribute translations of this manual
225 into another language, under the above conditions for modified versions.
231 @title September Gnus Manual
233 @author by Lars Magne Ingebrigtsen
236 @vskip 0pt plus 1filll
237 Copyright @copyright{} 1995 Free Software Foundation, Inc.
239 Permission is granted to make and distribute verbatim copies of
240 this manual provided the copyright notice and this permission notice
241 are preserved on all copies.
243 Permission is granted to copy and distribute modified versions of this
244 manual under the conditions for verbatim copying, provided that the
245 entire resulting derived work is distributed under the terms of a
246 permission notice identical to this one.
248 Permission is granted to copy and distribute translations of this manual
249 into another language, under the above conditions for modified versions.
258 @top The Gnus Newsreader
262 You can read news (and mail) from within Emacs by using Gnus. The news
263 can be gotten by any nefarious means you can think of---@sc{nntp}, local
264 spool or your mbox file. All at the same time, if you want to push your
272 \thispagestyle{empty}
275 Gnus is the advanced, self-documenting, customizable, extensible
276 unreal-time newsreader for GNU Emacs.
278 Oops. That sounds oddly familiar, so let's start over again to avoid
279 being accused of plagiarism:
281 Gnus is a message-reading laboratory. It will let you look at just
282 about anything as if it were a newsgroup. You can read mail with it,
283 you can browse directories with it, you can @code{ftp} with it---you can
284 even read news with it, if you feel like it.
286 Gnus tries to empower people who read news the same way Emacs empowers
287 people who edit text. Gnus sets no limits to what the user should be
288 allowed to do. Users are encouraged to extend Gnus to behave like they
289 want it to behave. A program should not control people; people should
290 be empowered to do what they want by using (or abusing) the program.
296 * History:: How Gnus got where it is today.
297 * Terminology:: We use really difficult, like, words here.
298 * Starting Up:: Finding news can be a pain.
299 * The Group Buffer:: Selecting, subscribing and killing groups.
300 * The Summary Buffer:: Reading, saving and posting articles.
301 * The Article Buffer:: Displaying and handling articles.
302 * The Server Buffer:: Making and editing virtual servers.
303 * Scoring:: Assigning values to articles.
304 * Various:: General purpose settings.
305 * Customization:: Tailoring Gnus to your needs.
306 * Troubleshooting:: What you might try if things do not work.
307 * The End:: Farewell and goodbye.
308 * Appendices:: Technical stuff, Emacs intro, FAQ
309 * Index:: Variable, function and concept index.
310 * Key Index:: Key Index.
318 @sc{gnus} was written by Masanobu UMEDA. When autumn crept up in '94,
319 Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
321 If you want to investigate the person responsible for this outrage, you
322 can point your (feh!) web browser to
323 @file{http://www.ifi.uio.no/~larsi/}. This is also the primary
324 distribution point for the new and spiffy versions of Gnus, also know as
325 The Site That Destroys Newsrcs And Drives People Mad.
327 During the first extended alpha period of development, the new Gnus was
328 called ``(ding) Gnus''. @dfn{(ding)}, is, of course, short for @dfn{ding
329 is not Gnus}, which is a total and utter lie, but who cares? (Besides,
330 the ``Gnus'' in this abbreviation should probably be pronounced ``news'' as
331 UMEDA intended, which makes it a more appropriate name, don't you
334 In any case, after spending all that energy with coming up with a new
335 and spiffy name, we decided that the name was @emph{too} spiffy, so we
336 renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs.
337 ``@sc{gnus}''. New vs. old.
339 Incidentally, the next Gnus generation will be called ``September Gnus'',
340 and won't be released until February. Confused? You will be.
343 * Why?:: What's the point of Gnus?
344 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
345 * Conformity:: Gnus tries to conform to all standards.
346 * Emacsen:: Gnus can be run on a few modern Emacsen.
347 * Contributors:: Oodles of people.
348 * New Features:: Pointers to some of the new stuff in Gnus.
349 * Newest Features:: Features so new that they haven't been written yet.
350 * Censorship:: This manual has been censored.
357 What's the point of Gnus?
359 I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep''
360 newsreader, that lets you do anything you can think of. That was my
361 original motivation, but while working on Gnus, it has become clear to
362 me that this generation of newsreaders really belong in the stone age.
363 Newsreaders haven't developed much since the infancy of the net. If the
364 volume continues to rise with the current rate of increase, all current
365 newsreaders will be pretty much useless. How do you deal with
366 newsgroups that have hundreds (or thousands) of new articles each day?
368 Gnus offers no real solutions to these questions, but I would very much
369 like to see Gnus being used as a testing ground for new methods of
370 reading and fetching news. Expanding on Umeda-san's wise decision to
371 separate the newsreader from the backends, Gnus now offers a simple
372 interface for anybody who wants to write new backends for fetching mail
373 and news from different sources. I have added hooks for customizations
374 everywhere I can imagine useful. By doing so, I'm inviting every one of
375 you to explore and invent new ways of reading news.
377 May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
381 @section Compatibility
383 @cindex compatibility
384 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
385 bindings have been kept. More key bindings have been added, of course,
386 but only in one or two obscure cases have old bindings been changed.
391 @center In a cloud bones of steel.
395 All commands have kept their names. Some internal functions have changed
398 The @code{gnus-uu} package has changed drastically. @xref{Decoding
401 One major compatibility question is the presence of several summary
402 buffers. All variables that are relevant while reading a group are
403 buffer-local to the summary buffer they belong in. Although most
404 important variables have their values copied into their global
405 counterparts whenever a command is executed in the summary buffer, this
406 change might lead to incorrect values being used unless you are careful.
408 All code that relies on knowledge of @sc{gnus} internals will probably
409 fail. To take two examples: Sorting @code{gnus-newsrc-assoc} (or
410 changing it in any way, as a matter of fact) is strictly verboten. Gnus
411 maintains a hash table that points to the entries in this assoc (which
412 speeds up many functions), and changing the assoc directly will lead to
417 Old hilit19 code does not work at all. In fact, you should probably
418 remove all hilit code from all Gnus hooks
419 (@code{gnus-group-prepare-hook}, @code{gnus-summary-prepare-hook} and
420 @code{gnus-summary-article-hook}). (Well, at the very least the first
421 two.) Gnus provides various integrated functions for highlighting.
422 These are faster and more accurate. To make life easier for everybody,
423 Gnus will by default remove all hilit calls from all hilit hooks.
426 Packages like @code{expire-kill} will no longer work. As a matter of
427 fact, you should probably remove all old @sc{gnus} packages (and other
428 code) when you start using Gnus. More likely than not, Gnus already
429 does what you have written code to make @sc{gnus} do. (Snicker.)
431 Even though old methods of doing things are still supported, only the
432 new methods are documented in this manual. If you detect a new method of
433 doing something while reading this manual, that does not mean you have
434 to stop doing it the old way.
436 Gnus understands all @sc{gnus} startup files.
439 Overall, a casual user who hasn't written much code that depends on
440 @sc{gnus} internals should suffer no problems. If problems occur,
441 please let me know (@kbd{M-x gnus-bug}).
447 No rebels without a clue here, ma'am. We conform to all standards known
448 to (wo)man. Except for those standards and/or conventions we disagree
454 There are no known breaches of this standard.
457 There are no known breaches of this standard, either.
459 @item Usenet Seal of Approval
460 Gnus hasn't been formally through the Seal process, but I have read
461 through the Seal text and I think Gnus would pass.
463 @item Son-of-RFC 1036
464 We do have some breaches to this one.
469 Gnus does no MIME handling, and this standard-to-be seems to think that
470 MIME is the bees' knees, so we have major breakage here.
473 This is considered to be a ``vanity header'', while I consider it to be
474 consumer information. After seeing so many badly formatted articles
475 coming from @code{tin} and @code{Netscape} I know not to use either of
476 those for posting articles. I would not have known that if it wasn't
477 for the @code{X-Newsreader} header.
480 Gnus breaks lines if this header is long. I infer from RFC1036 that
481 being conservative in what you output is not creating 5000-character
482 lines, so it seems like a good idea to me. However, this standard-to-be
483 says that whitespace in the @code{References} header is to be preserved,
484 so... It doesn't matter one way or the other to Gnus, so if somebody
485 tells me what The Way is, I'll change it. Or not.
490 If you ever see Gnus act non-compliantly to the texts mentioned above,
491 don't hesitate to drop a note to Gnus Towers and let us know.
501 Gnus should work on :
512 Mule versions based on Emacs 19.30 and up.
516 Gnus will absolutely not work on any Emacsen older than that. Not
519 There are some vague differences in what Gnus does, though:
524 The mouse-face on Gnus lines under Emacs and Mule is delimited to
525 certain parts of the lines while they cover the entire line under
529 The same with current-article marking---XEmacs puts an underline under
530 the entire summary line while Emacs and Mule are nicer and kinder.
533 XEmacs features more graphics---a logo and a toolbar.
536 Citation highlighting us better under Emacs and Mule than under XEmacs.
539 Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
546 @section Contributors
549 The new Gnus version couldn't have been done without the help of all the
550 people on the (ding) mailing list. Every day for months I have gotten
551 tens of nice bug reports from them, filling me with joy, every single
552 one of them. Smooches. The people on the list have been tried beyond
553 endurance, what with my ``oh, that's a neat idea <type type>, yup, I'll
554 release it right away <ship off> no wait, that doesn't work at all <type
555 type>, yup, I'll ship that one off right away <ship off> no, wait, that
556 absolutely does not work'' policy for releases. Micro$oft---bah.
557 Amateurs. I'm @emph{much} worse. (Or is that ``worser''? ``much worser''?
560 I would like to take this opportunity to thank the Academy for... oops,
565 Of course, GNUS was written by Masanobu UMEDA.
567 Many excellent functions, especially dealing with scoring and
568 highlighting (as well as the @sc{soup} support) was written
571 Design and graphics were done by Luis Fernandes.
573 Innumerable bug fixes were written by Sudish Joseph.
575 @code{gnus-topic} was written by Ilja Weis.
577 Lots and lots of bugs were found and fixed by Steven L. Baur.
579 The refcard was written by Vladimir Alexiev.
581 I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
583 @code{nnfolder} has been much enhanced by Scott Byer.
585 The orphan scoring was written by Peter Mutsaers.
587 GNU XEmacs support has been added by Fabrice Popineau.
589 POP mail support was written by Ken Raeburn.
591 Various bits and pieces, especially dealing with .newsrc files, were
592 suggested and added by Hallvard B Furuseth.
594 Brian Edmonds has written @code{gnus-bbdb}.
596 Ricardo Nassif and Mark Borges did the proff-reading (sic).
598 Kevin Davidson came up with the name @dfn{ding}, so blame him.
600 Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
601 Quinlan, Frank D. Cringle, Geoffrey T. Dairiki, and Andrew Eskilsson have
602 all contributed code and suggestions.
607 @section New Features
613 The look of all buffers can be changed by setting format-like variables
614 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
617 Local spool and several @sc{nntp} servers can be used at once
618 (@pxref{Foreign Groups}).
621 You can combine groups into virtual groups (@pxref{nnvirtual}).
624 You can read a number of different mail formats (@pxref{Reading Mail}).
625 All the mail backends implement a convenient mail expiry scheme
626 (@pxref{Expiring Old Mail Articles}).
629 Gnus can use various strategies for gathering threads that have lost
630 their roots (thereby gathering loose sub-threads into one thread) or it
631 can go back and retrieve enough headers to build a complete thread
632 (@pxref{Customizing Threading}).
635 Killed groups can be displayed in the group buffer, and you can read
639 Gnus can do partial group updates---you do not have to retrieve the
640 entire active file just to check for new articles in a few groups
641 (@pxref{The Active File}).
644 Gnus implements a sliding scale of subscribedness to groups
645 (@pxref{Group Levels}).
648 You can score articles according to any number of criteria
649 (@pxref{Scoring}). You can even get Gnus to find out how to score
650 articles for you (@pxref{Adaptive Scoring}).
653 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
654 manner, so it should be difficult to lose much data on what you have
655 read if your machine should go down (@pxref{Auto Save}).
658 Gnus now has its own startup file to avoid cluttering up the
662 You can set the process mark on both groups and articles and perform
663 operations on all the marked items (@pxref{Process/Prefix}).
666 You can grep through a subset of groups and create a group from the
667 results (@pxref{nnkiboze}).
670 You can list subsets of groups according to, well, anything
671 (@pxref{Listing Groups}).
674 You can browse foreign servers and subscribe to groups from those
675 servers (@pxref{Browse Foreign Server}).
678 Gnus can fetch articles asynchronously on a second connection to the
679 server (@pxref{Asynchronous Fetching}).
682 You can cache articles locally (@pxref{Article Caching}).
685 The uudecode functions have been expanded and generalized
686 (@pxref{Decoding Articles}).
689 You can still post uuencoded articles, which was a little-known feature
693 Fetching parents (and other articles) now actually works without
694 glitches (@pxref{Finding the Parent}).
697 Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
700 Digests (and other files) can be used as the basis for groups
704 Articles can be highlighted and customized (@pxref{Customizing
708 URLs and other external references can be buttonized (@pxref{Article
712 All Gnus buffers can be customized in a difficult fashion
713 (@pxref{Windows Configuration}).
716 You can click on buttons instead of using the keyboard
720 Gnus can use NoCeM files to weed out spam (@pxref{NoCeM}).
724 This is, of course, just a @emph{short} overview of the @emph{most}
725 important new features. No, really. There are tons more. Yes, we have
726 feeping creaturism in full effect, but nothing too gratuitous, I would
730 @node Newest Features
731 @section Newest Features
734 Also known as the @dfn{todo list}. Sure to be implemented before the
737 Be afraid. Be very afraid.
741 Native @sc{mime} support is something that should be done.
743 A better and simpler method for specifying mail composing methods.
745 Allow posting through mail-to-news gateways.
747 Really do unbinhexing.
750 And much, much, much more. There is more to come than has already been
751 implemented. (But that's always true, isn't it?)
753 @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
754 up-to-the-second todo list is located, so if you're really curious, you
755 could point your Web browser over that-a-way.
762 This version of the Gnus manual (as well as Gnus itself) has been
763 censored in accord with the Communications Decency Act. This law was
764 described by its proponents as a ban on pornography---which was a
765 deception, since it prohibits far more than that. This manual did not
766 contain pornography, but part of it was prohibited nonetheless.
768 For information on US government censorship of the Internet, and
769 what you can do to bring back freedom of the press, see the web
770 site @samp{http://www.vtw.org/}.
781 This is what you are supposed to use this thing for---reading news.
782 News is generally fetched from a nearby @sc{nntp} server, and is
783 generally publicly available to everybody. If you post news, the entire
784 world is likely to read just what you have written, and they'll all
785 snigger mischievously. Behind your back.
789 Everything that's delivered to you personally is mail. Some news/mail
790 readers (like Gnus) blur the distinction between mail and news, but
791 there is a difference. Mail is private. News is public. Mailing is
792 not posting, and replying is not following up.
795 Send a mail to the person who has written what you are reading.
798 Post an article to the current newsgroup responding to the article you
802 Gnus gets fed articles from a number of backends, both news and mail
803 backends. Gnus does not handle the underlying media, so to speak---this
804 is all done by the backends.
807 Gnus will always use one method (and backend) as the @dfn{native}, or
808 default, way of getting news.
811 You can also have any number of foreign groups at the same time. These
812 are groups that use different backends for getting news.
816 The top part of an article, where administration information (etc.) is
821 The rest of an article. Everything that is not in the head is in the
826 A line from the head of an article.
830 A collection of such lines, or a collection of heads. Or even a
831 collection of @sc{nov} lines.
835 When Gnus enters a group, it asks the backend for the headers for all
836 the unread articles in the group. Most servers support the News OverView
837 format, which is much smaller and much faster to read than the normal
842 Each group is subscribed at some @dfn{level} or other (1-9). The ones
843 that have a lower level are ``more'' subscribed than the groups with a
844 higher level. In fact, groups on levels 1-5 are considered
845 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
846 are @dfn{killed}. Commands for listing groups and scanning for new
847 articles will all use the numeric prefix as @dfn{working level}.
850 @cindex killed groups
851 No information on killed groups is stored or updated, which makes killed
852 groups much easier to handle than subscribed groups.
855 @cindex zombie groups
856 Just like killed groups, only slightly less dead.
860 The news server has to keep track of what articles it carries, and what
861 groups exist. All this information in stored in the active file, which
862 is rather large, as you might surmise.
866 A group that exists in the @file{.newsrc} file, but isn't known to the
867 server (i. e., it isn't in the active file), is a @emph{bogus group}.
868 This means that the group probably doesn't exist (any more).
873 @chapter Starting Gnus
878 If your system administrator has set things up properly, starting Gnus
879 and reading news is extremely easy---you just type @kbd{M-x gnus}.
881 @findex gnus-other-frame
882 @kindex M-x gnus-other-frame
883 If you want to start Gnus in a different frame, you can use the command
884 @kbd{M-x gnus-other-frame} instead.
886 If things do not go smoothly at startup, you have to twiddle some
890 * Finding the News:: Choosing a method for getting news.
891 * The First Time:: What does Gnus do the first time you start it?
892 * The Server is Down:: How can I read my mail then?
893 * Slave Gnusii:: You can have more than one Gnus active at a time.
894 * Fetching a Group:: Starting Gnus just to read a group.
895 * New Groups:: What is Gnus supposed to do with new groups?
896 * Startup Files:: Those pesky startup files---@file{.newsrc}.
897 * Auto Save:: Recovering from a crash.
898 * The Active File:: Reading the active file over a slow line Takes Time.
899 * Startup Variables:: Other variables you might change.
902 @node Finding the News
903 @section Finding the News
905 @vindex gnus-select-method
907 The @code{gnus-select-method} variable controls how Gnus finds news.
908 This variable should be a list where the first element says @dfn{how}
909 and the second element says @dfn{where}. This method is your native
910 method. All groups that are not fetched with this method are foreign
913 For instance, if you want to get your daily dosage of news from the
914 @samp{news.somewhere.edu} @sc{nntp} server, you'd say:
917 (setq gnus-select-method '(nntp "news.somewhere.edu"))
920 If you want to read directly from the local spool, say:
923 (setq gnus-select-method '(nnspool ""))
926 If you can use a local spool, you probably should, as it will almost
927 certainly be much faster.
929 @vindex gnus-nntpserver-file
931 @cindex @sc{nntp} server
932 If this variable is not set, Gnus will take a look at the
933 @code{NNTPSERVER} environment variable. If that variable isn't set,
934 Gnus will see whether @code{gnus-nntpserver-file} (default
935 @file{/etc/nntpserver}) has any opinions in the matter. It that fails
936 as well, Gnus will will try to use the machine that is running Emacs as
937 an @sc{nntp} server. That's a long-shot, though.
939 @vindex gnus-nntp-server
940 If @code{gnus-nntp-server} is set, this variable will override
941 @code{gnus-select-method}. You should therefore set
942 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
944 @vindex gnus-secondary-servers
945 You can also make Gnus prompt you interactively for the name of an
946 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
947 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
948 in the @code{gnus-secondary-servers} list (if any). You can also just
949 type in the name of any server you feel like visiting.
951 However, if you use one @sc{nntp} server regularly, and are just
952 interested in a couple of groups from a different server, you would be
953 better served by using the @code{gnus-group-browse-foreign-server}
954 command from the group buffer. It will let you have a look at what
955 groups are available, and you can subscribe to any of the groups you
956 want to. This also makes @file{.newsrc} maintenance much tidier.
957 @xref{Foreign Groups}.
959 @vindex gnus-secondary-select-methods
961 A slightly different approach to foreign groups is to set the
962 @code{gnus-secondary-select-methods} variable. The select methods
963 listed in this variable are in many ways just as native as the
964 @code{gnus-select-method} server. They will also be queried for active
965 files during startup (if that's required), and new newsgroups that
966 appear on these servers will be subscribed (or not) just as native
969 For instance, if you use the @code{nnmbox} backend to read you mail, you
970 would typically set this variable to
973 (setq gnus-secondary-select-methods '((nnmbox "")))
977 @section The First Time
978 @cindex first time usage
980 If no startup files exist, Gnus will try to determine what groups should
981 be subscribed by default.
983 @vindex gnus-default-subscribed-newsgroups
984 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
985 will subscribe you to just those groups in that list, leaving the rest
986 killed. Your system administrator should have set this variable to
989 Since she hasn't, Gnus will just subscribe you to a few randomly picked
990 groups (i.e., @samp{*.newusers}). (@dfn{Random} is here defined as
991 ``whatever Lars thinks you should read''.)
993 You'll also be subscribed to the Gnus documentation group, which should
994 help you with most common problems.
996 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
997 use the normal functions for handling new groups, and not do anything
1000 @node The Server is Down
1001 @section The Server is Down
1002 @cindex server errors
1004 If the default server is down, Gnus will understandably have some
1005 problems starting. However, if you have some mail groups in addition to
1006 the news groups, you may want to start Gnus anyway.
1008 Gnus, being the trusting sort of program, will ask whether to proceed
1009 without a native select method if that server can't be contacted. This
1010 will happen whether the server doesn't actually exist (i.e., you have
1011 given the wrong address) or the server has just momentarily taken ill
1012 for some reason or other.
1014 If Gnus says ``nntp server on <your server> can't be opened. Continue?'',
1015 you do not want to continue unless you have some foreign groups that you
1016 want to read. Even if you don't, Gnus will let you continue, but you'll
1017 find it difficult to actually do anything in the group buffer. But,
1018 hey, that's your problem. Blllrph!
1020 @findex gnus-no-server
1022 If you know that the server is definitely down, or you just want to read
1023 your mail without bothering with the server at all, you can use the
1024 @code{gnus-no-server} command to start Gnus. That might come in handy
1025 if you're in a hurry as well.
1029 @section Slave Gnusiï
1032 You might want to run more than one Emacs with more than one Gnus at the
1033 same time. If you are using different @file{.newsrc} files (eg., if you
1034 are using the two different Gnusiï to read from two different servers),
1035 that is no problem whatsoever. You just do it.
1037 The problem appears when you want to run two Gnusiï that use the same
1038 @code{.newsrc} file.
1040 To work around that problem some, we here at the Think-Tank at the Gnus
1041 Towers have come up with a new concept: @dfn{Masters} and
1042 @dfn{servants}. (We have applied for a patent on this concept, and have
1043 taken out a copyright on those words. If you wish to use those words in
1044 conjunction with each other, you have to send $1 per usage instance to
1045 me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
1046 Applications}) will be much more expensive, of course.)
1048 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
1049 however you do it). Each subsequent slave Gnusiï should be started with
1050 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
1051 files, but some slave files that contains information only on what
1052 groups have been read in the slave session. When a master Gnus starts,
1053 it will read (and delete) these slave files, incorporating all
1054 information from all of them. (The slave files will be read in the
1055 sequence they were created, so the latest changes will have precedence.)
1057 Information from the slave files has, of course, precedence over the
1058 information in the normal (i. e., master) @code{.newsrc} file.
1061 @node Fetching a Group
1062 @section Fetching a Group
1064 @findex gnus-fetch-group
1065 It it sometime convenient to be able to just say ``I want to read this
1066 group and I don't care whether Gnus has been started or not''. This is
1067 perhaps more useful for people who write code than for users, but the
1068 command @code{gnus-fetch-group} provides this functionality in any
1069 case. It takes the group name as a parameter.
1076 @vindex gnus-subscribe-newsgroup-method
1077 What Gnus does when it encounters a new group is determined by the
1078 @code{gnus-subscribe-newsgroup-method} variable.
1080 This variable should contain a function. Some handy pre-fab values
1085 @item gnus-subscribe-randomly
1086 @vindex gnus-subscribe-randomly
1087 Subscribe all new groups randomly.
1089 @item gnus-subscribe-alphabetically
1090 @vindex gnus-subscribe-alphabetically
1091 Subscribe all new groups alphabetically.
1093 @item gnus-subscribe-hierarchically
1094 @vindex gnus-subscribe-hierarchically
1095 Subscribe all new groups hierarchically.
1097 @item gnus-subscribe-interactively
1098 @vindex gnus-subscribe-interactively
1099 Subscribe new groups interactively. This means that Gnus will ask
1100 you about @strong{all} new groups.
1102 @item gnus-subscribe-killed
1103 @vindex gnus-subscribe-killed
1104 Kill all new groups.
1106 @item gnus-subscribe-zombies
1107 @vindex gnus-subscribe-zombies
1108 Make all new groups zombies. You can browse the zombies later (with
1109 @kbd{A z}) and either kill them all off properly, or subscribe to them.
1110 This is the default.
1113 @vindex gnus-subscribe-hierarchical-interactive
1114 A closely related variable is
1115 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
1116 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
1117 hierarchical fashion whether to subscribe to new groups or not. Gnus
1118 will ask you for each sub-hierarchy whether you want to descend the
1121 One common way to control which new newsgroups should be subscribed or
1122 ignored is to put an @dfn{options} line at the start of the
1123 @file{.newsrc} file. Here's an example:
1126 options -n !alt.all !rec.all sci.all
1129 @vindex gnus-subscribe-options-newsgroup-method
1130 This line obviously belongs to a serious-minded intellectual scientific
1131 person (or she may just be plain old boring), because it says that all
1132 groups that have names beginning with @samp{alt} and @samp{rec} should
1133 be ignored, and all groups with names beginning with @samp{sci} should
1134 be subscribed. Gnus will not use the normal subscription method for
1135 subscribing these groups.
1136 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
1137 variable defaults to @code{gnus-subscribe-alphabetically}.
1139 @vindex gnus-options-not-subscribe
1140 @vindex gnus-options-subscribe
1141 If you don't want to mess with your @file{.newsrc} file, you can just
1142 set the two variables @code{gnus-options-subscribe} and
1143 @code{gnus-options-not-subscribe}. These two variables do exactly the
1144 same as the @file{.newsrc} options -n trick. Both are regexps, and if
1145 the the new group matches the first, it will be unconditionally
1146 subscribed, and if it matches the latter, it will be ignored.
1148 @vindex gnus-auto-subscribed-groups
1149 Yet another variable that meddles here is
1150 @code{gnus-auto-subscribed-groups}. It works exactly like
1151 @code{gnus-options-subscribe}, and is therefore really superfluous, but I
1152 thought it would be nice to have two of these. This variable is more
1153 meant for setting some ground rules, while the other variable is used
1154 more for user fiddling. By default this variable makes all new groups
1155 that come from mail backends (@code{nnml}, @code{nnbabyl},
1156 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
1157 don't like that, just set this variable to @code{nil}.
1159 @vindex gnus-check-new-newsgroups
1160 If you are satisfied that you really never want to see any new groups,
1161 you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
1162 also save you some time at startup. Even if this variable is
1163 @code{nil}, you can always subscribe to the new groups just by pressing
1164 @kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
1165 is @code{t} by default.
1167 Gnus normally determines whether a group is new or not by comparing the
1168 list of groups from the active file(s) with the lists of subscribed and
1169 dead groups. This isn't a particularly fast method. If
1170 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
1171 server for new groups since the last time. This is both faster &
1172 cheaper. This also means that you can get rid of the list of killed
1173 groups altogether, so you may set @code{gnus-save-killed-list} to
1174 @code{nil}, which will save time both at startup, at exit, and all over.
1175 Saves disk space, too. Why isn't this the default, then?
1176 Unfortunately, not all servers support this function.
1178 I bet I know what you're thinking now: How do I find out whether my
1179 server supports @code{ask-server}? No? Good, because I don't have a
1180 fail-safe answer. I would suggest just setting this variable to
1181 @code{ask-server} and see whether any new groups appear after a few
1182 days. If they do, then it works. If they don't, then it doesn't work.
1183 I could write a function to make Gnus guess whether the server supports
1184 @code{ask-server}, but it would just be a guess. So I won't. You could
1185 @code{telnet} to the server and say @samp{HELP} and see whether it lists
1186 @samp{NEWGROUPS} among the commands it understands. If it does, then it
1187 might work. (But there are servers that lists @samp{NEWGROUPS} without
1188 supporting the function properly.)
1190 This variable can also be a list of select methods. If so, Gnus will
1191 issue an @code{ask-server} command to each of the select methods, and
1192 subscribe them (or not) using the normal methods. This might be handy
1193 if you are monitoring a few servers for new groups. A side effect is
1194 that startup will take much longer, so you can meditate while waiting.
1195 Use the mantra ``dingnusdingnusdingnus'' to achieve permanent happiness.
1198 @section Startup Files
1199 @cindex startup files
1202 Now, you all know about the @file{.newsrc} file. All subscription
1203 information is traditionally stored in this file.
1205 Things got a bit more complicated with @sc{gnus}. In addition to
1206 keeping the @file{.newsrc} file updated, it also used a file called
1207 @file{.newsrc.el} for storing all the information that didn't fit into
1208 the @file{.newsrc} file. (Actually, it duplicated everything in the
1209 @file{.newsrc} file.) @sc{gnus} would read whichever one of these files
1210 that were the most recently saved, which enabled people to swap between
1211 @sc{gnus} and other newsreaders.
1213 That was kinda silly, so Gnus went one better: In addition to the
1214 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
1215 @file{.newsrc.eld}. It will read whichever of these files that are most
1216 recent, but it will never write a @file{.newsrc.el} file.
1218 @vindex gnus-save-newsrc-file
1219 You can also turn off writing the @file{.newsrc} file by setting
1220 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
1221 the file and save some space, as well as making exit from Gnus faster.
1222 However, this will make it impossible to use other newsreaders than
1223 Gnus. But hey, who would want to, right?
1225 @vindex gnus-save-killed-list
1226 If @code{gnus-save-killed-list} is @code{nil}, Gnus will not save the
1227 list of killed groups to the startup file. This will save both time
1228 (when starting and quitting) and space (on disk). It will also means
1229 that Gnus has no record of what groups are new or old, so the automatic
1230 new groups subscription methods become meaningless. You should always
1231 set @code{gnus-check-new-newsgroups} to @code{nil} or @code{ask-server}
1232 if you set this variable to @code{nil} (@pxref{New Groups}).
1234 @vindex gnus-startup-file
1235 The @code{gnus-startup-file} variable says where the startup files are.
1236 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
1237 file being whatever that one is with a @samp{.eld} appended.
1239 @vindex gnus-save-newsrc-hook
1240 @vindex gnus-save-quick-newsrc-hook
1241 @vindex gnus-save-standard-newsrc-hook
1242 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
1243 files, while @code{gnus-save-quick-newsrc-hook} is called just before
1244 saving the @file{.newsrc.eld} file, and
1245 @code{gnus-save-standard-newsrc-hook} is called just before saving the
1246 @file{.newsrc} file. The latter two are commonly used to turn version
1247 control on or off. Version control is off by default when saving.
1251 @cindex dribble file
1254 Whenever you do something that changes the Gnus data (reading articles,
1255 catching up, killing/subscribing groups), the change is added to a
1256 special @dfn{dribble buffer}. This buffer is auto-saved the normal
1257 Emacs way. If your Emacs should crash before you have saved the
1258 @file{.newsrc} files, all changes you have made can be recovered from
1261 If Gnus detects this file at startup, it will ask the user whether to
1262 read it. The auto save file is deleted whenever the real startup file is
1265 @vindex gnus-use-dribble-file
1266 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
1267 maintain a dribble buffer. The default is @code{t}.
1269 @vindex gnus-dribble-directory
1270 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
1271 this variable is @code{nil}, which it is by default, Gnus will dribble
1272 into the same directory as the @file{.newsrc} file is located. (This is
1273 normally the user's home directory.)
1275 @node The Active File
1276 @section The Active File
1278 @cindex ignored groups
1280 When Gnus starts, or indeed whenever it tries to determine whether new
1281 articles have arrived, it reads the active file. This is a very large
1282 file that lists all the active groups and articles on the @sc{nntp}
1285 @vindex gnus-ignored-newsgroups
1286 Before examining the active file, Gnus deletes all lines that match the
1287 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
1288 any groups with bogus names, but you can use this variable to make Gnus
1289 ignore hierarchies you aren't ever interested in.
1291 @c @code{nil} by default, and will slow down active file handling somewhat
1292 @c if you set it to anything else.
1294 @vindex gnus-read-active-file
1296 The active file can be rather Huge, so if you have a slow network, you
1297 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
1298 reading the active file. This variable is @code{t} by default.
1300 Gnus will try to make do by just getting information on the groups
1301 that you actually subscribe to.
1303 Note that if you subscribe to lots and lots of groups, setting this
1304 variable to @code{nil} will probably make Gnus slower, not faster. At
1305 present, having this variable @code{nil} will slow Gnus down
1306 considerably, unless you read news over a 2400 baud modem.
1308 This variable can also have the value @code{some}. Gnus will then
1309 attempt to read active info only on the subscribed groups. On some
1310 servers this is quite fast (on sparkling, brand new INN servers that
1311 support the @samp{LIST ACTIVE group} command), on others this is not
1312 fast at all. In any case, @code{some} should be faster than @code{nil},
1313 and is certainly faster than @code{t} over slow lines.
1315 If this variable is @code{nil}, Gnus will as for group info in total
1316 lock-step, which isn't very fast. If it is @code{some} and you use an
1317 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
1318 read all the replies in one swoop. This will normally result in better
1319 performance, but if the server does not support the aforementioned
1320 @samp{LIST ACTIVE group} command, this isn't very nice to the server.
1322 In any case, if you use @code{some} or @code{nil}, you should kill all
1323 groups that you aren't interested in.
1325 @node Startup Variables
1326 @section Startup Variables
1330 @item gnus-load-hook
1331 @vindex gnus-load-hook
1332 A hook that is run while Gnus is being loaded. Note that this hook will
1333 normally be run just once in each Emacs session, no matter how many
1334 times you start Gnus.
1336 @item gnus-startup-hook
1337 @vindex gnus-startup-hook
1338 A hook that is run after starting up Gnus successfully.
1340 @item gnus-check-bogus-newsgroups
1341 @vindex gnus-check-bogus-newsgroups
1342 If non-@code{nil}, Gnus will check for and delete all bogus groups at
1343 startup. A @dfn{bogus group} is a group that you have in your
1344 @file{.newsrc} file, but doesn't exist on the news server. Checking for
1345 bogus groups isn't very quick, so to save time and resources, it's best
1346 to leave this option off, and instead do the checking for bogus groups
1347 once in a while from the group buffer (@pxref{Group Maintenance}).
1349 @item gnus-inhibit-startup-message
1350 @vindex gnus-inhibit-startup-message
1351 If non-@code{nil}, the startup message won't be displayed. That way,
1352 your boss might not notice that you are reading news instead of doing
1355 @item gnus-no-groups-message
1356 @vindex gnus-no-groups-message
1357 Message displayed by Gnus when no groups are available.
1360 @node The Group Buffer
1361 @chapter The Group Buffer
1362 @cindex group buffer
1364 The @dfn{group buffer} lists all (or parts) of the available groups. It
1365 is the first buffer shown when Gnus starts, and will never be killed as
1366 long as Gnus is active.
1369 * Group Buffer Format:: Information listed and how you can change it.
1370 * Group Maneuvering:: Commands for moving in the group buffer.
1371 * Selecting a Group:: Actually reading news.
1372 * Subscription Commands:: Unsubscribing, killing, subscribing.
1373 * Group Levels:: Levels? What are those, then?
1374 * Group Score:: A mechanism for finding out what groups you like.
1375 * Marking Groups:: You can mark groups for later processing.
1376 * Foreign Groups:: How to create foreign groups.
1377 * Group Parameters:: Each group may have different parameters set.
1378 * Listing Groups:: Gnus can list various subsets of the groups.
1379 * Sorting Groups:: Re-arrange the group order.
1380 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
1381 * Browse Foreign Server:: You can browse a server. See what if has to offer.
1382 * Exiting Gnus:: Stop reading news and get some work done.
1383 * Group Topics:: A folding group mode divided into topics.
1384 * Misc Group Stuff:: Other stuff that you can to do.
1387 @node Group Buffer Format
1388 @section Group Buffer Format
1389 @cindex group buffer format
1391 The default format of the group buffer is nice and dull, but you can
1392 make it as exciting and ugly as you feel like.
1394 Here's a couple of example group lines:
1397 25: news.announce.newusers
1398 * 0: alt.fan.andrea-dworkin
1403 You can see that there are 25 unread articles in
1404 @samp{news.announce.newusers}. There are no unread articles, but some
1405 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1406 asterisk at the beginning of the line?)
1408 @vindex gnus-group-line-format
1409 You can change that format to whatever you want by fiddling with the
1410 @code{gnus-group-line-format} variable. This variable works along the
1411 lines of a @code{format} specification, which is pretty much the same as
1412 a @code{printf} specifications, for those of you who use (feh!) C.
1413 @xref{Formatting Variables}.
1415 The default value that produced those lines above is
1416 @samp{"%M%S%5y: %(%g%)\n"}.
1418 There should always be a colon on the line; the cursor always moves to
1419 the colon after performing an operation. Nothing else is required---not
1420 even the group name. All displayed text is just window dressing, and is
1421 never examined by Gnus. Gnus stores all real information it needs using
1424 (Note that if you make a really strange, wonderful, spreadsheet-like
1425 layout, everybody will believe you are hard at work with the accounting
1426 instead of wasting time reading news.)
1428 Here's a list of all available format characters:
1433 Only marked articles.
1436 Whether the group is subscribed.
1439 Level of subscribedness.
1442 Number of unread articles.
1445 Number of dormant articles.
1448 Number of ticked articles.
1451 Number of read articles.
1454 Total number of articles.
1457 Number of unread, unticked, non-dormant articles.
1460 Number of ticked and dormant articles.
1469 Newsgroup description.
1472 @samp{m} if moderated.
1475 @samp{(m)} if moderated.
1484 A string that looks like @samp{<%s:%n>} if a foreign select method is
1488 Indentation based on the level of the topic (@pxref{Group Topics}).
1491 @vindex gnus-group-uncollapsed-levels
1492 Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels}
1493 variable says how many levels to leave at the end of the group name.
1494 The default is @samp{1}.
1497 User defined specifier. The next character in the format string should
1498 be a letter. @sc{gnus} will call the function
1499 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1500 following @samp{%u}. The function will be passed the current headers as
1501 argument. The function should return a string, which will be inserted
1502 into the buffer just like information from any other specifier.
1506 All the ``number-of'' specs will be filled with an asterisk (@samp{*}) if
1507 no info is available---for instance, if it is a non-activated foreign
1508 group, or a bogus (or semi-bogus) native group.
1510 @vindex gnus-group-mode-line-format
1511 The mode line can be changed by setting
1512 (@code{gnus-group-mode-line-format}). It doesn't understand that many
1517 The native news server.
1519 The native select method.
1522 @node Group Maneuvering
1523 @section Group Maneuvering
1524 @cindex group movement
1526 All movement commands understand the numeric prefix and will behave as
1527 expected, hopefully.
1533 @findex gnus-group-next-unread-group
1534 Go to the next group that has unread articles
1535 (@code{gnus-group-next-unread-group}).
1542 @findex gnus-group-prev-unread-group
1543 Go to the previous group group that has unread articles
1544 (@code{gnus-group-prev-unread-group}).
1548 @findex gnus-group-next-group
1549 Go to the next group (@code{gnus-group-next-group}).
1553 @findex gnus-group-prev-group
1554 Go to the previous group (@code{gnus-group-prev-group}).
1558 @findex gnus-group-next-unread-group-same-level
1559 Go to the next unread group on the same level (or lower)
1560 (@code{gnus-group-next-unread-group-same-level}).
1564 @findex gnus-group-prev-unread-group-same-level
1565 Go to the previous unread group on the same level (or lower)
1566 (@code{gnus-group-prev-unread-group-same-level}).
1569 Three commands for jumping to groups:
1575 @findex gnus-group-jump-to-group
1576 Jump to a group (and make it visible if it isn't already)
1577 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1582 @findex gnus-group-best-unread-group
1583 Jump to the unread group with the lowest level
1584 (@code{gnus-group-best-unread-group}).
1588 @findex gnus-group-first-unread-group
1589 Jump to the first group with unread articles
1590 (@code{gnus-group-first-unread-group}).
1593 @vindex gnus-group-goto-unread
1594 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1595 commands will move to the next group, not the next unread group. Even
1596 the commands that say they move to the next unread group. The default
1600 @node Selecting a Group
1601 @section Selecting a Group
1602 @cindex group selection
1607 @kindex SPACE (Group)
1608 @findex gnus-group-read-group
1609 Select the current group, switch to the summary buffer and display the
1610 first unread article (@code{gnus-group-read-group}). If there are no
1611 unread articles in the group, or if you give a non-numerical prefix to
1612 this command, Gnus will offer to fetch all the old articles in this
1613 group from the server. If you give a numerical prefix @var{N}, Gnus
1614 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1615 the @var{N} newest articles, if @var{N} is negative, fetch the
1616 @var{abs(N)} oldest articles.
1620 @findex gnus-group-select-group
1621 Select the current group and switch to the summary buffer
1622 (@code{gnus-group-select-group}). Takes the same arguments as
1623 @code{gnus-group-read-group}---the only difference is that this command
1624 does not display the first unread article automatically upon group
1628 @kindex M-RET (Group)
1629 @findex gnus-group-quick-select-group
1630 This does the same as the command above, but tries to do it with the
1631 minimum amount off fuzz (@code{gnus-group-quick-select-group}). No
1632 scoring/killing will be performed, there will be no highlights and no
1633 expunging. This might be useful if you're in a real hurry and have to
1634 enter some humongous groups.
1637 @kindex M-RET (Group)
1638 @findex gnus-group-visible-select-group
1639 This is yet one more command that does the same as the one above, but
1640 this one does it without expunging and hiding dormants
1641 (@code{gnus-group-visible-select-group}).
1645 @findex gnus-group-catchup-current
1646 Mark all unticked articles in this group as read
1647 (@code{gnus-group-catchup-current}).
1651 @findex gnus-group-catchup-current-all
1652 Mark all articles in this group, even the ticked ones, as read
1653 (@code{gnus-group-catchup-current-all}).
1656 @vindex gnus-large-newsgroup
1657 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1658 to be a big group. This is 200 by default. If the group has more
1659 unread articles than this, Gnus will query the user before entering the
1660 group. The user can then specify how many articles should be fetched
1661 from the server. If the user specifies a negative number (@samp{-n}),
1662 the @samp{n} oldest articles will be fetched. If it is positive, the
1663 @samp{n} articles that have arrived most recently will be fetched.
1665 @vindex gnus-select-group-hook
1666 @vindex gnus-auto-select-first
1667 @code{gnus-auto-select-first} control whether any articles are selected
1668 automatically when entering a group.
1673 Don't select any articles when entering the group. Just display the
1674 full summary buffer.
1677 Select the first unread article when entering the group.
1680 Select the most high-scored article in the group when entering the
1684 If you want to prevent automatic selection in some group (say, in a
1685 binary group with Huge articles) you can set this variable to @code{nil}
1686 in @code{gnus-select-group-hook}, which is called when a group is
1689 @findex gnus-thread-sort-by-total-score
1690 @findex gnus-thread-sort-by-date
1691 @findex gnus-thread-sort-by-score
1692 @findex gnus-thread-sort-by-subject
1693 @findex gnus-thread-sort-by-author
1694 @findex gnus-thread-sort-by-number
1695 @vindex gnus-thread-sort-functions
1696 If you are using a threaded summary display, you can sort the threads by
1697 setting @code{gnus-thread-sort-functions}, which is a list of functions.
1698 By default, sorting is done on article numbers. Ready-made sorting
1699 predicate functions include @code{gnus-thread-sort-by-number},
1700 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
1701 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
1702 @code{gnus-thread-sort-by-total-score}.
1704 Each function takes two threads and return non-@code{nil} if the first
1705 thread should be sorted before the other. Note that sorting really is
1706 normally done by looking only at the roots of each thread. If you use
1707 more than one function, the primary sort key should be the last function
1708 in the list. You should probably always include
1709 @code{gnus-thread-sort-by-number} in the list of sorting
1710 functions---preferably first. This will ensure that threads that are
1711 equal with respect to the other sort criteria will be displayed in
1712 ascending article order.
1714 If you would like to sort by score, then by subject, and finally by
1715 number, you could do something like:
1718 (setq gnus-thread-sort-functions
1719 '(gnus-thread-sort-by-number
1720 gnus-thread-sort-by-subject
1721 gnus-thread-sort-by-score))
1724 The threads that have highest score will be displayed first in the
1725 summary buffer. When threads have the same score, they will be sorted
1726 alphabetically. The threads that have the same score and the same
1727 subject will be sorted by number, which is (normally) the sequence in
1728 which the articles arrived.
1730 If you want to sort by score and then reverse arrival order, you could
1734 (setq gnus-thread-sort-functions
1736 (not (gnus-thread-sort-by-number t1 t2)))
1737 gnus-thread-sort-by-score))
1740 @vindex gnus-thread-score-function
1741 The function in the @code{gnus-thread-score-function} variable (default
1742 @code{+}) is used for calculating the total score of a thread. Useful
1743 functions might be @code{max}, @code{min}, or squared means, or whatever
1746 @findex gnus-article-sort-functions
1747 @findex gnus-article-sort-by-date
1748 @findex gnus-article-sort-by-score
1749 @findex gnus-article-sort-by-subject
1750 @findex gnus-article-sort-by-author
1751 @findex gnus-article-sort-by-number
1752 If you are using an unthreaded display for some strange reason or other,
1753 you have to fiddle with the @code{gnus-article-sort-functions} variable.
1754 It is very similar to the @code{gnus-thread-sort-functions}, except that
1755 is uses slightly different functions for article comparison. Available
1756 sorting predicate functions are @code{gnus-article-sort-by-number},
1757 @code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
1758 @code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
1760 If you want to sort an unthreaded summary display by subject, you could
1764 (setq gnus-article-sort-functions
1765 '(gnus-article-sort-by-number
1766 gnus-article-sort-by-subject))
1770 @node Subscription Commands
1771 @section Subscription Commands
1780 @findex gnus-group-unsubscribe-current-group
1781 Toggle subscription to the current group
1782 (@code{gnus-group-unsubscribe-current-group}).
1788 @findex gnus-group-unsubscribe-group
1789 Prompt for a group to subscribe, and then subscribe it. If it was
1790 subscribed already, unsubscribe it instead
1791 (@code{gnus-group-unsubscribe-group}).
1797 @findex gnus-group-kill-group
1798 Kill the current group (@code{gnus-group-kill-group}).
1804 @findex gnus-group-yank-group
1805 Yank the last killed group (@code{gnus-group-yank-group}).
1811 @findex gnus-group-kill-region
1812 Kill all groups in the region (@code{gnus-group-kill-region}).
1816 @findex gnus-group-kill-all-zombies
1817 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1820 @kindex S C-k (Group)
1821 @findex gnus-group-kill-level
1822 Kill all groups on a certain level (@code{gnus-group-kill-level}).
1823 These groups can't be yanked back after killing, so this command should
1824 be used with some caution. The only thing where this command comes in
1825 really handy is when you have a @file{.newsrc} with lots of unsubscribed
1826 groups that you want to get rid off. @kbd{S C-k} on level @code{7} will
1827 kill off all unsubscribed groups that do not have message numbers in the
1828 @file{.newsrc} file.
1832 Also @xref{Group Levels}.
1835 @section Group Levels
1838 All groups have a level of @dfn{subscribedness}. For instance, if a
1839 group is on level 2, it is more subscribed than a group on level 5. You
1840 can ask Gnus to just list groups on a given level or lower
1841 (@pxref{Listing Groups}), or to just check for new articles in groups on
1842 a given level or lower (@pxref{Misc Group Stuff}).
1848 @findex gnus-group-set-current-level
1849 Set the level of the current group. If a numeric prefix is given, the
1850 next @var{n} groups will have their levels set. The user will be
1851 prompted for a level.
1854 @vindex gnus-level-killed
1855 @vindex gnus-level-zombie
1856 @vindex gnus-level-unsubscribed
1857 @vindex gnus-level-subscribed
1858 Gnus considers groups on between levels 1 and
1859 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
1860 @code{gnus-level-subscribed} (exclusive) and
1861 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
1862 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
1863 (default 8) and @code{gnus-level-killed} to be killed (default 9),
1864 completely dead. Gnus treats subscribed and unsubscribed groups exactly
1865 the same, but zombie and killed groups have no information on what
1866 articles you have read, etc, stored. This distinction between dead and
1867 living groups isn't done because it is nice or clever, it is done purely
1868 for reasons of efficiency.
1870 It is recommended that you keep all your mail groups (if any) on quite
1871 low levels (eg. 1 or 2).
1873 If you want to play with the level variables, you should show some care.
1874 Set them once, and don't touch them ever again. Better yet, don't touch
1875 them at all unless you know exactly what you're doing.
1877 @vindex gnus-level-default-unsubscribed
1878 @vindex gnus-level-default-subscribed
1879 Two closely related variables are @code{gnus-level-default-subscribed}
1880 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
1881 which are the levels that new groups will be put on if they are
1882 (un)subscribed. These two variables should, of course, be inside the
1883 relevant legal ranges.
1885 @vindex gnus-keep-same-level
1886 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1887 will only move to groups that are of the same level (or lower). In
1888 particular, going from the last article in one group to the next group
1889 will go to the next group of the same level (or lower). This might be
1890 handy if you want to read the most important groups before you read the
1893 @vindex gnus-group-default-list-level
1894 All groups with a level less than or equal to
1895 @code{gnus-group-default-list-level} will be listed in the group buffer
1898 @vindex gnus-group-list-inactive-groups
1899 If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
1900 groups will be listed along with the unread groups. This variable is
1901 @code{t} by default. If it is @code{nil}, inactive groups won't be
1904 @vindex gnus-group-use-permanent-levels
1905 If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you
1906 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1907 use this level as the ``work'' level.
1909 @vindex gnus-activate-level
1910 Gnus will normally just activate groups that are on level
1911 @code{gnus-activate-level} or less. If you don't want to activate
1912 unsubscribed groups, for instance, you might set this variable to
1917 @section Group Score
1920 You would normally keep important groups on high levels, but that scheme
1921 is somewhat restrictive. Don't you wish you could have Gnus sort the
1922 group buffer according to how often you read groups, perhaps? Within
1925 This is what @dfn{group score} is for. You can assign a score to each
1926 group. You can then sort the group buffer based on this score.
1927 Alternatively, you can sort on score and then level. (Taken together,
1928 the level and the score is called the @dfn{rank} of the group. A group
1929 that is on level 4 and has a score of 1 has a higher rank than a group
1930 on level 5 that has a score of 300. (The level is the most significant
1931 part and the score is the least significant part.)
1933 @findex gnus-summary-bubble-group
1934 If you want groups you read often to get higher scores than groups you
1935 read seldom you can add the @code{gnus-summary-bubble-group} function to
1936 the @code{gnus-summary-exit-hook} hook. This will result (after
1937 sorting) in a bubbling sort of action. If you want to see that in
1938 action after each summary exit, you can add
1939 @code{gnus-group-sort-groups-by-rank} or
1940 @code{gnus-group-sort-groups-by-score} to the same hook, but that will
1941 slow things down somewhat.
1944 @node Marking Groups
1945 @section Marking Groups
1946 @cindex marking groups
1948 If you want to perform some command on several groups, and they appear
1949 subsequently in the group buffer, you would normally just give a
1950 numerical prefix to the command. Most group commands will then do your
1951 bidding on those groups.
1953 However, if the groups are not in sequential order, you can still
1954 perform a command on several groups. You simply mark the groups first
1955 with the process mark and then execute the command.
1963 @findex gnus-group-mark-group
1964 Set the mark on the current group (@code{gnus-group-mark-group}).
1970 @findex gnus-group-unmark-group
1971 Remove the mark from the current group
1972 (@code{gnus-group-unmark-group}).
1976 @findex gnus-group-unmark-all-groups
1977 Remove the mark from all groups (@code{gnus-group-unmark-all-groups}).
1981 @findex gnus-group-mark-region
1982 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1986 @findex gnus-group-mark-buffer
1987 Mark all groups in the buffer (@code{gnus-group-mark-buffer}).
1991 @findex gnus-group-mark-regexp
1992 Mark all groups that match some regular expression
1993 (@code{gnus-group-mark-regexp}).
1996 Also @xref{Process/Prefix}.
1998 If you want to execute some command on all groups that have been marked
1999 with the process mark, you can use the @kbd{M-&}
2000 (@code{gnus-group-universal-argument}) command. It will prompt you for
2001 the command to be executed.
2005 @node Foreign Groups
2006 @section Foreign Groups
2007 @cindex foreign groups
2009 A @dfn{foreign group} is a group that is not read by the usual (or
2010 default) means. It could be, for instance, a group from a different
2011 @sc{nntp} server, it could be a virtual group, or it could be your own
2012 personal mail group.
2014 A foreign group (or any group, really) is specified by a @dfn{name} and
2015 a @dfn{select method}. To take the latter first, a select method is a
2016 list where the first element says what backend to use (eg. @code{nntp},
2017 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
2018 name}. There may be additional elements in the select method, where the
2019 value may have special meaning for the backend in question.
2021 One could say that a select method defines a @dfn{virtual server}---so
2022 we do just that (@pxref{The Server Buffer}).
2024 The @dfn{name} of the group is the name the backend will recognize the
2027 For instance, the group @samp{soc.motss} on the @sc{nntp} server
2028 @samp{some.where.edu} will have the name @samp{soc.motss} and select
2029 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
2030 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
2031 @code{nntp} backend just knows this group as @samp{soc.motss}.
2033 Here are some commands for making and editing general foreign groups,
2034 and some commands to ease the creation of some special-purpose groups:
2040 @findex gnus-group-make-group
2041 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
2042 for a name, a method and possibly an @dfn{address}. For an easier way
2043 to subscribe to @sc{nntp} groups, @xref{Browse Foreign Server}.
2047 @findex gnus-group-rename-group
2048 Rename the current group to something else
2049 (@code{gnus-group-rename-group}). This is legal only on some groups --
2050 mail groups mostly. This command might very well be quite slow on some
2055 @findex gnus-group-edit-group-method
2056 Enter a buffer where you can edit the select method of the current
2057 group (@code{gnus-group-edit-group-method}).
2061 @findex gnus-group-edit-group-parameters
2062 Enter a buffer where you can edit the group parameters
2063 (@code{gnus-group-edit-group-parameters}).
2067 @findex gnus-group-edit-group
2068 Enter a buffer where you can edit the group info
2069 (@code{gnus-group-edit-group}).
2073 @findex gnus-group-make-directory-group
2074 Make a directory group. You will be prompted for a directory name
2075 (@code{gnus-group-make-directory-group}).
2079 @findex gnus-group-make-help-group
2080 Make the Gnus help group (@code{gnus-group-make-help-group}).
2084 @findex gnus-group-make-archive-group
2085 @vindex gnus-group-archive-directory
2086 @vindex gnus-group-recent-archive-directory
2087 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
2088 default a group pointing to the most recent articles will be created
2089 (@code{gnus-group-recent-archive-directory}), but given a prefix, a full
2090 group will be created from from @code{gnus-group-archive-directory}.
2094 @findex gnus-group-make-kiboze-group
2095 Make a kiboze group. You will be prompted for a name, for a regexp to
2096 match groups to be ``included'' in the kiboze group, and a series of
2097 strings to match on headers (@code{gnus-group-make-kiboze-group}).
2101 @findex gnus-group-enter-directory
2102 Read a random directory as if with were a newsgroup with the
2103 @code{nneething} backend (@code{gnus-group-enter-directory}).
2107 @findex gnus-group-make-doc-group
2108 Make a group based on some file or other
2109 (@code{gnus-group-make-doc-group}). If you give a prefix to this
2110 command, you will be prompted for a file name and a file type.
2111 Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
2112 @code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs}, and
2113 @code{forward}. If you run this command without a prefix, Gnus will
2114 guess at the file type.
2117 @kindex G DEL (Group)
2118 @findex gnus-group-delete-group
2119 This function will delete the current group
2120 (@code{gnus-group-delete-group}). If given a prefix, this function will
2121 actually delete all the articles in the group, and forcibly remove the
2122 group itself from the face of the Earth. Use a prefix only if you are
2123 sure of what you are doing.
2127 @findex gnus-group-make-empty-virtual
2128 Make a new, fresh, empty @code{nnvirtual} group
2129 (@code{gnus-group-make-empty-virtual}).
2133 @findex gnus-group-add-to-virtual
2134 Add the current group to an @code{nnvirtual} group
2135 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
2138 The different methods all have their peculiarities, of course.
2141 * nntp:: Reading news from a different @sc{nntp} server.
2142 * nnspool:: Reading news from the local spool.
2143 * nnvirtual:: Combining articles from many groups.
2144 * nnkiboze:: Looking through parts of the newsfeed for articles.
2145 * nndir:: You can read a directory as if it was a newsgroup.
2146 * nneething:: Dired? Who needs dired?
2147 * nndoc:: Single files can be the basis of a group.
2148 * SOUP:: Reading @sc{SOUP} packets ``offline''.
2149 * Reading Mail:: Reading your personal mail with Gnus.
2152 @vindex gnus-activate-foreign-newsgroups
2153 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
2154 Gnus will check all foreign groups with this level or lower at startup.
2155 This might take quite a while, especially if you subscribe to lots of
2156 groups from different @sc{nntp} servers.
2162 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
2163 You just specify @code{nntp} as method and the address of the @sc{nntp}
2164 server as the, uhm, address.
2166 If the @sc{nntp} server is located at a non-standard port, setting the
2167 third element of the select method to this port number should allow you
2168 to connect to the right port. You'll have to edit the group info for
2169 that (@pxref{Foreign Groups}).
2171 The name of the foreign group can be the same as a native group. In
2172 fact, you can subscribe to the same group from as many different servers
2173 you feel like. There will be no name collisions.
2175 The following variables can be used to create a virtual @code{nntp}
2180 @item nntp-server-opened-hook
2181 @vindex nntp-server-opened-hook
2182 @cindex @sc{mode reader}
2184 @cindex authentification
2185 @cindex nntp authentification
2186 @findex nntp-send-authinfo
2187 @findex nntp-send-mode-reader
2188 @code{nntp-server-opened-hook} is run after a connection has been made.
2189 It can be used to send commands to the @sc{nntp} server after it has
2190 been contacted. By default is sends the command @samp{MODE READER} to
2191 the server with the @code{nntp-send-mode-reader} function. Another
2192 popular function is @code{nntp-send-authinfo}, which will prompt you for
2193 an @sc{nntp} password and stuff.
2195 @item nntp-server-action-alist
2196 @vindex nntp-server-action-alist
2197 This is an list of regexps to match on server types and actions to be
2198 taken when matches are made. For instance, if you want Gnus to beep
2199 every time you connect to innd, you could say something like:
2202 (setq nntp-server-action-alist
2206 You probably don't want to do that, though.
2208 The default value is
2211 '(("nntpd 1\\.5\\.11t"
2212 (remove-hook 'nntp-server-opened-hook nntp-send-mode-reader)))
2215 This ensures that Gnus doesn't send the @samp{MODE READER} command to
2216 nntpd 1.5.11t, since that command chokes that server, I've been told.
2218 @item nntp-maximum-request
2219 @vindex nntp-maximum-request
2220 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
2221 will collect headers by sending a series of @code{head} commands. To
2222 speed things up, the backend sends lots of these commands without
2223 waiting for reply, and then reads all the replies. This is controlled
2224 by the @code{nntp-maximum-request} variable, and is 400 by default. If
2225 your network is buggy, you should set this to 1.
2227 @item nntp-connection-timeout
2228 @vindex nntp-connection-timeout
2229 If you have lots of foreign @code{nntp} groups that you connect to
2230 regularly, you're sure to have problems with @sc{nntp} servers not
2231 responding properly, or being too loaded to reply within reasonable
2232 time. This is can lead to awkward problems, which can be helped
2233 somewhat by setting @code{nntp-connection-timeout}. This is an integer
2234 that says how many seconds the @code{nntp} backend should wait for a
2235 connection before giving up. If it is @code{nil}, which is the default,
2236 no timeouts are done.
2238 @item nntp-server-hook
2239 @vindex nntp-server-hook
2240 This hook is run as the last step when connecting to an @sc{nntp}
2243 @c @findex nntp-open-rlogin
2244 @c @findex nntp-open-network-stream
2245 @c @item nntp-open-server-function
2246 @c @vindex nntp-open-server-function
2247 @c This function is used to connect to the remote system. Two pre-made
2248 @c functions are @code{nntp-open-network-stream}, which is the default, and
2249 @c simply connects to some port or other on the remote system. The other
2250 @c is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
2251 @c and then does a telnet to the @sc{nntp} server available there.
2253 @c @item nntp-rlogin-parameters
2254 @c @vindex nntp-rlogin-parameters
2255 @c If you use @code{nntp-open-rlogin} as the
2256 @c @code{nntp-open-server-function}, this list will be used as the
2257 @c parameter list given to @code{rsh}.
2259 @c @item nntp-rlogin-user-name
2260 @c @vindex nntp-rlogin-user-name
2261 @c User name on the remote system when using the @code{rlogin} connect
2265 @vindex nntp-address
2266 The address of the remote system running the @sc{nntp} server.
2268 @item nntp-port-number
2269 @vindex nntp-port-number
2270 Port number to connect to when using the @code{nntp-open-network-stream}
2273 @item nntp-buggy-select
2274 @vindex nntp-buggy-select
2275 Set this to non-@code{nil} if your select routine is buggy.
2277 @item nntp-nov-is-evil
2278 @vindex nntp-nov-is-evil
2279 If the @sc{nntp} server does not support @sc{nov}, you could set this
2280 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
2281 can be used automatically.
2283 @item nntp-xover-commands
2284 @vindex nntp-xover-commands
2285 List of strings that are used as commands to fetch @sc{nov} lines from a
2286 server. The default value of this variable is @code{("XOVER"
2290 @vindex nntp-nov-gap
2291 @code{nntp} normally sends just one big request for @sc{nov} lines to
2292 the server. The server responds with one huge list of lines. However,
2293 if you have read articles 2-5000 in the group, and only want to read
2294 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
2295 lines that you do not want, and will not use. This variable says how
2296 big a gap between two consecutive articles is allowed to be before the
2297 @code{XOVER} request is split into several request. Note that if your
2298 network is fast, setting this variable to a really small number means
2299 that fetching will probably be slower. If this variable is @code{nil},
2300 @code{nntp} will never split requests.
2302 @item nntp-prepare-server-hook
2303 @vindex nntp-prepare-server-hook
2304 A hook run before attempting to connect to an @sc{nntp} server.
2306 @item nntp-async-number
2307 @vindex nntp-async-number
2308 How many articles should be pre-fetched when in asynchronous mode. If
2309 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
2310 that it can without bound. If it is @code{nil}, no pre-fetching will be
2313 @item nntp-warn-about-losing-connection
2314 @vindex nntp-warn-about-losing-connection
2315 If this variable is non-@code{nil}, some noise will be made when a
2316 server closes connection.
2323 @cindex @code{nnspool}
2326 Subscribing to a foreign group from the local spool is extremely easy,
2327 and might be useful, for instance, to speed up reading groups like
2328 @samp{alt.binaries.pictures.furniture}.
2330 Anyways, you just specify @code{nnspool} as the method and @samp{""} (or
2331 anything else) as the address.
2333 If you have access to a local spool, you should probably use that as the
2334 native select method (@pxref{Finding the News}). It is normally faster
2335 than using an @code{nntp} select method, but might not be. It depends.
2336 You just have to try to find out what's best at your site.
2340 @item nnspool-inews-program
2341 @vindex nnspool-inews-program
2342 Program used to post an article.
2344 @item nnspool-inews-switches
2345 @vindex nnspool-inews-switches
2346 Parameters given to the inews program when posting an article.
2348 @item nnspool-spool-directory
2349 @vindex nnspool-spool-directory
2350 Where @code{nnspool} looks for the articles. This is normally
2351 @file{/usr/spool/news/}.
2353 @item nnspool-nov-directory
2354 @vindex nnspool-nov-directory
2355 Where @code{nnspool} will look for @sc{nov} files. This is normally
2356 @file{/usr/spool/news/over.view/}.
2358 @item nnspool-lib-dir
2359 @vindex nnspool-lib-dir
2360 Where the news lib dir is (@file{/usr/lib/news/} by default).
2362 @item nnspool-active-file
2363 @vindex nnspool-active-file
2364 The path of the active file.
2366 @item nnspool-newsgroups-file
2367 @vindex nnspool-newsgroups-file
2368 The path of the group descriptions file.
2370 @item nnspool-history-file
2371 @vindex nnspool-history-file
2372 The path of the news history file.
2374 @item nnspool-active-times-file
2375 @vindex nnspool-active-times-file
2376 The path of the active date file.
2378 @item nnspool-nov-is-evil
2379 @vindex nnspool-nov-is-evil
2380 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
2383 @item nnspool-sift-nov-with-sed
2384 @vindex nnspool-sift-nov-with-sed
2385 If non-@code{nil}, which is the default, use @code{sed} to get the
2386 relevant portion from the overview file. If nil, @code{nnspool} will
2387 load the entire file into a buffer and process it there.
2393 @subsection nnvirtual
2394 @cindex @code{nnvirtual}
2395 @cindex virtual groups
2397 An @dfn{nnvirtual group} is really nothing more than a collection of
2400 For instance, if you are tired of reading many small group, you can
2401 put them all in one big group, and then grow tired of reading one
2402 big, unwieldy group. The joys of computing!
2404 You specify @code{nnvirtual} as the method. The address should be a
2405 regexp to match component groups.
2407 All marks in the virtual group will stick to the articles in the
2408 component groups. So if you tick an article in a virtual group, the
2409 article will also be ticked in the component group from whence it came.
2410 (And vice versa---marks from the component groups will also be shown in
2413 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
2414 newsgroups into one, big, happy newsgroup:
2417 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
2420 The component groups can be native or foreign; everything should work
2421 smoothly, but if your computer explodes, it was probably my fault.
2423 Collecting the same group from several servers might actually be a good
2424 idea if users have set the Distribution header to limit distribution.
2425 If you would like to read @samp{soc.motss} both from a server in Japan
2426 and a server in Norway, you could use the following as the group regexp:
2429 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
2432 This should work kinda smoothly---all articles from both groups should
2433 end up in this one, and there should be no duplicates. Threading (and
2434 the rest) will still work as usual, but there might be problems with the
2435 sequence of articles. Sorting on date might be an option here
2436 (@pxref{Selecting a Group}.
2438 One limitation, however---all groups that are included in a virtual
2439 group has to be alive (i.e., subscribed or unsubscribed). Killed or
2440 zombie groups can't be component groups for @code{nnvirtual} groups.
2442 @vindex nnvirtual-always-rescan
2443 If the @code{nnvirtual-always-rescan} is non-@code{nil},
2444 @code{nnvirtual} will always scan groups for unread articles when
2445 entering a virtual group. If this variable is @code{nil} (which is the
2446 default) and you read articles in a component group after the virtual
2447 group has been activated, the read articles from the component group
2448 will show up when you enter the virtual group. You'll also see this
2449 effect if you have two virtual groups that contain the same component
2450 group. If that's the case, you should set this variable to @code{t}.
2451 Or you can just tap @code{M-g} on the virtual group every time before
2452 you enter it---it'll have much the same effect.
2456 @subsection nnkiboze
2457 @cindex @code{nnkiboze}
2460 @dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of)
2461 the news feed''. @code{nnkiboze} is a backend that will do this for you. Oh
2462 joy! Now you can grind any @sc{nntp} server down to a halt with useless
2463 requests! Oh happiness!
2465 The address field of the @code{nnkiboze} method is, as with
2466 @code{nnvirtual}, a regexp to match groups to be ``included'' in the
2467 @code{nnkiboze} group. There most similarities between @code{nnkiboze}
2468 and @code{nnvirtual} ends.
2470 In addition to this regexp detailing component groups, an @code{nnkiboze} group
2471 must have a score file to say what articles that are to be included in
2472 the group (@pxref{Scoring}).
2474 @kindex M-x nnkiboze-generate-groups
2475 @findex nnkiboze-generate-groups
2476 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
2477 @code{nnkiboze} groups you want to have. This command will take time. Lots of
2478 time. Oodles and oodles of time. Gnus has to fetch the headers from
2479 all the articles in all the components groups and run them through the
2480 scoring process to determine if there are any articles in the groups
2481 that are to be part of the @code{nnkiboze} groups.
2483 Please limit the number of component groups by using restrictive
2484 regexps. Otherwise your sysadmin may become annoyed with you, and the
2485 @sc{nntp} site may throw you off and never let you back in again.
2486 Stranger things have happened.
2488 @code{nnkiboze} component groups do not have to be alive---they can be dead,
2489 and they can be foreign. No restrictions.
2491 @vindex nnkiboze-directory
2492 The generation of an @code{nnkiboze} group means writing two files in
2493 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
2494 contains the @sc{nov} header lines for all the articles in the group,
2495 and the other is an additional @file{.newsrc} file to store information
2496 on what groups that have been searched through to find component
2499 Articles that are marked as read in the @code{nnkiboze} group will have their
2500 @sc{nov} lines removed from the @sc{nov} file.
2505 @cindex @code{nndir}
2506 @cindex directory groups
2508 If you have a directory that has lots of articles in separate files in
2509 it, you might treat it as a newsgroup. The files have to have numerical
2512 This might be an opportune moment to mention @code{ange-ftp}, that most
2513 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
2514 didn't think much about it---a backend to read directories. Big deal.
2516 @code{ange-ftp} changes that picture dramatically. For instance, if you
2517 enter @file{"/ftp.hpc.uh.edu:/pub/emacs/ding-list/"} as the the
2518 directory name, ange-ftp will actually allow you to read this directory
2519 over at @samp{sina} as a newsgroup. Distributed news ahoy!
2521 @code{nndir} will use @sc{nov} files if they are present.
2523 @code{nndir} is a ``read-only'' backend---you can't delete or expire
2524 articles with this method. You can use @code{nnmh} or @code{nnml} for
2525 whatever you use @code{nndir} for, so you could switch to any of those
2526 methods if you feel the need to have a non-read-only @code{nndir}.
2530 @subsection nneething
2531 @cindex @code{nneething}
2533 From the @code{nndir} backend (which reads a single spool-like
2534 directory), it's just a hop and a skip to @code{nneething}, which
2535 pretends that any random directory is a newsgroup. Strange, but true.
2537 When @code{nneething} is presented with a directory, it will scan this
2538 directory and assign article numbers to each file. When you enter such a
2539 group, @code{nneething} must create ``headers'' that Gnus can use. After
2540 all, Gnus is a newsreader, in case you're forgetting. @code{nneething}
2541 does this in a two-step process. First, it snoops each file in question.
2542 If the file looks like an article (i.e., the first few lines look like
2543 headers), it will use this as the head. If this is just some random file
2544 without a head (eg. a C source file), @code{nneething} will cobble up a
2545 header out of thin air. It will use file ownership, name and date and do
2546 whatever it can with these elements.
2548 All this should happen automatically for you, and you will be presented
2549 with something that looks very much like a newsgroup. Totally like a
2550 newsgroup, to be precise. If you select an article, it will be displayed
2551 in the article buffer, just as usual.
2553 If you select a line that represents a directory, Gnus will pop you into
2554 a new summary buffer for this @code{nneething} group. And so on. You can
2555 traverse the entire disk this way, if you feel like, but remember that
2556 Gnus is not dired, really, and does not intend to be, either.
2558 There are two overall modes to this action---ephemeral or solid. When
2559 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
2560 will not store information on what files you have read, and what files
2561 are new, and so on. If you create a solid @code{nneething} group the
2562 normal way with @kbd{G m}, Gnus will store a mapping table between
2563 article numbers and file names, and you can treat this group like any
2564 other groups. When you activate a solid @code{nneething} group, you will
2565 be told how many unread articles it contains, etc., etc.
2570 @item nneething-map-file-directory
2571 @vindex nneething-map-file-directory
2572 All the mapping files for solid @code{nneething} groups will be stored
2573 in this directory, which defaults to @file{~/.nneething/}.
2575 @item nneething-exclude-files
2576 @vindex nneething-exclude-files
2577 All files that match this regexp will be ignored. Nice to use to exclude
2578 auto-save files and the like, which is what it does by default.
2580 @item nneething-map-file
2581 @vindex nneething-map-file
2582 Name of the map files.
2588 @cindex @code{nndoc}
2589 @cindex documentation group
2592 @code{nndoc} is a cute little thing that will let you read a single file
2593 as a newsgroup. Several files types are supported:
2600 The babyl (rmail) mail box.
2605 The standard Unix mbox file.
2607 @cindex MMDF mail box
2609 The MMDF mail box format.
2612 Several news articles appended into a file.
2615 @cindex rnews batch files
2616 The rnews batch transport format.
2617 @cindex forwarded messages
2626 @cindex RFC 1153 digest
2627 @cindex RFC 341 digest
2628 MIME (RFC 1341) digest format.
2630 @item standard-digest
2631 The standard (RFC 1153) digest format.
2634 Non-standard digest format---matches most things, but does it badly.
2637 You can also use the special ``file type'' @code{guess}, which means that
2638 @code{nndoc} will try to guess what file type it is looking at.
2639 @code{digest} means that @code{nndoc} should guess what digest type the
2642 @code{nndoc} will not try to change the file or insert any extra headers into
2643 it---it will simply, like, let you use the file as the basis for a
2644 group. And that's it.
2646 If you have some old archived articles that you want to insert into your
2647 new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
2648 that. Say you have an old @file{RMAIL} file with mail that you now want
2649 to split into your new @code{nnml} groups. You look at that file using
2650 @code{nndoc}, set the process mark on all the articles in the buffer
2651 (@kbd{M P b}, for instance), and then re-spool (@kbd{B r}) using
2652 @code{nnml}. If all goes well, all the mail in the @file{RMAIL} file is
2653 now also stored in lots of @code{nnml} directories, and you can delete
2654 that pesky @file{RMAIL} file. If you have the guts!
2656 Virtual server variables:
2659 @item nndoc-article-type
2660 @vindex nndoc-article-type
2661 This should be one of @code{mbox}, @code{babyl}, @code{digest},
2662 @code{mmdf}, @code{forward}, @code{news}, @code{rnews},
2663 @code{mime-digest}, @code{clari-briefs}, or @code{guess}.
2665 @item nndoc-post-type
2666 @vindex nndoc-post-type
2667 This variable says whether Gnus is to consider the group a news group or
2668 a mail group. There are two legal values: @code{mail} (the default)
2678 In the PC world people often talk about ``offline'' newsreaders. These
2679 are thingies that are combined reader/news transport monstrosities.
2680 With built-in modem programs. Yecchh!
2682 Of course, us Unix Weenie types of human beans use things like
2683 @code{uucp} and, like, @code{nntpd} and set up proper news and mail
2684 transport things like Ghod intended. And then we just use normal
2687 However, it can sometimes be convenient to do something a that's a bit
2688 easier on the brain if you have a very slow modem, and you're not really
2689 that interested in doing things properly.
2691 A file format called @sc{soup} has been developed for transporting news
2692 and mail from servers to home machines and back again. It can be a bit
2698 You log in on the server and create a @sc{soup} packet. You can either
2699 use a dedicated @sc{soup} thingie, or you can use Gnus to create the
2700 packet with the @kbd{O s} command.
2703 You transfer the packet home. Rail, boat, car or modem will do fine.
2706 You put the packet in your home directory.
2709 You fire up Gnus using the @code{nnsoup} backend as the native server.
2712 You read articles and mail and answer and followup to the things you
2716 You do the @kbd{G s r} command to pack these replies into a @sc{soup}
2720 You transfer this packet to the server.
2723 You use Gnus to mail this packet out with the @kbd{G s s} command.
2726 You then repeat until you die.
2730 So you basically have a bipartite system---you use @code{nnsoup} for
2731 reading and Gnus for packing/sending these @sc{soup} packets.
2734 * SOUP Commands:: Commands for creating and sending @sc{soup} packets
2735 * nnsoup:: A backend for reading @sc{soup} packets.
2736 * SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
2741 @subsubsection SOUP Commands
2745 @kindex G s b (Group)
2746 @findex gnus-group-brew-soup
2747 Pack all unread articles in the current group
2748 (@code{gnus-group-brew-soup}). This command understands the
2749 process/prefix convention.
2752 @kindex G s w (Group)
2753 @findex gnus-soup-save-areas
2754 Save all data files (@code{gnus-soup-save-areas}).
2757 @kindex G s s (Group)
2758 @findex gnus-soup-send-replies
2759 Send all replies from the replies packet
2760 (@code{gnus-soup-send-replies}).
2763 @kindex G s p (Group)
2764 @findex gnus-soup-pack-packet
2765 Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
2768 @kindex G s r (Group)
2769 @findex nnsoup-pack-replies
2770 Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
2773 @kindex O s (Summary)
2774 @findex gnus-soup-add-article
2775 This summary-mode command adds the current article to a @sc{soup} packet
2776 (@code{gnus-soup-add-article}). It understands the process/prefix
2782 There are a few variables to customize where Gnus will put all these
2787 @item gnus-soup-directory
2788 @vindex gnus-soup-directory
2789 Directory where Gnus will save intermediate files while composing
2790 @sc{soup} packets. The default is @file{~/SoupBrew/}.
2792 @item gnus-soup-replies-directory
2793 @vindex gnus-soup-replies-directory
2794 This is what Gnus will use as a temporary directory while sending our
2795 reply packets. The default is @file{~/SoupBrew/SoupReplies/}.
2797 @item gnus-soup-prefix-file
2798 @vindex gnus-soup-prefix-file
2799 Name of the file where Gnus stores the last used prefix. The default is
2800 @samp{"gnus-prefix"}.
2802 @item gnus-soup-packer
2803 @vindex gnus-soup-packer
2804 A format string command for packing a @sc{soup} packet. The default is
2805 @samp{ "tar cf - %s | gzip > $HOME/Soupout%d.tgz"}.
2807 @item gnus-soup-unpacker
2808 @vindex gnus-soup-unpacker
2809 Format string command for unpacking a @sc{soup} packet. The default is
2810 @samp{"gunzip -c %s | tar xvf -"}.
2812 @item gnus-soup-packet-directory
2813 @vindex gnus-soup-packet-directory
2814 Where Gnus will look for reply packets. The default is @file{~/}.
2816 @item gnus-soup-packet-regexp
2817 @vindex gnus-soup-packet-regexp
2818 Regular expression matching @sc{soup} reply packets in
2819 @code{gnus-soup-packet-directory}.
2825 @subsubsection nnsoup
2826 @cindex @code{nnsoup}
2828 @code{nnsoup} is the backend for reading @sc{soup} packets. It will
2829 read incoming packets, unpack them, and put them in a directory where
2830 you can read them at leisure.
2832 These are the variables you can use to customize its behavior:
2836 @item nnsoup-directory
2837 @vindex nnsoup-directory
2838 @code{nnsoup} will move all incoming @sc{soup} packets to this directory
2839 and unpack them there. The default is @file{~/SOUP/}.
2841 @item nnsoup-replies-directory
2842 @vindex nnsoup-replies-directory
2843 All replies will stored in this directory before being packed into a
2844 reply packet. The default is @file{~/SOUP/replies/"}.
2846 @item nnsoup-replies-format-type
2847 @vindex nnsoup-replies-format-type
2848 The @sc{soup} format of the replies packets. The default is @samp{?n}
2849 (rnews), and I don't think you should touch that variable. I probably
2850 shouldn't even have documented it. Drats! Too late!
2852 @item nnsoup-replies-index-type
2853 @vindex nnsoup-replies-index-type
2854 The index type of the replies packet. The is @samp{?n}, which means
2855 ``none''. Don't fiddle with this one either!
2857 @item nnsoup-active-file
2858 @vindex nnsoup-active-file
2859 Where @code{nnsoup} stores lots of information. This is not an ``active
2860 file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
2861 this file or mess it up in any way, you're dead. The default is
2862 @file{~/SOUP/active}.
2865 @vindex nnsoup-packer
2866 Format string command for packing a reply @sc{soup} packet. The default
2867 is @samp{"tar cf - %s | gzip > $HOME/Soupin%d.tgz"}.
2869 @item nnsoup-unpacker
2870 @vindex nnsoup-unpacker
2871 Format string command for unpacking incoming @sc{soup} packets. The
2872 default is @samp{"gunzip -c %s | tar xvf -"}.
2874 @item nnsoup-packet-directory
2875 @vindex nnsoup-packet-directory
2876 Where @code{nnsoup} will look for incoming packets. The default is
2879 @item nnsoup-packet-regexp
2880 @vindex nnsoup-packet-regexp
2881 Regular expression matching incoming @sc{soup} packets. The default is
2888 @subsubsection SOUP Replies
2890 Just using @code{nnsoup} won't mean that your postings and mailings end
2891 up in @sc{soup} reply packets automagically. You have to work a bit
2892 more for that to happen.
2894 @findex nnsoup-set-variables
2895 The @code{nnsoup-set-variables} command will set the appropriate
2896 variables to ensure that all your followups and replies end up in the
2899 In specific, this is what it does:
2902 (setq gnus-inews-article-function 'nnsoup-request-post)
2903 (setq send-mail-function 'nnsoup-request-mail)
2906 And that's it, really. If you only want news to go into the @sc{soup}
2907 system you just use the first line. If you only want mail to be
2908 @sc{soup}ed you use the second.
2912 @subsection Reading Mail
2913 @cindex reading mail
2916 Reading mail with a newsreader---isn't that just plain WeIrD? But of
2919 Gnus will read the mail spool when you activate a mail group. The mail
2920 file is first copied to your home directory. What happens after that
2921 depends on what format you want to store your mail in.
2924 * Creating Mail Groups:: How to create mail groups.
2925 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
2926 * Mail and Procmail:: Reading mail groups that procmail create.
2927 * Expiring Old Mail Articles:: Getting rid of unwanted mail.
2928 * Not Reading Mail:: Using mail backends for reading other files.
2929 * nnmbox:: Using the (quite) standard Un*x mbox.
2930 * nnbabyl:: Emacs programs use the rmail babyl format.
2931 * nnml:: Store your mail in a private spool?
2932 * nnmh:: An mhspool-like backend.
2933 * nnfolder:: Having one file for each group.
2936 @vindex nnmail-read-incoming-hook
2937 The mail backends all call @code{nnmail-read-incoming-hook} after
2938 reading new mail. You can use this hook to notify any mail watch
2939 programs, if you want to.
2941 @vindex nnmail-spool-file
2944 @code{nnmail-spool-file} says where to look for new mail. If this
2945 variable is @code{nil}, the mail backends will never attempt to fetch
2946 mail by themselves. If you are using a POP mail server and your name is
2947 @samp{"larsi"}, you should set this variable to @samp{"po:larsi"}. If
2948 your name is not @samp{"larsi"}, you should probably modify that
2949 slightly, but you may have guessed that already, you smart & handsome
2950 devil! You can also set this variable to @code{pop}, and Gnus will try
2951 to figure out the POP mail string by itself. In any case, Gnus will
2952 call @code{movemail} which will contact the POP server named in the
2953 @samp{MAILHOST} environment variable.
2955 When you use a mail backend, Gnus will slurp all your mail from your
2956 inbox and plonk it down in your home directory. Gnus doesn't move any
2957 mail if you're not using a mail backend---you have to do a lot of magic
2958 invocations first. At the time when you have finished drawing the
2959 pentagram, lightened the candles, and sacrificed the goat, you really
2960 shouldn't be too surprised when Gnus moves your mail.
2962 @vindex nnmail-use-procmail
2963 If @code{nnmail-use-procmail} is non-@code{nil}, the mail backends will
2964 look in @code{nnmail-procmail-directory} for incoming mail. All the
2965 files in that directory that have names ending in
2966 @code{gnus-procmail-suffix} will be considered incoming mailboxes, and
2967 will be searched for new mail.
2969 @vindex nnmail-prepare-incoming-hook
2970 @code{nnmail-prepare-incoming-hook} is run in a buffer that holds all
2971 the new incoming mail, and can be used for, well, anything, really.
2973 @vindex nnmail-pre-get-new-mail-hook
2974 @vindex nnmail-post-get-new-mail-hook
2975 There are two more useful hooks executed when treating new incoming
2976 mail---@code{nnmail-pre-get-new-mail-hook} (which is called just before
2977 starting to handle the new mail) and
2978 @code{nnmail-post-get-new-mail-hook} (which is called when the mail
2979 handling is done). Here's and example of using these two hooks to
2980 change the default file modes the new mail files get:
2983 (add-hook 'gnus-pre-get-new-mail-hook
2984 (lambda () (set-default-file-modes 511)))
2986 (add-hook 'gnus-post-get-new-mail-hook
2987 (lambda () (set-default-file-modes 551)))
2990 @vindex nnmail-tmp-directory
2991 @code{nnmail-tmp-directory} says where to move the incoming mail to
2992 while processing it. This is usually done in the same directory that
2993 the mail backend inhabits (i.e., @file{~/Mail/}), but if this variable is
2994 non-@code{nil}, it will be used instead.
2996 @vindex nnmail-movemail-program
2997 @code{nnmail-movemail-program} is executed to move mail from the user's
2998 inbox to her home directory. The default is @samp{"movemail"}.
3000 @vindex nnmail-delete-incoming
3001 If @code{nnmail-delete-incoming} is non-@code{nil}, the mail backends
3002 will delete the temporary incoming file after splitting mail into the
3003 proper groups. This is @code{nil} by default for reasons of security.
3005 @vindex nnmail-use-long-file-names
3006 If @code{nnmail-use-long-file-names} is non-@code{nil} the mail backends
3007 will use long file and directory names. Groups like @samp{mail.misc}
3008 will end up in directories like @file{mail.misc/}. If it is @code{nil},
3009 the same group will end up in @file{mail/misc/}.
3011 @vindex nnmail-message-id-cache-length
3012 @vindex nnmail-message-id-cache-file
3013 @vindex nnmail-treat-duplicates
3014 @cindex duplicate mails
3015 If you are a member of a couple of mailing list, you will sometime
3016 receive two copies of the same mail. This can be quite annoying, so
3017 @code{nnmail} checks for and treats any duplicates it might find. To do
3018 this, it keeps a cache of old @code{Message-ID}s -
3019 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
3020 default. The approximate maximum number of @code{Message-ID}s stored
3021 there is controlled by the @code{nnmail-message-id-cache-length}
3022 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
3023 stored.) If all this sounds scary to you, you can set
3024 @code{nnmail-delete-duplicates} to @code{warn} (which is what it is by
3025 default), and @code{nnmail} won't delete duplicate mails. Instead it
3026 will generate a brand new @code{Message-ID} for the mail and insert a
3027 warning into the head of the mail saying that it thinks that this is a
3028 duplicate of a different message.
3030 This variable can also be a function. If that's the case, the function
3031 will be called from a buffer narrowed to the message in question with
3032 the @code{Message-ID} as a parameter. The function must return either
3033 @code{nil}, @code{warn}, or @code{delete}.
3035 You can turn this feature off completely by setting the variable to
3038 If you want all the duplicate mails to be put into a special
3039 @dfn{duplicates} group, you could do that using the normal mail split
3043 (setq nnmail-split-fancy
3044 '(| ;; Messages duplicates go to a separate group.
3045 ("gnus-warning" "duplication of message" "duplicate")
3046 ;; Message from daemons, postmaster, and the like to another.
3047 (any mail "mail.misc")
3054 (setq nnmail-split-methods
3055 '(("duplicates" "^Gnus-Warning:")
3060 Here's a neat feature: If you know that the recipient reads her mail
3061 with Gnus, and that she has @code{nnmail-treat-duplicates} set to
3062 @code{delete}, you can send her as many insults as you like, just by
3063 using a @code{Message-ID} of a mail that you know that she's already
3064 received. Think of all the fun! She'll never see any of it! Whee!
3066 Gnus gives you all the opportunity you could possibly want for shooting
3067 yourself in the foot. Let's say you create a group that will contain
3068 all the mail you get from your boss. And then you accidentally
3069 unsubscribe from the group. Gnus will still put all the mail from your
3070 boss in the unsubscribed group, and so, when your boss mails you ``Have
3071 that report ready by Monday or you're fired!'', you'll never see it and,
3072 come Tuesday, you'll still believe that you're gainfully employed while
3073 you really should be out collecting empty bottles to save up for next
3076 @node Creating Mail Groups
3077 @subsubsection Creating Mail Groups
3078 @cindex creating mail groups
3080 You can make Gnus read your personal, private, secret mail.
3082 You should first set @code{gnus-secondary-select-methods} to, for
3083 instance, @code{((nnmbox ""))}. When you start up Gnus, Gnus will ask
3084 this backend for what groups it carries (@samp{mail.misc} by default)
3085 and subscribe it the normal way. (Which means you may have to look for
3086 it among the zombie groups, I guess, all depending on your
3087 @code{gnus-subscribe-newsgroup-method} variable.)
3089 @vindex nnmail-split-methods
3090 Then you should set the variable @code{nnmail-split-methods} to specify
3091 how the incoming mail is to be split into groups.
3094 (setq nnmail-split-methods
3095 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
3096 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
3100 This variable is a list of lists, where the first element of each of
3101 these lists is the name of the mail group (they do not have to be called
3102 something beginning with @samp{mail}, by the way), and the second
3103 element is a regular expression used on the header of each mail to
3104 determine if it belongs in this mail group.
3106 The second element can also be a function. In that case, it will be
3107 called narrowed to the headers with the first element of the rule as the
3108 argument. It should return a non-@code{nil} value if it thinks that the
3109 mail belongs in that group.
3111 The last of these groups should always be a general one, and the regular
3112 expression should @emph{always} be @samp{""} so that it matches any
3113 mails that haven't been matched by any of the other regexps.
3115 If you like to tinker with this yourself, you can set this variable to a
3116 function of your choice. This function will be called without any
3117 arguments in a buffer narrowed to the headers of an incoming mail
3118 message. The function should return a list of groups names that it
3119 thinks should carry this mail message.
3121 Note that the mail backends are free to maul the poor, innocent
3122 incoming headers all they want to. They all add @code{Lines} headers;
3123 some add @code{X-Gnus-Group} headers; most rename the Unix mbox
3124 @code{From<SPC>} line to something else.
3126 @vindex nnmail-crosspost
3127 The mail backends all support cross-posting. If several regexps match,
3128 the mail will be ``cross-posted'' to all those groups.
3129 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
3130 that no articles are crossposted to the general (@samp{""}) group.
3132 @vindex nnmail-crosspost-link-function
3135 @code{nnmh} and @code{nnml} makes crossposts by creating hard links to
3136 the crossposted articles. However, not all files systems support hard
3137 links. If that's the case for you, set
3138 @code{nnmail-crosspost-link-function} to @code{copy-file}. (This
3139 variable is @code{add-name-to-file} by default.)
3142 @node Fancy Mail Splitting
3143 @subsubsection Fancy Mail Splitting
3144 @cindex mail splitting
3145 @cindex fancy mail splitting
3147 @vindex nnmail-split-fancy
3148 @findex nnmail-split-fancy
3149 If the rather simple, standard method for specifying how to split mail
3150 doesn't allow you to do what you want, you can set
3151 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
3152 play with the @code{nnmail-split-fancy} variable.
3154 Let's look at an example value of this variable first:
3157 ;; Messages from the mailer daemon are not crossposted to any of
3158 ;; the ordinary groups. Warnings are put in a separate group
3159 ;; from real errors.
3160 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
3162 ;; Non-error messages are crossposted to all relevant
3163 ;; groups, but we don't crosspost between the group for the
3164 ;; (ding) list and the group for other (ding) related mail.
3165 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
3166 ("subject" "ding" "ding.misc"))
3167 ;; Other mailing lists...
3168 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
3169 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
3171 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
3172 ;; Unmatched mail goes to the catch all group.
3176 This variable has the format of a @dfn{split}. A split is a (possibly)
3177 recursive structure where each split may contain other splits. Here are
3178 the four possible split syntaxes:
3183 If the split is a string, that will be taken as a group name.
3185 @item (FIELD VALUE SPLIT)
3186 If the split is a list, and the first element is a string, then that
3187 means that if header FIELD (a regexp) contains VALUE (also a regexp),
3188 then store the message as specified by SPLIT.
3191 If the split is a list, and the first element is @code{|} (vertical
3192 bar), then process each SPLIT until one of them matches. A SPLIT is
3193 said to match if it will cause the mail message to be stored in one or
3197 If the split is a list, and the first element is @code{&}, then process
3198 all SPLITs in the list.
3201 In these splits, FIELD must match a complete field name. VALUE must
3202 match a complete word according to the fundamental mode syntax table.
3203 You can use @code{.*} in the regexps to match partial field names or
3206 @vindex nnmail-split-abbrev-alist
3207 FIELD and VALUE can also be lisp symbols, in that case they are expanded
3208 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
3209 an alist of cons cells, where the car of the cells contains the key, and
3210 the cdr contains a string.
3212 @node Mail and Procmail
3213 @subsubsection Mail and Procmail
3216 Many people use @code{procmail} (or some other mail filter program or
3217 external delivery agent---@code{slocal}, @code{elm}, etc) to split
3218 incoming mail into groups. If you do that, you should set
3219 @code{nnmail-spool-file} to @code{procmail} to ensure that the mail
3220 backends never ever try to fetch mail by themselves.
3222 This also means that you probably don't want to set
3223 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
3226 When a mail backend is queried for what groups it carries, it replies
3227 with the contents of that variable, along with any groups it has figured
3228 out that it carries by other means. None of the backends (except
3229 @code{nnmh}) actually go out to the disk and check what groups actually
3230 exist. (It's not trivial to distinguish between what the user thinks is
3231 a basis for a newsgroup and what is just a plain old file or directory.)
3233 This means that you have to tell Gnus (and the backends) what groups
3236 Let's take the @code{nnmh} backend as an example.
3238 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
3239 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
3241 Go to the group buffer and type @kbd{G m}. When prompted, answer
3242 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
3243 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
3244 to include all your mail groups.
3246 That's it. You are now set to read your mail. An active file for this
3247 method will be created automatically.
3249 @vindex nnmail-procmail-suffix
3250 @vindex nnmail-procmail-directory
3251 If you use @code{nnfolder} or any other backend that store more than a
3252 single article in each file, you should never have procmail add mails to
3253 the file that Gnus sees. Instead, procmail should put all incoming mail
3254 in @code{nnmail-procmail-directory}. To arrive at the file name to put
3255 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
3256 name. The mail backends will read the mail from these files.
3258 @vindex nnmail-resplit-incoming
3259 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
3260 put in the @code{mail.misc}, as one would expect. However, if you want
3261 Gnus to split the mail the normal way, you could set
3262 @code{nnmail-resplit-incoming} to @code{t}.
3264 @vindex nnmail-keep-last-article
3265 If you use @code{procmail} to split things directory into an @code{nnmh}
3266 directory (which you shouldn't do), you should set
3267 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
3268 ever expiring the final article in a mail newsgroup. This is quite,
3272 @node Expiring Old Mail Articles
3273 @subsubsection Expiring Old Mail Articles
3274 @cindex article expiry
3276 Traditional mail readers have a tendency to remove mail articles when
3277 you mark them as read, in some way. Gnus takes a fundamentally
3278 different approach to mail reading.
3280 Gnus basically considers mail just to be news that has been received in
3281 a rather peculiar manner. It does not think that it has the power to
3282 actually change the mail, or delete any mail messages. If you enter a
3283 mail group, and mark articles as ``read'', or kill them in some other
3284 fashion, the mail articles will still exist on the system. I repeat:
3285 Gnus will not delete your old, read mail. Unless you ask it to, of
3288 To make Gnus get rid of your unwanted mail, you have to mark the
3289 articles as @dfn{expirable}. This does not mean that the articles will
3290 disappear right away, however. In general, a mail article will be
3291 deleted from your system if, 1) it is marked as expirable, AND 2) it is
3292 more than one week old. If you do not mark an article as expirable, it
3293 will remain on your system until hell freezes over. This bears
3294 repeating one more time, with some spurious capitalizations: IF you do
3295 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
3297 @vindex gnus-auto-expirable-newsgroups
3298 You do not have to mark articles as expirable by hand. Groups that
3299 match the regular expression @code{gnus-auto-expirable-newsgroups} will
3300 have all articles that you read marked as expirable automatically. All
3301 articles that are marked as expirable have an @samp{E} in the first
3302 column in the summary buffer.
3304 Let's say you subscribe to a couple of mailing lists, and you want the
3305 articles you have read to disappear after a while:
3308 (setq gnus-auto-expirable-newsgroups
3309 "mail.nonsense-list\\|mail.nice-list")
3312 Another way to have auto-expiry happen is to have the element
3313 @code{auto-expire} in the select method of the group.
3315 @vindex nnmail-expiry-wait
3316 The @code{nnmail-expiry-wait} variable supplies the default time an
3317 expirable article has to live. The default is seven days.
3319 Gnus also supplies a function that lets you fine-tune how long articles
3320 are to live, based on what group they are in. Let's say you want to
3321 have one month expiry period in the @samp{mail.private} group, a one day
3322 expiry period in the @samp{mail.junk} group, and a six day expiry period
3326 (setq nnmail-expiry-wait-function
3328 (cond ((string= group "mail.private")
3330 ((string= group "mail.junk")
3332 ((string= group "important")
3338 The group names that this function is fed are ``unadorned'' group
3339 names---no @samp{"nnml:"} prefixes and the like.
3341 The @code{nnmail-expiry-wait} variable and
3342 @code{nnmail-expiry-wait-function} function can be either a number (not
3343 necessarily an integer) or the symbols @code{immediate} or
3346 You can also use the @code{expiry-wait} group parameter to selectively
3347 change the expiry period (@pxref{Group Parameters}).
3349 @vindex nnmail-keep-last-article
3350 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
3351 expire the final article in a mail newsgroup. This is to make life
3352 easier for procmail users.
3354 @vindex gnus-total-expirable-newsgroups
3355 By the way, that line up there about Gnus never expiring non-expirable
3356 articles is a lie. If you put @code{total-expire} in the group
3357 parameters, articles will not be marked as expirable, but all read
3358 articles will be put through the expiry process. Use with extreme
3359 caution. Even more dangerous is the
3360 @code{gnus-total-expirable-newsgroups} variable. All groups that match
3361 this regexp will have all read articles put through the expiry process,
3362 which means that @emph{all} old mail articles in the groups in question
3363 will be deleted after a while. Use with extreme caution, and don't come
3364 crying to me when you discover that the regexp you used matched the
3365 wrong group and all your important mail has disappeared. Be a
3366 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
3370 @node Not Reading Mail
3371 @subsubsection Not Reading Mail
3373 If you start using any of the mail backends, they have the annoying
3374 habit of assuming that you want to read mail with them. This might not
3375 be unreasonable, but it might not be what you want.
3377 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
3378 will ever attempt to read incoming mail, which should help.
3380 @vindex nnbabyl-get-new-mail
3381 @vindex nnmbox-get-new-mail
3382 @vindex nnml-get-new-mail
3383 @vindex nnmh-get-new-mail
3384 @vindex nnfolder-get-new-mail
3385 This might be too much, if, for instance, you are reading mail quite
3386 happily with @code{nnml} and just want to peek at some old @sc{rmail}
3387 file you have stashed away with @code{nnbabyl}. All backends have
3388 variables called backend-@code{get-new-mail}. If you want to disable
3389 the @code{nnbabyl} mail reading, you edit the virtual server for the
3390 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
3392 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
3393 narrowed to the article to be saved before saving it when reading
3397 @subsubsection nnmbox
3398 @cindex @code{nnmbox}
3399 @cindex unix mail box
3401 @vindex nnmbox-active-file
3402 @vindex nnmbox-mbox-file
3403 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
3404 mail. @code{nnmbox} will add extra headers to each mail article to say
3405 which group it belongs in.
3407 Virtual server settings:
3410 @item nnmbox-mbox-file
3411 @vindex nnmbox-mbox-file
3412 The name of the mail box in the user's home directory.
3414 @item nnmbox-active-file
3415 @vindex nnmbox-active-file
3416 The name of the active file for the mail box.
3418 @item nnmbox-get-new-mail
3419 @vindex nnmbox-get-new-mail
3420 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
3425 @subsubsection nnbabyl
3426 @cindex @code{nnbabyl}
3429 @vindex nnbabyl-active-file
3430 @vindex nnbabyl-mbox-file
3431 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
3432 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
3433 article to say which group it belongs in.
3435 Virtual server settings:
3438 @item nnbabyl-mbox-file
3439 @vindex nnbabyl-mbox-file
3440 The name of the rmail mbox file.
3442 @item nnbabyl-active-file
3443 @vindex nnbabyl-active-file
3444 The name of the active file for the rmail box.
3446 @item nnbabyl-get-new-mail
3447 @vindex nnbabyl-get-new-mail
3448 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
3454 @cindex mail @sc{nov} spool
3456 The @dfn{nnml} spool mail format isn't compatible with any other known
3457 format. It should be used with some caution.
3459 @vindex nnml-directory
3460 If you use this backend, Gnus will split all incoming mail into files;
3461 one file for each mail, and put the articles into the correct
3462 directories under the directory specified by the @code{nnml-directory}
3463 variable. The default value is @file{~/Mail/}.
3465 You do not have to create any directories beforehand; Gnus will take
3468 If you have a strict limit as to how many files you are allowed to store
3469 in your account, you should not use this backend. As each mail gets its
3470 own file, you might very well occupy thousands of inodes within a few
3471 weeks. If this is no problem for you, and it isn't a problem for you
3472 having your friendly systems administrator walking around, madly,
3473 shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should
3474 know that this is probably the fastest format to use. You do not have
3475 to trudge through a big mbox file just to read your new mail.
3477 @code{nnml} is probably the slowest backend when it comes to article
3478 splitting. It has to create lots of files, and it also generates
3479 @sc{nov} databases for the incoming mails. This makes is the fastest
3480 backend when it comes to reading mail.
3482 Virtual server settings:
3485 @item nnml-directory
3486 @vindex nnml-directory
3487 All @code{nnml} directories will be placed under this directory.
3489 @item nnml-active-file
3490 @vindex nnml-active-file
3491 The active file for the @code{nnml} server.
3493 @item nnml-newsgroups-file
3494 @vindex nnml-newsgroups-file
3495 The @code{nnml} group descriptions file. @xref{Newsgroups File
3498 @item nnml-get-new-mail
3499 @vindex nnml-get-new-mail
3500 If non-@code{nil}, @code{nnml} will read incoming mail.
3502 @item nnml-nov-is-evil
3503 @vindex nnml-nov-is-evil
3504 If non-@code{nil}, this backend will ignore any @sc{nov} files.
3506 @item nnml-nov-file-name
3507 @vindex nnml-nov-file-name
3508 The name of the @sc{nov} files. The default is @file{.overview}.
3512 @findex nnml-generate-nov-databases
3513 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
3514 you can do a complete update by typing @kbd{M-x
3515 nnml-generate-nov-databases}. This command will trawl through the
3516 entire @code{nnml} hierarchy, looking at each and every article, so it
3517 might take a while to complete.
3522 @cindex mh-e mail spool
3524 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
3525 @sc{nov} databases and it doesn't keep an active file. This makes
3526 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
3527 makes it easier to write procmail scripts for.
3529 Virtual server settings:
3532 @item nnmh-directory
3533 @vindex nnmh-directory
3534 All @code{nnmh} directories will be located under this directory.
3536 @item nnmh-get-new-mail
3537 @vindex nnmh-get-new-mail
3538 If non-@code{nil}, @code{nnmh} will read incoming mail.
3541 @vindex nnmh-be-safe
3542 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
3543 sure that the articles in the folder are actually what Gnus thinks they
3544 are. It will check date stamps and stat everything in sight, so
3545 setting this to @code{t} will mean a serious slow-down. If you never
3546 use anything but Gnus to read the @code{nnmh} articles, you do not have
3547 to set this variable to @code{t}.
3552 @subsubsection nnfolder
3553 @cindex @code{nnfolder}
3554 @cindex mbox folders
3556 @code{nnfolder} is a backend for storing each mail group in a separate
3557 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
3558 will add extra headers to keep track of article numbers and arrival
3561 Virtual server settings:
3564 @item nnfolder-directory
3565 @vindex nnfolder-directory
3566 All the @code{nnfolder} mail boxes will be stored under this directory.
3568 @item nnfolder-active-file
3569 @vindex nnfolder-active-file
3570 The name of the active file.
3572 @item nnfolder-newsgroups-file
3573 @vindex nnfolder-newsgroups-file
3574 The name of the group descriptions file. @xref{Newsgroups File Format}.
3576 @item nnfolder-get-new-mail
3577 @vindex nnfolder-get-new-mail
3578 If non-@code{nil}, @code{nnfolder} will read incoming mail.
3581 @findex nnfolder-generate-active-file
3582 @kindex M-x nnfolder-generate-active-file
3583 If you have lots of @code{nnfolder}-like files you'd like to read with
3584 @code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
3585 command to make @code{nnfolder} aware of all likely files in
3586 @code{nnfolder-directory}.
3589 @node Group Parameters
3590 @section Group Parameters
3591 @cindex group parameters
3593 Gnus stores all information on a group in a list that is usually known
3594 as the @dfn{group info}. This list has from three to six elements.
3595 Here's an example info.
3598 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
3599 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
3602 The first element is the @dfn{group name}, as Gnus knows the group,
3603 anyway. The second element is the @dfn{subscription level}, which
3604 normally is a small integer. The third element is a list of ranges of
3605 read articles. The fourth element is a list of lists of article marks
3606 of various kinds. The fifth element is the select method (or virtual
3607 server, if you like). The sixth element is a list of @dfn{group
3608 parameters}, which is what this section is about.
3610 Any of the last three elements may be missing if they are not required.
3611 In fact, the vast majority of groups will normally only have the first
3612 three elements, which saves quite a lot of cons cells.
3614 The group parameters store information local to a particular group:
3619 If the group parameter list contains an element that looks like
3620 @samp{(to-address . "some@@where.com")}, that address will be used by
3621 the backend when doing followups and posts. This is primarily useful in
3622 mail groups that represent closed mailing lists---mailing lists where
3623 it's expected that everybody that writes to the mailing list is
3624 subscribed to it. Since using this parameter ensures that the mail only
3625 goes to the mailing list itself, it means that members won't receive two
3626 copies of your followups.
3628 Using @code{to-address} will actually work whether the group is foreign
3629 or not. Let's say there's a group on the server that is called
3630 @samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten
3631 the articles from a mail-to-news gateway. Posting directly to this
3632 group is therefore impossible---you have to send mail to the mailing
3633 list address instead.
3637 If the group parameter list has an element that looks like
3638 @code{(to-list . "some@@where.com")}, that address will be used when
3639 doing a @kbd{a} in any group. It is totally ignored when doing a
3640 followup---except that if it is present in a news group, you'll get mail
3641 group semantics when doing @kbd{f}.
3643 @item broken-reply-to
3644 @cindex broken-reply-to
3645 Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To}
3646 headers in this group are to be ignored. This can be useful if you're
3647 reading a mailing list group where the listserv has inserted
3648 @code{Reply-To} headers that point back to the listserv itself. This is
3649 broken behavior. So there!
3653 If the group parameter list contains an element like @code{(to-group
3654 . "some.group.name")}, all posts will be sent to that group.
3658 If this symbol is present in the group parameter list, all articles that
3659 are read will be marked as expirable. For an alternative approach,
3660 @xref{Expiring Old Mail Articles}.
3663 @cindex total-expire
3664 If this symbol is present, all read articles will be put through the
3665 expiry process, even if they are not marked as expirable. Use with
3670 If the group parameter has an element that looks like @samp{(expiry-wait
3671 . 10)}, this value will override any @code{nnmail-expiry-wait} and
3672 @code{nnmail-expiry-wait-functions} when expiring expirable messages.
3673 The value can either be a number of days (not necessarily an integer) or
3674 the symbols @code{never} or @code{immediate}.
3677 Elements that look like @samp{(score-file . "file")} will make
3678 @samp{file} into the current score file for the group in question. This
3679 means that all score commands you issue will end up in that file.
3682 When unsubscribing to a mailing list you should never send the
3683 unsubscription notice to the mailing list itself. Instead, you'd send
3684 messages to the administrative address. This parameter allows you to
3685 put the admin address somewhere convenient.
3688 This parameter allows you to enter a random comment on the group.
3690 @item @var{(variable form)}
3691 You can use the group parameters to set variables local to the group you
3692 are entering. Say you want to turn threading off in
3693 @samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
3694 the group parameters of that group. @code{gnus-show-threads} will be
3695 made into a local variable in the summary buffer you enter, and the form
3696 @code{nil} will be @code{eval}ed there.
3698 This can also be used as a group-specific hook function, if you'd like.
3699 If you want to hear a beep when you enter the group
3700 @samp{alt.binaries.pictures.furniture}, you could put something like
3701 @code{(dummy-variable (ding))} in the parameters of that group.
3702 @code{dummy-variable} will be set to the result of the @code{(ding)}
3703 form, but who cares?
3707 If you want to change the group info you can use the @kbd{G E} command
3708 to enter a buffer where you can edit it.
3710 You usually don't want to edit the entire group info, so you'd be better
3711 off using the @kbd{G p} command to just edit the group parameters.
3713 @node Listing Groups
3714 @section Listing Groups
3715 @cindex group listing
3717 These commands all list various slices of the groups that are available.
3725 @findex gnus-group-list-groups
3726 List all groups that have unread articles
3727 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
3728 command will list only groups of level ARG and lower. By default, it
3729 only lists groups of level five or lower (i.e., just subscribed groups).
3735 @findex gnus-group-list-all-groups
3736 List all groups, whether they have unread articles or not
3737 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
3738 this command will list only groups of level ARG and lower. By default,
3739 it lists groups of level seven or lower (i.e., just subscribed and
3740 unsubscribed groups).
3744 @findex gnus-group-list-level
3745 List all unread groups on a specific level
3746 (@code{gnus-group-list-level}). If given a prefix, also list the groups
3747 with no unread articles.
3751 @findex gnus-group-list-killed
3752 List all killed groups (@code{gnus-group-list-killed}). If given a
3753 prefix argument, really list all groups that are available, but aren't
3754 currently (un)subscribed. This could entail reading the active file
3759 @findex gnus-group-list-zombies
3760 List all zombie groups (@code{gnus-group-list-zombies}).
3764 @findex gnus-group-list-matching
3765 List all subscribed groups with unread articles that match a regexp
3766 (@code{gnus-group-list-matching}).
3770 @findex gnus-group-list-all-matching
3771 List groups that match a regexp (@code{gnus-group-list-all-matching}).
3775 @findex gnus-group-list-active
3776 List absolutely all groups that are in the active file(s) of the
3777 server(s) you are connected to (@code{gnus-group-list-active}). This
3778 might very well take quite a while. It might actually be a better idea
3779 to do a @kbd{A m} to list all matching, and just give @samp{.} as the
3784 @vindex gnus-permanently-visible-groups
3785 @cindex visible group parameter
3786 Groups that match the @code{gnus-permanently-visible-groups} regexp will
3787 always be shown, whether they have unread articles or not. You can also
3788 add the @code{visible} element to the group parameters in question to
3789 get the same effect.
3791 @vindex gnus-list-groups-with-ticked-articles
3792 Groups that have just ticked articles in it are normally listed in the
3793 group buffer. If @code{gnus-list-groups-with-ticked-articles} is
3794 @code{nil}, these groups will be treated just like totally empty
3795 groups. It is @code{t} by default.
3798 @node Sorting Groups
3799 @section Sorting Groups
3800 @cindex sorting groups
3802 @kindex C-c C-s (Group)
3803 @findex gnus-group-sort-groups
3804 @vindex gnus-group-sort-function
3805 The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the
3806 group buffer according to the function(s) given by the
3807 @code{gnus-group-sort-function} variable. Available sorting functions
3812 @item gnus-group-sort-by-alphabet
3813 @findex gnus-group-sort-by-alphabet
3814 Sort the group names alphabetically. This is the default.
3816 @item gnus-group-sort-by-level
3817 @findex gnus-group-sort-by-level
3818 Sort by group level.
3820 @item gnus-group-sort-by-score
3821 @findex gnus-group-sort-by-score
3822 Sort by group score.
3824 @item gnus-group-sort-by-rank
3825 @findex gnus-group-sort-by-rank
3826 Sort by group score and then the group level. The level and the score
3827 are, when taken together, the group's @dfn{rank}.
3829 @item gnus-group-sort-by-unread
3830 @findex gnus-group-sort-by-unread
3831 Sort by number of unread articles.
3833 @item gnus-group-sort-by-method
3834 @findex gnus-group-sort-by-method
3835 Sort by alphabetically on the select method.
3840 @code{gnus-group-sort-function} can also be a list of sorting
3841 functions. In that case, the most significant sort key function must be
3845 There are also a number of commands for sorting directly according to
3846 some sorting criteria:
3850 @kindex G S a (Group)
3851 @findex gnus-group-sort-groups-by-alphabet
3852 Sort the group buffer alphabetically by group name
3853 (@code{gnus-group-sort-groups-by-alphabet}).
3856 @kindex G S u (Group)
3857 @findex gnus-group-sort-groups-by-unread
3858 Sort the group buffer by the number of unread articles
3859 (@code{gnus-group-sort-groups-by-unread}).
3862 @kindex G S l (Group)
3863 @findex gnus-group-sort-groups-by-level
3864 Sort the group buffer by group level
3865 (@code{gnus-group-sort-groups-by-level}).
3868 @kindex G S v (Group)
3869 @findex gnus-group-sort-groups-by-score
3870 Sort the group buffer by group score
3871 (@code{gnus-group-sort-groups-by-score}).
3874 @kindex G S r (Group)
3875 @findex gnus-group-sort-groups-by-rank
3876 Sort the group buffer by group level
3877 (@code{gnus-group-sort-groups-by-rank}).
3880 @kindex G S m (Group)
3881 @findex gnus-group-sort-groups-by-method
3882 Sort the group buffer alphabetically by backend name
3883 (@code{gnus-group-sort-groups-by-method}).
3887 When given a prefix, all these commands will sort in reverse order.
3891 @node Group Maintenance
3892 @section Group Maintenance
3893 @cindex bogus groups
3898 @findex gnus-group-check-bogus-groups
3899 Find bogus groups and delete them
3900 (@code{gnus-group-check-bogus-groups}).
3904 @findex gnus-find-new-newsgroups
3905 Find new groups and process them (@code{gnus-find-new-newsgroups}). If
3906 given a prefix, use the @code{ask-server} method to query the server for
3910 @kindex C-c C-x (Group)
3911 @findex gnus-group-expire-articles
3912 Run all expirable articles in the current group through the expiry
3913 process (if any) (@code{gnus-group-expire-articles}).
3916 @kindex C-c M-C-x (Group)
3917 @findex gnus-group-expire-all-groups
3918 Run all articles in all groups through the expiry process
3919 (@code{gnus-group-expire-all-groups}).
3924 @node Browse Foreign Server
3925 @section Browse Foreign Server
3926 @cindex foreign servers
3927 @cindex browsing servers
3932 @findex gnus-group-browse-foreign-server
3933 You will be queried for a select method and a server name. Gnus will
3934 then attempt to contact this server and let you browse the groups there
3935 (@code{gnus-group-browse-foreign-server}).
3938 @findex gnus-browse-server-mode
3939 A new buffer with a list of available groups will appear. This buffer
3940 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
3941 (well, a lot) like a normal group buffer, but with one major difference
3942 - you can't enter any of the groups. If you want to read any of the
3943 news available on that server, you have to subscribe to the groups you
3944 think may be interesting, and then you have to exit this buffer. The
3945 new groups will be added to the group buffer, and then you can read them
3946 as you would any other group.
3948 Future versions of Gnus may possibly permit reading groups straight from
3951 Here's a list of keystrokes available in the browse mode:
3956 @findex gnus-group-next-group
3957 Go to the next group (@code{gnus-group-next-group}).
3961 @findex gnus-group-prev-group
3962 Go to the previous group (@code{gnus-group-prev-group}).
3965 @kindex SPACE (Browse)
3966 @findex gnus-browse-read-group
3967 Enter the current group and display the first article
3968 (@code{gnus-browse-read-group}).
3971 @kindex RET (Browse)
3972 @findex gnus-browse-select-group
3973 Enter the current group (@code{gnus-browse-select-group}).
3977 @findex gnus-browse-unsubscribe-current-group
3978 Unsubscribe to the current group, or, as will be the case here,
3979 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
3985 @findex gnus-browse-exit
3986 Exit browse mode (@code{gnus-browse-exit}).
3990 @findex gnus-browse-describe-briefly
3991 Describe browse mode briefly (well, there's not much to describe, is
3992 there) (@code{gnus-browse-describe-briefly}).
3996 @section Exiting Gnus
3997 @cindex exiting Gnus
3999 Yes, Gnus is ex(c)iting.
4004 @findex gnus-group-suspend
4005 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
4006 but it kills all buffers except the Group buffer. I'm not sure why this
4007 is a gain, but then who am I to judge?
4011 @findex gnus-group-exit
4012 Quit Gnus (@code{gnus-group-exit}).
4016 @findex gnus-group-quit
4017 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
4020 @vindex gnus-exit-gnus-hook
4021 @vindex gnus-suspend-gnus-hook
4022 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
4023 @code{gnus-exit-gnus-hook} is called when you quit Gnus.
4027 If you wish to completely unload Gnus and all its adherents, you can use
4028 the @code{gnus-unload} command. This command is also very handy when
4029 trying to customize meta-variables.
4034 Miss Lisa Cannifax, while sitting in English class, feels her feet go
4035 numbly heavy and herself fall into a hazy trance as the boy sitting
4036 behind her drew repeated lines with his pencil across the back of her
4042 @section Group Topics
4045 If you read lots and lots of groups, it might be convenient to group
4046 them hierarchically according to topics. You put your Emacs groups over
4047 here, your sex groups over there, and the rest (what, two groups or so?)
4048 you put in some misc section that you never bother with anyway. You can
4049 even group the Emacs sex groups as a sub-topic to either the Emacs
4050 groups or the sex groups---or both! Go wild!
4052 @findex gnus-topic-mode
4054 To get this @emph{fab} functionality you simply turn on (ooh!) the
4055 @code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
4056 is a toggling command.)
4058 Go ahead, just try it. I'll still be here when you get back. La de
4059 dum... Nice tune, that... la la la... What, you're back? Yes, and now
4060 press @kbd{l}. There. All your groups are now listed under
4061 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
4064 If you want this permanently enabled, you should add that minor mode to
4065 the hook for the group mode:
4068 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
4072 * Topic Variables:: How to customize the topics the Lisp Way.
4073 * Topic Commands:: Interactive E-Z commands.
4074 * Topic Topology:: A map of the world.
4078 @node Topic Variables
4079 @subsection Topic Variables
4080 @cindex topic variables
4083 @vindex gnus-topic-unique
4084 If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
4085 of (tops) one topic each. If this is @code{nil}, each group might end
4086 up being a member of several topics.
4088 Now, if you select a topic, if will fold/unfold that topic, which is
4089 really neat, I think.
4091 @vindex gnus-topic-line-format
4092 The topic lines themselves are created according to the
4093 @code{gnus-topic-line-format} variable. @xref{Formatting Variables}.
4094 Elements allowed are:
4106 Number of groups in the topic.
4108 Number of unread articles in the topic.
4110 Number of unread articles in the topic and all its subtopics.
4113 @vindex gnus-topic-indent-level
4114 Each sub-topic (and the groups in the sub-topics) will be indented with
4115 @code{gnus-topic-indent-level} times the topic level number of spaces.
4116 The default is @samp{2}.
4119 @node Topic Commands
4120 @subsection Topic Commands
4121 @cindex topic commands
4123 When the topic minor mode is turned on, a new @kbd{T} submap will be
4124 available. In addition, a few of the standard keys change their
4125 definitions slightly.
4131 @findex gnus-topic-create-topic
4132 Create a new topic (@code{gnus-topic-create-subtopic}). You will be
4133 prompted for a topic name and the name of the parent topic.
4137 @findex gnus-topic-move-group
4138 Move the current group to some other topic
4139 (@code{gnus-topic-move-group}). This command understands the
4140 process/prefix convention (@pxref{Process/Prefix}).
4144 @findex gnus-topic-copy-group
4145 Copy the current group to some other topic
4146 (@code{gnus-topic-copy-group}). This command understands the
4147 process/prefix convention (@pxref{Process/Prefix}).
4151 @findex gnus-topic-remove-group
4152 Remove a group from the current topic (@code{gnus-topic-remove-group}).
4153 This command understands the process/prefix convention
4154 (@pxref{Process/Prefix}).
4158 @findex gnus-topic-move-matching
4159 Move all groups that match some regular expression to a topic
4160 (@code{gnus-topic-move-matching}).
4164 @findex gnus-topic-copy-matching
4165 Copy all groups that match some regular expression to a topic
4166 (@code{gnus-topic-copy-matching}).
4170 @findex gnus-topic-select-group
4172 Either select a group or fold a topic (@code{gnus-topic-select-group}).
4173 When you perform this command on a group, you'll enter the group, as
4174 usual. When done on a topic line, the topic will be folded (if it was
4175 visible) or unfolded (if it was folded already). So it's basically a
4176 toggling command on topics. In addition, if you give a numerical
4177 prefix, group on that level (and lower) will be displayed.
4181 @findex gnus-topic-indent
4182 ``Indent'' the current topic so that it becomes a sub-topic of the
4183 previous topic (@code{gnus-topic-indent}). If given a prefix,
4184 ``un-indent'' the topic instead.
4188 @findex gnus-topic-kill-group
4189 Kill a group or topic (@code{gnus-topic-kill-group}).
4193 @findex gnus-topic-yank-group
4194 Yank the previously killed group or topic (@code{gnus-topic-yank-group}).
4195 Note that all topics will be yanked before all groups.
4199 @findex gnus-topic-rename
4200 Rename a topic (@code{gnus-topic-rename}).
4203 @kindex T DEL (Group)
4204 @findex gnus-topic-delete
4205 Delete an empty topic (@code{gnus-topic-delete}).
4209 @findex gnus-topic-list-active
4210 List all groups that Gnus knows about in a topics-ified way
4211 (@code{gnus-topic-list-active}).
4216 @node Topic Topology
4217 @subsection Topic Topology
4218 @cindex topic topology
4221 So, let's have a look at an example group buffer:
4227 2: alt.religion.emacs
4230 0: comp.talk.emacs.recovery
4232 8: comp.binaries.fractals
4233 13: comp.sources.unix
4236 So, here we have one top-level topic, two topics under that, and one
4237 sub-topic under one of the sub-topics. (There is always just one (1)
4238 top-level topic). This topology can be expressed as follows:
4242 (("Emacs -- I wuw it!" visible)
4243 (("Naughty Emacs" visible)))
4247 This is in fact how the variable @code{gnus-topic-topology} would look
4248 for the display above. That variable is saved in the @file{.newsrc.eld}
4249 file, and shouldn't be messed with manually---unless you really want
4250 to. Since this variable is read from the @file{.newsrc.eld} file,
4251 setting it in any other startup files will have no effect.
4253 This topology shows what topics are sub-topics of what topics (right),
4254 and which topics are visible. Two settings are currently
4255 allowed---@code{visible} and @code{invisible}.
4258 @node Misc Group Stuff
4259 @section Misc Group Stuff
4265 @findex gnus-group-get-new-news
4266 Check the server(s) for new articles. If the numerical prefix is used,
4267 this command will check only groups of level @var{arg} and lower
4268 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
4269 command will force a total rereading of the active file(s) from the
4274 @findex gnus-group-get-new-news-this-group
4275 @vindex gnus-goto-next-group-when-activating
4276 Check whether new articles have arrived in the current group
4277 (@code{gnus-group-get-new-news-this-group}). The
4278 @code{gnus-goto-next-group-when-activating} variable controls whether
4279 this command is to move point to the next group or not. It is @code{t}
4282 @findex gnus-activate-all-groups
4284 @kindex C-c M-g (Group)
4285 Activate absolutely all groups (@code{gnus-activate-all-groups}).
4289 @findex gnus-group-enter-server-mode
4290 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
4295 @findex gnus-group-fetch-faq
4296 Try to fetch the FAQ for the current group
4297 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
4298 @code{gnus-group-faq-directory}, which is usually a directory on a
4299 remote machine. @code{ange-ftp} will be used for fetching the file.
4303 @findex gnus-group-restart
4304 Restart Gnus (@code{gnus-group-restart}).
4308 @findex gnus-group-read-init-file
4309 @vindex gnus-init-file
4310 Read the init file (@code{gnus-init-file}, which defaults to
4311 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
4315 @findex gnus-group-save-newsrc
4316 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
4317 (@code{gnus-group-save-newsrc}). If given a prefix, force saving the
4318 file(s) whether Gnus thinks it is necessary or not.
4322 @findex gnus-group-clear-dribble
4323 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
4327 @findex gnus-group-describe-group
4328 Describe the current group (@code{gnus-group-describe-group}). If given
4329 a prefix, force Gnus to re-read the description from the server.
4333 @findex gnus-group-apropos
4334 List all groups that have names that match a regexp
4335 (@code{gnus-group-apropos}).
4339 @findex gnus-group-description-apropos
4340 List all groups that have names or descriptions that match a regexp
4341 (@code{gnus-group-description-apropos}).
4345 @findex gnus-group-post-news
4346 Post an article to a group (@code{gnus-group-post-news}). The current
4347 group name will be used as the default.
4351 @findex gnus-group-mail
4352 Mail a message somewhere (@code{gnus-group-mail}).
4355 @kindex C-x C-t (Group)
4356 @findex gnus-group-transpose-groups
4357 Transpose two groups (@code{gnus-group-transpose-groups}).
4361 @findex gnus-version
4362 Display current Gnus version numbers (@code{gnus-version}).
4366 @findex gnus-group-describe-all-groups
4367 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
4368 prefix, force Gnus to re-read the description file from the server.
4372 @findex gnus-group-describe-briefly
4373 Give a very short help message (@code{gnus-group-describe-briefly}).
4376 @kindex C-c C-i (Group)
4377 @findex gnus-info-find-node
4378 Go to the Gnus info node (@code{gnus-info-find-node}).
4381 @vindex gnus-group-prepare-hook
4382 @code{gnus-group-prepare-hook} is called after the group buffer is
4383 generated. It may be used to modify the buffer in some strange,
4386 @node The Summary Buffer
4387 @chapter The Summary Buffer
4388 @cindex summary buffer
4390 A line for each article is displayed in the summary buffer. You can
4391 move around, read articles, post articles and reply to articles.
4394 * Summary Buffer Format:: Deciding how the summary buffer is to look.
4395 * Summary Maneuvering:: Moving around the summary buffer.
4396 * Choosing Articles:: Reading articles.
4397 * Paging the Article:: Scrolling the current article.
4398 * Reply Followup and Post:: Posting articles.
4399 * Canceling and Superseding:: ``Whoops, I shouldn't have called him that.''
4400 * Marking Articles:: Marking articles as read, expirable, etc.
4401 * Limiting:: You can limit the summary buffer.
4402 * Threading:: How threads are made.
4403 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
4404 * Article Caching:: You may store articles in a cache.
4405 * Persistent Articles:: Making articles expiry-resistant.
4406 * Article Backlog:: Having already read articles hang around.
4407 * Exiting the Summary Buffer:: Returning to the Group buffer.
4408 * Process/Prefix:: A convention used by many treatment commands.
4409 * Saving Articles:: Ways of customizing article saving.
4410 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
4411 * Article Treatment:: The article buffer can be mangled at will.
4412 * Summary Sorting:: You can sort the summary buffer four ways.
4413 * Finding the Parent:: No child support? Get the parent.
4414 * Alternative Approaches:: Reading using non-default summaries.
4415 * Tree Display:: A more visual display of threads.
4416 * Mail Group Commands:: Some commands can only be used in mail groups.
4417 * Various Summary Stuff:: What didn't fit anywhere else.
4421 @node Summary Buffer Format
4422 @section Summary Buffer Format
4423 @cindex summary buffer format
4426 * Summary Buffer Lines:: You can specify how summary lines should look.
4427 * Summary Buffer Mode Line:: You can say how the mode line should look.
4430 @findex mail-extract-address-components
4431 @findex gnus-extract-address-components
4432 @vindex gnus-extract-address-components
4433 Gnus will use the value of the @code{gnus-extract-address-components}
4434 variable as a function for getting the name and address parts of a
4435 @code{From} header. Two pre-defined function exist:
4436 @code{gnus-extract-address-components}, which is the default, quite
4437 fast, and too simplistic solution; and
4438 @code{mail-extract-address-components}, which works very nicely, but is
4441 @vindex gnus-summary-same-subject
4442 @code{gnus-summary-same-subject} is a string indicating that the current
4443 article has the same subject as the previous. This string will be used
4444 with those specs that require it. The default is @samp{""}.
4446 @node Summary Buffer Lines
4447 @subsection Summary Buffer Lines
4449 @vindex gnus-summary-line-format
4450 You can change the format of the lines in the summary buffer by changing
4451 the @code{gnus-summary-line-format} variable. It works along the same
4452 lines a a normal @code{format} string, with some extensions.
4454 The default string is @samp{"%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n"}.
4456 The following format specification characters are understood:
4464 Subject if the article is the root, @code{gnus-summary-same-subject}
4467 Full @code{From} line.
4469 The name (from the @code{From} header).
4471 The name (from the @code{From} header). This differs from the @code{n}
4472 spec in that it uses @code{gnus-extract-address-components}, which is
4473 slower, but may be more thorough.
4475 The address (from the @code{From} header). This works the same way as
4478 Number of lines in the article.
4480 Number of characters in the article.
4482 Indentation based on thread level (@pxref{Customizing Threading}).
4484 Nothing if the article is a root and lots of spaces if it isn't (it
4485 pushes everything after it off the screen).
4487 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
4488 for adopted articles.
4490 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
4491 for adopted articles.
4493 One space for each thread level.
4495 Twenty minus thread level spaces.
4503 @vindex gnus-summary-zcore-fuzz
4504 Zcore, @samp{+} if above the default level and @samp{-} if below the
4505 default level. If the difference between
4506 @code{gnus-summary-default-level} and the score is less than
4507 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
4519 Number of articles in the current sub-thread. Using this spec will slow
4520 down summary buffer generation somewhat.
4522 A single character will be displayed if the article has any children.
4524 User defined specifier. The next character in the format string should
4525 be a letter. @sc{gnus} will call the function
4526 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
4527 following @samp{%u}. The function will be passed the current header as
4528 argument. The function should return a string, which will be inserted
4529 into the summary just like information from any other summary specifier.
4532 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
4533 have to be handled with care. For reasons of efficiency, Gnus will
4534 compute what column these characters will end up in, and ``hard-code''
4535 that. This means that it is illegal to have these specs after a
4536 variable-length spec. Well, you might not be arrested, but your summary
4537 buffer will look strange, which is bad enough.
4539 The smart choice is to have these specs as far to the left as possible.
4540 (Isn't that the case with everything, though? But I digress.)
4542 This restriction may disappear in later versions of Gnus.
4544 @node Summary Buffer Mode Line
4545 @subsection Summary Buffer Mode Line
4547 @vindex gnus-summary-mode-line-format
4548 You can also change the format of the summary mode bar. Set
4549 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
4550 elements you can play with:
4556 Unprefixed group name.
4558 Current article number.
4562 Number of unread articles in this group.
4564 Number of unselected articles in this group.
4566 A string with the number of unread and unselected articles represented
4567 either as @samp{<%U(+%u) more>} if there are both unread and unselected
4568 articles, and just as @samp{<%U more>} if there are just unread articles
4569 and no unselected ones.
4571 Shortish group name. For instance, @samp{rec.arts.anime} will be
4572 shortened to @samp{r.a.anime}.
4574 Subject of the current article.
4578 Name of the current score file.
4580 Number of dormant articles.
4582 Number of ticked articles.
4584 Number of articles that have been marked as read in this session.
4586 Number of articles expunged by the score files.
4590 @node Summary Maneuvering
4591 @section Summary Maneuvering
4592 @cindex summary movement
4594 All the straight movement commands understand the numeric prefix and
4595 behave pretty much as you'd expect.
4597 None of these commands select articles.
4602 @kindex M-n (Summary)
4603 @kindex G M-n (Summary)
4604 @findex gnus-summary-next-unread-subject
4605 Go to the next summary line of an unread article
4606 (@code{gnus-summary-next-unread-subject}).
4610 @kindex M-p (Summary)
4611 @kindex G M-p (Summary)
4612 @findex gnus-summary-prev-unread-subject
4613 Go to the previous summary line of an unread article
4614 (@code{gnus-summary-prev-unread-subject}).
4619 @kindex G g (Summary)
4620 @findex gnus-summary-goto-subject
4621 Ask for an article number and then go to this summary line
4622 (@code{gnus-summary-goto-subject}).
4625 If Gnus asks you to press a key to confirm going to the next group, you
4626 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
4627 buffer, searching for the next group to read without actually returning
4628 to the group buffer.
4630 Variables related to summary movement:
4634 @vindex gnus-auto-select-next
4635 @item gnus-auto-select-next
4636 If you are at the end of the group and issue one of the movement
4637 commands, Gnus will offer to go to the next group. If this variable is
4638 @code{t} and the next group is empty, Gnus will exit summary mode and
4639 return to the group buffer. If this variable is neither @code{t} nor
4640 @code{nil}, Gnus will select the next group, no matter whether it has
4641 any unread articles or not. As a special case, if this variable is
4642 @code{quietly}, Gnus will select the next group without asking for
4643 confirmation. If this variable is @code{almost-quietly}, the same will
4644 happen only if you are located on the last article in the group.
4645 Finally, if this variable is @code{slightly-quietly}, the @kbd{Z n}
4646 command will go to the next group without confirmation. Also
4647 @xref{Group Levels}.
4649 @item gnus-auto-select-same
4650 @vindex gnus-auto-select-same
4651 If non-@code{nil}, all the movement commands will try to go to the next
4652 article with the same subject as the current. This variable is not
4653 particularly useful if you use a threaded display.
4655 @item gnus-summary-check-current
4656 @vindex gnus-summary-check-current
4657 If non-@code{nil}, all the ``unread'' movement commands will not proceed
4658 to the next (or previous) article if the current article is unread.
4659 Instead, they will choose the current article.
4661 @item gnus-auto-center-summary
4662 @vindex gnus-auto-center-summary
4663 If non-@code{nil}, Gnus will keep the point in the summary buffer
4664 centered at all times. This makes things quite tidy, but if you have a
4665 slow network connection, or simply do not like this un-Emacsism, you can
4666 set this variable to @code{nil} to get the normal Emacs scrolling
4667 action. This will also inhibit horizontal re-centering of the summary
4668 buffer, which might make it more inconvenient to read extremely long
4674 @node Choosing Articles
4675 @section Choosing Articles
4676 @cindex selecting articles
4678 None of the following movement commands understand the numeric prefix,
4679 and they all select and display an article.
4683 @kindex SPACE (Summary)
4684 @findex gnus-summary-next-page
4685 Select the current article, or, if that one's read already, the next
4686 unread article (@code{gnus-summary-next-page}).
4691 @kindex G n (Summary)
4692 @findex gnus-summary-next-unread-article
4693 Go to next unread article (@code{gnus-summary-next-unread-article}).
4698 @findex gnus-summary-prev-unread-article
4699 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
4704 @kindex G N (Summary)
4705 @findex gnus-summary-next-article
4706 Go to the next article (@code{gnus-summary-next-article}).
4711 @kindex G P (Summary)
4712 @findex gnus-summary-prev-article
4713 Go to the previous article (@code{gnus-summary-prev-article}).
4716 @kindex G C-n (Summary)
4717 @findex gnus-summary-next-same-subject
4718 Go to the next article with the same subject
4719 (@code{gnus-summary-next-same-subject}).
4722 @kindex G C-p (Summary)
4723 @findex gnus-summary-prev-same-subject
4724 Go to the previous article with the same subject
4725 (@code{gnus-summary-prev-same-subject}).
4729 @kindex G f (Summary)
4731 @findex gnus-summary-first-unread-article
4732 Go to the first unread article
4733 (@code{gnus-summary-first-unread-article}).
4737 @kindex G b (Summary)
4739 Go to the article with the highest score
4740 (@code{gnus-summary-best-unread-article}).
4745 @kindex G l (Summary)
4746 @findex gnus-summary-goto-last-article
4747 Go to the previous article read (@code{gnus-summary-goto-last-article}).
4750 @kindex G p (Summary)
4751 @findex gnus-summary-pop-article
4752 Pop an article off the summary history and go to this article
4753 (@code{gnus-summary-pop-article}). This command differs from the
4754 command above in that you can pop as many previous articles off the
4755 history as you like.
4758 Some variables that are relevant for moving and selecting articles:
4761 @item gnus-auto-extend-newsgroup
4762 @vindex gnus-auto-extend-newsgroup
4763 All the movement commands will try to go to the previous (or next)
4764 article, even if that article isn't displayed in the Summary buffer if
4765 this variable is non-@code{nil}. Gnus will then fetch the article from
4766 the server and display it in the article buffer.
4768 @item gnus-select-article-hook
4769 @vindex gnus-select-article-hook
4770 This hook is called whenever an article is selected. By default it
4771 exposes any threads hidden under the selected article.
4773 @item gnus-mark-article-hook
4774 @vindex gnus-mark-article-hook
4775 This hook is called whenever an article is selected. It is intended to
4776 be used for marking articles as read.
4778 @item gnus-visual-mark-article-hook
4779 @vindex gnus-visual-mark-article-hook
4780 This hook is run after selecting an article. It is meant to be used for
4781 highlighting the article in some way. It is not run if
4782 @code{gnus-visual} is @code{nil}.
4784 @item gnus-summary-update-hook
4785 @vindex gnus-summary-update-hook
4786 This hook is called when a summary line is changed. It is not run if
4787 @code{gnus-visual} is @code{nil}.
4789 @item gnus-summary-selected-face
4790 @vindex gnus-summary-selected-face
4791 This is the face (or @dfn{font} as some people call it) that is used to
4792 highlight the current article in the summary buffer.
4794 @item gnus-summary-highlight
4795 @vindex gnus-summary-highlight
4796 Summary lines are highlighted according to this variable, which is a
4797 list where the elements are on the format @code{(FORM . FACE)}. If you
4798 would, for instance, like ticked articles to be italic and high-scored
4799 articles to be bold, you could set this variable to something like
4801 (((eq mark gnus-ticked-mark) . italic)
4802 ((> score default) . bold))
4804 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
4805 @var{FACE} will be applied to the line.
4808 @node Paging the Article
4809 @section Scrolling the Article
4810 @cindex article scrolling
4815 @kindex SPACE (Summary)
4816 @findex gnus-summary-next-page
4817 Pressing @kbd{SPACE} will scroll the current article forward one page,
4818 or, if you have come to the end of the current article, will choose the
4819 next article (@code{gnus-summary-next-page}).
4822 @kindex DEL (Summary)
4823 @findex gnus-summary-prev-page
4824 Scroll the current article back one page (@code{gnus-summary-prev-page}).
4827 @kindex RET (Summary)
4828 @findex gnus-summary-scroll-up
4829 Scroll the current article one line forward
4830 (@code{gnus-summary-scroll-up}).
4835 @kindex A < (Summary)
4836 @findex gnus-summary-beginning-of-article
4837 Scroll to the beginning of the article
4838 (@code{gnus-summary-beginning-of-article}).
4843 @kindex A > (Summary)
4844 @findex gnus-summary-end-of-article
4845 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
4848 @kindex A s (Summary)
4849 @findex gnus-summary-isearch-article
4850 Perform an isearch in the article buffer
4851 (@code{gnus-summary-isearch-article}).
4855 @node Reply Followup and Post
4856 @section Reply, Followup and Post
4861 @kindex C-c C-c (Post)
4862 All the commands for posting and mailing will put you in a post or mail
4863 buffer where you can edit the article all you like, before you send the
4864 article by pressing @kbd{C-c C-c}. If you are in a foreign news group,
4865 and you wish to post the article using the foreign server, you can give
4866 a prefix to @kbd{C-c C-c} to make Gnus try to post using the foreign
4870 * Mail:: Mailing & replying.
4871 * Post:: Posting and following up.
4872 * Posting Server:: What server should you post via?
4873 * Mail and Post:: Mailing and posting at the same time.
4874 * Archived Messages:: Where Gnus stores the messages you've sent.
4875 * Posting Styles:: An easier way to configure some key elements.
4876 * Drafts:: Postponing messages and rejected messages.
4877 * Rejected Articles:: What happens if the server doesn't like your article?
4883 Commands for composing a mail message:
4889 @kindex S r (Summary)
4891 @findex gnus-summary-reply
4892 Mail a reply to the author of the current article
4893 (@code{gnus-summary-reply}).
4898 @kindex S R (Summary)
4899 @findex gnus-summary-reply-with-original
4900 Mail a reply to the author of the current article and include the
4901 original message (@code{gnus-summary-reply-with-original}). This
4902 command uses the process/prefix convention.
4905 @kindex S o m (Summary)
4906 @findex gnus-summary-mail-forward
4907 Forward the current article to some other person
4908 (@code{gnus-summary-mail-forward}).
4911 @kindex S o p (Summary)
4912 @findex gnus-summary-post-forward
4913 Forward the current article to a newsgroup
4914 (@code{gnus-summary-post-forward}).
4919 @kindex S m (Summary)
4920 @findex gnus-summary-mail-other-window
4921 Send a mail to some other person
4922 (@code{gnus-summary-mail-other-window}).
4925 @kindex S D b (Summary)
4926 @findex gnus-summary-resend-bounced-mail
4927 If you have sent a mail, but the mail was bounced back to you for some
4928 reason (wrong address, transient failure), you can use this command to
4929 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
4930 will be popped into a mail buffer where you can edit the headers before
4931 sending the mail off again. The headers that match the regexp
4932 @code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
4933 automatically deleted first. If you give a prefix to this command, and
4934 the bounced mail is a reply to some other mail, Gnus will try to fetch
4935 that mail and display it for easy perusal of its headers. This might
4936 very well fail, though.
4939 @kindex S D r (Summary)
4940 @findex gnus-summary-resend-message
4941 Not to be confused with the previous command,
4942 @code{gnus-summary-resend-message} will prompt you for an address to
4943 send the current message off to, and then send it to that place. The
4944 headers of the message won't be altered---but lots of headers that say
4945 @samp{Resent-To}, @samp{Resent-From} and so on will be added. This
4946 means that you actually send a mail to someone that has a @samp{To}
4947 header that (probably) points to yourself. This will confuse people.
4948 So, natcherly you'll only do that if you're really eVIl.
4950 This command is mainly used if you have several accounts and want to
4951 ship a mail to a different account of yours. (If you're both
4952 @samp{root} and @samp{postmaster} and get a mail for @samp{postmaster}
4953 to the @samp{root} account, you may want to resend it to
4954 @samp{postmaster}. Ordnung muss sein!
4957 @kindex S O m (Summary)
4958 @findex gnus-uu-digest-mail-forward
4959 Digest the current series and forward the result using mail
4960 (@code{gnus-uu-digest-mail-forward}). This command uses the
4961 process/prefix convention (@pxref{Process/Prefix}).
4964 @kindex S O p (Summary)
4965 @findex gnus-uu-digest-post-forward
4966 Digest the current series and forward the result to a newsgroup
4967 (@code{gnus-uu-digest-mail-forward}).
4970 Variables for customizing outgoing mail:
4973 @item gnus-reply-to-function
4974 @vindex gnus-reply-to-function
4975 Gnus uses the normal methods to determine where replies are to go, but
4976 you can change the behavior to suit your needs by fiddling with this
4979 If you want the replies to go to the @samp{Sender} instead of the
4980 @samp{From} in the group @samp{mail.stupid-list}, you could do something
4984 (setq gnus-reply-to-function
4986 (cond ((string= group "mail.stupid-list")
4987 (mail-fetch-field "sender"))
4992 This function will be called narrowed to the head of the article that is
4995 As you can see, this function should return a string if it has an
4996 opinion as to what the To header should be. If it does not, it should
4997 just return @code{nil}, and the normal methods for determining the To
4998 header will be used.
5000 This function can also return a list. In that case, each list element
5001 should be a cons, where the car should be the name of an header
5002 (eg. @samp{Cc}) and the cdr should be the header value
5003 (eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
5004 the head of the outgoing mail.
5006 @item gnus-mail-send-method
5007 @vindex gnus-mail-send-method
5008 This variable says how a mail should be mailed. It uses the function in
5009 the @code{send-mail-function} variable as the default.
5011 @item gnus-uu-digest-headers
5012 @vindex gnus-uu-digest-headers
5013 List of regexps to match headers included in digested messages. The
5014 headers will be included in the sequence they are matched.
5016 @item gnus-mail-hook
5017 @vindex gnus-mail-hook
5018 Hook called as the last thing after setting up a mail buffer.
5020 @item gnus-required-mail-headers
5021 @vindex gnus-required-mail-headers
5022 Gnus will generate headers in all outgoing mail instead of letting
5023 @code{sendmail} do it for us. This makes it possible to do more neat
5024 stuff, like putting mail without sending it, do hairy @code{Fcc}
5025 handling, and much more. This variable controls what headers Gnus will
5026 generate, and is of the exact same form as @code{gnus-required-headers},
5027 which does the same for news articles (@pxref{Post}).
5029 The @code{Newsgroups} header is illegal in this list, while @code{To} is
5030 required, and @code{X-Mailer} can be added if you so should want.
5032 @findex gnus-forward-start-separator
5033 @item gnus-forward-start-separator
5034 Delimiter inserted before forwarded messages.
5036 @findex gnus-forward-end-separator
5037 @item gnus-forward-end-separator
5038 Delimiter inserted after forwarded messages.
5040 @vindex gnus-signature-before-forwarded-message
5041 @item gnus-signature-before-forwarded-message
5042 If this variable is @code{t}, which it is by default, your personal
5043 signature will be inserted before the forwarded message. If not, the
5044 forwarded message will be inserted first in the new mail.
5046 @item gnus-forward-included-headers
5047 @vindex gnus-forward-included-headers
5048 Regexp matching header lines to be included in forwarded messages. It
5049 uses the same regexp as @code{gnus-visible-headers} by default.
5053 @kindex C-c C-c (Mail)
5054 @kindex C-c C-p (Mail)
5055 @findex gnus-put-message
5056 You normally send a mail message by pressing @kbd{C-c C-c}. However,
5057 you may wish to just put the mail message you have just written in your
5058 own local mail group instead of sending it. Sounds quite unlikely, but
5059 I found that useful, so you can now also press @kbd{C-c C-p} to
5060 @dfn{put} the article in the current mail group, or, if there is no such
5061 thing, you will be prompted for a mail group, and then the article will
5062 be put there. This means that the article is @dfn{not} mailed.
5064 @findex gnus-kill-message-buffer
5065 @cindex kill mail buffer
5066 @kindex C-x k (Mail)
5067 @kindex C-x k (Post)
5068 If enter a mail (or post) buffer and then decide not to compose a
5069 message after all, you'd normally just kill the buffer with @kbd{C-x k}.
5070 However, since the mail and post buffers are associated with articles in
5071 the draft group, this will leave lots of rubbish articles in the draft
5072 group. To avoid that problem, kill mail and post buffer with @kbd{C-c
5073 C-k} (@code{gnus-kill-message-buffer}) instead. This will make sure
5074 that everything is properly cleaned up before the buffer is killed.
5076 There are three ``methods'' for handling all mail. The default is
5077 @code{sendmail}. Some people like what @code{mh} does better, and some
5078 people prefer @code{vm}.
5080 Three variables for customizing what to use when:
5084 @vindex gnus-mail-reply-method
5085 @item gnus-mail-reply-method
5086 This function is used to compose replies. The three functions available
5089 @findex gnus-mail-reply-using-vm
5090 @findex gnus-mail-reply-using-mhe
5091 @findex gnus-mail-reply-using-mail
5094 @code{gnus-mail-reply-using-mail} (sendmail)
5096 @code{gnus-mail-reply-using-mhe} (mh)
5098 @code{gnus-mail-reply-using-vm} (vm)
5101 @vindex gnus-mail-forward-method
5102 @item gnus-mail-forward-method
5103 This function is used to forward messages. The three functions available
5106 @findex gnus-mail-forward-using-vm
5107 @findex gnus-mail-forward-using-mhe
5108 @findex gnus-mail-forward-using-mail
5111 @code{gnus-mail-forward-using-mail} (sendmail)
5113 @code{gnus-mail-forward-using-mhe} (mh)
5115 @code{gnus-mail-forward-using-vm} (vm)
5118 @vindex gnus-mail-other-window-method
5119 @item gnus-mail-other-window-method
5120 This function is used to send mails. The three functions available are:
5122 @findex gnus-mail-other-window-using-vm
5123 @findex gnus-mail-other-window-using-mhe
5124 @findex gnus-mail-other-window-using-mail
5127 @code{gnus-mail-other-window-using-mail} (sendmail)
5129 @code{gnus-mail-other-window-using-mhe} (mh)
5131 @code{gnus-mail-other-window-using-vm} (vm)
5140 Commands for posting an article:
5146 @kindex S p (Summary)
5147 @findex gnus-summary-post-news
5148 Post an article to the current group
5149 (@code{gnus-summary-post-news}).
5154 @kindex S f (Summary)
5155 @findex gnus-summary-followup
5156 Post a followup to the current article (@code{gnus-summary-followup}).
5160 @kindex S F (Summary)
5162 @findex gnus-summary-followup-with-original
5163 Post a followup to the current article and include the original message
5164 (@code{gnus-summary-followup-with-original}). This command uses the
5165 process/prefix convention.
5168 @kindex S u (Summary)
5169 @findex gnus-uu-post-news
5170 Uuencode a file, split it into parts, and post it as a series
5171 (@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}).
5174 @vindex gnus-required-headers
5175 @code{gnus-required-headers} a list of header symbols. These headers
5176 will either be automatically generated, or, if that's impossible, they
5177 will be prompted for. The following symbols are legal:
5182 This required header will be filled out with the result of the
5183 @code{gnus-inews-user-name} function, which depends on the
5184 @code{gnus-user-from-line}, @code{gnus-user-login-name},
5185 @code{gnus-local-domain} and @code{user-mail-address} variables.
5188 This required header will be prompted for if not present already.
5191 This required header says which newsgroups the article is to be posted
5192 to. If it isn't present already, it will be prompted for.
5195 @cindex organization
5196 @vindex gnus-local-organization
5197 @vindex gnus-organization-file
5198 This optional header will be filled out depending on the
5199 @code{gnus-local-organization} variable. @code{gnus-organization-file}
5200 will be used if that variable is nil.
5203 This optional header will be computed by Gnus.
5207 This required header will be generated by Gnus. A unique ID will be
5208 created based on date, time, user name and system name.
5211 @cindex X-Newsreader
5212 This optional header will be filled out with the Gnus version numbers.
5215 @vindex gnus-article-expires
5217 This extremely optional header will be inserted according to the
5218 @code{gnus-article-expires} variable. It is highly deprecated and
5219 shouldn't be used unless you know what you're doing.
5222 This optional header is filled out according to the
5223 @code{gnus-distribution-function} variable. It is a deprecated and much
5224 misunderstood header.
5227 In addition, you can enter conses into this list. The car of this cons
5228 should be a symbol. This symbol's name is the name of the header, and
5229 the cdr can either be a string to be entered verbatim as the value of
5230 this header, or it can be a function to be called. This function should
5231 return a string to be inserted. For instance, if you want to insert
5232 @samp{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
5233 into the list. If you want to insert a funny quote, you could enter
5234 something like @code{(X-Yow . yow)} into the list. The function
5235 @code{yow} will then be called without any arguments.
5237 The list contains a cons where the car of the cons is @code{optional},
5238 the cdr of this cons will only be inserted if it is non-@code{nil}.
5240 Other variables for customizing outgoing articles:
5243 @item nntp-news-default-headers
5244 @vindex nntp-news-default-headers
5245 If non-@code{nil}, this variable will override
5246 @code{mail-default-headers} when posting. This variable should then be
5247 a string. This string will be inserted, as is, in the head of all
5250 @item gnus-use-followup-to
5251 @vindex gnus-use-followup-to
5252 If @code{nil}, always ignore the Followup-To header. If it is @code{t},
5253 use its value, but ignore the special value @samp{poster}, which will
5254 send the followup as a reply mail to the person you are responding to.
5255 If it is the symbol @code{ask}, query the user before posting.
5256 If it is the symbol @code{use}, always use the value.
5258 @item gnus-followup-to-function
5259 @vindex gnus-followup-to-function
5260 This variable is most useful in mail groups, where ``following up'' really
5261 means sending a mail to a list address. Gnus uses the normal methods to
5262 determine where follow-ups are to go, but you can change the behavior
5263 to suit your needs by fiddling with this variable.
5265 If you want the followups to go to the @samp{Sender} instead of the
5266 @samp{From} in the group @samp{mail.stupid-list}, you could do something
5270 (setq gnus-followup-to-function
5272 (cond ((string= group "mail.stupid-list")
5273 (mail-fetch-field "sender"))
5278 This function will be called narrowed to header of the article that is
5281 @item gnus-removable-headers
5282 @vindex gnus-removable-headers
5283 Some headers that are generated are toxic to the @sc{nntp} server.
5284 These include the @code{NNTP-Posting-Host}, @code{Bcc} and @code{Xref},
5285 so these headers are deleted if they are present in this list of
5288 @item gnus-deletable-headers
5289 @vindex gnus-deletable-headers
5290 Headers in this list that were previously generated by Gnus will be
5291 deleted before posting. Let's say you post an article. Then you decide
5292 to post it again to some other group, you naughty boy, so you jump back
5293 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
5294 ship it off again. By default, this variable makes sure that the old
5295 generated @code{Message-ID} is deleted, and a new one generated. If
5296 this isn't done, the entire empire would probably crumble, anarchy would
5297 prevail, and cats would start walking on two legs and rule the world.
5300 @item gnus-signature-function
5301 @vindex gnus-signature-function
5302 If non-@code{nil}, this variable should be a function that returns a
5303 signature file name. The function will be called with the name of the
5304 group being posted to. If the function returns a string that doesn't
5305 correspond to a file, the string itself is inserted. If the function
5306 returns @code{nil}, the @code{gnus-signature-file} variable will be used
5309 @item gnus-post-prepare-function
5310 @vindex gnus-post-prepare-function
5311 This function is called with the name of the current group after the
5312 post buffer has been initialized, and can be used for inserting a
5313 signature. Nice if you use different signatures in different groups.
5315 @item gnus-post-prepare-hook
5316 @vindex gnus-post-prepare-hook
5317 This hook is called after a post buffer has been prepared. If you want
5318 to insert a signature at this point, you could put
5319 @code{gnus-inews-insert-signature} into this hook.
5321 @item news-reply-header-hook
5322 @vindex news-reply-header-hook
5323 A related variable when following up and replying is this variable,
5324 which inserts the @dfn{quote line}. The default value is:
5327 (defvar news-reply-header-hook
5329 (insert "In article " news-reply-yank-message-id
5330 " " news-reply-yank-from " writes:\n\n")))
5333 This will create lines like:
5336 In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
5339 Having the @code{Message-ID} in this line is probably overkill, so I
5340 would suggest this hook instead:
5343 (setq news-reply-header-hook
5344 (lambda () (insert news-reply-yank-from " writes:\n\n")))
5347 @item gnus-prepare-article-hook
5348 @vindex gnus-prepare-article-hook
5349 This hook is called before the headers have been prepared.
5351 @item gnus-inews-article-function
5352 @vindex gnus-inews-article-function
5353 This function is used to do the actual article processing and header
5354 checking/generation.
5356 @item gnus-inews-article-hook
5357 @vindex gnus-inews-article-hook
5358 This hook is called right before the article is posted. By default it
5359 handles FCC processing (i.e., saving the article to a file.) You can
5360 also have this hook add a score to all followups to the article you've
5361 written (@pxref{Followups To Yourself}).
5363 @item gnus-inews-article-header-hook
5364 @vindex gnus-inews-article-header-hook
5365 This hook is called after inserting the required headers in an article
5366 to be posted. The hook is called from the @code{*post-news*} buffer,
5367 narrowed to the head, and is intended for people who would like to
5368 insert additional headers, or just change headers in some way or other.
5370 @item gnus-check-before-posting
5371 @vindex gnus-check-before-posting
5372 If non-@code{nil}, Gnus will attempt to check the legality of the
5373 headers, as well as some other stuff, before posting. You can control
5374 the granularity of the check by adding or removing elements from this
5375 list. Legal elements are:
5379 Check the subject for commands.
5381 Insert a new @code{Sender} header if the @code{From} header looks odd.
5382 @item multiple-headers
5383 Check for the existence of multiple equal headers.
5385 Check for the existence of version and sendsys commands.
5387 Check whether the @code{Message-ID} looks ok.
5389 Check whether the @code{From} header seems nice.
5391 Check for too long lines.
5393 Check for illegal characters.
5395 Check for excessive size.
5397 Check whether there is any new text in the messages.
5399 Check the length of the signature.
5401 Check whether the article has an @code{Approved} header, which is
5402 something only moderators should include.
5404 Check whether the article is empty.
5411 @node Posting Server
5412 @subsection Posting Server
5414 When you press those magical @kbd{C-c C-c} keys to ship off your latest
5415 (extremely intelligent, of course) article, where does it go?
5417 Thank you for asking. I hate you.
5419 @vindex gnus-post-method
5421 It can be quite complicated. Normally, Gnus will use the same native
5422 server. However. If your native server doesn't allow posting, just
5423 reading, you probably want to use some other server to post your
5424 (extremely intelligent and fabulously interesting) articles. You can
5425 then set the @code{gnus-post-method} to some other method:
5428 (setq gnus-post-method '(nnspool ""))
5431 Now, if you've done this, and then this server rejects your article, or
5432 this server is down, what do you do then? To override this variable you
5433 can use a non-zero prefix to the @kbd{C-c C-c} command to force using
5434 the ``current'' server for posting.
5436 If you give a zero prefix (i. e., @kbd{C-u 0 C-c C-c}) to that command,
5437 Gnus will prompt you for what method to use for posting.
5439 You can also set @code{gnus-post-method} to a list of select methods.
5440 If that's the case, Gnus will always prompt you for what method to use
5445 @subsection Mail and Post
5447 Commands for sending mail and post at the same time:
5451 @kindex S b (Summary)
5452 @findex gnus-summary-followup-and-reply
5453 Post a followup and send a reply to the current article
5454 (@code{gnus-summary-followup-and-reply}).
5457 @kindex S B (Summary)
5458 @findex gnus-summary-followup-and-reply-with-original
5459 Post a followup and send a reply to the current article and include the
5460 original message (@code{gnus-summary-followup-and-reply-with-original}).
5461 This command uses the process/prefix convention.
5464 Here's a list of variables that are relevant to both mailing and
5468 @item gnus-signature-file
5469 @itemx mail-signature
5470 @vindex mail-signature
5471 @vindex gnus-signature-file
5472 @cindex double signature
5474 If @code{gnus-signature-file} is non-@code{nil}, it should be the name
5475 of a file containing a signature (@samp{~/.signature} by default). This
5476 signature will be appended to all outgoing post. Most people find it
5477 more convenient to use @code{mail-signature}, which (sort of) does the
5478 same, but inserts the signature into the buffer before you start editing
5479 the post (or mail). So---if you have both of these variables set, you
5480 will get two signatures. Note that @code{mail-signature} does not work
5481 the same way as @code{gnus-signature-file}, which is a bit confusing.
5482 If @code{mail-signature} is @code{t}, it will insert
5483 @file{~/.signature}. If it is a string, this string will be inserted.
5485 Note that RFC1036 says that a signature should be preceded by the three
5486 characters @samp{-- } on a line by themselves. This is to make it
5487 easier for the recipient to automatically recognize and process the
5488 signature. So don't remove those characters, even though you might feel
5489 that they ruin you beautiful design, like, totally.
5491 Also note that no signature should be more than four lines long.
5492 Including ASCII graphics is an efficient way to get everybody to believe
5493 that you are silly and have nothing important to say.
5495 @item mail-yank-prefix
5496 @vindex mail-yank-prefix
5499 When you are replying to or following up an article, you normally want
5500 to quote the person you are answering. Inserting quoted text is done by
5501 @dfn{yanking}, and each quoted line you yank will have
5502 @code{mail-yank-prefix} prepended to it. This is @code{nil} by default,
5503 which isn't very pretty---the prefix will just be some spaces. Most
5504 everybody prefers that lines are prepended with @samp{> }, so
5505 @code{(setq mail-yank-prefix "> ")} in your @file{.emacs} file.
5507 @item mail-yank-ignored-headers
5508 @vindex mail-yank-ignored-headers
5509 When you yank a message, you do not want to quote any headers, so
5510 @code{(setq mail-yank-ignored-headers "^")}.
5512 @item user-mail-address
5513 @vindex user-mail-address
5514 If all of @code{gnus-user-login-name}, @code{gnus-use-generic-from} and
5515 @code{gnus-local-domain} are @code{nil}, Gnus will use
5516 @code{user-mail-address} as the address part of the @code{From} header.
5518 @item gnus-local-domain
5519 @vindex gnus-local-domain
5521 The local domain name excluding the host name. If your host is called
5522 @samp{"narfi.ifi.uio.no"}, then this variable should be
5523 @samp{"ifi.uio.no"}.
5525 @item gnus-local-domain
5526 @vindex gnus-local-domain
5528 The local domain name excluding the host name. If your host is called
5529 @samp{"narfi.ifi.uio.no"}, then this variable should be
5530 @samp{"ifi.uio.no"}.
5532 @item gnus-user-from-line
5533 @vindex gnus-user-from-line
5534 Your full, complete e-mail address with name. This variable overrides
5535 the other Gnus variables if it is non-@code{nil}.
5537 Here are two example values of this variable: @samp{"larsi@@ifi.uio.no
5538 (Lars Magne Ingebrigtsen)"} and @samp{"Lars Magne Ingebrigtsen
5539 <larsi@@ifi.uio.no>"}. The latter version is recommended in news (and is
5540 probably illegal in mail), but the name has to be quoted if it contains
5541 non-alpha-numerical characters---@samp{"\"Lars M. Ingebrigtsen\"
5542 <larsi@@ifi.uio.no>"}.
5544 @item mail-default-headers
5545 @vindex mail-default-headers
5546 This is a string that will be inserted into the header of all outgoing
5547 mail messages and news articles. Convenient to use to insert standard
5548 headers. If @code{nntp-news-default-headers} is non-@code{nil}, that
5549 variable will override this one when posting articles.
5551 @item gnus-auto-mail-to-author
5552 @vindex gnus-auto-mail-to-author
5553 If @code{ask}, you will be prompted for whether you want to send a mail
5554 copy to the author of the article you are following up. If
5555 non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
5556 all follow-ups to the authors of the articles you follow up. It's nice
5557 in one way---you make sure that the person you are responding to gets
5558 your response. Other people loathe this method and will hate you dearly
5559 for it, because it means that they will first get a mail, and then have
5560 to read the same article later when they read the news. It is
5561 @code{nil} by default.
5563 @item gnus-mail-courtesy-message
5564 @vindex gnus-mail-courtesy-message
5565 This is a string that will be prepended to all mails that are the result
5566 of using the variable described above.
5568 @item gnus-mailing-list-groups
5569 @findex gnus-mailing-list-groups
5570 @cindex mailing lists
5572 If your news server offers groups that are really mailing lists that are
5573 gatewayed to the @sc{nntp} server, you can read those groups without
5574 problems, but you can't post/followup to them without some difficulty.
5575 One solution is to add a @code{to-address} to the group parameters
5576 (@pxref{Group Parameters}). An easier thing to do is set the
5577 @code{gnus-mailing-list-groups} to a regexp that match the groups that
5578 really are mailing lists. Then, at least, followups to the mailing
5579 lists will work most of the time. Posting to these groups (@kbd{a}) is
5580 still a pain, though.
5585 You may want to do spell-checking on messages that you send out. Or, if
5586 you don't want to spell-check by hand, you could add automatic
5587 spell-checking via the @code{ispell} package:
5589 @vindex news-inews-hook
5591 (add-hook 'news-inews-hook 'ispell-message) ;For news posts
5592 (add-hook 'mail-send-hook 'ispell-message) ;for mail posts via sendmail
5595 @findex gnus-inews-insert-mime-headers
5596 If you want to insert some @sc{mime} headers into the articles you post,
5597 without doing any actual encoding, you could add
5598 @code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
5602 @node Archived Messages
5603 @subsection Archived Messages
5604 @cindex archived messages
5605 @cindex sent messages
5607 Gnus provides a few different methods for storing the mail you send.
5608 The default method is to use the @dfn{archive virtual server} to store
5611 @vindex gnus-message-archive-method
5612 @code{gnus-message-archive-method} says what virtual server Gnus is to
5613 use to store sent messages. It is @code{(nnfolder "archive"
5614 (nnfolder-directory "~/Mail/archive/"))} by default, but you can use any
5615 mail select method (@code{nnml}, @code{nnmbox}, etc.). However,
5616 @code{nnfolder} is a quite likeable select method for doing this sort of
5617 thing. If you don't like the default directory chosen, you could say
5621 (setq gnus-message-archive-method
5622 '((nnfolder "archive"
5623 (nnfolder-inhibit-expiry t)
5624 (nnfolder-active-file "~/Mail/sent-mail/active")
5625 (nnfolder-directory "~/News/sent-mail/"))))
5628 @vindex gnus-message-archive-group
5629 Gnus will insert @code{Gcc} headers in all outgoing messages that point
5630 to one or more group(s) on that server. Which group to use is
5631 determined by the @code{gnus-message-archive-group} variable.
5633 This variable can be:
5637 Messages will be saved in that group.
5638 @item a list of strings
5639 Messages will be saved in all those groups.
5640 @item an alist of regexps, functions and forms
5641 When a key ``matches'', the result is used.
5646 Just saving to a single group called @samp{"MisK"}:
5648 (setq gnus-message-archive-group "MisK")
5651 Saving to two groups, @samp{"MisK"} and @samp{"safe"}:
5653 (setq gnus-message-archive-group '("MisK" "safe"))
5656 Save to different groups based on what group you are in:
5658 (setq gnus-message-archive-group
5659 '(("^alt" "sent-to-alt")
5660 ("mail" "sent-to-mail")
5661 (".*" "sent-to-misc")))
5666 (setq gnus-message-archive-group
5667 '((if (eq major-mode news-reply-mode) "misc-news" "misc-mail")))
5670 This last one is the default.
5672 Now, when you send a message off, it will be stored in the appropriate
5673 group. (If you want to disable storing for just one particular article,
5674 you can just remove the @code{Gcc} header that has been inserted.) The
5675 archive group will appear in the group buffer the next time you start
5676 Gnus, or the next time you press @kbd{F} in the group buffer. You can
5677 enter it and read the articles in it just like you'd read any other
5678 group. If the group gets really big and annoying, you can simply rename
5679 if (using @kbd{G r} in the group buffer) to something nice --
5680 @samp{"misc-mail-september-1995"}, or whatever. New messages will
5681 continue to be stored in the old (now empty) group.
5684 That's the default method of archiving sent mail. Gnus also offers two
5685 other variables for the people who don't like the default method. In
5686 that case you should set @code{gnus-message-archive-group} to
5687 @code{nil}; this will disable archiving.
5690 @item gnus-author-copy
5691 @vindex gnus-author-copy
5692 This is a file name, and all outgoing articles will be saved in that
5693 file. Initialized from the @code{AUTHORCOPY} environment variable.
5695 If this variable begins with the character @samp{"|"}, outgoing articles
5696 will be piped to the named program. It is possible to save an article in
5697 an MH folder as follows:
5700 (setq gnus-author-copy
5701 "|/usr/local/lib/mh/rcvstore +Article")
5704 If the first character is not a pipe, articles are saved using the
5705 function specified by the @code{gnus-author-copy-saver} variable.
5707 @item gnus-author-copy-saver
5708 @vindex gnus-author-copy-saver
5709 A function called to save outgoing articles. This function will be
5710 called with the same of the file to store the article in. The default
5711 function is @code{rmail-output} which saves in the Unix mailbox format.
5713 @item gnus-mail-self-blind
5714 @vindex gnus-mail-self-blind
5715 Non-@code{nil} means insert a BCC header in all outgoing articles
5716 pointing to yourself. This will result you receiving a copy of the
5717 article mailed to yourself. The BCC header is inserted when the post
5718 buffer is initialized, so you can remove or alter the BCC header to
5719 override the default.
5721 @item gnus-outgoing-message-group
5722 @vindex gnus-outgoing-message-group
5723 All outgoing messages will be put in this group. If you want to store
5724 all your outgoing mail and articles in the group @samp{nnml:archive},
5725 you set this variable to that value. This variable can also be a list of
5728 If you want to have greater control over what group to put each
5729 message in, you can set this variable to a function that checks the
5730 current newsgroup name and then returns a suitable group name (or list
5735 @node Posting Styles
5736 @subsection Posting Styles
5737 @cindex posting styles
5740 All them variables, they make my head swim.
5742 So what if you want a different @code{Organization} and signature based
5743 on what groups you post to? And you post both from your home machine
5744 and your work machine, and you want different @code{From} lines, and so
5747 @vindex gnus-posting-styles
5748 One way to do stuff like that is to write clever hooks that change the
5749 variables you need to have changed. That's a bit boring, so somebody
5750 came up with the bright idea of letting the user specify these things in
5751 a handy alist. Here's an example of a @code{gnus-posting-styles}
5755 ((".*" (signature . "Peace and happiness") (organization . "What me?"))
5756 ("^comp" (signature . "Death to everybody"))
5757 ("comp.emacs.i-love-it" (organization . "Emacs is it")))
5760 As you might surmise from this example, this alist consists of several
5761 @dfn{styles}. Each style will be applicable if the first element
5762 ``matches'', in some form or other. The entire alist will be iterated
5763 over, from the beginning towards the end, and each match will be
5764 applied, which means that attributes in later styles that match override
5765 the same attributes in earlier matching styles. So
5766 @samp{comp.programming.literate} will have the @samp{Death to everybody}
5767 signature and the @samp{What me?} @code{Organization} header.
5769 The first element in each style is called the @code{match}. If it's a
5770 string, then Gnus will try to regexp match it against the group name.
5771 If it's a function symbol, that function will be called with no
5772 arguments. If it's a variable symbol, then the variable will be
5773 referenced. If it's a list, then that list will be @code{eval}ed. In
5774 any case, if this returns a non-@code{nil} value, then the style is said
5777 Each style may contain a random amount of @dfn{attributes}. Each
5778 attribute consists of a @var{(name . value)} pair. The attribute name
5779 can be one of @code{signature}, @code{organization} or @code{from}.
5780 The attribute name can also be a string. In that case, this will be
5781 used as a header name, and the value will be inserted in the headers of
5784 The attribute value can be a string (used verbatim), a function (the
5785 return value will be used), a variable (its value will be used) or a
5786 list (it will be @code{eval}ed and the return value will be used).
5788 So here's a new example:
5791 (setq gnus-posting-styles
5793 (signature . "~/.signature")
5794 (from . "user@@foo (user)")
5795 ("X-Home-Page" . (getenv "WWW_HOME"))
5796 (organization . "People's Front Against MWM"))
5798 (signature . my-funny-signature-randomizer))
5799 ((equal (system-name) "gnarly")
5800 (signature . my-quote-randomizer))
5801 (posting-from-work-p
5802 (signature . "~/.work-signature")
5803 (from . "user@@bar.foo (user)")
5804 (organization . "Important Work, Inc"))
5806 (signature . "~/.mail-signature"))))
5815 If you are writing a message (mail or news) and suddenly remember that
5816 you have a steak in the oven (or some pesto in the food processor, you
5817 craazy vegetarians), you'll probably wish there was a method to save the
5818 message you are writing so that you can continue editing it some other
5819 day, and send it when you feel its finished.
5821 Well, don't worry about it. Whenever you start composing a message of
5822 some sort using the Gnus mail and post commands, the buffer you get will
5823 automatically associate to an article in a special @dfn{draft} group.
5824 If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
5825 article will be saved there. (Auto-save files also go to the draft
5828 The draft group is a special group (which is implemented as an
5829 @code{nndraft} group, if you absolutely have to know) called
5830 @samp{nndraft:drafts}. The variable @code{gnus-draft-group-directory}
5831 controls both the name of the group and the location---the leaf element
5832 in the path will be used as the name of the group. What makes this
5833 group special is that you can't tick any articles in it or mark any
5834 articles as read---all articles in the group are permanently unread.
5836 If the group doesn't exist, it will be created and you'll be subscribed
5839 @findex gnus-dissociate-buffer-from-draft
5840 @kindex C-c M-d (Mail)
5841 @kindex C-c M-d (Post)
5842 @findex gnus-associate-buffer-with-draft
5843 @kindex C-c C-d (Mail)
5844 @kindex C-c C-d (Post)
5845 If you're writing some super-secret message that you later want to
5846 encode with PGP before sending, you may wish to turn the auto-saving
5847 (and association with the draft group) off. You never know who might be
5848 interested in reading all your extremely valuable and terribly horrible
5849 and interesting secrets. The @kbd{C-c M-d}
5850 (@code{gnus-dissociate-buffer-from-draft}) command does that for you.
5851 If you change your mind and want to turn the auto-saving back on again,
5852 @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that.
5854 @vindex gnus-use-draft
5855 To leave association with the draft group off by default, set
5856 @code{gnus-use-draft} to @code{nil}. It is @code{t} by default.
5858 @findex gnus-summary-send-draft
5859 @kindex S D c (Summary)
5860 When you want to continue editing the article, you simply enter the
5861 draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
5862 that. You will be placed in a buffer where you left off.
5864 Rejected articles will also be put in this draft group (@pxref{Rejected
5867 @findex gnus-summary-send-all-drafts
5868 If you have lots of rejected messages you want to post (or mail) without
5869 doing further editing, you can use the @kbd{S D a} command
5870 (@code{gnus-summary-send-all-drafts}). This command understands the
5871 process/prefix convention (@pxref{Process/Prefix}).
5874 @node Rejected Articles
5875 @subsection Rejected Articles
5876 @cindex rejected articles
5878 Sometimes a news server will reject an article. Perhaps the server
5879 doesn't like your face. Perhaps it just feels miserable. Perhaps
5880 @emph{there be demons}. Perhaps you have included too much cited text.
5881 Perhaps the disk is full. Perhaps the server is down.
5883 These situations are, of course, totally beyond the control of Gnus.
5884 (Gnus, of course, loves the way you look, always feels great, has angels
5885 fluttering around inside of it, doesn't care about how much cited text
5886 you include, never runs full and never goes down.) So Gnus saves these
5887 articles until some later time when the server feels better.
5889 The rejected articles will automatically be put in a special draft group
5890 (@pxref{Drafts}). When the server comes back up again, you'd then
5891 typically enter that group and send all the articles off.
5894 @node Canceling and Superseding
5895 @section Canceling Articles
5896 @cindex canceling articles
5897 @cindex superseding articles
5899 Have you ever written something, and then decided that you really,
5900 really, really wish you hadn't posted that?
5902 Well, you can't cancel mail, but you can cancel posts.
5904 @findex gnus-summary-cancel-article
5906 Find the article you wish to cancel (you can only cancel your own
5907 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
5908 c} (@code{gnus-summary-cancel-article}). Your article will be
5909 canceled---machines all over the world will be deleting your article.
5911 Be aware, however, that not all sites honor cancels, so your article may
5912 live on here and there, while most sites will delete the article in
5915 If you discover that you have made some mistakes and want to do some
5916 corrections, you can post a @dfn{superseding} article that will replace
5917 your original article.
5919 @findex gnus-summary-supersede-article
5921 Go to the original article and press @kbd{S s}
5922 (@code{gnus-summary-supersede-article}). You will be put in a buffer
5923 where you can edit the article all you want before sending it off the
5926 @vindex gnus-delete-supersedes-headers
5927 You probably want to delete some of the old headers before sending the
5928 superseding article---@code{Path} and @code{Date} are probably
5929 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
5930 match the lines you want removed. The default is
5931 @samp{"^Path:\\|^Date"}.
5933 The same goes for superseding as for canceling, only more so: Some
5934 sites do not honor superseding. On those sites, it will appear that you
5935 have posted almost the same article twice.
5937 If you have just posted the article, and change your mind right away,
5938 there is a trick you can use to cancel/supersede the article without
5939 waiting for the article to appear on your site first. You simply return
5940 to the post buffer (which is called @code{*post-buf*}). There you will
5941 find the article you just posted, with all the headers intact. Change
5942 the @samp{Message-ID} header to a @samp{Cancel} or @samp{Supersedes}
5943 header by substituting one of those words for @samp{Message-ID}. Then
5944 just press @kbd{C-c C-c} to send the article as you would do normally.
5945 The previous article will be canceled/superseded.
5947 Just remember, kids: There is no 'c' in 'supersede'.
5949 @node Marking Articles
5950 @section Marking Articles
5951 @cindex article marking
5952 @cindex article ticking
5955 There are several marks you can set on an article.
5957 You have marks that decide the @dfn{readed-ness} (whoo, neato-keano
5958 neologism ohoy!) of the article. Alphabetic marks generally mean
5959 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
5961 In addition, you also have marks that do not affect readedness.
5964 * Unread Articles:: Marks for unread articles.
5965 * Read Articles:: Marks for read articles.
5966 * Other Marks:: Marks that do not affect readedness.
5970 There's a plethora of commands for manipulating these marks:
5974 * Setting Marks:: How to set and remove marks.
5975 * Setting Process Marks:: How to mark articles for later processing.
5978 @node Unread Articles
5979 @subsection Unread Articles
5981 The following marks mark articles as unread, in one form or other.
5983 @vindex gnus-dormant-mark
5984 @vindex gnus-ticked-mark
5987 @dfn{Ticked articles} are articles that will remain visible always. If
5988 you see an article that you find interesting, or you want to put off
5989 reading it, or replying to it, until sometime later, you'd typically
5990 tick it. However, articles can be expired, so if you want to keep an
5991 article forever, you'll have to save it. Ticked articles have a
5992 @samp{!} (@code{gnus-ticked-mark}) in the first column.
5995 A @dfn{dormant} article is marked with a @samp{?}
5996 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
5997 if there are followups to it.
6000 An @dfn{unread} article is marked with a @samp{SPC}
6001 (@code{gnus-unread-mark}). These are articles that haven't been read at
6006 @subsection Read Articles
6007 @cindex expirable mark
6009 All the following marks mark articles as read.
6014 Articles that are marked as read. They have a @samp{r}
6015 (@code{gnus-del-mark}) in the first column. These are articles that the
6016 user has marked as read more or less manually.
6019 Articles that are actually read are marked with @samp{R}
6020 (@code{gnus-read-mark}).
6023 Articles that were marked as read in previous sessions are now
6024 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
6027 Marked as killed (@code{gnus-killed-mark}).
6030 Marked as killed by kill files (@code{gnus-kill-file-mark}).
6033 Marked as read by having a too low score (@code{gnus-low-score-mark}).
6036 Marked as read by a catchup (@code{gnus-catchup-mark}).
6039 Canceled article (@code{gnus-cancelled-mark})
6042 All these marks just mean that the article is marked as read, really.
6043 They are interpreted differently by the adaptive scoring scheme,
6046 One more special mark, though:
6050 You can also mark articles as @dfn{expirable} (or have them marked as
6051 such automatically). That doesn't make much sense in normal groups,
6052 because a user does not control the expiring of news articles, but in
6053 mail groups, for instance, articles that are marked as @dfn{expirable}
6054 can be deleted by Gnus at any time. Expirable articles are marked with
6055 @samp{E} (@code{gnus-expirable-mark}).
6059 @subsection Other Marks
6060 @cindex process mark
6063 There are some marks that have nothing to do with whether the article is
6069 You can set a bookmark in the current article. Say you are reading a
6070 long thesis on cats' urinary tracts, and have to go home for dinner
6071 before you've finished reading the thesis. You can then set a bookmark
6072 in the article, and Gnus will jump to this bookmark the next time it
6073 encounters the article.
6076 All articles that you have replied to or made a followup to (i.e., have
6077 answered) will be marked with an @samp{A} in the second column
6078 (@code{gnus-replied-mark}).
6081 Articles that are stored in the article cache will be marked with an
6082 @samp{*} in the second column (@code{gnus-cached-mark}).
6085 Articles that are ``saved'' (in some manner or other; not necessarily
6086 religiously) are marked with an @samp{S} in the second column
6087 (@code{gnus-saved-mark}.
6090 @vindex gnus-not-empty-thread-mark
6091 @vindex gnus-empty-thread-mark
6092 It the @samp{%e} spec is used, the presence of threads or not will be
6093 marked with @code{gnus-not-empty-thread-mark} and
6094 @code{gnus-empty-thread-mark} in the third column, respectively.
6097 @vindex gnus-process-mark
6098 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
6099 variety of commands react to the presence of the process mark. For
6100 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
6101 all articles that have been marked with the process mark. Articles
6102 marked with the process mark have a @samp{#} in the second column.
6106 You might have noticed that most of these ``non-readedness'' marks appear
6107 in the second column by default. So if you have a cached, saved,
6108 replied article that you have process-marked, what will that look like?
6110 Nothing much. The precedence rules go as follows: process -> cache ->
6111 replied -> saved. So if the article is in the cache and is replied,
6112 you'll only see the cache mark and not the replied mark.
6116 @subsection Setting Marks
6117 @cindex setting marks
6119 All the marking commands understand the numeric prefix.
6125 @kindex M t (Summary)
6126 @findex gnus-summary-tick-article-forward
6127 Tick the current article (@code{gnus-summary-tick-article-forward}).
6132 @kindex M ? (Summary)
6133 @findex gnus-summary-mark-as-dormant
6134 Mark the current article as dormant
6135 (@code{gnus-summary-mark-as-dormant}).
6139 @kindex M d (Summary)
6141 @findex gnus-summary-mark-as-read-forward
6142 Mark the current article as read
6143 (@code{gnus-summary-mark-as-read-forward}).
6148 @kindex M k (Summary)
6149 @findex gnus-summary-kill-same-subject-and-select
6150 Mark all articles that have the same subject as the current one as read,
6151 and then select the next unread article
6152 (@code{gnus-summary-kill-same-subject-and-select}).
6156 @kindex M K (Summary)
6157 @kindex C-k (Summary)
6158 @findex gnus-summary-kill-same-subject
6159 Mark all articles that have the same subject as the current one as read
6160 (@code{gnus-summary-kill-same-subject}).
6163 @kindex M C (Summary)
6164 @findex gnus-summary-catchup
6165 Mark all unread articles in the group as read
6166 (@code{gnus-summary-catchup}).
6169 @kindex M C-c (Summary)
6170 @findex gnus-summary-catchup-all
6171 Mark all articles in the group as read---even the ticked and dormant
6172 articles (@code{gnus-summary-catchup-all}).
6175 @kindex M H (Summary)
6176 @findex gnus-summary-catchup-to-here
6177 Catchup the current group to point
6178 (@code{gnus-summary-catchup-to-here}).
6181 @kindex C-w (Summary)
6182 @findex gnus-summary-mark-region-as-read
6183 Mark all articles between point and mark as read
6184 (@code{gnus-summary-mark-region-as-read}).
6187 @kindex M V k (Summary)
6188 @findex gnus-summary-kill-below
6189 Kill all articles with scores below the default score (or below the
6190 numeric prefix) (@code{gnus-summary-kill-below}).
6194 @kindex M c (Summary)
6195 @kindex M-u (Summary)
6196 @findex gnus-summary-clear-mark-forward
6197 Clear all readedness-marks from the current article
6198 (@code{gnus-summary-clear-mark-forward}).
6202 @kindex M e (Summary)
6204 @findex gnus-summary-mark-as-expirable
6205 Mark the current article as expirable
6206 (@code{gnus-summary-mark-as-expirable}).
6209 @kindex M b (Summary)
6210 @findex gnus-summary-set-bookmark
6211 Set a bookmark in the current article
6212 (@code{gnus-summary-set-bookmark}).
6215 @kindex M B (Summary)
6216 @findex gnus-summary-remove-bookmark
6217 Remove the bookmark from the current article
6218 (@code{gnus-summary-remove-bookmark}).
6221 @kindex M V c (Summary)
6222 @findex gnus-summary-clear-above
6223 Clear all marks from articles with scores over the default score (or
6224 over the numeric prefix) (@code{gnus-summary-clear-above}).
6227 @kindex M V u (Summary)
6228 @findex gnus-summary-tick-above
6229 Tick all articles with scores over the default score (or over the
6230 numeric prefix) (@code{gnus-summary-tick-above}).
6233 @kindex M V m (Summary)
6234 @findex gnus-summary-mark-above
6235 Prompt for a mark, and mark all articles with scores over the default
6236 score (or over the numeric prefix) with this mark
6237 (@code{gnus-summary-clear-above}).
6240 @code{gnus-summary-goto-unread} The @code{gnus-summary-goto-unread}
6241 variable controls what action should be taken after setting a mark. If
6242 non-@code{nil}, point will move to the next/previous unread article. If
6243 @code{nil}, point will just move one line up or down. As a special
6244 case, if this variable is @code{never}, all the marking commands as well
6245 as other commands (like @kbd{SPC}) will move to the next article,
6246 whether it is unread or not. The default is @code{t}.
6249 @node Setting Process Marks
6250 @subsection Setting Process Marks
6251 @cindex setting process marks
6258 @kindex M P p (Summary)
6259 @findex gnus-summary-mark-as-processable
6260 Mark the current article with the process mark
6261 (@code{gnus-summary-mark-as-processable}).
6262 @findex gnus-summary-unmark-as-processable
6266 @kindex M P u (Summary)
6267 @kindex M-# (Summary)
6268 Remove the process mark, if any, from the current article
6269 (@code{gnus-summary-unmark-as-processable}).
6272 @kindex M P U (Summary)
6273 @findex gnus-summary-unmark-all-processable
6274 Remove the process mark from all articles
6275 (@code{gnus-summary-unmark-all-processable}).
6278 @kindex M P R (Summary)
6279 @findex gnus-uu-mark-by-regexp
6280 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
6283 @kindex M P r (Summary)
6284 @findex gnus-uu-mark-region
6285 Mark articles in region (@code{gnus-uu-mark-region}).
6288 @kindex M P t (Summary)
6289 @findex gnus-uu-mark-thread
6290 Mark all articles in the current (sub)thread
6291 (@code{gnus-uu-mark-thread}).
6294 @kindex M P T (Summary)
6295 @findex gnus-uu-unmark-thread
6296 Unmark all articles in the current (sub)thread
6297 (@code{gnus-uu-unmark-thread}).
6300 @kindex M P v (Summary)
6301 @findex gnus-uu-mark-over
6302 Mark all articles that have a score above the prefix argument
6303 (@code{gnus-uu-mark-over}).
6306 @kindex M P s (Summary)
6307 @findex gnus-uu-mark-series
6308 Mark all articles in the current series (@code{gnus-uu-mark-series}).
6311 @kindex M P S (Summary)
6312 @findex gnus-uu-mark-sparse
6313 Mark all series that have already had some articles marked
6314 (@code{gnus-uu-mark-sparse}).
6317 @kindex M P a (Summary)
6318 @findex gnus-uu-mark-all
6319 Mark all articles in series order (@code{gnus-uu-mark-series}).
6322 @kindex M P b (Summary)
6323 @findex gnus-uu-mark-buffer
6324 Mark all articles in the buffer in the order they appear
6325 (@code{gnus-uu-mark-buffer}).
6333 It can be convenient to limit the summary buffer to just show some
6334 subset of the articles currently in the group. The effect most limit
6335 commands have is to remove a few (or many) articles from the summary
6342 @kindex / / (Summary)
6343 @findex gnus-summary-limit-to-subject
6344 Limit the summary buffer to articles that match some subject
6345 (@code{gnus-summary-limit-to-subject}).
6348 @kindex / a (Summary)
6349 @findex gnus-summary-limit-to-author
6350 Limit the summary buffer to articles that match some author
6351 (@code{gnus-summary-limit-to-author}).
6355 @kindex / u (Summary)
6357 @findex gnus-summary-limit-to-unread
6358 Limit the summary buffer to articles that are not marked as read
6359 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
6360 buffer to articles that are strictly unread. This means that ticked and
6361 dormant articles will also be excluded.
6364 @kindex / m (Summary)
6365 @findex gnus-summary-limit-to-marks
6366 Ask for a mark and then limit to all articles that have not been marked
6367 with that mark (@code{gnus-summary-limit-to-marks}).
6370 @kindex / n (Summary)
6371 @findex gnus-summary-limit-to-articles
6372 Limit the summary buffer to the current article
6373 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
6374 convention (@pxref{Process/Prefix}).
6377 @kindex / w (Summary)
6378 @findex gnus-summary-pop-limit
6379 Pop the previous limit off the stack and restore it
6380 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
6384 @kindex / v (Summary)
6385 @findex gnus-summary-limit-to-score
6386 Limit the summary buffer to articles that have a score at or above some
6387 score (@code{gnus-summary-limit-to-score}).
6391 @kindex M S (Summary)
6392 @kindex / E (Summary)
6393 @findex gnus-summary-limit-include-expunged
6394 Display all expunged articles
6395 (@code{gnus-summary-limit-include-expunged}).
6398 @kindex / D (Summary)
6399 @findex gnus-summary-limit-include-dormant
6400 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
6403 @kindex / d (Summary)
6404 @findex gnus-summary-limit-exclude-dormant
6405 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
6408 @kindex / c (Summary)
6409 @findex gnus-summary-limit-exclude-childless-dormant
6410 Hide all dormant articles that have no children
6411 (@code{gnus-summary-limit-exclude-childless-dormant}).
6414 @kindex / C (Summary)
6415 @findex gnus-summary-limit-mark-excluded-as-read
6416 Mark all excluded unread articles as read
6417 (@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix,
6418 also mark excluded ticked and dormant articles as read.
6426 @cindex article threading
6428 Gnus threads articles by default. @dfn{To thread} is to put replies to
6429 articles directly after the articles they reply to---in a hierarchical
6433 * Customizing Threading:: Variables you can change to affect the threading.
6434 * Thread Commands:: Thread based commands in the summary buffer.
6437 @node Customizing Threading
6438 @subsection Customizing Threading
6439 @cindex customizing threading
6445 @item gnus-show-threads
6446 @vindex gnus-show-threads
6447 If this variable is @code{nil}, no threading will be done, and all of
6448 the rest of the variables here will have no effect. Turning threading
6449 off will speed group selection up a bit, but it is sure to make reading
6450 slower and more awkward.
6452 @item gnus-fetch-old-headers
6453 @vindex gnus-fetch-old-headers
6454 If non-@code{nil}, Gnus will attempt to build old threads by fetching
6455 more old headers---headers to articles that are marked as read. If you
6456 would like to display as few summary lines as possible, but still
6457 connect as many loose threads as possible, you should set this variable
6458 to @code{some} or a number. If you set it to a number, no more than
6459 that number of extra old headers will be fetched. In either case,
6460 fetching old headers only works if the backend you are using carries
6461 overview files---this would normally be @code{nntp}, @code{nnspool} and
6462 @code{nnml}. Also remember that if the root of the thread has been
6463 expired by the server, there's not much Gnus can do about that.
6465 @item gnus-build-sparse-threads
6466 @vindex gnus-build-sparse-threads
6467 Fetching old headers can be slow. A low-rent similar effect can be
6468 gotten by setting this variable to @code{some}. Gnus will then look at
6469 the complete @code{References} headers of all articles and try to string
6470 articles that belong in the same thread together. This will leave
6471 @dfn{gaps} in the threading display where Gnus guesses that an article
6472 is missing from the thread. (These gaps appear like normal summary
6473 lines. If you select a gap, Gnus will try to fetch the article in
6474 question.) If this variable is @code{t}, Gnus will display all these
6475 ``gaps'' without regard for whether they are useful for completing the
6476 thread or not. Finally, if this variable is @code{more}, Gnus won't cut
6477 off sparse leaf nodes that don't lead anywhere. This variable is
6478 @code{nil} by default.
6480 @item gnus-summary-gather-subject-limit
6481 @vindex gnus-summary-gather-subject-limit
6482 Loose threads are gathered by comparing subjects of articles. If this
6483 variable is @code{nil}, Gnus requires an exact match between the
6484 subjects of the loose threads before gathering them into one big
6485 super-thread. This might be too strict a requirement, what with the
6486 presence of stupid newsreaders that chop off long subjects lines. If
6487 you think so, set this variable to, say, 20 to require that only the
6488 first 20 characters of the subjects have to match. If you set this
6489 variable to a really low number, you'll find that Gnus will gather
6490 everything in sight into one thread, which isn't very helpful.
6492 @cindex fuzzy article gathering
6493 If you set this variable to the special value @code{fuzzy}, Gnus will
6494 use a fuzzy string comparison algorithm on the subjects.
6496 @item gnus-simplify-ignored-prefixes
6497 @vindex gnus-simplify-ignored-prefixes
6498 If you set @code{gnus-summary-gather-subject-limit} to something as low
6499 as 10, you might consider setting this variable to something sensible:
6501 @c Written by Michael Ernst <mernst@cs.rice.edu>
6503 (setq gnus-simplify-ignored-prefixes
6506 (mapconcat 'identity
6508 "wanted" "followup" "summary\\( of\\)?"
6509 "help" "query" "problem" "question"
6510 "answer" "reference" "announce"
6511 "How can I" "How to" "Comparison of"
6516 (mapconcat 'identity
6517 '("for" "for reference" "with" "about")
6519 "\\)?\\]?:?[ \t]*"))
6522 All words that match this regexp will be removed before comparing two
6525 @item gnus-summary-gather-exclude-subject
6526 @vindex gnus-summary-gather-exclude-subject
6527 Since loose thread gathering is done on subjects only, that might lead
6528 to many false hits, especially with certain common subjects like
6529 @samp{""} and @samp{"(none)"}. To make the situation slightly better,
6530 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
6531 what subjects should be excluded from the gathering process. The
6532 default is @samp{"^ *$\\|^(none)$"}.
6534 @item gnus-summary-thread-gathering-function
6535 @vindex gnus-summary-thread-gathering-function
6536 Gnus gathers threads by looking at @code{Subject} headers. This means
6537 that totally unrelated articles may end up in the same ``thread'', which
6538 is confusing. An alternate approach is to look at all the
6539 @code{Message-ID}s in all the @code{References} headers to find
6540 matches. This will ensure that no gathered threads ever includes
6541 unrelated articles, but it's also means that people who have posted with
6542 broken newsreaders won't be gathered properly. The choice is
6543 yours---plague or cholera:
6546 @item gnus-summary-gather-threads-by-subject
6547 @findex gnus-summary-gather-threads-by-subject
6548 This function is the default gathering function and looks at
6549 @code{Subject}s exclusively.
6551 @item gnus-summary-gather-threads-by-references
6552 @findex gnus-summary-gather-threads-by-references
6553 This function looks at @code{References} headers exclusively.
6556 If you want to test gathering by @code{References}, you could say
6560 (setq gnus-summary-thread-gathering-function
6561 'gnus-summary-gather-threads-by-references)
6564 @item gnus-summary-make-false-root
6565 @vindex gnus-summary-make-false-root
6566 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
6567 and create a dummy root at the top. (Wait a minute. Root at the top?
6568 Yup.) Loose subtrees occur when the real root has expired, or you've
6569 read or killed the root in a previous session.
6571 When there is no real root of a thread, Gnus will have to fudge
6572 something. This variable says what fudging method Gnus should use.
6573 There are four possible values:
6575 @cindex adopting articles
6580 Gnus will make the first of the orphaned articles the parent. This
6581 parent will adopt all the other articles. The adopted articles will be
6582 marked as such by pointy brackets (@samp{<>}) instead of the standard
6583 square brackets (@samp{[]}). This is the default method.
6586 Gnus will create a dummy summary line that will pretend to be the
6587 parent. This dummy line does not correspond to any real article, so
6588 selecting it will just select the first real article after the dummy
6592 Gnus won't actually make any article the parent, but simply leave the
6593 subject field of all orphans except the first empty. (Actually, it will
6594 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
6598 Don't make any article parent at all. Just gather the threads and
6599 display them after one another.
6602 Don't gather loose threads.
6605 @item gnus-thread-hide-subtree
6606 @vindex gnus-thread-hide-subtree
6607 If non-@code{nil}, all threads will be hidden when the summary buffer is
6610 @item gnus-thread-hide-killed
6611 @vindex gnus-thread-hide-killed
6612 if you kill a thread and this variable is non-@code{nil}, the subtree
6615 @item gnus-thread-ignore-subject
6616 @vindex gnus-thread-ignore-subject
6617 Sometimes somebody changes the subject in the middle of a thread. If
6618 this variable is non-@code{nil}, the subject change is ignored. If it
6619 is @code{nil}, which is the default, a change in the subject will result
6622 @item gnus-thread-indent-level
6623 @vindex gnus-thread-indent-level
6624 This is a number that says how much each sub-thread should be indented.
6625 The default is @samp{4}.
6628 @node Thread Commands
6629 @subsection Thread Commands
6630 @cindex thread commands
6636 @kindex T k (Summary)
6637 @kindex M-C-k (Summary)
6638 @findex gnus-summary-kill-thread
6639 Mark all articles in the current sub-thread as read
6640 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
6641 remove all marks instead. If the prefix argument is negative, tick
6646 @kindex T l (Summary)
6647 @kindex M-C-l (Summary)
6648 @findex gnus-summary-lower-thread
6649 Lower the score of the current thread
6650 (@code{gnus-summary-lower-thread}).
6653 @kindex T i (Summary)
6654 @findex gnus-summary-raise-thread
6655 Increase the score of the current thread
6656 (@code{gnus-summary-raise-thread}).
6659 @kindex T # (Summary)
6660 @findex gnus-uu-mark-thread
6661 Set the process mark on the current thread
6662 (@code{gnus-uu-mark-thread}).
6665 @kindex T M-# (Summary)
6666 @findex gnus-uu-unmark-thread
6667 Remove the process mark from the current thread
6668 (@code{gnus-uu-unmark-thread}).
6671 @kindex T T (Summary)
6672 @findex gnus-summary-toggle-threads
6673 Toggle threading (@code{gnus-summary-toggle-threads}).
6676 @kindex T s (Summary)
6677 @findex gnus-summary-show-thread
6678 Expose the thread hidden under the current article, if any
6679 (@code{gnus-summary-show-thread}).
6682 @kindex T h (Summary)
6683 @findex gnus-summary-hide-thread
6684 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
6687 @kindex T S (Summary)
6688 @findex gnus-summary-show-all-threads
6689 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
6692 @kindex T H (Summary)
6693 @findex gnus-summary-hide-all-threads
6694 Hide all threads (@code{gnus-summary-hide-all-threads}).
6697 @kindex T t (Summary)
6698 @findex gnus-summary-rethread-current
6699 Re-thread the thread the current article is part of
6700 (@code{gnus-summary-rethread-current}). This works even when the
6701 summary buffer is otherwise unthreaded.
6704 @kindex T ^ (Summary)
6705 @findex gnus-summary-reparent-thread
6706 Make the current article the child of the marked (or previous) article
6707 (@code{gnus-summary-reparent-thread}.
6711 The following commands are thread movement commands. They all
6712 understand the numeric prefix.
6717 @kindex T n (Summary)
6718 @findex gnus-summary-next-thread
6719 Go to the next thread (@code{gnus-summary-next-thread}).
6722 @kindex T p (Summary)
6723 @findex gnus-summary-prev-thread
6724 Go to the previous thread (@code{gnus-summary-prev-thread}).
6727 @kindex T d (Summary)
6728 @findex gnus-summary-down-thread
6729 Descend the thread (@code{gnus-summary-down-thread}).
6732 @kindex T u (Summary)
6733 @findex gnus-summary-up-thread
6734 Ascend the thread (@code{gnus-summary-up-thread}).
6737 @kindex T o (Summary)
6738 @findex gnus-summary-top-thread
6739 Go to the top of the thread (@code{gnus-summary-top-thread}).
6742 @vindex gnus-thread-operation-ignore-subject
6743 If you ignore subject while threading, you'll naturally end up with
6744 threads that have several different subjects in them. If you then issue
6745 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
6746 wish to kill the entire thread, but just those parts of the thread that
6747 have the same subject as the current article. If you like this idea,
6748 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
6749 is non-@code{nil} (which it is by default), subjects will be ignored
6750 when doing thread commands. If this variable is @code{nil}, articles in
6751 the same thread with different subjects will not be included in the
6752 operation in question. If this variable is @code{fuzzy}, only articles
6753 that have subjects that are fuzzily equal will be included.
6756 @node Asynchronous Fetching
6757 @section Asynchronous Article Fetching
6758 @cindex asynchronous article fetching
6760 If you read your news from an @sc{nntp} server that's far away, the
6761 network latencies may make reading articles a chore. You have to wait
6762 for a while after pressing @kbd{n} to go to the next article before the
6763 article appears. Why can't Gnus just go ahead and fetch the article
6764 while you are reading the previous one? Why not, indeed.
6766 First, some caveats. There are some pitfalls to using asynchronous
6767 article fetching, especially the way Gnus does it.
6769 Let's say you are reading article 1, which is short, and article 2 is
6770 quite long, and you are not interested in reading that. Gnus does not
6771 know this, so it goes ahead and fetches article 2. You decide to read
6772 article 3, but since Gnus is in the process of fetching article 2, the
6773 connection is blocked.
6775 To avoid these situations, Gnus will open two (count 'em two)
6776 connections to the server. Some people may think this isn't a very nice
6777 thing to do, but I don't see any real alternatives. Setting up that
6778 extra connection takes some time, so Gnus startup will be slower.
6780 Gnus will fetch more articles than you will read. This will mean that
6781 the link between your machine and the @sc{nntp} server will become more
6782 loaded than if you didn't use article pre-fetch. The server itself will
6783 also become more loaded---both with the extra article requests, and the
6786 Ok, so now you know that you shouldn't really use this thing... unless
6789 @vindex gnus-asynchronous
6790 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
6791 happen automatically.
6793 @vindex nntp-async-number
6794 You can control how many articles that are to be pre-fetched by setting
6795 @code{nntp-async-number}. This is five by default, which means that when
6796 you read an article in the group, @code{nntp} will pre-fetch the next
6797 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
6798 all the articles that it can without bound. If it is @code{nil}, no
6799 pre-fetching will be made.
6801 @vindex gnus-asynchronous-article-function
6802 You may wish to create some sort of scheme for choosing which articles
6803 that @code{nntp} should consider as candidates for pre-fetching. For
6804 instance, you may wish to pre-fetch all articles with high scores, and
6805 not pre-fetch low-scored articles. You can do that by setting the
6806 @code{gnus-asynchronous-article-function}, which will be called with an
6807 alist where the keys are the article numbers. Your function should
6808 return an alist where the articles you are not interested in have been
6809 removed. You could also do sorting on article score and the like.
6811 @node Article Caching
6812 @section Article Caching
6813 @cindex article caching
6816 If you have an @emph{extremely} slow @sc{nntp} connection, you may
6817 consider turning article caching on. Each article will then be stored
6818 locally under your home directory. As you may surmise, this could
6819 potentially use @emph{huge} amounts of disk space, as well as eat up all
6820 your inodes so fast it will make your head swim. In vodka.
6822 Used carefully, though, it could be just an easier way to save articles.
6824 @vindex gnus-use-long-file-name
6825 @vindex gnus-cache-directory
6826 @vindex gnus-use-cache
6827 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
6828 all articles that are ticked or marked as dormant will then be copied
6829 over to your local cache (@code{gnus-cache-directory}). Whether this
6830 cache is flat or hierarchal is controlled by the
6831 @code{gnus-use-long-file-name} variable, as usual.
6833 When re-select a ticked or dormant article, it will be fetched from the
6834 cache instead of from the server. As articles in your cache will never
6835 expire, this might serve as a method of saving articles while still
6836 keeping them where they belong. Just mark all articles you want to save
6837 as dormant, and don't worry.
6839 When an article is marked as read, is it removed from the cache.
6841 @vindex gnus-cache-remove-articles
6842 @vindex gnus-cache-enter-articles
6843 The entering/removal of articles from the cache is controlled by the
6844 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
6845 variables. Both are lists of symbols. The first is @code{(ticked
6846 dormant)} by default, meaning that ticked and dormant articles will be
6847 put in the cache. The latter is @code{(read)} by default, meaning that
6848 articles that are marked as read are removed from the cache. Possibly
6849 symbols in these two lists are @code{ticked}, @code{dormant},
6850 @code{unread} and @code{read}.
6852 @findex gnus-jog-cache
6853 So where does the massive article-fetching and storing come into the
6854 picture? The @code{gnus-jog-cache} command will go through all
6855 subscribed newsgroups, request all unread articles, and store them in
6856 the cache. You should only ever, ever ever ever, use this command if 1)
6857 your connection to the @sc{nntp} server is really, really, really slow
6858 and 2) you have a really, really, really huge disk. Seriously.
6860 @vindex gnus-uncacheable-groups
6861 It is likely that you do not want caching on some groups. For instance,
6862 if your @code{nnml} mail is located under your home directory, it makes no
6863 sense to cache it somewhere else under your home directory. Unless you
6864 feel that it's neat to use twice as much space. To limit the caching,
6865 you could set the @code{gnus-uncacheable-groups} regexp to
6866 @samp{"^nnml"}, for instance. This variable is @code{nil} by
6869 @findex gnus-cache-generate-nov-databases
6870 @findex gnus-cache-generate-active
6871 If your cache becomes all messed up for some reason or other, Gnus
6872 offers two functions that will try to set things right. @kbd{M-x
6873 gnus-cache-generate-nov-databases} will (re)build all the @sc{nov}
6874 files, and @kbd{gnus-cache-generate-active} will (re)generate the active
6878 @node Persistent Articles
6879 @section Persistent Articles
6880 @cindex persistent articles
6882 Closely related to article caching, we have @dfn{persistent articles}.
6883 In fact, it's just a different way of looking at caching, and much more
6884 useful in my opinion.
6886 Say you're reading a newsgroup, and you happen on to some valuable gem
6887 that you want to keep and treasure forever. You'd normally just save it
6888 (using one of the many saving commands) in some file. The problem with
6889 that is that it's just, well, yucky. Ideally you'd prefer just having
6890 the article remain in the group where you found it forever; untouched by
6891 the expiry going on at the news server.
6893 This is what a @dfn{persistent article} is---an article that just won't
6894 be deleted. It's implemented using the normal cache functions, but
6895 you use two explicit commands for managing persistent articles:
6901 @findex gnus-cache-enter-article
6902 Make the current article persistent (@code{gnus-cache-enter-article}).
6905 @kindex M-* (Summary)
6906 @findex gnus-cache-remove-article
6907 Remove the current article from the persistent articles
6908 (@code{gnus-cache-remove-article}). This will normally delete the
6912 Both these commands understand the process/prefix convention.
6914 To avoid having all ticked articles (and stuff) entered into the cache,
6915 you should set @code{gnus-use-cache} to @code{passive} if you're just
6916 interested in persistent articles:
6919 (setq gnus-use-cache 'passive)
6923 @node Article Backlog
6924 @section Article Backlog
6926 @cindex article backlog
6928 If you have a slow connection, but the idea of using caching seems
6929 unappealing to you (and it is, really), you can help the situation some
6930 by switching on the @dfn{backlog}. This is where Gnus will buffer
6931 already read articles so that it doesn't have to re-fetch articles
6932 you've already read. This only helps if you are in the habit of
6933 re-selecting articles you've recently read, of course. If you never do
6934 that, turning the backlog on will slow Gnus down a little bit, and
6935 increase memory usage some.
6937 @vindex gnus-keep-backlog
6938 If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
6939 at most @var{n} old articles in a buffer for later re-fetching. If this
6940 variable is non-@code{nil} and is not a number, Gnus will store
6941 @emph{all} read articles, which means that your Emacs will group without
6942 bound before exploding and taking your machine down with you. I put
6943 that in there just to keep y'all on your toes.
6945 This variable is @code{nil} by default.
6948 @node Exiting the Summary Buffer
6949 @section Exiting the Summary Buffer
6950 @cindex summary exit
6952 Exiting from the summary buffer will normally update all info on the
6953 group and return you to the group buffer.
6959 @kindex Z Z (Summary)
6961 @findex gnus-summary-exit
6962 @vindex gnus-summary-exit-hook
6963 @vindex gnus-summary-prepare-exit-hook
6964 Exit the current group and update all information on the group
6965 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
6966 called before doing much of the exiting, and calls
6967 @code{gnus-summary-expire-articles} by default.
6968 @code{gnus-summary-exit-hook} is called after finishing the exiting
6973 @kindex Z E (Summary)
6975 @findex gnus-summary-exit-no-update
6976 Exit the current group without updating any information on the group
6977 (@code{gnus-summary-exit-no-update}).
6981 @kindex Z c (Summary)
6983 @findex gnus-summary-catchup-and-exit
6984 Mark all unticked articles in the group as read and then exit
6985 (@code{gnus-summary-catchup-and-exit}).
6988 @kindex Z C (Summary)
6989 @findex gnus-summary-catchup-all-and-exit
6990 Mark all articles, even the ticked ones, as read and then exit
6991 (@code{gnus-summary-catchup-all-and-exit}).
6994 @kindex Z n (Summary)
6995 @findex gnus-summary-catchup-and-goto-next-group
6996 Mark all articles as read and go to the next group
6997 (@code{gnus-summary-catchup-and-goto-next-group}).
7000 @kindex Z R (Summary)
7001 @findex gnus-summary-reselect-current-group
7002 Exit this group, and then enter it again
7003 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
7004 all articles, both read and unread.
7008 @kindex Z G (Summary)
7009 @kindex M-g (Summary)
7010 @findex gnus-summary-rescan-group
7011 Exit the group, check for new articles in the group, and select the
7012 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
7013 articles, both read and unread.
7016 @kindex Z N (Summary)
7017 @findex gnus-summary-next-group
7018 Exit the group and go to the next group
7019 (@code{gnus-summary-next-group}).
7022 @kindex Z P (Summary)
7023 @findex gnus-summary-prev-group
7024 Exit the group and go to the previous group
7025 (@code{gnus-summary-prev-group}).
7028 @vindex gnus-exit-group-hook
7029 @code{gnus-exit-group-hook} is called when you exit the current
7032 @findex gnus-summary-wake-up-the-dead
7033 @findex gnus-dead-summary-mode
7034 @vindex gnus-kill-summary-on-exit
7035 If you're in the habit of exiting groups, and then changing your mind
7036 about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}.
7037 If you do that, Gnus won't kill the summary buffer when you exit it.
7038 (Quelle surprise!) Instead it will change the name of the buffer to
7039 something like @samp{"*Dead Summary ... *"} and install a minor mode
7040 called @code{gnus-dead-summary-mode}. Now, if you switch back to this
7041 buffer, you'll find that all keys are mapped to a function called
7042 @code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead
7043 summary buffer will result in a live, normal summary buffer.
7045 There will never be more than one dead summary buffer at any one time.
7047 @vindex gnus-use-cross-reference
7048 The data on the current group will be updated (which articles you have
7049 read, which articles you have replied to, etc.) when you exit the
7050 summary buffer. If the @code{gnus-use-cross-reference} variable is
7051 @code{t} (which is the default), articles that are cross-referenced to
7052 this group and are marked as read, will also be marked as read in the
7053 other subscribed groups they were cross-posted to. If this variable is
7054 neither @code{nil} nor @code{t}, the article will be marked as read in
7055 both subscribed and unsubscribed groups.
7057 Marking cross-posted articles as read ensures that you'll never have to
7058 read the same article more than once. Unless, of course, somebody has
7059 posted it to several groups separately. Posting the same article to
7060 several groups (not cross-posting) is called @dfn{spamming}, and you are
7061 by law required to send nasty-grams to anyone who perpetrates such a
7064 Remember: Cross-posting is kinda ok, but posting the same article
7065 separately to several groups is not.
7067 One thing that may cause Gnus to not do the cross-posting thing
7068 correctly is if you use an @sc{nntp} server that supports @sc{xover}
7069 (which is very nice, because it speeds things up considerably) which
7070 does not include the @code{Xref} header in its @sc{nov} lines. This is
7071 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
7072 even with @sc{xover} by registering the @code{Xref} lines of all
7073 articles you actually read, but if you kill the articles, or just mark
7074 them as read without reading them, Gnus will not get a chance to snoop
7075 the @code{Xref} lines out of these articles, and will be unable to use
7076 the cross reference mechanism.
7078 @vindex gnus-nov-is-evil
7079 If you want Gnus to get the @code{Xref}s right all the time, you have to
7080 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
7086 @node Process/Prefix
7087 @section Process/Prefix
7088 @cindex process/prefix convention
7090 Many functions, among them functions for moving, decoding and saving
7091 articles, use what is known as the @dfn{Process/Prefix convention}.
7093 This is a method for figuring out what articles that the user wants the
7094 command to be performed on.
7098 If the numeric prefix is N, perform the operation on the next N
7099 articles, starting with the current one. If the numeric prefix is
7100 negative, perform the operation on the previous N articles, starting
7101 with the current one.
7103 If @code{transient-mark-mode} in non-@code{nil} and the region is
7104 active, all articles in the region will be worked upon.
7106 If there is no numeric prefix, but some articles are marked with the
7107 process mark, perform the operation on the articles that are marked with
7110 If there is neither a numeric prefix nor any articles marked with the
7111 process mark, just perform the operation on the current article.
7113 Quite simple, really, but it needs to be made clear so that surprises
7116 @vindex gnus-summary-goto-unread
7117 One thing that seems to shock & horrify lots of people is that, for
7118 instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
7119 Since each @kbd{d} (which marks the current article as read) by default
7120 goes to the next unread article after marking, this means that @kbd{3 d}
7121 will mark the next three unread articles as read, no matter what the
7122 summary buffer looks like. Set @code{gnus-summary-goto-unread} to
7123 @code{nil} for a more straightforward action.
7126 @node Saving Articles
7127 @section Saving Articles
7128 @cindex saving articles
7130 Gnus can save articles in a number of ways. Below is the documentation
7131 for saving articles in a fairly straight-forward fashion (i.e., little
7132 processing of the article is done before it is saved). For a different
7133 approach (uudecoding, unsharing) you should use @code{gnus-uu}
7134 (@pxref{Decoding Articles}).
7136 @vindex gnus-save-all-headers
7137 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
7138 unwanted headers before saving the article.
7140 @vindex gnus-saved-headers
7141 If the preceding variable is @code{nil}, all headers that match the
7142 @code{gnus-saved-headers} regexp will be kept, while the rest will be
7143 deleted before saving.
7149 @kindex O o (Summary)
7151 @findex gnus-summary-save-article
7152 Save the current article using the default article saver
7153 (@code{gnus-summary-save-article}).
7156 @kindex O m (Summary)
7157 @findex gnus-summary-save-article-mail
7158 Save the current article in mail format
7159 (@code{gnus-summary-save-article-mail}).
7162 @kindex O r (Summary)
7163 @findex gnus-summary-save-article-mail
7164 Save the current article in rmail format
7165 (@code{gnus-summary-save-article-rmail}).
7168 @kindex O f (Summary)
7169 @findex gnus-summary-save-article-file
7170 Save the current article in plain file format
7171 (@code{gnus-summary-save-article-file}).
7174 @kindex O b (Summary)
7175 @findex gnus-summary-save-article-body-file
7176 Save the current article body in plain file format
7177 (@code{gnus-summary-save-article-body-file}).
7180 @kindex O h (Summary)
7181 @findex gnus-summary-save-article-folder
7182 Save the current article in mh folder format
7183 (@code{gnus-summary-save-article-folder}).
7186 @kindex O p (Summary)
7187 @findex gnus-summary-pipe-output
7188 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
7189 the current article to a process (@code{gnus-summary-pipe-output}).
7192 @vindex gnus-prompt-before-saving
7193 All these commands use the process/prefix convention
7194 (@pxref{Process/Prefix}). If you save bunches of articles using these
7195 functions, you might get tired of being prompted for files to save each
7196 and every article in. The prompting action is controlled by
7197 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
7198 default, giving you that excessive prompting action you know and
7199 loathe. If you set this variable to @code{t} instead, you'll be prompted
7200 just once for each series of articles you save. If you like to really
7201 have Gnus do all your thinking for you, you can even set this variable
7202 to @code{nil}, which means that you will never be prompted for files to
7203 save articles in. Gnus will simply save all the articles in the default
7207 @vindex gnus-default-article-saver
7208 You can customize the @code{gnus-default-article-saver} variable to make
7209 Gnus do what you want it to. You can use any of the four ready-made
7210 functions below, or you can create your own.
7214 @item gnus-summary-save-in-rmail
7215 @findex gnus-summary-save-in-rmail
7216 This is the default format, @dfn{babyl}. Uses the function in the
7217 @code{gnus-rmail-save-name} variable to get a file name to save the
7218 article in. The default is @code{gnus-plain-save-name}.
7220 @item gnus-summary-save-in-mail
7221 @findex gnus-summary-save-in-mail
7222 Save in a Unix mail (mbox) file. Uses the function in the
7223 @code{gnus-mail-save-name} variable to get a file name to save the
7224 article in. The default is @code{gnus-plain-save-name}.
7226 @item gnus-summary-save-in-file
7227 @findex gnus-summary-save-in-file
7228 Append the article straight to an ordinary file. Uses the function in
7229 the @code{gnus-file-save-name} variable to get a file name to save the
7230 article in. The default is @code{gnus-numeric-save-name}.
7232 @item gnus-summary-save-body-in-file
7233 @findex gnus-summary-save-body-in-file
7234 Append the article body to an ordinary file. Uses the function in the
7235 @code{gnus-file-save-name} variable to get a file name to save the
7236 article in. The default is @code{gnus-numeric-save-name}.
7238 @item gnus-summary-save-in-folder
7239 @findex gnus-summary-save-in-folder
7240 Save the article to an MH folder using @code{rcvstore} from the MH
7243 @item gnus-summary-save-in-vm
7244 @findex gnus-summary-save-in-vm
7245 Save the article in a VM folder. You have to have the VM mail
7246 reader to use this setting.
7249 All of these functions, except for the last one, will save the article
7250 in the @code{gnus-article-save-directory}, which is initialized from the
7251 @samp{SAVEDIR} environment variable. This is @file{~/News/} by
7254 As you can see above, the functions use different functions to find a
7255 suitable name of a file to save the article in. Below is a list of
7256 available functions that generate names:
7260 @item gnus-Numeric-save-name
7261 @findex gnus-Numeric-save-name
7262 Generates file names that look like @samp{~/News/Alt.andrea-dworkin/45}.
7264 @item gnus-numeric-save-name
7265 @findex gnus-numeric-save-name
7266 Generates file names that look like @samp{~/News/alt.andrea-dworkin/45}.
7268 @item gnus-Plain-save-name
7269 @findex gnus-Plain-save-name
7270 Generates file names that look like @samp{~/News/Alt.andrea-dworkin}.
7272 @item gnus-plain-save-name
7273 @findex gnus-plain-save-name
7274 Generates file names that look like @samp{~/News/alt.andrea-dworkin}.
7277 @vindex gnus-split-methods
7278 You can have Gnus suggest where to save articles by plonking regexp into
7279 the @code{gnus-split-methods} alist. For instance, if you would like to
7280 save articles related to Gnus in the file @file{gnus-stuff}, and articles
7281 related to VM in @code{vm-stuff}, you could set this variable to something
7285 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
7286 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
7287 (my-choosing-function "../other-dir/my-stuff")
7288 ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
7291 We see that this is a list where each element is a list that has two
7292 elements---the @dfn{match} and the @dfn{file}. The match can either be
7293 a string (in which case it is used as a regexp to match on the article
7294 head); it can be a symbol (which will be called as a function); or it
7295 can be a list (which will be @code{eval}ed). If any of these actions
7296 have a non-@code{nil} result, the @dfn{file} will be used as a default
7297 prompt. In addition, the result of the operation itself will be used if
7298 the function or form called returns a string or a list of strings.
7300 You basically end up with a list of file names that might be used when
7301 saving the current article. (All ``matches'' will be used.) You will
7302 then be prompted for what you really want to use as a name, with file
7303 name completion over the results from applying this variable.
7305 This variable is @code{((gnus-article-archive-name))} by default, which
7306 means that Gnus will look at the articles it saves for an
7307 @samp{Archive-name} line and use that as a suggestion for the file
7310 @vindex gnus-use-long-file-name
7311 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
7312 @code{nil}, all the preceding functions will replace all periods
7313 (@samp{.}) in the group names with slashes (@samp{/})---which means that
7314 the functions will generate hierarchies of directories instead of having
7315 all the files in the toplevel directory
7316 (@samp{~/News/alt/andrea-dworkin} instead of
7317 @samp{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
7318 on most systems. However, for historical reasons, this is @code{nil} on
7319 Xenix and usg-unix-v machines by default.
7321 This function also affects kill and score file names. If this variable
7322 is a list, and the list contains the element @code{not-score}, long file
7323 names will not be used for score files, if it contains the element
7324 @code{not-save}, long file names will not be used for saving, and if it
7325 contains the element @code{not-kill}, long file names will not be used
7328 If you'd like to save articles in a hierarchy that looks something like
7332 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
7333 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
7336 Then just save with @kbd{o}. You'd then read this hierarchy with
7337 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
7338 the toplevel directory as the argument (@file{~/News/}). Then just walk
7339 around to the groups/directories with @code{nneething}.
7342 @node Decoding Articles
7343 @section Decoding Articles
7344 @cindex decoding articles
7346 Sometime users post articles (or series of articles) that have been
7347 encoded in some way or other. Gnus can decode them for you.
7350 * Uuencoded Articles:: Uudecode articles.
7351 * Shared Articles:: Unshar articles.
7352 * PostScript Files:: Split PostScript.
7353 * Decoding Variables:: Variables for a happy decoding.
7354 * Viewing Files:: You want to look at the result of the decoding?
7357 All these functions use the process/prefix convention
7358 (@pxref{Process/Prefix}) for finding out what articles to work on, with
7359 the extension that a ``single article'' means ``a single series''. Gnus can
7360 find out by itself what articles belong to a series, decode all the
7361 articles and unpack/view/save the resulting file(s).
7363 Gnus guesses what articles are in the series according to the following
7364 simplish rule: The subjects must be (nearly) identical, except for the
7365 last two numbers of the line. (Spaces are largely ignored, however.)
7367 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
7368 will find all the articles that match the regexp @samp{^cat.gif
7369 ([0-9]+/[0-9]+).*$}.
7371 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
7372 series}, will not be properly recognized by any of the automatic viewing
7373 commands, and you have to mark the articles manually with @kbd{#}.
7375 @node Uuencoded Articles
7376 @subsection Uuencoded Articles
7378 @cindex uuencoded articles
7383 @kindex X u (Summary)
7384 @findex gnus-uu-decode-uu
7385 Uudecodes the current series (@code{gnus-uu-decode-uu}).
7388 @kindex X U (Summary)
7389 @findex gnus-uu-decode-uu-and-save
7390 Uudecodes and saves the current series
7391 (@code{gnus-uu-decode-uu-and-save}).
7394 @kindex X v u (Summary)
7395 @findex gnus-uu-decode-uu-view
7396 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
7399 @kindex X v U (Summary)
7400 @findex gnus-uu-decode-uu-and-save-view
7401 Uudecodes, views and saves the current series
7402 (@code{gnus-uu-decode-uu-and-save-view}).
7405 Remember that these all react to the presence of articles marked with
7406 the process mark. If, for instance, you'd like to uncode and save an
7407 entire newsgroup, you'd typically do @kbd{M P a}
7408 (@code{gnus-uu-mark-all}) and then @kbd{X U}
7409 (@code{gnus-uu-decode-uu-and-save}).
7411 All this is very much different from how @code{gnus-uu} worked with
7412 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
7413 the sun. This version of @code{gnus-uu} generally assumes that you mark
7414 articles in some way (@pxref{Setting Process Marks}) and then press
7417 Note: When trying to decode articles that have names matching
7418 @code{gnus-uu-notify-files}, which is hard-coded to
7419 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
7420 automatically post an article on @samp{comp.unix.wizards} saying that
7421 you have just viewed the file in question. This feature can't be turned
7424 @node Shared Articles
7425 @subsection Shared Articles
7427 @cindex shared articles
7432 @kindex X s (Summary)
7433 @findex gnus-uu-decode-unshar
7434 Unshars the current series (@code{gnus-uu-decode-unshar}).
7437 @kindex X S (Summary)
7438 @findex gnus-uu-decode-unshar-and-save
7439 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
7442 @kindex X v s (Summary)
7443 @findex gnus-uu-decode-unshar-view
7444 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
7447 @kindex X v S (Summary)
7448 @findex gnus-uu-decode-unshar-and-save-view
7449 Unshars, views and saves the current series
7450 (@code{gnus-uu-decode-unshar-and-save-view}).
7453 @node PostScript Files
7454 @subsection PostScript Files
7460 @kindex X p (Summary)
7461 @findex gnus-uu-decode-postscript
7462 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
7465 @kindex X P (Summary)
7466 @findex gnus-uu-decode-postscript-and-save
7467 Unpack and save the current PostScript series
7468 (@code{gnus-uu-decode-postscript-and-save}).
7471 @kindex X v p (Summary)
7472 @findex gnus-uu-decode-postscript-view
7473 View the current PostScript series
7474 (@code{gnus-uu-decode-postscript-view}).
7477 @kindex X v P (Summary)
7478 @findex gnus-uu-decode-postscript-and-save-view
7479 View and save the current PostScript series
7480 (@code{gnus-uu-decode-postscript-and-save-view}).
7483 @node Decoding Variables
7484 @subsection Decoding Variables
7486 Adjective, not verb.
7489 * Rule Variables:: Variables that say how a file is to be viewed.
7490 * Other Decode Variables:: Other decode variables.
7491 * Uuencoding and Posting:: Variables for customizing uuencoding.
7494 @node Rule Variables
7495 @subsubsection Rule Variables
7496 @cindex rule variables
7498 Gnus uses @dfn{rule variables} to decide how to view a file. All these
7499 variables are on the form
7502 (list '(regexp1 command2)
7509 @item gnus-uu-user-view-rules
7510 @vindex gnus-uu-user-view-rules
7511 This variable is consulted first when viewing files. If you wish to use,
7512 for instance, @code{sox} to convert an @samp{.au} sound file, you could
7515 (setq gnus-uu-user-view-rules
7516 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
7519 @item gnus-uu-user-view-rules-end
7520 @vindex gnus-uu-user-view-rules-end
7521 This variable is consulted if Gnus couldn't make any matches from the
7522 user and default view rules.
7524 @item gnus-uu-user-archive-rules
7525 @vindex gnus-uu-user-archive-rules
7526 This variable can be used to say what commands should be used to unpack
7531 @node Other Decode Variables
7532 @subsubsection Other Decode Variables
7535 @vindex gnus-uu-grabbed-file-functions
7537 @item gnus-uu-grabbed-file-functions
7538 All functions in this list will be called right each file has been
7539 successfully decoded---so that you can move or view files right away,
7540 and don't have to wait for all files to be decoded before you can do
7541 anything. Ready-made functions you can put in this list are:
7545 @item gnus-uu-grab-view
7546 @findex gnus-uu-grab-view
7549 @item gnus-uu-grab-move
7550 @findex gnus-uu-grab-move
7551 Move the file (if you're using a saving function.)
7554 @item gnus-uu-ignore-files-by-name
7555 @vindex gnus-uu-ignore-files-by-name
7556 Files with name matching this regular expression won't be viewed.
7558 @item gnus-uu-ignore-files-by-type
7559 @vindex gnus-uu-ignore-files-by-type
7560 Files with a @sc{mime} type matching this variable won't be viewed.
7561 Note that Gnus tries to guess what type the file is based on the name.
7562 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
7565 @item gnus-uu-tmp-dir
7566 @vindex gnus-uu-tmp-dir
7567 Where @code{gnus-uu} does its work.
7569 @item gnus-uu-do-not-unpack-archives
7570 @vindex gnus-uu-do-not-unpack-archives
7571 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
7572 looking for files to display.
7574 @item gnus-uu-view-and-save
7575 @vindex gnus-uu-view-and-save
7576 Non-@code{nil} means that the user will always be asked to save a file
7579 @item gnus-uu-ignore-default-view-rules
7580 @vindex gnus-uu-ignore-default-view-rules
7581 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
7584 @item gnus-uu-ignore-default-archive-rules
7585 @vindex gnus-uu-ignore-default-archive-rules
7586 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
7589 @item gnus-uu-kill-carriage-return
7590 @vindex gnus-uu-kill-carriage-return
7591 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
7594 @item gnus-uu-unmark-articles-not-decoded
7595 @vindex gnus-uu-unmark-articles-not-decoded
7596 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
7597 unsuccessfully decoded as unread.
7599 @item gnus-uu-correct-stripped-uucode
7600 @vindex gnus-uu-correct-stripped-uucode
7601 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
7602 uuencoded files that have had trailing spaces deleted.
7604 @item gnus-uu-view-with-metamail
7605 @vindex gnus-uu-view-with-metamail
7606 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
7607 commands defined by the rule variables and just fudge a @sc{mime}
7608 content type based on the file name. The result will be fed to
7609 @code{metamail} for viewing.
7611 @item gnus-uu-save-in-digest
7612 @vindex gnus-uu-save-in-digest
7613 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
7614 decoding, will save in digests. If this variable is @code{nil},
7615 @code{gnus-uu} will just save everything in a file without any
7616 embellishments. The digesting almost conforms to RFC1153---no easy way
7617 to specify any meaningful volume and issue numbers were found, so I
7618 simply dropped them.
7622 @node Uuencoding and Posting
7623 @subsubsection Uuencoding and Posting
7627 @item gnus-uu-post-include-before-composing
7628 @vindex gnus-uu-post-include-before-composing
7629 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
7630 before you compose the article. If this variable is @code{t}, you can
7631 either include an encoded file with @kbd{C-c C-i} or have one included
7632 for you when you post the article.
7634 @item gnus-uu-post-length
7635 @vindex gnus-uu-post-length
7636 Maximum length of an article. The encoded file will be split into how
7637 many articles it takes to post the entire file.
7639 @item gnus-uu-post-threaded
7640 @vindex gnus-uu-post-threaded
7641 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
7642 thread. This may not be smart, as no other decoder I have seen are able
7643 to follow threads when collecting uuencoded articles. (Well, I have
7644 seen one package that does that---@code{gnus-uu}, but somehow, I don't
7645 think that counts...) Default is @code{nil}.
7647 @item gnus-uu-post-separate-description
7648 @vindex gnus-uu-post-separate-description
7649 Non-@code{nil} means that the description will be posted in a separate
7650 article. The first article will typically be numbered (0/x). If this
7651 variable is @code{nil}, the description the user enters will be included
7652 at the beginning of the first article, which will be numbered (1/x).
7653 Default is @code{t}.
7658 @subsection Viewing Files
7659 @cindex viewing files
7660 @cindex pseudo-articles
7662 After decoding, if the file is some sort of archive, Gnus will attempt
7663 to unpack the archive and see if any of the files in the archive can be
7664 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
7665 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
7666 uncompress and de-tar the main file, and then view the two pictures.
7667 This unpacking process is recursive, so if the archive contains archives
7668 of archives, it'll all be unpacked.
7670 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
7671 extracted file into the summary buffer. If you go to these ``articles'',
7672 you will be prompted for a command to run (usually Gnus will make a
7673 suggestion), and then the command will be run.
7675 @vindex gnus-view-pseudo-asynchronously
7676 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
7677 until the viewing is done before proceeding.
7679 @vindex gnus-view-pseudos
7680 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
7681 the pseudo-articles into the summary buffer, but view them
7682 immediately. If this variable is @code{not-confirm}, the user won't even
7683 be asked for a confirmation before viewing is done.
7685 @vindex gnus-view-pseudos-separately
7686 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
7687 pseudo-article will be created for each file to be viewed. If
7688 @code{nil}, all files that use the same viewing command will be given as
7689 a list of parameters to that command.
7691 If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert
7692 pseudo-articles when decoding. It is @code{t} by default.
7694 So; there you are, reading your @emph{pseudo-articles} in your
7695 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
7696 Why isn't anything real anymore? How did we get here?
7699 @node Article Treatment
7700 @section Article Treatment
7702 Reading through this huge manual, you may have quite forgotten that the
7703 object of newsreaders are to actually, like, read what people have
7704 written. Reading articles. Unfortunately, people are quite bad at
7705 writing, so there are tons of functions and variables to make reading
7706 these articles easier.
7709 * Article Highlighting:: You want to make the article look like fruit salad.
7710 * Article Hiding:: You also want to make certain info go away.
7711 * Article Washing:: Lots of way-neat functions to make life better.
7712 * Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
7713 * Article Date:: Grumble, UT!
7717 @node Article Highlighting
7718 @subsection Article Highlighting
7721 Not only do you want your article buffer to look like fruit salad, but
7722 you want it to look like technicolor fruit salad.
7727 @kindex W H a (Summary)
7728 @findex gnus-article-highlight
7729 Highlight the current article (@code{gnus-article-highlight}).
7732 @kindex W H h (Summary)
7733 @findex gnus-article-highlight-headers
7734 @vindex gnus-header-face-alist
7735 Highlight the headers (@code{gnus-article-highlight-headers}). The
7736 highlighting will be done according to the @code{gnus-header-face-alist}
7737 variable, which is a list where each element has the form @var{(regexp
7738 name content)}. @var{regexp} is a regular expression for matching the
7739 header, @var{name} is the face used for highlighting the header name and
7740 @var{content} is the face for highlighting the header value. The first
7741 match made will be used. Note that @var{regexp} shouldn't have @samp{^}
7742 prepended---Gnus will add one.
7745 @kindex W H c (Summary)
7746 @findex gnus-article-highlight-citation
7747 Highlight cited text (@code{gnus-article-highlight-citation}).
7749 Some variables to customize the citation highlights:
7752 @vindex gnus-cite-parse-max-size
7754 @item gnus-cite-parse-max-size
7755 If the article size if bigger than this variable (which is 25000 by
7756 default), no citation highlighting will be performed.
7758 @item gnus-cite-prefix-regexp
7759 @vindex gnus-cite-prefix-regexp
7760 Regexp matching the longest possible citation prefix on a line.
7762 @item gnus-cite-max-prefix
7763 @vindex gnus-cite-max-prefix
7764 Maximum possible length for a citation prefix (default 20).
7766 @item gnus-supercite-regexp
7767 @vindex gnus-supercite-regexp
7768 Regexp matching normal SuperCite attribution lines.
7770 @item gnus-supercite-secondary-regexp
7771 @vindex gnus-supercite-secondary-regexp
7772 Regexp matching mangled SuperCite attribution lines.
7774 @item gnus-cite-minimum-match-count
7775 @vindex gnus-cite-minimum-match-count
7776 Minimum number of identical prefixes we have to see before we believe
7777 that it's a citation.
7779 @item gnus-cite-attribution-prefix
7780 @vindex gnus-cite-attribution-prefix
7781 Regexp matching the beginning of an attribution line.
7783 @item gnus-cite-attribution-suffix
7784 @vindex gnus-cite-attribution-suffix
7785 Regexp matching the end of an attribution line.
7787 @item gnus-cite-attribution-face
7788 @vindex gnus-cite-attribution-face
7789 Face used for attribution lines. It is merged with the face for the
7790 cited text belonging to the attribution.
7796 @kindex W H s (Summary)
7797 @vindex gnus-signature-separator
7798 @findex gnus-article-highlight-signature
7799 Highlight the signature (@code{gnus-article-highlight-signature}).
7800 Everything after @code{gnus-signature-separator} in an article will be
7801 considered a signature.
7806 @node Article Hiding
7807 @subsection Article Hiding
7808 @cindex article hiding
7810 Or rather, hiding certain things in each article. There usually is much
7811 too much cruft in most articles.
7816 @kindex W W a (Summary)
7817 @findex gnus-article-hide
7818 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
7821 @kindex W W h (Summary)
7822 @findex gnus-article-hide-headers
7823 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
7827 @kindex W W b (Summary)
7828 @findex gnus-article-hide-boring-headers
7829 Hide headers that aren't particularly interesting
7830 (@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}.
7833 @kindex W W s (Summary)
7834 @findex gnus-article-hide-signature
7835 Hide signature (@code{gnus-article-hide-signature}).
7838 @kindex W W p (Summary)
7839 @findex gnus-article-hide-pgp
7840 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}).
7843 @kindex W W c (Summary)
7844 @findex gnus-article-hide-citation
7845 Hide citation (@code{gnus-article-hide-citation}). Some variables for
7846 customizing the hiding:
7850 @item gnus-cite-hide-percentage
7851 @vindex gnus-cite-hide-percentage
7852 If the cited text is of a bigger percentage than this variable (default
7853 50), hide the cited text.
7855 @item gnus-cite-hide-absolute
7856 @vindex gnus-cite-hide-absolute
7857 The cited text must be have at least this length (default 10) before it
7860 @item gnus-cited-text-button-line-format
7861 @vindex gnus-cited-text-button-line-format
7862 Gnus adds buttons show where the cited text has been hidden, and to
7863 allow toggle hiding the text. The format of the variable is specified
7864 by this format-like variable. These specs are legal:
7868 Start point of the hidden text.
7870 End point of the hidden text.
7872 Length of the hidden text.
7875 @item gnus-cited-lines-visible
7876 @vindex gnus-cited-lines-visible
7877 The number of lines at the beginning of the cited text to leave shown.
7882 @kindex W W C (Summary)
7883 @findex gnus-article-hide-citation-in-followups
7884 Hide cited text in articles that aren't roots
7885 (@code{gnus-article-hide-citation-in-followups}). This isn't very
7886 useful as an interactive command, but might be a handy function to stick
7887 in @code{gnus-article-display-hook} (@pxref{Customizing Articles}).
7891 All these ``hiding'' commands are toggles, but if you give a negative
7892 prefix to these commands, they will show what they have previously
7893 hidden. If you give a positive prefix, they will always hide.
7895 Also see @xref{Article Highlighting} for further variables for
7896 citation customization.
7898 @vindex gnus-signature-limit
7899 @code{gnus-signature-limit} provides a limit to what is considered a
7900 signature. If it is a number, no signature may not be longer (in
7901 characters) than that number. If it is a function, the function will be
7902 called without any parameters, and if it returns @code{nil}, there is no
7903 signature in the buffer. If it is a string, it will be used as a
7904 regexp. If it matches, the text in question is not a signature.
7907 @node Article Washing
7908 @subsection Article Washing
7910 @cindex article washing
7912 We call this ``article washing'' for a really good reason. Namely, the
7913 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
7915 @dfn{Washing} is defined by us as ``changing something from something to
7916 something else'', but normally results in something looking better.
7922 @kindex W l (Summary)
7923 @findex gnus-summary-stop-page-breaking
7924 Remove page breaks from the current article
7925 (@code{gnus-summary-stop-page-breaking}).
7928 @kindex W r (Summary)
7929 @findex gnus-summary-caesar-message
7930 Do a Caesar rotate (rot13) on the article buffer
7931 (@code{gnus-summary-caesar-message}).
7934 @kindex A g (Summary)
7935 @findex gnus-summary-show-article
7936 (Re)fetch the current article (@code{gnus-summary-show-article}). If
7937 given a prefix, fetch the current article, but don't run any of the
7938 article treatment functions. This will give you a ``raw'' article, just
7939 the way it came from the server.
7942 @kindex W t (Summary)
7943 @findex gnus-summary-toggle-header
7944 Toggle whether to display all headers in the article buffer
7945 (@code{gnus-summary-toggle-header}).
7948 @kindex W v (Summary)
7949 @findex gnus-summary-verbose-header
7950 Toggle whether to display all headers in the article buffer permanently
7951 (@code{gnus-summary-verbose-header}).
7954 @kindex W m (Summary)
7955 @findex gnus-summary-toggle-mime
7956 Toggle whether to run the article through @sc{mime} before displaying
7957 (@code{gnus-summary-toggle-mime}).
7960 @kindex W o (Summary)
7961 @findex gnus-article-treat-overstrike
7962 Treat overstrike (@code{gnus-article-treat-overstrike}).
7965 @kindex W w (Summary)
7966 @findex gnus-article-word-wrap
7967 Do word wrap (@code{gnus-article-word-wrap}).
7970 @kindex W c (Summary)
7971 @findex gnus-article-remove-cr
7972 Remove CR (@code{gnus-article-remove-cr}).
7975 @kindex W L (Summary)
7976 @findex gnus-article-remove-trailing-blank-lines
7977 Remove all blank lines at the end of the article
7978 (@code{gnus-article-remove-trailing-blank-lines}).
7981 @kindex W q (Summary)
7982 @findex gnus-article-de-quoted-unreadable
7983 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
7986 @kindex W f (Summary)
7988 @findex gnus-article-display-x-face
7989 @findex gnus-article-x-face-command
7990 @vindex gnus-article-x-face-command
7991 @vindex gnus-article-x-face-too-ugly
7992 Look for and display any X-Face headers
7993 (@code{gnus-article-display-x-face}). The command executed by this
7994 function is given by the @code{gnus-article-x-face-command} variable. If
7995 this variable is a string, this string will be executed in a sub-shell.
7996 If it is a function, this function will be called with the face as the
7997 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
7998 matches the @code{From} header, the face will not be shown.
8001 @kindex W b (Summary)
8002 @findex gnus-article-add-buttons
8003 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
8006 @kindex W B (Summary)
8007 @findex gnus-article-add-buttons-to-head
8008 Add clickable buttons to the article headers
8009 (@code{gnus-article-add-buttons-to-head}).
8014 @node Article Buttons
8015 @subsection Article Buttons
8018 People often include references to other stuff in articles, and it would
8019 be nice if Gnus could just fetch whatever it is that people talk about
8020 with the minimum of fuzz.
8022 Gnus adds @dfn{buttons} to certain standard references by default:
8023 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
8024 two variables, one that handles article bodies and one that handles
8029 @item gnus-button-alist
8030 @vindex gnus-header-button-alist
8031 This is an alist where each entry has this form:
8034 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
8040 All text that match this regular expression will be considered an
8041 external reference. Here's a typical regexp that match embedded URLs:
8042 @samp{"<URL:\\([^\n\r>]*\\)>"}.
8045 Gnus has to know which parts of the match is to be highlighted. This is
8046 a number that says what sub-expression of the regexp that is to be
8047 highlighted. If you want it all highlighted, you use @samp{0} here.
8050 This form will be @code{eval}ed, and if the result is non-@code{nil},
8051 this is considered a match. This is useful if you want extra sifting to
8052 avoid false matches.
8055 This function will be called when you click on this button.
8058 As with @var{button-par}, this is a sub-expression number, but this one
8059 says which part of the match is to be sent as data to @var{function}.
8063 So the full entry for buttonizing URLs is then
8066 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
8069 @item gnus-header-button-alist
8070 @vindex gnus-header-button-alist
8071 This is just like the other alist, except that it is applied to the
8072 article head only, and that each entry has an additional element that is
8073 used to say what headers to apply the buttonize coding to:
8076 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
8079 @var{header} is a regular expression.
8083 @vindex gnus-article-button-face
8084 @vindex gnus-article-mouse-face
8085 Buttons are highlighted with @code{gnus-article-button-face}, while
8086 @code{gnus-article-mouse-face} is used when the mouse cursor is over the
8091 @subsection Article Date
8093 The date is most likely generated in some obscure timezone you've never
8094 heard of, so it's quite nice to be able to find out what the time was
8095 when the article was sent.
8100 @kindex W T u (Summary)
8101 @findex gnus-article-date-ut
8102 Display the date in UT (aka. GMT, aka ZULU)
8103 (@code{gnus-article-date-ut}).
8106 @kindex W T l (Summary)
8107 @findex gnus-article-date-local
8108 Display the date in the local timezone (@code{gnus-article-date-local}).
8111 @kindex W T e (Summary)
8112 @findex gnus-article-date-lapsed
8113 Say how much time has (e)lapsed between the article was posted and now
8114 (@code{gnus-article-date-lapsed}).
8117 @kindex W T o (Summary)
8118 @findex gnus-article-date-original
8119 Display the original date (@code{gnus-article-date-original}). This can
8120 be useful if you normally use some other conversion function and is
8121 worried that it might be doing something totally wrong. Say, claiming
8122 that the article was posted in 1854. Although something like that is
8123 @emph{totally} impossible. Don't you trust me? *titter*
8128 @node Summary Sorting
8129 @section Summary Sorting
8130 @cindex summary sorting
8132 You can have the summary buffer sorted in various ways, even though I
8133 can't really see why you'd want that.
8138 @kindex C-c C-s C-n (Summary)
8139 @findex gnus-summary-sort-by-number
8140 Sort by article number (@code{gnus-summary-sort-by-number}).
8143 @kindex C-c C-s C-a (Summary)
8144 @findex gnus-summary-sort-by-author
8145 Sort by author (@code{gnus-summary-sort-by-author}).
8148 @kindex C-c C-s C-s (Summary)
8149 @findex gnus-summary-sort-by-subject
8150 Sort by subject (@code{gnus-summary-sort-by-subject}).
8153 @kindex C-c C-s C-d (Summary)
8154 @findex gnus-summary-sort-by-date
8155 Sort by date (@code{gnus-summary-sort-by-date}).
8158 @kindex C-c C-s C-i (Summary)
8159 @findex gnus-summary-sort-by-score
8160 Sort by score (@code{gnus-summary-sort-by-score}).
8163 These functions will work both when you use threading and when you don't
8164 use threading. In the latter case, all summary lines will be sorted,
8165 line by line. In the former case, sorting will be done on a
8166 root-by-root basis, which might not be what you were looking for. To
8167 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
8171 @node Finding the Parent
8172 @section Finding the Parent
8173 @cindex parent articles
8174 @cindex referring articles
8176 @findex gnus-summary-refer-parent-article
8178 If you'd like to read the parent of the current article, and it is not
8179 displayed in the article buffer, you might still be able to. That is,
8180 if the current group is fetched by @sc{nntp}, the parent hasn't expired
8181 and the @code{References} in the current article are not mangled, you
8182 can just press @kbd{^} or @kbd{A r}
8183 (@code{gnus-summary-refer-parent-article}). If everything goes well,
8184 you'll get the parent. If the parent is already displayed in the
8185 summary buffer, point will just move to this article.
8187 @findex gnus-summary-refer-references
8188 @kindex A R (Summary)
8189 You can have Gnus fetch all articles mentioned in the @code{References}
8190 header of the article by pushing @kbd{A R}
8191 (@code{gnus-summary-refer-references}).
8193 @findex gnus-summary-refer-article
8194 @kindex M-^ (Summary)
8195 You can also ask the @sc{nntp} server for an arbitrary article, no
8196 matter what group it belongs to. @kbd{M-^}
8197 (@code{gnus-summary-refer-article}) will ask you for a
8198 @code{Message-ID}, which is one of those long thingies that look
8199 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
8200 it all exactly right. No fuzzy searches, I'm afraid.
8202 @vindex gnus-refer-article-method
8203 If the group you are reading is located on a backend that does not
8204 support fetching by @code{Message-ID} very well (like @code{nnspool}),
8205 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
8206 would, perhaps, be best if the @sc{nntp} server you consult is the same
8207 as the one that keeps the spool you are reading from updated, but that's
8208 not really necessary.
8210 Most of the mail backends support fetching by @code{Message-ID}, but do
8211 not do a particularly excellent job of it. That is, @code{nnmbox} and
8212 @code{nnbabyl} are able to locate articles from any groups, while
8213 @code{nnml} and @code{nnfolder} are only able to locate articles that
8214 have been posted to the current group. (Anything else would be too time
8215 consuming.) @code{nnmh} does not support this at all.
8218 @node Alternative Approaches
8219 @section Alternative Approaches
8221 Different people like to read news using different methods. This being
8222 Gnus, we offer a small selection of minor modes for the summary buffers.
8225 * Pick and Read:: First mark articles and then read them.
8226 * Binary Groups:: Auto-decode all articles.
8231 @subsection Pick and Read
8232 @cindex pick and read
8234 Some newsreaders (like @code{nn} and, uhm, @code{nn}) use a two-phased
8235 reading interface. The user first marks the articles she wants to read
8236 from a summary buffer. Then she starts reading the articles with just
8237 an article buffer displayed.
8239 @findex gnus-pick-mode
8240 @kindex M-x gnus-pick-mode
8241 Gnus provides a summary buffer minor mode that allows
8242 this---@code{gnus-pick-mode}. This basically means that a few process
8243 mark commands become one-keystroke commands to allow easy marking, and
8244 it makes one additional command for switching to the summary buffer
8247 Here are the available keystrokes when using pick mode:
8251 Pick the article (@code{gnus-summary-mark-as-processable}).
8254 Unpick the article (@code{gnus-summary-unmark-as-processable}).
8257 Unpick all articles (@code{gnus-summary-unmark-all-processable}).
8260 Pick the thread (@code{gnus-uu-mark-thread}).
8263 Unpick the thread (@code{gnus-uu-unmark-thread}).
8266 Pick the region (@code{gnus-uu-mark-region}).
8269 Unpick the region (@code{gnus-uu-unmark-region}).
8272 Pick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
8275 Unpick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
8278 Pick the buffer (@code{gnus-uu-mark-buffer}).
8281 Unpick the buffer (@code{gnus-uu-unmark-buffer}).
8284 @vindex gnus-pick-display-summary
8285 Start reading the picked articles (@code{gnus-pick-start-reading}). If
8286 given a prefix, mark all unpicked articles as read first. If
8287 @code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer
8288 will still be visible when you are reading.
8292 If this sounds like a good idea to you, you could say:
8295 (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
8300 @subsection Binary Groups
8301 @cindex binary groups
8303 @findex gnus-binary-mode
8304 @kindex M-x gnus-binary-mode
8305 If you spend much time in binary groups, you may grow tired of hitting
8306 @kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode}
8307 is a minor mode for summary buffers that makes all ordinary Gnus article
8308 selection functions uudecode series of articles and display the result
8309 instead of just displaying the articles the normal way.
8312 @findex gnus-binary-show-article
8313 In fact, the only way to see the actual articles if you have turned this
8314 mode on is the @kbd{g} command (@code{gnus-binary-show-article}).
8318 @section Tree Display
8321 @vindex gnus-use-trees
8322 If you don't like the normal Gnus summary display, you might try setting
8323 @code{gnus-use-trees} to @code{t}. This will create (by default) an
8324 additional @dfn{tree buffer}. You can execute all summary mode commands
8327 There are a few variables to customize the tree display, of course:
8330 @item gnus-tree-mode-hook
8331 @vindex gnus-tree-mode-hook
8332 A hook called in all tree mode buffers.
8334 @item gnus-tree-mode-line-format
8335 @vindex gnus-tree-mode-line-format
8336 A format string for the mode bar in the tree mode buffers. The default
8337 is @samp{"Gnus: %%b [%A] %Z"}. For a list of legal specs, @xref{Summary
8340 @item gnus-selected-tree-face
8341 @vindex gnus-selected-tree-face
8342 Face used for highlighting the selected article in the tree buffer. The
8343 default is @code{modeline}.
8345 @item gnus-tree-line-format
8346 @vindex gnus-tree-line-format
8347 A format string for the tree nodes. The name is a bit of a misnomer,
8348 though---it doesn't define a line, but just the node. The default value
8349 is @samp{"%(%[%3,3n%]%)"}, which displays the first three characters of
8350 the name of the poster. It is vital that all nodes are of the same
8351 length, so you @emph{must} use @samp{%4,4n}-like specifiers.
8357 The name of the poster.
8359 The @code{From} header.
8361 The number of the article.
8363 The opening bracket.
8365 The closing bracket.
8370 @xref{Formatting Variables}.
8372 Variables related to the display are:
8375 @item gnus-tree-brackets
8376 @vindex gnus-tree-brackets
8377 This is used for differentiating between ``real'' articles and ``sparse''
8378 articles. The format is @var{((real-open . real-close) (sparse-open
8379 . sparse-close) (dummy-open . dummy-close))}, and the default is
8380 @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}))}.
8382 @item gnus-tree-parent-child-edges
8383 @vindex gnus-tree-parent-child-edges
8384 This is a list that contains the characters used for connecting parent
8385 nodes to their children. The default is @code{(?- ?\\ ?|)}.
8389 @item gnus-tree-minimize-window
8390 @vindex gnus-tree-minimize-window
8391 If this variable is non-@code{nil}, Gnus will try to keep the tree
8392 buffer as small as possible to allow more room for the other Gnus
8393 windows. If this variable is a number, the tree buffer will never be
8394 higher than that number. The default is @code{t}.
8396 @item gnus-generate-tree-function
8397 @vindex gnus-generate-tree-function
8398 @findex gnus-generate-horizontal-tree
8399 @findex gnus-generate-vertical-tree
8400 The function that actually generates the thread tree. Two predefined
8401 functions are available: @code{gnus-generate-horizontal-tree} and
8402 @code{gnus-generate-vertical-tree} (which is the default).
8406 Here's and example from a horizontal tree buffer:
8409 @{***@}-(***)-[odd]-[Gun]
8419 Here's the same thread displayed in a vertical tree buffer:
8423 |--------------------------\-----\-----\
8424 (***) [Bjo] [Gun] [Gun]
8426 [odd] [Jan] [odd] (***) [Jor]
8428 [Gun] [Eri] [Eri] [odd]
8434 @node Mail Group Commands
8435 @section Mail Group Commands
8436 @cindex mail group commands
8438 Some commands only make sense in mail groups. If these commands are
8439 illegal in the current group, they will raise a hell and let you know.
8441 All these commands (except the expiry and edit commands) use the
8442 process/prefix convention (@pxref{Process/Prefix}).
8447 @kindex B e (Summary)
8448 @findex gnus-summary-expire-articles
8449 Expire all expirable articles in the group
8450 (@code{gnus-summary-expire-articles}).
8453 @kindex B M-C-e (Summary)
8454 @findex gnus-summary-expire-articles-now
8455 Expunge all the expirable articles in the group
8456 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
8457 articles that are eligible for expiry in the current group will
8458 disappear forever into that big @file{/dev/null} in the sky.
8461 @kindex B DEL (Summary)
8462 @findex gnus-summary-delete-articles
8463 Delete the mail article. This is ``delete'' as in ``delete it from your
8464 disk forever and ever, never to return again.'' Use with caution.
8465 (@code{gnus-summary-delete-article}).
8468 @kindex B m (Summary)
8470 @findex gnus-summary-move-article
8471 Move the article from one mail group to another
8472 (@code{gnus-summary-move-article}).
8475 @kindex B c (Summary)
8477 @findex gnus-summary-copy-article
8478 Copy the article from one group (mail group or not) to a mail group
8479 (@code{gnus-summary-copy-article}).
8482 @kindex B C (Summary)
8483 @cindex crosspost mail
8484 @findex gnus-summary-crosspost-article
8485 Crosspost the current article to some other group
8486 (@code{gnus-summary-crosspost-article}). This will create a new copy of
8487 the article in the other group, and the Xref headers of the article will
8488 be properly updated.
8491 @kindex B i (Summary)
8492 @findex gnus-summary-import-article
8493 Import a random file into the current mail newsgroup
8494 (@code{gnus-summary-import-article}). You will be prompted for a file
8495 name, a @code{From} header and a @code{Subject} header.
8497 Something similar can be done by just starting to compose a mail
8498 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
8499 @kbd{C-c C-p} instead. This will put the message you have just created
8500 into the current mail group.
8503 @kindex B r (Summary)
8504 @findex gnus-summary-respool-article
8505 Respool the mail article (@code{gnus-summary-move-article}).
8509 @kindex B w (Summary)
8511 @findex gnus-summary-edit-article
8512 @kindex C-c C-c (Article)
8513 Edit the current article (@code{gnus-summary-edit-article}). To finish
8514 editing and make the changes permanent, type @kbd{C-c C-c}
8515 (@kbd{gnus-summary-edit-article-done}).
8518 @kindex B q (Summary)
8519 @findex gnus-summary-respool-query
8520 If you want to re-spool an article, you might be curious as to what group
8521 the article will end up in before you do the re-spooling. This command
8522 will tell you (@code{gnus-summary-fancy-query}).
8525 If you move (or copy) articles regularly, you might wish to have Gnus
8526 suggest where to put the articles. @code{gnus-move-split-methods} is a
8527 variable that uses the same syntax as @code{gnus-split-methods}
8528 (@pxref{Saving Articles}). You may customize that variable to create
8529 suggestions you find reasonable.
8532 @node Various Summary Stuff
8533 @section Various Summary Stuff
8536 * Group Information:: Information oriented commands.
8537 * Searching for Articles:: Multiple article commands.
8538 * Really Various Summary Commands:: Those pesky non-conformant commands.
8541 @vindex gnus-summary-generate-hook
8542 @code{gnus-summary-generate-hook} is called as the last thing before
8543 doing the threading and the generation of the summary buffer. It's
8544 quite convenient for customizing the threading variables based on what
8545 data the newsgroup has. This hook is called from the summary buffer
8546 after most summary buffer variables has been set.
8548 @vindex gnus-summary-prepare-hook
8549 @code{gnus-summary-prepare-hook} is called after the summary buffer has
8550 been generated. You might use it to, for instance, highlight lines or
8551 modify the look of the buffer in some other ungodly manner. I don't
8554 @node Group Information
8555 @subsection Group Information
8560 @kindex H f (Summary)
8561 @findex gnus-summary-fetch-faq
8562 @vindex gnus-group-faq-directory
8563 Try to fetch the FAQ (list of frequently asked questions) for the
8564 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
8565 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
8566 on a remote machine. This variable can also be a list of directories.
8567 In that case, giving a prefix to this command will allow you to choose
8568 between the various sites. @code{ange-ftp} probably will be used for
8572 @kindex H d (Summary)
8573 @findex gnus-summary-describe-group
8574 Give a brief description of the current group
8575 (@code{gnus-summary-describe-group}). If given a prefix, force
8576 rereading the description from the server.
8579 @kindex H h (Summary)
8580 @findex gnus-summary-describe-briefly
8581 Give a very brief description of the most important summary keystrokes
8582 (@code{gnus-summary-describe-briefly}).
8585 @kindex H i (Summary)
8586 @findex gnus-info-find-node
8587 Go to the Gnus info node (@code{gnus-info-find-node}).
8590 @node Searching for Articles
8591 @subsection Searching for Articles
8596 @kindex M-s (Summary)
8597 @findex gnus-summary-search-article-forward
8598 Search through all subsequent articles for a regexp
8599 (@code{gnus-summary-search-article-forward}).
8602 @kindex M-r (Summary)
8603 @findex gnus-summary-search-article-backward
8604 Search through all previous articles for a regexp
8605 (@code{gnus-summary-search-article-backward}).
8609 @findex gnus-summary-execute-command
8610 This command will prompt you for a header field, a regular expression to
8611 match on this field, and a command to be executed if the match is made
8612 (@code{gnus-summary-execute-command}).
8615 @kindex M-& (Summary)
8616 @findex gnus-summary-universal-argument
8617 Perform any operation on all articles that have been marked with
8618 the process mark (@code{gnus-summary-universal-argument}).
8621 @node Really Various Summary Commands
8622 @subsection Really Various Summary Commands
8627 @kindex A D (Summary)
8628 @findex gnus-summary-enter-digest-group
8629 If the current article is a collection of other articles (for instance,
8630 a digest), you might use this command to enter a group based on the that
8631 article (@code{gnus-summary-enter-digest-group}). Gnus will try to
8632 guess what article type is currently displayed unless you give a prefix
8633 to this command, which forces a ``digest'' interpretation. Basically,
8634 whenever you see a message that is a collection of other messages on
8635 some format, you @kbd{A D} and read these messages in a more convenient
8639 @kindex C-t (Summary)
8640 @findex gnus-summary-toggle-truncation
8641 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
8645 @findex gnus-summary-expand-window
8646 Expand the summary buffer window (@code{gnus-summary-expand-window}).
8647 If given a prefix, force an @code{article} window configuration.
8651 @node The Article Buffer
8652 @chapter The Article Buffer
8653 @cindex article buffer
8655 The articles are displayed in the article buffer, of which there is only
8656 one. All the summary buffers share the same article buffer unless you
8657 tell Gnus otherwise.
8660 * Hiding Headers:: Deciding what headers should be displayed.
8661 * Using MIME:: Pushing articles through @sc{mime} before reading them.
8662 * Customizing Articles:: Tailoring the look of the articles.
8663 * Article Keymap:: Keystrokes available in the article buffer
8664 * Misc Article:: Other stuff.
8668 @node Hiding Headers
8669 @section Hiding Headers
8670 @cindex hiding headers
8671 @cindex deleting headers
8673 The top section of each article is the @dfn{head}. (The rest is the
8674 @dfn{body}, but you may have guessed that already.)
8676 @vindex gnus-show-all-headers
8677 There is a lot of useful information in the head: the name of the person
8678 who wrote the article, the date it was written and the subject of the
8679 article. That's well and nice, but there's also lots of information
8680 most people do not want to see---what systems the article has passed
8681 through before reaching you, the @code{Message-ID}, the
8682 @code{References}, etc. ad nauseum---and you'll probably want to get rid
8683 of some of those lines. If you want to keep all those lines in the
8684 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
8686 Gnus provides you with two variables for sifting headers:
8690 @item gnus-visible-headers
8691 @vindex gnus-visible-headers
8692 If this variable is non-@code{nil}, it should be a regular expression
8693 that says what headers you wish to keep in the article buffer. All
8694 headers that do not match this variable will be hidden.
8696 For instance, if you only want to see the name of the person who wrote
8697 the article and the subject, you'd say:
8700 (setq gnus-visible-headers "^From:\\|^Subject:")
8703 This variable can also be a list of regexps to match headers that are to
8706 @item gnus-ignored-headers
8707 @vindex gnus-ignored-headers
8708 This variable is the reverse of @code{gnus-visible-headers}. If this
8709 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
8710 should be a regular expression that matches all lines that you want to
8711 hide. All lines that do not match this variable will remain visible.
8713 For instance, if you just want to get rid of the @code{References} line
8714 and the @code{Xref} line, you might say:
8717 (setq gnus-ignored-headers "^References:\\|^Xref:")
8720 This variable can also be a list of regexps to match headers that are to
8723 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
8724 variable will have no effect.
8728 @vindex gnus-sorted-header-list
8729 Gnus can also sort the headers for you. (It does this by default.) You
8730 can control the sorting by setting the @code{gnus-sorted-header-list}
8731 variable. It is a list of regular expressions that says in what order
8732 the headers are to be displayed.
8734 For instance, if you want the name of the author of the article first,
8735 and then the subject, you might say something like:
8738 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
8741 Any headers that are to remain visible, but are not listed in this
8742 variable, will be displayed in random order after all the headers that
8743 are listed in this variable.
8745 @findex gnus-article-hide-boring-headers
8746 @vindex gnus-article-display-hook
8747 @vindex gnus-boring-article-headers
8748 You can hide further boring headers by entering
8749 @code{gnus-article-hide-boring-headers} into
8750 @code{gnus-article-display-hook}. What this function does depends on
8751 the @code{gnus-boring-article-headers} variable. It's a list, but this
8752 list doesn't actually contain header names. Instead is lists various
8753 @dfn{boring conditions} that Gnus can check and remove from sight.
8755 These conditions are:
8758 Remove all empty headers.
8760 Remove the @code{Newsgroups} header if it only contains the current group
8763 Remove the @code{Followup-To} header if it is identical to the
8764 @code{Newsgroups} header.
8766 Remove the @code{Reply-To} header if it lists the same address as the
8769 Remove the @code{Date} header if the article is less than three days
8773 To include the four first elements, you could say something like;
8776 (setq gnus-boring-article-headers
8777 '(empty newsgroups followup-to reply-to))
8780 This is also the default value for this variable.
8784 @section Using @sc{mime}
8787 Mime is a standard for waving your hands through the air, aimlessly,
8788 while people stand around yawning.
8790 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
8791 while all newsreaders die of fear.
8793 @sc{mime} may specify what character set the article uses, the encoding
8794 of the characters, and it also makes it possible to embed pictures and
8795 other naughty stuff in innocent-looking articles.
8797 @vindex gnus-show-mime
8798 @vindex gnus-show-mime-method
8799 @vindex gnus-strict-mime
8800 Gnus handles @sc{mime} by shoving the articles through
8801 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
8802 default. Set @code{gnus-show-mime} to @code{t} if you want to use
8803 @sc{mime} all the time. However, if @code{gnus-strict-mime} is
8804 non-@code{nil}, the @sc{mime} method will only be used if there are
8805 @sc{mime} headers in the article.
8807 It might be best to just use the toggling functions from the summary
8808 buffer to avoid getting nasty surprises. (For instance, you enter the
8809 group @samp{alt.sing-a-long} and, before you know it, @sc{mime} has
8810 decoded the sound file in the article and some horrible sing-a-long song
8811 comes streaming out out your speakers, and you can't find the volume
8812 button, because there isn't one, and people are starting to look at you,
8813 and you try to stop the program, but you can't, and you can't find the
8814 program to control the volume, and everybody else in the room suddenly
8815 decides to look at you disdainfully, and you'll feel rather stupid.)
8817 Any similarity to real events and people is purely coincidental. Ahem.
8820 @node Customizing Articles
8821 @section Customizing Articles
8822 @cindex article customization
8824 @vindex gnus-article-display-hook
8825 The @code{gnus-article-display-hook} is called after the article has
8826 been inserted into the article buffer. It is meant to handle all
8827 treatment of the article before it is displayed.
8829 By default it contains @code{gnus-article-hide-headers},
8830 @code{gnus-article-treat-overstrike}, and
8831 @code{gnus-article-maybe-highlight}, but there are thousands, nay
8832 millions, of functions you can put in this hook. For an overview of
8833 functions @xref{Article Highlighting}, @xref{Article Hiding},
8834 @xref{Article Washing}, @xref{Article Buttons} and @xref{Article Date}.
8836 You can, of course, write your own functions. The functions are called
8837 from the article buffer, and you can do anything you like, pretty much.
8838 There is no information that you have to keep in the buffer---you can
8839 change everything. However, you shouldn't delete any headers. Instead
8840 make them invisible if you want to make them go away.
8843 @node Article Keymap
8844 @section Article Keymap
8846 Most of the keystrokes in the summary buffer can also be used in the
8847 article buffer. They should behave as if you typed them in the summary
8848 buffer, which means that you don't actually have to have a summary
8849 buffer displayed while reading. You can do it all from the article
8852 A few additional keystrokes are available:
8857 @kindex SPACE (Article)
8858 @findex gnus-article-next-page
8859 Scroll forwards one page (@code{gnus-article-next-page}).
8862 @kindex DEL (Article)
8863 @findex gnus-article-prev-page
8864 Scroll backwards one page (@code{gnus-article-prev-page}).
8867 @kindex C-c ^ (Article)
8868 @findex gnus-article-refer-article
8869 If point is in the neighborhood of a @code{Message-ID} and you press
8870 @kbd{r}, Gnus will try to get that article from the server
8871 (@code{gnus-article-refer-article}).
8874 @kindex C-c C-m (Article)
8875 @findex gnus-article-mail
8876 Send a reply to the address near point (@code{gnus-article-mail}). If
8877 given a prefix, include the mail.
8881 @findex gnus-article-show-summary
8882 Reconfigure the buffers so that the summary buffer becomes visible
8883 (@code{gnus-article-show-summary}).
8887 @findex gnus-article-describe-briefly
8888 Give a very brief description of the available keystrokes
8889 (@code{gnus-article-describe-briefly}).
8892 @kindex TAB (Article)
8893 @findex gnus-article-next-button
8894 Go to the next button, if any (@code{gnus-article-next-button}. This
8895 only makes sense if you have buttonizing turned on.
8898 @kindex M-TAB (Article)
8899 @findex gnus-article-prev-button
8900 Go to the previous button, if any (@code{gnus-article-prev-button}.
8906 @section Misc Article
8910 @item gnus-single-article-buffer
8911 @vindex gnus-single-article-buffer
8912 If non-@code{nil}, use the same article buffer for all the groups.
8913 (This is the default.) If @code{nil}, each group will have its own
8916 @vindex gnus-article-prepare-hook
8918 @item gnus-article-prepare-hook
8919 This hook is called right after the article has been inserted into the
8920 article buffer. It is mainly intended for functions that do something
8921 depending on the contents; it should probably not be used for changing
8922 the contents of the article buffer.
8923 @vindex gnus-article-display-hook
8925 @item gnus-article-display-hook
8926 This hook is called as the last thing when displaying an article, and is
8927 intended for modifying the contents of the buffer, doing highlights,
8928 hiding headers, and the like.
8929 @vindex gnus-article-mode-line-format
8931 @item gnus-article-mode-line-format
8932 This variable is a format string along the same lines as
8933 @code{gnus-summary-mode-line-format}. It accepts exactly the same
8934 format specifications as that variable.
8935 @vindex gnus-break-pages
8937 @item gnus-break-pages
8938 Controls whether @dfn{page breaking} is to take place. If this variable
8939 is non-@code{nil}, the articles will be divided into pages whenever a
8940 page delimiter appears in the article. If this variable is @code{nil},
8941 paging will not be done.
8943 @item gnus-page-delimiter
8944 @vindex gnus-page-delimiter
8945 This is the delimiter mentioned above. By default, it is @samp{^L}
8949 @node The Server Buffer
8950 @chapter The Server Buffer
8952 Traditionally, a @dfn{server} is a machine or a piece of software that
8953 one connects to, and then requests information from. Gnus does not
8954 connect directly to any real servers, but does all transactions through
8955 one backend or other. But that's just putting one layer more between
8956 the actual media and Gnus, so we might just as well say that each
8957 backend represents a virtual server.
8959 For instance, the @code{nntp} backend may be used to connect to several
8960 different actual @sc{nntp} servers, or, perhaps, to many different ports
8961 on the same actual @sc{nntp} server. You tell Gnus which backend to
8962 use, and what parameters to set by specifying a @dfn{select method}.
8964 These select methods specifications can sometimes become quite
8965 complicated---say, for instance, that you want to read from the
8966 @sc{nntp} server @samp{news.funet.fi} on port number @samp{13}, which
8967 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
8968 Anyways, if you had to specify that for each group that used this
8969 server, that would be too much work, so Gnus offers a way of putting
8970 names to methods, which is what you do in the server buffer.
8972 To enter the server buffer, user the @kbd{^}
8973 (@code{gnus-group-enter-server-mode}) command in the group buffer.
8976 * Server Buffer Format:: You can customize the look of this buffer.
8977 * Server Commands:: Commands to manipulate servers.
8978 * Example Methods:: Examples server specifications.
8979 * Servers and Methods:: You can use server names as select methods.
8980 * Unavailable Servers:: Some servers you try to contact may be down.
8983 @node Server Buffer Format
8984 @section Server Buffer Format
8985 @cindex server buffer format
8987 @vindex gnus-server-line-format
8988 You can change the look of the server buffer lines by changing the
8989 @code{gnus-server-line-format} variable. This is a @code{format}-like
8990 variable, with some simple extensions:
8995 How the news is fetched---the backend name.
8998 The name of this server.
9001 Where the news is to be fetched from---the address.
9004 @node Server Commands
9005 @section Server Commands
9006 @cindex server commands
9011 Browse the current server (@code{gnus-server-read-server}).
9014 Return to the group buffer (@code{gnus-server-exit}).
9017 List all servers (@code{gnus-server-list-servers}).
9020 Kill the current server (@code{gnus-server-kill-server}).
9023 Yank the previously killed server (@code{gnus-server-yank-server}).
9026 Copy the current server (@code{gnus-server-copy-server}).
9029 Add a new server (@code{gnus-server-add-server}).
9032 Edit a server (@code{gnus-server-edit-server}).
9035 @node Example Methods
9036 @section Example Methods
9038 Most select methods are pretty simple and self-explanatory:
9041 (nntp "news.funet.fi")
9044 Reading directly from the spool is even simpler:
9050 As you can see, the first element in a select method is the name of the
9051 backend, and the second is the @dfn{address}, or @dfn{name}, if you
9054 After these two elements, there may be a random number of @var{(variable
9057 To go back to the first example---imagine that you want to read from
9058 port @code{15} from that machine. This is what the select method should
9062 (nntp "news.funet.fi" (nntp-port-number 15))
9065 You should read the documentation to each backend to find out what
9066 variables are relevant, but here's an @code{nnmh} example.
9068 @code{nnmh} is a mail backend that reads a spool-like structure. Say
9069 you have two structures that you wish to access: One is your private
9070 mail spool, and the other is a public one. Here's the possible spec for
9074 (nnmh "private" (nnmh-directory "~/private/mail/"))
9077 (This server is then called @samp{private}, but you may have guessed
9080 Here's the method for the public spool:
9084 (nnmh-directory "/usr/information/spool/")
9085 (nnmh-get-new-mail nil))
9088 @node Servers and Methods
9089 @section Servers and Methods
9091 Wherever you would normally use a select method
9092 (eg. @code{gnus-secondary-select-method}, in the group select method,
9093 when browsing a foreign server) you can use a virtual server name
9094 instead. This could potentially save lots of typing. And it's nice all
9098 @node Unavailable Servers
9099 @section Unavailable Servers
9101 If a server seems to be unreachable, Gnus will mark that server as
9102 @code{denied}. That means that any subsequent attempt to make contact
9103 with that server will just be ignored. ``It can't be opened,'' Gnus will
9104 tell you, without making the least effort to see whether that is
9105 actually the case or not.
9107 That might seem quite naughty, but it does make sense most of the time.
9108 Let's say you have 10 groups subscribed to the server
9109 @samp{nepholococcygia.com}. This server is located somewhere quite far
9110 away from you, the machine is quite, so it takes 1 minute just to find
9111 out that it refuses connection from you today. If Gnus were to attempt
9112 to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
9113 that. Once it has gotten a single ``connection refused'', it will regard
9114 that server as ``down''.
9116 So, what happens if the machine was only feeling unwell temporarily?
9117 How do you test to see whether the machine has come up again?
9119 You jump to the server buffer (@pxref{The Server Buffer}) and poke ut
9120 with the following commands:
9126 @findex gnus-server-open-server
9127 Try to establish connection to the server on the current line
9128 (@code{gnus-server-open-server}).
9132 @findex gnus-server-close-server
9133 Close the connection (if any) to the server
9134 (@code{gnus-server-close-server}).
9138 @findex gnus-server-deny-server
9139 Mark the current server as unreachable
9140 (@code{gnus-server-deny-server}).
9144 @findex gnus-server-remove-denials
9145 Remove all marks to whether Gnus was denied connection from all servers
9146 (@code{gnus-server-remove-denials}).
9155 Other people use @dfn{kill files}, but we here at Gnus Towers like
9156 scoring better than killing, so we'd rather switch than fight. They do
9157 something completely different as well, so sit up straight and pay
9160 @vindex gnus-summary-mark-below
9161 All articles have a default score (@code{gnus-summary-default-score}),
9162 which is 0 by default. This score may be raised or lowered either
9163 interactively or by score files. Articles that have a score lower than
9164 @code{gnus-summary-mark-below} are marked as read.
9166 Gnus will read any @dfn{score files} that apply to the current group
9167 before generating the summary buffer.
9169 There are several commands in the summary buffer that insert score
9170 entries based on the current article. You can, for instance, ask Gnus to
9171 lower or increase the score of all articles with a certain subject.
9173 There are two sorts of scoring entries: Permanent and temporary.
9174 Temporary score entries are self-expiring entries. Any entries that are
9175 temporary and have not been used for, say, a week, will be removed
9176 silently to help keep the sizes of the score files down.
9179 * Summary Score Commands:: Adding score entries for the current group.
9180 * Group Score Commands:: General score commands.
9181 * Score Variables:: Customize your scoring. (My, what terminology).
9182 * Score File Format:: What a score file may contain.
9183 * Score File Editing:: You can edit score files by hand as well.
9184 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
9185 * Followups To Yourself:: Having Gnus notice when people answer you.
9186 * Scoring Tips:: How to score effectively.
9187 * Reverse Scoring:: That problem child of old is not problem.
9188 * Global Score Files:: Earth-spanning, ear-splitting score files.
9189 * Kill Files:: They are still here, but they can be ignored.
9192 @node Summary Score Commands
9193 @section Summary Score Commands
9194 @cindex score commands
9196 The score commands that alter score entries do not actually modify real
9197 score files. That would be too inefficient. Gnus maintains a cache of
9198 previously loaded score files, one of which is considered the
9199 @dfn{current score file alist}. The score commands simply insert
9200 entries into this list, and upon group exit, this list is saved.
9202 The current score file is by default the group's local score file, even
9203 if no such score file actually exists. To insert score commands into
9204 some other score file (eg. @file{all.SCORE}), you must first make this
9205 score file the current one.
9207 General score commands that don't actually change the score file:
9212 @kindex V s (Summary)
9213 @findex gnus-summary-set-score
9214 Set the score of the current article (@code{gnus-summary-set-score}).
9217 @kindex V S (Summary)
9218 @findex gnus-summary-current-score
9219 Display the score of the current article
9220 (@code{gnus-summary-current-score}).
9223 @kindex V t (Summary)
9224 @findex gnus-score-find-trace
9225 Display all score rules that have been used on the current article
9226 (@code{gnus-score-find-trace}).
9230 @findex gnus-summary-rescore
9231 Run the current summary through the scoring process
9232 (@code{gnus-summary-rescore}). This might be useful if you're playing
9233 around with your score files behind Gnus' back and want to see the
9234 effect you're having.
9237 @kindex V a (Summary)
9238 @findex gnus-summary-score-entry
9239 Add a new score entry, and allow specifying all elements
9240 (@code{gnus-summary-score-entry}).
9243 @kindex V c (Summary)
9244 @findex gnus-score-change-score-file
9245 Make a different score file the current
9246 (@code{gnus-score-change-score-file}).
9249 @kindex V e (Summary)
9250 @findex gnus-score-edit-alist
9251 Edit the current score file (@code{gnus-score-edit-alist}). You will be
9252 popped into a @code{gnus-score-mode} buffer (@pxref{Score File
9256 @kindex V f (Summary)
9257 @findex gnus-score-edit-file
9258 Edit a score file and make this score file the current one
9259 (@code{gnus-score-edit-file}).
9262 @kindex V C (Summary)
9263 @findex gnus-score-customize
9264 Customize a score file in a visually pleasing manner
9265 (@code{gnus-score-customize}).
9268 @kindex I C-i (Summary)
9269 @findex gnus-summary-raise-score
9270 Increase the score of the current article
9271 (@code{gnus-summary-raise-score}).
9274 @kindex L C-l (Summary)
9275 @findex gnus-summary-lower-score
9276 Lower the score of the current article
9277 (@code{gnus-summary-lower-score}).
9280 The rest of these commands modify the local score file.
9285 @kindex V m (Summary)
9286 @findex gnus-score-set-mark-below
9287 Prompt for a score, and mark all articles with a score below this as
9288 read (@code{gnus-score-set-mark-below}).
9291 @kindex V E (Summary)
9292 @findex gnus-score-set-expunge-below
9293 Expunge all articles with a score below the default score (or the
9294 numeric prefix) (@code{gnus-score-set-expunge-below}).
9297 The keystrokes for actually making score entries follow a very regular
9298 pattern, so there's no need to list all the commands. (Hundreds of
9303 The first key is either @kbd{I} (upper case i) for increasing the score
9304 or @kbd{L} for lowering the score.
9306 The second key says what header you want to score on. The following
9311 Score on the author name.
9314 Score on the subject line.
9317 Score on the Xref line---i.e., the cross-posting line.
9320 Score on thread---the References line.
9326 Score on the number of lines.
9329 Score on the Message-ID.
9342 The third key is the match type. Which match types are legal depends on
9343 what headers you are scoring on.
9387 Greater than number.
9392 The fourth and final key says whether this is a temporary (i.e., expiring)
9393 score entry, or a permanent (i.e., non-expiring) score entry, or whether
9394 it is to be done immediately, without adding to the score file.
9398 Temporary score entry.
9401 Permanent score entry.
9404 Immediately scoring.
9409 So, let's say you want to increase the score on the current author with
9410 exact matching permanently: @kbd{I a e p}. If you want to lower the
9411 score based on the subject line, using substring matching, and make a
9412 temporary score entry: @kbd{L s s t}. Pretty easy.
9414 To make things a bit more complicated, there are shortcuts. If you use
9415 a capital letter on either the second or third keys, Gnus will use
9416 defaults for the remaining one or two keystrokes. The defaults are
9417 ``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s t},
9418 and @kbd{I a R} is the same as @kbd{I a r t}.
9420 @vindex gnus-score-mimic-keymap
9421 The @code{gnus-score-mimic-keymap} says whether these commands will
9422 pretend they are keymaps or not.
9425 @node Group Score Commands
9426 @section Group Score Commands
9427 @cindex group score commands
9429 There aren't many of these as yet, I'm afraid.
9435 @findex gnus-score-flush-cache
9436 Gnus maintains a cache of score alists to avoid having to reload them
9437 all the time. This command will flush the cache
9438 (@code{gnus-score-flush-cache}).
9443 @node Score Variables
9444 @section Score Variables
9445 @cindex score variables
9449 @item gnus-use-scoring
9450 @vindex gnus-use-scoring
9451 If @code{nil}, Gnus will not check for score files, and will not, in
9452 general, do any score-related work. This is @code{t} by default.
9454 @item gnus-kill-killed
9455 @vindex gnus-kill-killed
9456 If this variable is @code{nil}, Gnus will never apply score files to
9457 articles that have already been through the kill process. While this
9458 may save you lots of time, it also means that if you apply a kill file
9459 to a group, and then change the kill file and want to run it over you
9460 group again to kill more articles, it won't work. You have to set this
9461 variable to @code{t} to do that. (It is @code{t} by default.)
9463 @item gnus-kill-files-directory
9464 @vindex gnus-kill-files-directory
9465 All kill and score files will be stored in this directory, which is
9466 initialized from the @samp{SAVEDIR} environment variable by default.
9467 This is @file{~/News/} by default.
9469 @item gnus-score-file-suffix
9470 @vindex gnus-score-file-suffix
9471 Suffix to add to the group name to arrive at the score file name
9472 (@samp{SCORE} by default.)
9474 @item gnus-score-uncacheable-files
9475 @vindex gnus-score-uncacheable-files
9477 All score files are normally cached to avoid excessive re-loading of
9478 score files. However, if this might make you Emacs grow big and
9479 bloated, so this regexp can be used to weed out score files that are
9480 unlikely to be needed again. It would be a bad idea to deny caching of
9481 @file{all.SCORE}, while it might be a good idea to not cache
9482 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
9483 variable is @samp{"ADAPT$"} by default, so no adaptive score files will
9486 @item gnus-save-score
9487 @vindex gnus-save-score
9488 If you have really complicated score files, and do lots of batch
9489 scoring, then you might set this variable to @code{t}. This will make
9490 Gnus save the scores into the @file{.newsrc.eld} file.
9492 @item gnus-score-interactive-default-score
9493 @vindex gnus-score-interactive-default-score
9494 Score used by all the interactive raise/lower commands to raise/lower
9495 score with. Default is 1000, which may seem excessive, but this is to
9496 ensure that the adaptive scoring scheme gets enough room to play with.
9497 We don't want the small changes from the adaptive scoring to overwrite
9498 manually entered data.
9500 @item gnus-summary-default-score
9501 @vindex gnus-summary-default-score
9502 Default score of an article, which is 0 by default.
9504 @item gnus-score-over-mark
9505 @vindex gnus-score-over-mark
9506 Mark (in the third column) used for articles with a score over the
9507 default. Default is @samp{+}.
9509 @item gnus-score-below-mark
9510 @vindex gnus-score-below-mark
9511 Mark (in the third column) used for articles with a score below the
9512 default. Default is @samp{-}.
9514 @item gnus-score-find-score-files-function
9515 @vindex gnus-score-find-score-files-function
9516 Function used to find score files for the current group. This function
9517 is called with the name of the group as the argument.
9519 Predefined functions available are:
9522 @item gnus-score-find-single
9523 @findex gnus-score-find-single
9524 Only apply the group's own score file.
9526 @item gnus-score-find-bnews
9527 @findex gnus-score-find-bnews
9528 Apply all score files that match, using bnews syntax. This is the
9529 default. For instance, if the current group is @samp{gnu.emacs.gnus},
9530 @samp{all.emacs.all.SCORE}, @samp{not.alt.all.SCORE} and
9531 @samp{gnu.all.SCORE} would all apply. In short, the instances of
9532 @samp{all} in the score file names are translated into @samp{.*}, and
9533 then a regexp match is done.
9535 This means that if you have some score entries that you want to apply to
9536 all groups, then you put those entries in the @file{all.SCORE} file.
9538 If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
9539 very will. It will find stuff like @file{gnu/all/SCORE}, but will not
9540 find files like @file{not/gnu/all/SCORE}.
9542 @item gnus-score-find-hierarchical
9543 @findex gnus-score-find-hierarchical
9544 Apply all score files from all the parent groups. This means that you
9545 can't have score files like @file{all.SCORE} or @file{all.emacs.SCORE},
9546 but you can have @file{SCORE}, @file{comp.SCORE} and
9547 @file{comp.emacs.SCORE}.
9550 This variable can also be a list of functions. In that case, all these
9551 functions will be called, and all the returned lists of score files will
9552 be applied. These functions can also return lists of score alists
9553 directly. In that case, the functions that return these non-file score
9554 alists should probably be placed before the ``real'' score file functions,
9555 to ensure that the last score file returned is the local score file.
9558 @item gnus-score-expiry-days
9559 @vindex gnus-score-expiry-days
9560 This variable says how many days should pass before an unused score file
9561 entry is expired. If this variable is @code{nil}, no score file entries
9562 are expired. It's 7 by default.
9564 @item gnus-update-score-entry-dates
9565 @vindex gnus-update-score-entry-dates
9566 If this variable is non-@code{nil}, matching score entries will have
9567 their dates updated. (This is how Gnus controls expiry---all
9568 non-matching entries will become too old while matching entries will
9569 stay fresh and young.) However, if you set this variable to @code{nil},
9570 even matching entries will grow old and will have to face that oh-so
9576 @node Score File Format
9577 @section Score File Format
9578 @cindex score file format
9580 A score file is an @code{emacs-lisp} file that normally contains just a
9581 single form. Casual users are not expected to edit these files;
9582 everything can be changed from the summary buffer.
9584 Anyway, if you'd like to dig into it yourself, here's an example:
9588 ("Lars Ingebrigtsen" -10000)
9590 ("larsi\\|lmi" -50000 nil R))
9592 ("Ding is Badd" nil 728373))
9594 ("alt.politics" -1000 728372 s))
9599 (mark-and-expunge -10)
9603 (files "/hom/larsi/News/gnu.SCORE")
9604 (exclude-files "all.SCORE")
9605 (local (gnus-newsgroup-auto-expire t)
9606 (gnus-summary-make-false-root 'empty))
9610 This example demonstrates absolutely everything about a score file.
9612 Even though this looks much like lisp code, nothing here is actually
9613 @code{eval}ed. The lisp reader is used to read this form, though, so it
9614 has to be legal syntactically, if not semantically.
9616 Six keys are supported by this alist:
9621 If the key is a string, it is the name of the header to perform the
9622 match on. Scoring can only be performed on these eight headers:
9623 @samp{From}, @samp{Subject}, @samp{References}, @samp{Message-ID},
9624 @samp{Xref}, @samp{Lines}, @samp{Chars} and @samp{Date}. In addition to
9625 these headers, there are three strings to tell Gnus to fetch the entire
9626 article and do the match on larger parts of the article: @samp{Body}
9627 will perform the match on the body of the article, @samp{Head} will
9628 perform the match on the head of the article, and @samp{All} will
9629 perform the match on the entire article. Note that using any of these
9630 last three keys will slow down group entry @emph{considerably}. The
9631 final ``header'' you can score on is @samp{Followup}. These score entries
9632 will result in new score entries being added for all follow-ups to
9633 articles that matches these score entries.
9635 Following this key is a random number of score entries, where each score
9636 entry has one to four elements.
9640 The first element is the @dfn{match element}. On most headers this will
9641 be a string, but on the Lines and Chars headers, this must be an
9645 If the second element is present, it should be a number---the @dfn{score
9646 element}. This number should be an integer in the neginf to posinf
9647 interval. This number is added to the score of the article if the match
9648 is successful. If this element is not present, the
9649 @code{gnus-score-interactive-default-score} number will be used
9650 instead. This is 1000 by default.
9653 If the third element is present, it should be a number---the @dfn{date
9654 element}. This date says when the last time this score entry matched,
9655 which provides a mechanism for expiring the score entries. It this
9656 element is not present, the score entry is permanent. The date is
9657 represented by the number of days since December 31, 1 ce.
9660 If the fourth element is present, it should be a symbol---the @dfn{type
9661 element}. This element specifies what function should be used to see
9662 whether this score entry matches the article. What match types that can
9663 be used depends on what header you wish to perform the match on.
9666 @item From, Subject, References, Xref, Message-ID
9667 For most header types, there are the @code{r} and @code{R} (regexp) as
9668 well as @code{s} and @code{S} (substring) types and @code{e} and
9669 @code{E} (exact match) types. If this element is not present, Gnus will
9670 assume that substring matching should be used. @code{R} and @code{S}
9671 differ from the other two in that the matches will be done in a
9672 case-sensitive manner. All these one-letter types are really just
9673 abbreviations for the @code{regexp}, @code{string} and @code{exact}
9674 types, which you can use instead, if you feel like.
9677 These two headers use different match types: @code{<}, @code{>},
9678 @code{=}, @code{>=} and @code{<=}.
9681 For the Date header we have three match types: @code{before}, @code{at}
9682 and @code{after}. I can't really imagine this ever being useful, but,
9683 like, it would feel kinda silly not to provide this function. Just in
9684 case. You never know. Better safe than sorry. Once burnt, twice shy.
9685 Don't judge a book by its cover. Never not have sex on a first date.
9687 @item Head, Body, All
9688 These three match keys use the same match types as the @code{From} (etc)
9692 This match key will add a score entry on all articles that followup to
9693 some author. Uses the same match types as the @code{From} header uses.
9696 This match key will add a score entry on all articles that are part of
9697 a thread. Uses the same match types as the @code{References} header
9703 The value of this entry should be a number. Any articles with a score
9704 lower than this number will be marked as read.
9707 The value of this entry should be a number. Any articles with a score
9708 lower than this number will be removed from the summary buffer.
9710 @item mark-and-expunge
9711 The value of this entry should be a number. Any articles with a score
9712 lower than this number will be marked as read and removed from the
9715 @item thread-mark-and-expunge
9716 The value of this entry should be a number. All articles that belong to
9717 a thread that has a total score below this number will be marked as read
9718 and removed from the summary buffer. @code{gnus-thread-score-function}
9719 says how to compute the total score for a thread.
9722 The value of this entry should be any number of file names. These files
9723 are assumed to be score files as well, and will be loaded the same way
9727 The clue of this entry should be any number of files. This files will
9728 not be loaded, even though they would normally be so, for some reason or
9732 The value of this entry will be @code{eval}el. This element will be
9733 ignored when handling global score files.
9736 Read-only score files will not be updated or saved. Global score files
9737 should feature this atom (@pxref{Global Score Files}).
9740 The value of this entry should be a number. Articles that do not have
9741 parents will get this number added to their scores.
9744 This entry controls the adaptive scoring. If it is @code{t}, the
9745 default adaptive scoring rules will be used. If it is @code{ignore}, no
9746 adaptive scoring will be performed on this group. If it is a list, this
9747 list will be used as the adaptive scoring rules. If it isn't present,
9748 or is something other than @code{t} or @code{ignore}, the default
9749 adaptive scoring rules will be used. If you want to use adaptive
9750 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
9751 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
9752 not want adaptive scoring. If you only want adaptive scoring in a few
9753 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
9754 insert @code{(adapt t)} in the score files of the groups where you want
9758 All adaptive score entries will go to the file named by this entry. It
9759 will also be applied when entering the group. This atom might be handy
9760 if you want to adapt on several groups at once, using the same adaptive
9761 file for a number of groups.
9764 @cindex local variables
9765 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
9766 Each @var{var} will be made buffer-local to the current summary buffer,
9767 and set to the value specified. This is a convenient, if somewhat
9768 strange, way of setting variables in some groups if you don't like hooks
9772 @node Score File Editing
9773 @section Score File Editing
9775 You normally enter all scoring commands from the summary buffer, but you
9776 might feel the urge to edit them by hand as well, so we've supplied you
9777 with a mode for that.
9779 It's simply a slightly customized @code{emacs-lisp} mode, with these
9780 additional commands:
9785 @kindex C-c C-c (Score)
9786 @findex gnus-score-edit-done
9787 Save the changes you have made and return to the summary buffer
9788 (@code{gnus-score-edit-done}).
9791 @kindex C-c C-d (Score)
9792 @findex gnus-score-edit-insert-date
9793 Insert the current date in numerical format
9794 (@code{gnus-score-edit-insert-date}). This is really the day number, if
9798 @kindex C-c C-p (Score)
9799 @findex gnus-score-pretty-print
9800 The adaptive score files are saved in an unformatted fashion. If you
9801 intend to read one of these files, you want to @dfn{pretty print} it
9802 first. This command (@code{gnus-score-pretty-print}) does that for
9807 @node Adaptive Scoring
9808 @section Adaptive Scoring
9809 @cindex adaptive scoring
9811 If all this scoring is getting you down, Gnus has a way of making it all
9812 happen automatically---as if by magic. Or rather, as if by artificial
9813 stupidity, to be precise.
9815 @vindex gnus-use-adaptive-scoring
9816 When you read an article, or mark an article as read, or kill an
9817 article, you leave marks behind. On exit from the group, Gnus can sniff
9818 these marks and add score elements depending on what marks it finds.
9819 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
9822 @vindex gnus-default-adaptive-score-alist
9823 To give you complete control over the scoring process, you can customize
9824 the @code{gnus-default-adaptive-score-alist} variable. By default, it
9825 looks something like this:
9828 (defvar gnus-default-adaptive-score-alist
9829 '((gnus-unread-mark)
9830 (gnus-ticked-mark (from 4))
9831 (gnus-dormant-mark (from 5))
9832 (gnus-del-mark (from -4) (subject -1))
9833 (gnus-read-mark (from 4) (subject 2))
9834 (gnus-expirable-mark (from -1) (subject -1))
9835 (gnus-killed-mark (from -1) (subject -3))
9836 (gnus-kill-file-mark)
9837 (gnus-catchup-mark (from -1) (subject -1))))
9840 As you see, each element in this alist has a mark as a key (either a
9841 variable name or a ``real'' mark---a character). Following this key is a
9842 random number of header/score pairs.
9844 To take @code{gnus-del-mark} as an example---this alist says that all
9845 articles that have that mark (i.e., are marked with @samp{D}) will have a
9846 score entry added to lower based on the @code{From} header by -4, and
9847 lowered by @code{Subject} by -1. Change this to fit your prejudices.
9849 The headers you can score on are @code{from}, @code{subject},
9850 @code{message-id}, @code{references}, @code{xref}, @code{lines},
9851 @code{chars} and @code{date}. In addition, you can score on
9852 @code{followup}, which will create an adaptive score entry that matches
9853 on the @code{References} header using the @code{Message-ID} of the
9854 current article, thereby matching the following thread.
9856 You can also score on @code{thread}, which will try to score all
9857 articles that appear in a thread. @code{thread} matches uses a
9858 @code{Message-ID} to match on the @code{References} header of the
9859 article. If the match is made, the @code{Message-ID} of the article is
9860 added to the @code{thread} rule. (Think about it. I'd recommend two
9861 aspirins afterwards.)
9863 If you use this scheme, you should set @code{mark-below} to something
9864 small---like -300, perhaps, to avoid having small random changes result
9865 in articles getting marked as read.
9867 After using adaptive scoring for a week or so, Gnus should start to
9868 become properly trained and enhance the authors you like best, and kill
9869 the authors you like least, without you having to say so explicitly.
9871 You can control what groups the adaptive scoring is to be performed on
9872 by using the score files (@pxref{Score File Format}). This will also
9873 let you use different rules in different groups.
9875 @vindex gnus-adaptive-file-suffix
9876 The adaptive score entries will be put into a file where the name is the
9877 group name with @code{gnus-adaptive-file-suffix} appended. The default
9880 @vindex gnus-score-exact-adapt-limit
9881 When doing adaptive scoring, substring or fuzzy matching would probably
9882 give you the best results in most cases. However, if the header one
9883 matches is short, the possibility for false positives is great, so if
9884 the length of the match is less than
9885 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
9886 this variable is @code{nil}, exact matching will always be used to avoid
9890 @node Followups To Yourself
9891 @section Followups To Yourself
9893 Gnus offers two commands for picking out the @code{Message-ID} header in
9894 the current buffer. Gnus will then add a score rule that scores using
9895 this @code{Message-ID} on the @code{References} header of other
9896 articles. This will, in effect, increase the score of all articles that
9897 respond to the article in the current buffer. Quite useful if you want
9898 to easily note when people answer what you've said.
9902 @item gnus-score-followup-article
9903 @findex gnus-score-followup-article
9904 This will add a score to articles that directly follow up your own
9907 @item gnus-score-followup-thread
9908 @findex gnus-score-followup-thread
9909 This will add a score to all articles that appear in a thread ``below''
9913 @vindex gnus-inews-article-hook
9914 These two functions are both primarily meant to be used in hooks like
9915 @code{gnus-inews-article-hook}.
9919 @section Scoring Tips
9920 @cindex scoring tips
9925 If you want to lower the score of crossposts, the line to match on is
9926 the @code{Xref} header.
9928 ("xref" (" talk.politics.misc:" -1000))
9931 @item Multiple crossposts
9932 If you want to lower the score of articles that have been crossposted to
9933 more than, say, 3 groups:
9935 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
9938 @item Matching on the body
9939 This is generally not a very good idea---it takes a very long time.
9940 Gnus actually has to fetch each individual article from the server. But
9941 you might want to anyway, I guess. Even though there are three match
9942 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
9943 and stick with it in each score file. If you use any two, each article
9944 will be fetched @emph{twice}. If you want to match a bit on the
9945 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
9948 @item Marking as read
9949 You will probably want to mark articles that has a score below a certain
9950 number as read. This is most easily achieved by putting the following
9951 in your @file{all.SCORE} file:
9955 You may also consider doing something similar with @code{expunge}.
9957 @item Negated character classes
9958 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
9959 That will match newlines, which might lead to, well, The Unknown. Say
9960 @code{[^abcd\n]*} instead.
9963 @node Reverse Scoring
9964 @section Reverse Scoring
9965 @cindex reverse scoring
9967 If you want to keep just articles that have @samp{Sex with Emacs} in the
9968 subject header, and expunge all other articles, you could put something
9969 like this in your score file:
9973 ("Sex with Emacs" 2))
9978 So, you raise all articles that match @samp{Sex with Emacs} and mark the
9979 rest as read, and expunge them to boot.
9981 @node Global Score Files
9982 @section Global Score Files
9983 @cindex global score files
9985 Sure, other newsreaders have ``global kill files''. These are usually
9986 nothing more than a single kill file that applies to all groups, stored
9987 in the user's home directory. Bah! Puny, weak newsreaders!
9989 What I'm talking about here are Global Score Files. Score files from
9990 all over the world, from users everywhere, uniting all nations in one
9991 big, happy score file union! Ange-score! New and untested!
9993 @vindex gnus-global-score-files
9994 All you have to do to use other people's score files is to set the
9995 @code{gnus-global-score-files} variable. One entry for each score file,
9996 or each score file directory. Gnus will decide by itself what score
9997 files are applicable to which group.
9999 Say you want to use all score files in the
10000 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
10001 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
10004 (setq gnus-global-score-files
10005 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
10006 "/ftp@@ftp.some-where:/pub/score/"))
10009 @findex gnus-score-search-global-directories
10010 Simple, eh? Directory names must end with a @samp{/}. These
10011 directories are typically scanned only once during each Gnus session.
10012 If you feel the need to manually re-scan the remote directories, you can
10013 use the @code{gnus-score-search-global-directories} command.
10015 Note that, at present, using this option will slow down group entry
10016 somewhat. (That is---a lot.)
10018 If you want to start maintaining score files for other people to use,
10019 just put your score file up for anonymous ftp and announce it to the
10020 world. Become a retro-moderator! Participate in the retro-moderator
10021 wars sure to ensue, where retro-moderators battle it out for the
10022 sympathy of the people, luring them to use their score files on false
10023 premises! Yay! The net is saved!
10025 Here are some tips for the would-be retro-moderator, off the top of my
10031 Articles that are heavily crossposted are probably junk.
10033 To lower a single inappropriate article, lower by @code{Message-ID}.
10035 Particularly brilliant authors can be raised on a permanent basis.
10037 Authors that repeatedly post off-charter for the group can safely be
10038 lowered out of existence.
10040 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
10041 articles completely.
10044 Use expiring score entries to keep the size of the file down. You
10045 should probably have a long expiry period, though, as some sites keep
10046 old articles for a long time.
10049 ... I wonder whether other newsreaders will support global score files
10050 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
10051 Wave, xrn and 1stReader are bound to implement scoring. Should we start
10052 holding our breath yet?
10056 @section Kill Files
10059 Gnus still supports those pesky old kill files. In fact, the kill file
10060 entries can now be expiring, which is something I wrote before Daniel
10061 Quinlan thought of doing score files, so I've left the code in there.
10063 In short, kill processing is a lot slower (and I do mean @emph{a lot})
10064 than score processing, so it might be a good idea to rewrite your kill
10065 files into score files.
10067 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
10068 forms into this file, which means that you can use kill files as some
10069 sort of primitive hook function to be run on group entry, even though
10070 that isn't a very good idea.
10072 XCNormal kill files look like this:
10075 (gnus-kill "From" "Lars Ingebrigtsen")
10076 (gnus-kill "Subject" "ding")
10080 This will mark every article written by me as read, and remove them from
10081 the summary buffer. Very useful, you'll agree.
10083 Other programs use a totally different kill file syntax. If Gnus
10084 encounters what looks like a @code{rn} kill file, it will take a stab at
10087 Two functions for editing a GNUS kill file:
10092 @kindex M-k (Summary)
10093 @findex gnus-summary-edit-local-kill
10094 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
10097 @kindex M-K (Summary)
10098 @findex gnus-summary-edit-global-kill
10099 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
10102 @vindex gnus-kill-file-name
10103 A kill file for the group @samp{soc.motss} is normally called
10104 @file{soc.motss.KILL}. The suffix appended to the group name to get
10105 this file name is detailed by the @code{gnus-kill-file-name} variable.
10106 The ``global'' kill file (not in the score file sense of ``global'', of
10107 course) is called just @file{KILL}.
10109 @vindex gnus-kill-save-kill-file
10110 If @code{gnus-kill-save-kill-file} is non-@code{nil}, Gnus will save the
10111 kill file after processing, which is necessary if you use expiring
10121 * Interactive:: Making Gnus ask you many questions.
10122 * Formatting Variables:: How to control the look of the buffers.
10123 * Windows Configuration:: Configuring the Gnus buffer windows.
10124 * Buttons:: Get tendonitis in ten easy steps!
10125 * Compilation and Init File:: How to speed Gnus up.
10126 * Daemons:: Gnus can do things behind your back.
10127 * NoCeM:: How to avoid spam and other fatty foods.
10128 * Various Various:: Things that are really various.
10132 @section Interactive
10133 @cindex interaction
10137 @item gnus-novice-user
10138 @vindex gnus-novice-user
10139 If this variable is non-@code{nil}, you are either a newcomer to the
10140 World of Usenet, or you are very cautious, which is a nice thing to be,
10141 really. You will be given questions of the type ``Are you sure you want
10142 to do this?'' before doing anything dangerous. This is @code{t} by
10145 @item gnus-expert-user
10146 @vindex gnus-expert-user
10147 If this variable is non-@code{nil}, you will never ever be asked any
10148 questions by Gnus. It will simply assume you know what you're doing, no
10149 matter how strange.
10151 @item gnus-interactive-catchup
10152 @vindex gnus-interactive-catchup
10153 Require confirmation before catching up a group if non-@code{nil}. It
10154 is @code{t} by default.
10156 @item gnus-interactive-post
10157 @vindex gnus-interactive-post
10158 If non-@code{nil}, the user will be prompted for a group name when
10159 posting an article. It is @code{t} by default.
10161 @item gnus-interactive-exit
10162 @vindex gnus-interactive-exit
10163 Require confirmation before exiting Gnus. This variable is @code{t} by
10168 @node Formatting Variables
10169 @section Formatting Variables
10170 @cindex formatting variables
10172 Throughout this manual you've probably noticed lots of variables that
10173 are called things like @code{gnus-group-line-format} and
10174 @code{gnus-summary-mode-line-format}. These control how Gnus is to
10175 output lines in the various buffers. There's quite a lot of them.
10176 Fortunately, they all use the same syntax, so there's not that much to
10179 Here's an example format spec (from the group buffer): @samp{"%M%S%5y:
10180 %(%g%)\n"}. We see that it is indeed extremely ugly, and that there are
10181 lots of percentages everywhere.
10183 Each @samp{%} element will be replaced by some string or other when the
10184 buffer in question is generated. @samp{%5y} means ``insert the @samp{y}
10185 spec, and pad with spaces to get a 5-character field''. Just like a
10186 normal format spec, almost.
10188 You can also say @samp{%6,4y}, which means that the field will never be
10189 more than 6 characters wide and never less than 4 characters wide.
10191 There are also specs for highlighting, and these are shared by all the
10192 format variables. Text inside the @samp{%(} and @samp{%)} specifiers
10193 will get the special @code{mouse-face} property set, which means that it
10194 will be highlighted (with @code{gnus-mouse-face}) when you put the mouse
10197 Text inside the @samp{%[} and @samp{%]} specifiers will have their
10198 normal faces set using @code{gnus-face-0}, which is @code{bold} by
10199 default. If you say @samp{%1[} instead, you'll get @code{gnus-face-1}
10200 instead, and so on. Create as many faces as you wish. The same goes
10201 for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
10202 @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
10204 Here's an alternative recipe for the group buffer:
10207 ;; Create three face types.
10208 (setq gnus-face-1 'bold)
10209 (setq gnus-face-3 'italic)
10211 ;; We want the article count to be in
10212 ;; a bold and green face. So we create
10213 ;; a new face called `my-green-bold'.
10214 (copy-face 'bold 'my-green-bold)
10216 (set-face-foreground 'my-green-bold "ForestGreen")
10217 (setq gnus-face-2 'my-green-bold)
10219 ;; Set the new & fancy format.
10220 (setq gnus-group-line-format
10221 "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
10224 I'm sure you'll be able to use this scheme to create totally unreadable
10225 and extremely vulgar displays. Have fun!
10227 Currently Gnus uses the following formatting variables:
10228 @code{gnus-group-line-format}, @code{gnus-summary-line-format},
10229 @code{gnus-server-line-format}, @code{gnus-topic-line-format},
10230 @code{gnus-group-mode-line-format},
10231 @code{gnus-summary-mode-line-format},
10232 @code{gnus-article-mode-line-format},
10233 @code{gnus-server-mode-line-format}.
10235 Note that the @samp{%(} specs (and friends) do not make any sense on the
10236 mode-line variables.
10238 All these format variables can also be random elisp forms. In that
10239 case, they will be @code{eval}ed to insert the required lines.
10241 @kindex M-x gnus-update-format
10242 @findex gnus-update-format
10243 Gnus includes a command to help you while creating your own format
10244 specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
10245 update the spec in question and pop you to a buffer where you can
10246 examine the resulting lisp code to be run to generate the line.
10249 @node Windows Configuration
10250 @section Windows Configuration
10251 @cindex windows configuration
10253 No, there's nothing here about X, so be quiet.
10255 @vindex gnus-use-full-window
10256 If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
10257 other windows and occupy the entire Emacs screen by itself. It is
10258 @code{t} by default.
10260 @code{gnus-buffer-configuration} describes how much space each Gnus
10261 buffer should be given. Here's an excerpt of this variable:
10264 ((group (vertical 1.0 (group 1.0 point)
10265 (if gnus-carpal (group-carpal 4))))
10266 (article (vertical 1.0 (summary 0.25 point)
10270 This is an alist. The @dfn{key} is a symbol that names some action or
10271 other. For instance, when displaying the group buffer, the window
10272 configuration function will use @code{group} as the key. A full list of
10273 possible names is listed below.
10275 The @dfn{value} (i. e., the @dfn{split}) says how much space each buffer
10276 should occupy. To take the @code{article} split as an example -
10279 (article (vertical 1.0 (summary 0.25 point)
10283 This @dfn{split} says that the summary buffer should occupy 25% of upper
10284 half of the screen, and that it is placed over the article buffer. As
10285 you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
10286 reaching for that calculator there). However, the special number
10287 @code{1.0} is used to signal that this buffer should soak up all the
10288 rest of the space available after the rest of the buffers have taken
10289 whatever they need. There should be only one buffer with the @code{1.0}
10290 size spec per split.
10292 Point will be put in the buffer that has the optional third element
10295 Here's a more complicated example:
10298 (article (vertical 1.0 (group 4)
10299 (summary 0.25 point)
10300 (if gnus-carpal (summary-carpal 4))
10304 If the size spec is an integer instead of a floating point number,
10305 then that number will be used to say how many lines a buffer should
10306 occupy, not a percentage.
10308 If the @dfn{split} looks like something that can be @code{eval}ed (to be
10309 precise---if the @code{car} of the split is a function or a subr), this
10310 split will be @code{eval}ed. If the result is non-@code{nil}, it will
10311 be used as a split. This means that there will be three buffers if
10312 @code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
10315 Not complicated enough for you? Well, try this on for size:
10318 (article (horizontal 1.0
10323 (summary 0.25 point)
10328 Whoops. Two buffers with the mystery 100% tag. And what's that
10329 @code{horizontal} thingie?
10331 If the first element in one of the split is @code{horizontal}, Gnus will
10332 split the window horizontally, giving you two windows side-by-side.
10333 Inside each of these strips you may carry on all you like in the normal
10334 fashion. The number following @code{horizontal} says what percentage of
10335 the screen is to be given to this strip.
10337 For each split, there @emph{must} be one element that has the 100% tag.
10338 The splitting is never accurate, and this buffer will eat any leftover
10339 lines from the splits.
10341 To be slightly more formal, here's a definition of what a legal split
10345 split = frame | horizontal | vertical | buffer | form
10346 frame = "(frame " size *split ")"
10347 horizontal = "(horizontal " size *split ")"
10348 vertical = "(vertical " size *split ")"
10349 buffer = "(" buffer-name " " size *[ "point" ] ")"
10350 size = number | frame-params
10351 buffer-name = group | article | summary ...
10354 The limitations are that the @samp{frame} split can only appear as the
10355 top-level split. @samp{form} should be an Emacs Lisp form that should
10356 return a valid split. We see that each split is fully recursive, and
10357 may contain any number of @samp{vertical} and @samp{horizontal} splits.
10359 @vindex gnus-window-min-width
10360 @vindex gnus-window-min-height
10361 @cindex window height
10362 @cindex window width
10363 Finding the right sizes can be a bit complicated. No window may be less
10364 than @code{gnus-window-min-height} (default 2) characters high, and all
10365 windows must be at least @code{gnus-window-min-wide} (default 1)
10366 characters wide. Gnus will try to enforce this before applying the
10367 splits. If you want to use the normal Emacs window width/height limit,
10368 you can just set these two variables to @code{nil}.
10370 If you're not familiar with Emacs terminology, @samp{horizontal} and
10371 @samp{vertical} splits may work the opposite way of what you'd expect.
10372 Windows inside a @samp{horizontal} split are shown side-by-side, and
10373 windows within a @samp{vertical} split are shown above each other.
10375 @findex gnus-configure-frame
10376 If you want to experiment with window placement, a good tip is to call
10377 @code{gnus-configure-frame} directly with a split. This is the function
10378 that does all the real work when splitting buffers. Below is a pretty
10379 nonsensical configuration with 5 windows; two for the group buffer and
10380 three for the article buffer. (I said it was nonsensical.) If you
10381 @code{eval} the statement below, you can get an idea of how that would
10382 look straight away, without going through the normal Gnus channels.
10383 Play with it until you're satisfied, and then use
10384 @code{gnus-add-configuration} to add your new creation to the buffer
10385 configuration list.
10388 (gnus-configure-frame
10392 (article 0.3 point))
10400 You might want to have several frames as well. No prob---just use the
10401 @code{frame} split:
10404 (gnus-configure-frame
10407 (summary 0.25 point)
10409 (vertical ((height . 5) (width . 15)
10410 (user-position . t)
10411 (left . -1) (top . 1))
10416 This split will result in the familiar summary/article window
10417 configuration in the first (or ``main'') frame, while a small additional
10418 frame will be created where picons will be shown. As you can see,
10419 instead of the normal @samp{1.0} top-level spec, each additional split
10420 should have a frame parameter alist as the size spec.
10421 @xref{(elisp)Frame Parameters}.
10423 Here's a list of all possible keys for
10424 @code{gnus-buffer-configuration}:
10426 @code{group}, @code{summary}, @code{article}, @code{server},
10427 @code{browse}, @code{group-mail}, @code{summary-mail},
10428 @code{summary-reply}, @code{info}, @code{summary-faq},
10429 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
10430 @code{followup}, @code{followup-yank}, @code{edit-score}.
10432 @findex gnus-add-configuration
10433 Since the @code{gnus-buffer-configuration} variable is so long and
10434 complicated, there's a function you can use to ease changing the config
10435 of a single setting: @code{gnus-add-configuration}. If, for instance,
10436 you want to change the @code{article} setting, you could say:
10439 (gnus-add-configuration
10440 '(article (vertical 1.0
10442 (summary .25 point)
10446 You'd typically stick these @code{gnus-add-configuration} calls in your
10447 @file{.gnus} file or in some startup hook -- they should be run after
10448 Gnus has been loaded.
10457 Those new-fangled @dfn{mouse} contraptions is very popular with the
10458 young, hep kids who don't want to learn the proper way to do things
10459 these days. Why, I remember way back in the summer of '89, when I was
10460 using Emacs on a Tops 20 system. Three hundred users on one single
10461 machine, and every user was running Simula compilers. Bah!
10465 @vindex gnus-carpal
10466 Well, you can make Gnus display bufferfuls of buttons you can click to
10467 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
10468 really. Tell the chiropractor I sent you.
10473 @item gnus-carpal-mode-hook
10474 @vindex gnus-carpal-mode-hook
10475 Hook run in all carpal mode buffers.
10477 @item gnus-carpal-button-face
10478 @vindex gnus-carpal-button-face
10479 Face used on buttons.
10481 @item gnus-carpal-group-buffer-buttons
10482 @vindex gnus-carpal-group-buffer-buttons
10483 Buttons in the group buffer.
10485 @item gnus-carpal-summary-buffer-buttons
10486 @vindex gnus-carpal-summary-buffer-buttons
10487 Buttons in the summary buffer.
10489 @item gnus-carpal-server-buffer-buttons
10490 @vindex gnus-carpal-server-buffer-buttons
10491 Buttons in the server buffer.
10493 @item gnus-carpal-browse-buffer-buttons
10494 @vindex gnus-carpal-browse-buffer-buttons
10495 Buttons in the browse buffer.
10498 All the @code{buttons} variables are lists. The elements in these list
10499 is either a cons cell where the car contains a text to be displayed and
10500 the cdr contains a function symbol, or a simple string.
10503 @node Compilation and Init File
10504 @section Compilation and Init File
10505 @cindex compilation
10507 @cindex byte-compilation
10509 @vindex gnus-init-file
10510 @findex gnus-compile
10511 When Gnus starts up, it will read the Gnus init file
10512 @code{gnus-init-file}, which is @file{.gnus} by default. It is
10513 recommended that you keep any Gnus-related functions that you have
10514 written in that file. If you want to byte-compile the file, Gnus offers
10515 the handy @kbd{M-x gnus-compile} function that will do that for you.
10517 That's not really why that function was written, though.
10519 Remember all those line format specification variables?
10520 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
10521 on. Now, Gnus will of course heed whatever these variables are, but,
10522 unfortunately, changing them will mean a quite significant slow-down.
10523 (The default values of these variables have byte-compiled functions
10524 associated with them, while the user-generated versions do not, of
10527 To help with this, you can run @code{gnus-compile} after you've fiddled
10528 around with the variables and feel that you're (kind of) satisfied.
10529 This will result in the new specs being byte-compiled, and you'll get
10532 The result of these byte-compilations will be written to
10533 @file{.gnus.elc} by default.
10535 Note that Gnus will read @file{.gnus.elc} instead of @file{.gnus} if
10536 @file{.gnus.elc} exists, so if you change @file{.gnus}, you should
10537 remove @file{.gnus.elc}.
10545 Gnus, being larger than any program ever written (allegedly), does lots
10546 of strange stuff that you may wish to have done while you're not
10547 present. For instance, you may want it to check for new mail once in a
10548 while. Or you may want it to close down all connections to all servers
10549 when you leave Emacs idle. And stuff like that.
10551 Gnus will let you do stuff like that by defining various
10552 @dfn{handlers}. Each handler consists of three elements: A
10553 @var{function}, a @var{time}, and an @var{idle} parameter.
10555 Here's an example of a handler that closes connections when Emacs has
10556 been idle for thirty minutes:
10559 (gnus-demon-close-connections nil 30)
10562 Here's a handler that scans for PGP headers every hour when Emacs is
10566 (gnus-demon-scan-pgp 60 t)
10569 This @var{time} parameter and than @var{idle} parameter works together
10570 in a strange, but wonderful fashion. Basically, if @var{idle} is
10571 @code{nil}, then the function will be called every @var{time} minutes.
10573 If @var{idle} is @code{t}, then the function will be called after
10574 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
10575 the function will never be called. But once Emacs goes idle, the
10576 function will be called every @var{time} minutes.
10578 If @var{idle} is a number and @var{time} is a number, the function will
10579 be called every @var{time} minutes only when Emacs has been idle for
10580 @var{idle} minutes.
10582 If @var{idle} is a number and @var{time} is @code{nil}, the function
10583 will be called once every time Emacs has been idle for @var{idle}
10586 And if @var{time} is a string, it should look like @samp{"07:31"}, and
10587 the function will then be called once every day somewhere near that
10588 time. Modified by the @var{idle} parameter, of course.
10590 @vindex gnus-demon-timestep
10591 (When I say ``minute'' here, I really mean @code{gnus-demon-timestep}
10592 seconds. This is @samp{60} by default. If you change that variable,
10593 all the timings in the handlers will be affected.)
10595 @vindex gnus-use-demon
10596 To set the whole thing in motion, though, you have to set
10597 @code{gnus-use-demon} to @code{t}.
10599 So, if you want to add a handler, you could put something like this in
10600 your @file{.gnus} file:
10602 @findex gnus-demon-add-handler
10604 (gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
10607 @findex gnus-demon-add-nocem
10608 @findex gnus-demon-add-scanmail
10609 @findex gnus-demon-add-disconnection
10610 Some ready-made functions to do this has been created:
10611 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
10612 @code{gnus-demon-add-scanmail}. Just put those functions in your
10613 @file{.gnus} if you want those abilities.
10615 @findex gnus-demon-init
10616 @findex gnus-demon-cancel
10617 @vindex gnus-demon-handlers
10618 If you add handlers to @code{gnus-demon-handlers} directly, you should
10619 run @code{gnus-demon-init} to make the changes take hold. To cancel all
10620 daemons, you can use the @code{gnus-demon-cancel} function.
10622 Note that adding daemons can be pretty naughty if you overdo it. Adding
10623 functions that scan all news and mail from all servers every two seconds
10624 is a sure-fire way of getting booted off any respectable system. So
10635 @node Various Various
10636 @section Various Various
10643 @vindex gnus-verbose
10644 This variable is an integer between zero and ten. The higher the value,
10645 the more messages will be displayed. If this variable is zero, Gnus
10646 will never flash any messages, if it is seven (which is the default),
10647 most important messages will be shown, and if it is ten, Gnus won't ever
10648 shut up, but will flash so many messages it will make your head swim.
10650 @item gnus-verbose-backends
10651 @vindex gnus-verbose-backends
10652 This variable works the same way as @code{gnus-verbose}, but it applies
10653 to the Gnus backends instead of Gnus proper.
10655 @item gnus-updated-mode-lines
10656 @vindex gnus-updated-mode-lines
10657 This is a list of buffers that should keep their mode lines updated.
10658 The list may contain the symbols @code{group}, @code{article} and
10659 @code{summary}. If the corresponding symbol is present, Gnus will keep
10660 that mode line updated with information that may be pertinent. If this
10661 variable is @code{nil}, screen refresh may be quicker.
10663 @cindex display-time
10665 @item gnus-mode-non-string-length
10666 @vindex gnus-mode-non-string-length
10667 By default, Gnus displays information on the current article in the mode
10668 lines of the summary and article buffers. The information Gnus wishes
10669 to display (eg. the subject of the article) is often longer than the
10670 mode lines, and therefore have to be cut off at some point. This
10671 variable says how long the other elements on the line is (i.e., the
10672 non-info part). If you put additional elements on the mode line (eg. a
10673 clock), you should modify this variable:
10675 @c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
10677 (add-hook 'display-time-hook
10678 (lambda () (setq gnus-mode-non-string-length
10680 (if line-number-mode 5 0)
10681 (if column-number-mode 4 0)
10682 (length display-time-string)))))
10685 If this variable is @code{nil} (which is the default), the mode line
10686 strings won't be chopped off, and they won't be padded either.
10689 @vindex gnus-visual
10691 @cindex highlighting
10694 If @code{nil}, Gnus won't attempt to create menus or use fancy colors
10695 or fonts. This will also inhibit loading the @file{gnus-visual.el}
10698 This variable can also be a list of visual properties that are enabled.
10699 The following elements are legal, and are all set by default:
10703 @item summary-highlight
10704 Perform various highlighting in the summary buffer.
10706 @item article-highlight
10707 Perform various highlighting in the article buffer.
10710 Turn on highlighting in all buffers.
10713 Create menus in the group buffer.
10716 Create menus in the summary buffer.
10719 Create menus in the article buffer.
10722 Create menus in the browse buffer.
10725 Create menus in the server buffer.
10728 Create menus in all buffers.
10732 So if you only want highlighting in the article buffer and menus in all
10733 buffers, you could say something like:
10736 (setq gnus-visual '(article-highlight menu))
10739 If you want only highlighting and no menus whatsoever, you'd say:
10742 (setq gnus-visual '(highlight))
10745 @item gnus-mouse-face
10746 @vindex gnus-mouse-face
10747 This is the face (i.e., font) used for mouse highlighting in Gnus. No
10748 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
10750 @item gnus-display-type
10751 @vindex gnus-display-type
10752 This variable is symbol indicating the display Emacs is running under.
10753 The symbol should be one of @code{color}, @code{grayscale} or
10754 @code{mono}. If Gnus guesses this display attribute wrongly, either set
10755 this variable in your @file{~/.emacs} or set the resource
10756 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
10758 @item gnus-background-mode
10759 @vindex gnus-background-mode
10760 This is a symbol indicating the Emacs background brightness. The symbol
10761 should be one of @code{light} or @code{dark}. If Gnus guesses this
10762 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
10763 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
10764 `gnus-display-type'.
10766 @item nnheader-max-head-length
10767 @vindex nnheader-max-head-length
10768 When the backends read straight heads of articles, they all try to read
10769 as little as possible. This variable (default @code{4096}) specifies
10770 the absolute max length the backends will try to read before giving up
10771 on finding a separator line between the head and the body. If this
10772 variable is @code{nil}, there is no upper read bound. If it is
10773 @code{t}, the backends won't try to read the articles piece by piece,
10774 but read the entire articles. This makes sense with some versions of
10777 @item nnheader-file-name-translation-alist
10778 @vindex nnheader-file-name-translation-alist
10780 @cindex illegal characters in file names
10781 @cindex characters in file names
10782 This is an alist that says how to translate characters in file names.
10783 For instance, if @samp{:} is illegal as a file character in file names
10784 on your system (you OS/2 user you), you could say something like:
10787 (setq nnheader-file-name-translation-alist
10791 In fact, this is the default value for this variable on OS/2 and MS
10792 Windows (phooey) systems.
10796 @node Customization
10797 @chapter Customization
10798 @cindex general customization
10800 All variables are properly documented elsewhere in this manual. This
10801 section is designed to give general pointers on how to customize Gnus
10802 for some quite common situations.
10805 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
10806 * Slow Terminal Connection:: You run a remote Emacs.
10807 * Little Disk Space:: You feel that having large setup files is icky.
10808 * Slow Machine:: You feel like buying a faster machine.
10811 @node Slow/Expensive Connection
10812 @section Slow/Expensive @sc{nntp} Connection
10814 If you run Emacs on a machine locally, and get your news from a machine
10815 over some very thin strings, you want to cut down on the amount of data
10816 Gnus has to get from the @sc{nntp} server.
10820 @item gnus-read-active-file
10821 Set this to @code{nil}, which will inhibit Gnus from requesting the
10822 entire active file from the server. This file is often v. large. You
10823 also have to set @code{gnus-check-new-news} and
10824 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
10825 doesn't suddenly decide to fetch the active file anyway.
10827 @item gnus-nov-is-evil
10828 This one has to be @code{nil}. If not, grabbing article headers from
10829 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
10830 support @sc{xover}; Gnus will detect this by itself.
10833 @node Slow Terminal Connection
10834 @section Slow Terminal Connection
10836 Let's say you use your home computer for dialing up the system that
10837 runs Emacs and Gnus. If your modem is slow, you want to reduce the
10838 amount of data that is sent over the wires as much as possible.
10842 @item gnus-auto-center-summary
10843 Set this to @code{nil} to inhibit Gnus from re-centering the summary
10844 buffer all the time.
10846 @item gnus-visible-headers
10847 Cut down on the headers that are included in the articles to the
10848 minimum. You can, in fact, make do without them altogether---most of the
10849 useful data is in the summary buffer, anyway. Set this variable to
10850 @samp{"^NEVVVVER"} or @samp{"From:"}, or whatever you feel you need.
10852 @item gnus-article-display-hook
10853 Set this hook to all the available hiding commands:
10855 (setq gnus-article-display-hook
10856 '(gnus-article-hide-headers gnus-article-hide-signature
10857 gnus-article-hide-citation))
10860 @item gnus-use-full-window
10861 By setting this to @code{nil}, you can make all the windows smaller.
10862 While this doesn't really cut down much generally, it means that you
10863 have to see smaller portions of articles before deciding that you didn't
10864 want to read them anyway.
10866 @item gnus-thread-hide-subtree
10867 If this is non-@code{nil}, all threads in the summary buffer will be
10870 @item gnus-updated-mode-lines
10871 If this is @code{nil}, Gnus will not put information in the buffer mode
10872 lines, which might save some time.
10875 @node Little Disk Space
10876 @section Little Disk Space
10878 The startup files can get rather large, so you may want to cut their
10879 sizes a bit if you are running out of space.
10883 @item gnus-save-newsrc-file
10884 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
10885 only save @file{.newsrc.eld}. This means that you will not be able to
10886 use any other newsreaders than Gnus. This variable is @code{t} by
10889 @item gnus-save-killed-list
10890 If this is @code{nil}, Gnus will not save the list of dead groups. You
10891 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
10892 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
10893 variable to @code{nil}. This variable is @code{t} by default.
10899 @section Slow Machine
10901 If you have a slow machine, or are just really impatient, there are a
10902 few things you can do to make Gnus run faster.
10904 Set@code{gnus-check-new-newsgroups} and
10905 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
10907 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
10908 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
10909 summary buffer faster.
10911 Set @code{gnus-article-display-hook} to @code{nil} to make article
10912 processing a bit faster.
10915 @node Troubleshooting
10916 @chapter Troubleshooting
10917 @cindex troubleshooting
10919 Gnus works @emph{so} well straight out of the box---I can't imagine any
10927 Make sure your computer is switched on.
10930 Make sure that you really load the current Gnus version. If you have
10931 been running @sc{gnus}, you need to exit Emacs and start it up again before
10935 Try doing an @kbd{M-x gnus-version}. If you get something that looks
10936 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
10937 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
10938 flee}, you have some old @file{.el} files lying around. Delete these.
10941 Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
10945 If all else fails, report the problem as a bug.
10948 @cindex reporting bugs
10950 @kindex M-x gnus-bug
10952 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
10953 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
10954 me the backtrace. I will fix bugs, but I can only fix them if you send
10955 me a precise description as to how to reproduce the bug.
10957 You really can never be too detailed in a bug report. Always use the
10958 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
10959 a 10Kb mail each time you use it, and even if you have sent me your
10960 environment 500 times before. I don't care. I want the full info each
10963 It is also important to remember that I have no memory whatsoever. If
10964 you send a bug report, and I send you a reply, and then you send back
10965 just ``No, it's not! Moron!'', I will have no idea what you are insulting
10966 me about. Always over-explain everything. It's much easier for all of
10967 us---if I don't have all the information I need, I will just mail you
10968 and ask for more info, and everything takes more time.
10970 If you just need help, you are better off asking on
10971 @samp{gnu.emacs.gnus}. I'm not very helpful.
10973 @cindex gnu.emacs.gnus
10974 @cindex ding mailing list
10975 You can also ask on the ding mailing list---@samp{ding@@ifi.uio.no}.
10976 Write to @samp{ding-request@@ifi.uio.no} to subscribe.
10982 Well, that's the manual---you can get on with your life now. Keep in
10983 touch. Say hello to your cats from me.
10985 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
10987 Ol' Charles Reznikoff said it pretty well, so I leave the floor to him:
10992 Not because of victories @*
10995 but for the common sunshine,@*
10997 the largess of the spring.
11000 but for the day's work done@*
11001 as well as I was able;@*
11002 not for a seat upon the dais@*
11003 but at the common table.@*
11007 @chapter Appendices
11010 * A Programmer@'s Guide to Gnus:: Rilly, rilly technical stuff.
11011 * Emacs for Heathens:: A short introduction to Emacsian terms.
11012 * Frequently Asked Questions:: A question-and-answer session.
11016 @node A Programmer@'s Guide to Gnus
11017 @section A Programmer's Guide to Gnus
11019 It is my hope that other people will figure out smart stuff that Gnus
11020 can do, and that other people will write those smart things as well. To
11021 facilitate that I thought it would be a good idea to describe the inner
11022 workings of Gnus. And some of the not-so-inner workings, while I'm at
11025 You can never expect the internals of a program not to change, but I
11026 will be defining (in some details) the interface between Gnus and its
11027 backends (this is written in stone), the format of the score files
11028 (ditto), data structures (some are less likely to change than others)
11029 and general method of operations.
11032 * Backend Interface:: How Gnus communicates with the servers.
11033 * Score File Syntax:: A BNF definition of the score file standard.
11034 * Headers:: How Gnus stores headers internally.
11035 * Ranges:: A handy format for storing mucho numbers.
11036 * Group Info:: The group info format.
11037 * Various File Formats:: Formats of files that Gnus use.
11041 @node Backend Interface
11042 @subsection Backend Interface
11044 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
11045 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
11046 server is a @dfn{backend} and some @dfn{backend variables}. As examples
11047 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
11048 examples of the latter we have @code{nntp-port-number} and
11049 @code{nnmbox-directory}.
11051 When Gnus asks for information from a backend---say @code{nntp}---on
11052 something, it will normally include a virtual server name in the
11053 function parameters. (If not, the backend should use the ``current''
11054 virtual server.) For instance, @code{nntp-request-list} takes a virtual
11055 server as its only (optional) parameter. If this virtual server hasn't
11056 been opened, the function should fail.
11058 Note that a virtual server name has no relation to some physical server
11059 name. Take this example:
11063 (nntp-address "ifi.uio.no")
11064 (nntp-port-number 4324))
11067 Here the virtual server name is @samp{"odd-one"} while the name of
11068 the physical server is @samp{"ifi.uio.no"}.
11070 The backends should be able to switch between several virtual servers.
11071 The standard backends implement this by keeping an alist of virtual
11072 server environments that it pulls down/pushes up when needed.
11074 There are two groups of interface functions: @dfn{required functions},
11075 which must be present, and @dfn{optional functions}, which Gnus will
11076 always check whether are present before attempting to call.
11078 All these functions are expected to return data in the buffer
11079 @code{nntp-server-buffer} (@samp{" *nntpd*"}), which is somewhat
11080 unfortunately named, but we'll have to live with it. When I talk about
11081 ``resulting data'', I always refer to the data in that buffer. When I
11082 talk about ``return value'', I talk about the function value returned by
11085 Some backends could be said to be @dfn{server-forming} backends, and
11086 some might be said to not be. The latter are backends that generally
11087 only operate on one group at a time, and have no concept of ``server'' --
11088 they have a group, and they deliver info on that group and nothing more.
11090 In the examples and definitions I will refer to the imaginary backend
11093 @cindex @code{nnchoke}
11096 * Required Backend Functions:: Functions that must be implemented.
11097 * Optional Backend Functions:: Functions that need not be implemented.
11101 @node Required Backend Functions
11102 @subsubsection Required Backend Functions
11106 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
11108 @var{articles} is either a range of article numbers or a list of
11109 @code{Message-ID}s. Current backends do not fully support either---only
11110 sequences (lists) of article numbers, and most backends do not support
11111 retrieval of @code{Message-ID}s. But they should try for both.
11113 The result data should either be HEADs or NOV lines, and the result
11114 value should either be @code{headers} or @code{nov} to reflect this.
11115 This might later be expanded to @code{various}, which will be a mixture
11116 of HEADs and NOV lines, but this is currently not supported by Gnus.
11118 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
11119 headers, in some meaning of the word. This is generally done by
11120 fetching (at most) @var{fetch-old} extra headers less than the smallest
11121 article number in @code{articles}, and fill in the gaps as well. The
11122 presence of this parameter can be ignored if the backend finds it
11123 cumbersome to follow the request. If this is non-@code{nil} and not a
11124 number, do maximum fetches.
11126 Here's an example HEAD:
11129 221 1056 Article retrieved.
11130 Path: ifi.uio.no!sturles
11131 From: sturles@@ifi.uio.no (Sturle Sunde)
11132 Newsgroups: ifi.discussion
11133 Subject: Re: Something very droll
11134 Date: 27 Oct 1994 14:02:57 +0100
11135 Organization: Dept. of Informatics, University of Oslo, Norway
11137 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
11138 References: <38jdmq$4qu@@visbur.ifi.uio.no>
11139 NNTP-Posting-Host: holmenkollen.ifi.uio.no
11143 So a @code{headers} return value would imply that there's a number of
11144 these in the data buffer.
11146 Here's a BNF definition of such a buffer:
11150 head = error / valid-head
11151 error-message = [ "4" / "5" ] 2number " " <error message> eol
11152 valid-head = valid-message *header "." eol
11153 valid-message = "221 " <number> " Article retrieved." eol
11154 header = <text> eol
11157 If the return value is @code{nov}, the data buffer should contain
11158 @dfn{network overview database} lines. These are basically fields
11162 nov-buffer = *nov-line
11163 nov-line = 8*9 [ field <TAB> ] eol
11164 field = <text except TAB>
11167 For a closer explanation what should be in those fields,
11171 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
11173 @var{server} is here the virtual server name. @var{definitions} is a
11174 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
11176 If the server can't be opened, no error should be signaled. The backend
11177 may then choose to refuse further attempts at connecting to this
11178 server. In fact, it should do so.
11180 If the server is opened already, this function should return a
11181 non-@code{nil} value. There should be no data returned.
11184 @item (nnchoke-close-server &optional SERVER)
11186 Close connection to @var{server} and free all resources connected
11189 There should be no data returned.
11192 @item (nnchoke-request-close)
11194 Close connection to all servers and free all resources that the backend
11195 have reserved. All buffers that have been created by that backend
11196 should be killed. (Not the @code{nntp-server-buffer}, though.)
11198 There should be no data returned.
11201 @item (nnchoke-server-opened &optional SERVER)
11203 This function should return whether @var{server} is opened, and that the
11204 connection to it is still alive. This function should under no
11205 circumstances attempt to reconnect to a server that is has lost
11208 There should be no data returned.
11211 @item (nnchoke-status-message &optional SERVER)
11213 This function should return the last error message from @var{server}.
11215 There should be no data returned.
11218 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
11220 The result data from this function should be the article specified by
11221 @var{article}. This might either be a @code{Message-ID} or a number.
11222 It is optional whether to implement retrieval by @code{Message-ID}, but
11223 it would be nice if that were possible.
11225 If @var{to-buffer} is non-@code{nil}, the result data should be returned
11226 in this buffer instead of the normal data buffer. This is to make it
11227 possible to avoid copying large amounts of data from one buffer to
11228 another, and Gnus mainly request articles to be inserted directly into
11229 its article buffer.
11232 @item (nnchoke-open-group GROUP &optional SERVER)
11234 Make @var{group} the current group.
11236 There should be no data returned by this function.
11239 @item (nnchoke-request-group GROUP &optional SERVER)
11241 Get data on @var{group}. This function also has the side effect of
11242 making @var{group} the current group.
11244 Here's an example of some result data and a definition of the same:
11247 211 56 1000 1059 ifi.discussion
11250 The first number is the status, which should be @samp{211}. Next is the
11251 total number of articles in the group, the lowest article number, the
11252 highest article number, and finally the group name. Note that the total
11253 number of articles may be less than one might think while just
11254 considering the highest and lowest article numbers, but some articles
11255 may have been cancelled. Gnus just discards the total-number, so
11256 whether one should take the bother to generate it properly (if that is a
11257 problem) is left as an exercise to the reader.
11260 group-status = [ error / info ] eol
11261 error = [ "4" / "5" ] 2<number> " " <Error message>
11262 info = "211 " 3* [ <number> " " ] <string>
11266 @item (nnchoke-close-group GROUP &optional SERVER)
11268 Close @var{group} and free any resources connected to it. This will be
11269 a no-op on most backends.
11271 There should be no data returned.
11274 @item (nnchoke-request-list &optional SERVER)
11276 Return a list of all groups available on @var{server}. And that means
11279 Here's an example from a server that only carries two groups:
11282 ifi.test 0000002200 0000002000 y
11283 ifi.discussion 3324 3300 n
11286 On each line we have a group name, then the highest article number in
11287 that group, the lowest article number, and finally a flag.
11290 active-file = *active-line
11291 active-line = name " " <number> " " <number> " " flags eol
11293 flags = "n" / "y" / "m" / "x" / "j" / "=" name
11296 The flag says whether the group is read-only (@samp{n}), is moderated
11297 (@samp{m}), is dead (@samp{x}), is aliased to some other group
11298 (@samp{=other-group} or none of the above (@samp{y}).
11301 @item (nnchoke-request-post &optional SERVER)
11303 This function should post the current buffer. It might return whether
11304 the posting was successful or not, but that's not required. If, for
11305 instance, the posting is done asynchronously, it has generally not been
11306 completed by the time this function concludes. In that case, this
11307 function should set up some kind of sentinel to beep the user loud and
11308 clear if the posting could not be completed.
11310 There should be no result data from this function.
11313 @item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
11315 This function should return a buffer suitable for composing an article
11316 to be posted by @code{nnchoke-request-post}. If @var{post} is
11317 non-@code{nil}, this is not a followup, but a totally new article.
11318 @var{group} is the name of the group to be posted to. @var{subject} is
11319 the subject of the message. @var{article-buffer} is the buffer being
11320 followed up, if that is the case. @var{info} is the group info.
11321 @var{follow-to} is the group that one is supposed to re-direct the
11322 article ot. If @var{respect-poster} is non-@code{nil}, the special
11323 @samp{"poster"} value of a @code{Followup-To} header is to be respected.
11325 There should be no result data returned.
11329 @node Optional Backend Functions
11330 @subsubsection Optional Backend Functions
11334 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
11336 @var{groups} is a list of groups, and this function should request data
11337 on all those groups. How it does it is of no concern to Gnus, but it
11338 should attempt to do this in a speedy fashion.
11340 The return value of this function can be either @code{active} or
11341 @code{group}, which says what the format of the result data is. The
11342 former is in the same format as the data from
11343 @code{nnchoke-request-list}, while the latter is a buffer full of lines
11344 in the same format as @code{nnchoke-request-group} gives.
11347 group-buffer = *active-line / *group-status
11351 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
11353 A Gnus group info (@pxref{Group Info}) is handed to the backend for
11354 alterations. This comes in handy if the backend really carries all the
11355 information (as is the case with virtual an imap groups). This function
11356 may alter the info in any manner it sees fit, and should return the
11357 (altered) group info. This function may alter the group info
11358 destructively, so no copying is needed before boogeying.
11360 There should be no result data from this function.
11363 @item (nnchoke-request-type GROUP &optional ARTICLE)
11365 When the user issues commands for ``sending news'' (@kbd{F} in the summary
11366 buffer, for instance), Gnus has to know whether the article the user is
11367 following up is news or mail. This function should return @code{news}
11368 if @var{article} in @var{group} is news, @code{mail} if it is mail and
11369 @code{unknown} if the type can't be decided. (The @var{article}
11370 parameter is necessary in @code{nnvirtual} groups which might very well
11371 combine mail groups and news groups.)
11373 There should be no result data from this function.
11376 @item (nnchoke-request-update-mark GROUP ARTICLE MARK)
11378 If the user tries to set a mark that the backend doesn't like, this
11379 function may change the mark. Gnus will use whatever this function
11380 returns as the mark for @var{article} instead of the original
11381 @var{mark}. If the backend doesn't care, it must return the original
11382 @var{mark}, and not @code{nil} or any other type of garbage.
11384 The only use for this that I can see is what @code{nnvirtual} does with
11385 it---if a component group is auto-expirable, marking an article as read
11386 in the virtual group should result in the article being marked as
11389 There should be no result data from this function.
11392 @item (nnchoke-request-scan &optional GROUP SERVER)
11394 This function may be called at any time (by Gnus or anything else) to
11395 request that the backend check for incoming articles, in one way or
11396 another. A mail backend will typically read the spool file or query the
11397 POP server when this function is invoked. The @var{group} doesn't have
11398 to be heeded---if the backend decides that it is too much work just
11399 scanning for a single group, it may do a total scan of all groups. It
11400 would be nice, however, to keep things local if that's practical.
11402 There should be no result data from this function.
11405 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
11407 This is a request to fetch articles asynchronously later.
11408 @var{articles} is an alist of @var{(article-number line-number)}. One
11409 would generally expect that if one later fetches article number 4, for
11410 instance, some sort of asynchronous fetching of the articles after 4
11411 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
11412 alist) would be fetched asynchronously, but that is left up to the
11413 backend. Gnus doesn't care.
11415 There should be no result data from this function.
11418 @item (nnchoke-request-group-description GROUP &optional SERVER)
11420 The result data from this function should be a description of
11424 description-line = name <TAB> description eol
11426 description = <text>
11429 @item (nnchoke-request-list-newsgroups &optional SERVER)
11431 The result data from this function should be the description of all
11432 groups available on the server.
11435 description-buffer = *description-line
11439 @item (nnchoke-request-newgroups DATE &optional SERVER)
11441 The result data from this function should be all groups that were
11442 created after @samp{date}, which is in normal human-readable date
11443 format. The data should be in the active buffer format.
11446 @item (nnchoke-request-create-groups GROUP &optional SERVER)
11448 This function should create an empty group with name @var{group}.
11450 There should be no return data.
11453 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
11455 This function should run the expiry process on all articles in the
11456 @var{articles} range (which is currently a simple list of article
11457 numbers.) It is left up to the backend to decide how old articles
11458 should be before they are removed by this function. If @var{force} is
11459 non-@code{nil}, all @var{articles} should be deleted, no matter how new
11462 This function should return a list of articles that it did not/was not
11465 There should be no result data returned.
11468 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
11471 This function should move @var{article} (which is a number) from
11472 @var{group} by calling @var{accept-form}.
11474 This function should ready the article in question for moving by
11475 removing any header lines it has added to the article, and generally
11476 should ``tidy up'' the article. Then it should @code{eval}
11477 @var{accept-form} in the buffer where the ``tidy'' article is. This will
11478 do the actual copying. If this @code{eval} returns a non-@code{nil}
11479 value, the article should be removed.
11481 If @var{last} is @code{nil}, that means that there is a high likelihood
11482 that there will be more requests issued shortly, so that allows some
11485 There should be no data returned.
11488 @item (nnchoke-request-accept-article GROUP &optional LAST)
11490 This function takes the current buffer and inserts it into @var{group}.
11491 If @var{last} in @code{nil}, that means that there will be more calls to
11492 this function in short order.
11494 There should be no data returned.
11497 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
11499 This function should remove @var{article} (which is a number) from
11500 @var{group} and insert @var{buffer} there instead.
11502 There should be no data returned.
11505 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
11507 This function should delete @var{group}. If @var{force}, it should
11508 really delete all the articles in the group, and then delete the group
11509 itself. (If there is such a thing as ``the group itself''.)
11511 There should be no data returned.
11514 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
11516 This function should rename @var{group} into @var{new-name}. All
11517 articles that are in @var{group} should move to @var{new-name}.
11519 There should be no data returned.
11525 @node Score File Syntax
11526 @subsection Score File Syntax
11528 Score files are meant to be easily parsable, but yet extremely
11529 mallable. It was decided that something that had the same read syntax
11530 as an Emacs Lisp list would fit that spec.
11532 Here's a typical score file:
11536 ("win95" -10000 nil s)
11543 BNF definition of a score file:
11546 score-file = "" / "(" *element ")"
11547 element = rule / atom
11548 rule = string-rule / number-rule / date-rule
11549 string-rule = "(" quote string-header quote space *string-match ")"
11550 number-rule = "(" quote number-header quote space *number-match ")"
11551 date-rule = "(" quote date-header quote space *date-match ")"
11553 string-header = "subject" / "from" / "references" / "message-id" /
11554 "xref" / "body" / "head" / "all" / "followup"
11555 number-header = "lines" / "chars"
11556 date-header = "date"
11557 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
11558 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
11559 score = "nil" / <integer>
11560 date = "nil" / <natural number>
11561 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
11562 "r" / "regex" / "R" / "Regex" /
11563 "e" / "exact" / "E" / "Exact" /
11564 "f" / "fuzzy" / "F" / "Fuzzy"
11565 number-match = "(" <integer> [ "" / [ space score [ "" /
11566 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
11567 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
11568 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
11569 space date [ "" / [ space date-match-t ] ] ] ] ")"
11570 date-match-t = "nil" / "at" / "before" / "after"
11571 atom = "(" [ required-atom / optional-atom ] ")"
11572 required-atom = mark / expunge / mark-and-expunge / files /
11573 exclude-files / read-only / touched
11574 optional-atom = adapt / local / eval
11575 mark = "mark" space nil-or-number
11576 nil-or-number = "nil" / <integer>
11577 expunge = "expunge" space nil-or-number
11578 mark-and-expunge = "mark-and-expunge" space nil-or-number
11579 files = "files" *[ space <string> ]
11580 exclude-files = "exclude-files" *[ space <string> ]
11581 read-only = "read-only" [ space "nil" / space "t" ]
11582 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
11583 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
11584 local = "local" *[ space "(" <string> space <form> ")" ]
11585 eval = "eval" space <form>
11586 space = *[ " " / <TAB> / <NEWLINE> ]
11589 Any unrecognized elements in a score file should be ignored, but not
11592 As you can see, white space is needed, but the type and amount of white
11593 space is irrelevant. This means that formatting of the score file is
11594 left up to the programmer---if it's simpler to just spew it all out on
11595 one looong line, then that's ok.
11597 The meaning of the various atoms are explained elsewhere in this
11602 @subsection Headers
11604 Gnus uses internally a format for storing article headers that
11605 corresponds to the @sc{nov} format in a mysterious fashion. One could
11606 almost suspect that the author looked at the @sc{nov} specification and
11607 just shamelessly @emph{stole} the entire thing, and one would be right.
11609 @dfn{Header} is a severely overloaded term. ``Header'' is used in RFC1036
11610 to talk about lines in the head of an article (eg., @code{From}). It is
11611 used by many people as a synonym for ``head''---``the header and the
11612 body''. (That should be avoided, in my opinion.) And Gnus uses a format
11613 internally that it calls ``header'', which is what I'm talking about
11614 here. This is a 9-element vector, basically, with each header (ouch)
11617 These slots are, in order: @code{number}, @code{subject}, @code{from},
11618 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
11619 @code{xref}. There are macros for accessing and setting these slots --
11620 they all have predictable names beginning with @code{mail-header-} and
11621 @code{mail-header-set-}, respectively.
11623 The @code{xref} slot is really a @code{misc} slot. Any extra info will
11630 @sc{gnus} introduced a concept that I found so useful that I've started
11631 using it a lot and have elaborated on it greatly.
11633 The question is simple: If you have a large amount of objects that are
11634 identified by numbers (say, articles, to take a @emph{wild} example)
11635 that you want to callify as being ``included'', a normal sequence isn't
11636 very useful. (A 200,000 length sequence is a bit long-winded.)
11638 The solution is as simple as the question: You just collapse the
11642 (1 2 3 4 5 6 10 11 12)
11645 is transformed into
11648 ((1 . 6) (10 . 12))
11651 To avoid having those nasty @samp{(13 . 13)} elements to denote a
11652 lonesome object, a @samp{13} is a valid element:
11655 ((1 . 6) 7 (10 . 12))
11658 This means that comparing two ranges to find out whether they are equal
11659 is slightly tricky:
11662 ((1 . 5) 7 8 (10 . 12))
11668 ((1 . 5) (7 . 8) (10 . 12))
11671 are equal. In fact, any non-descending list is a range:
11677 is a perfectly valid range, although a pretty long-winded one. This is
11684 and is equal to the previous range.
11686 Here's a BNF definition of ranges. Of course, one must remember the
11687 semantic requirement that the numbers are non-descending. (Any number
11688 of repetition of the same number is allowed, but apt to disappear in
11692 range = simple-range / normal-range
11693 simple-range = "(" number " . " number ")"
11694 normal-range = "(" start-contents ")"
11695 contents = "" / simple-range *[ " " contents ] /
11696 number *[ " " contents ]
11699 Gnus currently uses ranges to keep track of read articles and article
11700 marks. I plan on implementing a number of range operators in C if The
11701 Powers That Be are willing to let me. (I haven't asked yet, because I
11702 need to do some more thinking on what operators I need to make life
11703 totally range-based without ever having to convert back to normal
11708 @subsection Group Info
11710 Gnus stores all permanent info on groups in a @dfn{group info} list.
11711 This list is from three to six elements (or more) long and exhaustively
11712 describes the group.
11714 Here are two example group infos; one is a very simple group while the
11715 second is a more complex one:
11718 ("no.group" 5 (1 . 54324))
11720 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
11721 ((tick (15 . 19)) (replied 3 6 (19 . 3)))
11723 (auto-expire (to-address "ding@@ifi.uio.no")))
11726 The first element is the group name as Gnus knows the group; the second
11727 is the group level; the third is the read articles in range format; the
11728 fourth is a list of article marks lists; the fifth is the select method;
11729 and the sixth contains the group parameters.
11731 Here's a BNF definition of the group info format:
11734 info = "(" group space level space read
11735 [ "" / [ space marks-list [ "" / [ space method [ "" /
11736 space parameters ] ] ] ] ] ")"
11737 group = quote <string> quote
11738 level = <integer in the range of 1 to inf>
11740 marks-lists = nil / "(" *marks ")"
11741 marks = "(" <string> range ")"
11742 method = "(" <string> *elisp-forms ")"
11743 parameters = "(" *elisp-forms ")"
11746 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
11747 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
11751 @node Various File Formats
11752 @subsection Various File Formats
11755 * Active File Format:: Information on articles and groups available.
11756 * Newsgroups File Format:: Group descriptions.
11760 @node Active File Format
11761 @subsubsection Active File Format
11763 The active file lists all groups that are available on the server in
11764 question. It also lists the highest and lowest current article numbers
11767 Here's an excerpt from a typical active file:
11770 soc.motss 296030 293865 y
11771 alt.binaries.pictures.fractals 3922 3913 n
11772 comp.sources.unix 1605 1593 m
11773 comp.binaries.ibm.pc 5097 5089 y
11774 no.general 1000 900 y
11777 Here's a pseudo-BNF definition of this file:
11780 active = *group-line
11781 group-line = group space high-number space low-number space flag <NEWLINE>
11782 group = <non-white-space string>
11784 high-number = <non-negative integer>
11785 low-number = <positive integer>
11786 flag = "y" / "n" / "m" / "j" / "x" / "=" group
11790 @node Newsgroups File Format
11791 @subsubsection Newsgroups File Format
11793 The newsgroups file lists groups along with their descriptions. Not all
11794 groups on the server have to be listed, and not all groups in the file
11795 have to exist on the server. The file is meant purely as information to
11798 The format is quite simple; a group name, a tab, and the description.
11799 Here's the definition:
11803 line = group tab description <NEWLINE>
11804 group = <non-white-space string>
11806 description = <string>
11810 @node Emacs for Heathens
11811 @section Emacs for Heathens
11813 Believe it or not, but some people who use Gnus haven't really used
11814 Emacs much before they embarked on their journey on the Gnus Love Boat.
11815 If you are one of those unfortunates whom ``@kbd{M-C-a}'', ``kill the
11816 region'', and ``set @code{gnus-flargblossen} to an alist where the key is
11817 a regexp that is used for matching on the group name'' are magical
11818 phrases with little or no meaning, then this appendix is for you. If
11819 you are already familiar with Emacs, just ignore this and go fondle your
11823 * Keystrokes:: Entering text and executing commands.
11824 * Emacs Lisp:: The built-in Emacs programming language.
11829 @subsection Keystrokes
11833 Q: What is an experienced Emacs user?
11836 A: A person who wishes that the terminal had pedals.
11839 Yes, when you use Emacs, you are apt to use the control key, the shift
11840 key and the meta key a lot. This is very annoying to some people
11841 (notably @code{vi}le users), and the rest of us just love the hell out
11842 of it. Just give up and submit. Emacs really does stand for
11843 ``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you may
11844 have heard from other disreputable sources (like the Emacs author).
11846 The shift key is normally located near your pinky fingers, and are
11847 normally used to get capital letters and stuff. You probably use it all
11848 the time. The control key is normally marked ``CTRL'' or something like
11849 that. The meta key is, funnily enough, never marked as such on any
11850 keyboards. The one I'm currently at has a key that's marked ``Alt'', which
11851 is the meta key on this keyboard. It's usually located somewhere to the
11852 left hand side of the keyboard, usually on the bottom row.
11854 Now, us Emacs people doesn't say ``press the meta-control-m key'', because
11855 that's just too inconvenient. We say ``press the @kbd{M-C-m} key''.
11856 @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the prefix that
11857 means ``control''. So ``press @kbd{C-k}'' means ``press down the control
11858 key, and hold it down while you press @kbd{k}''. ``Press @kbd{M-C-k}''
11859 means ``press down and hold down the meta key and the control key and
11860 then press @kbd{k}''. Simple, ay?
11862 This is somewhat complicated by the fact that not all keyboards have a
11863 meta key. In that case you can use the ``escape'' key. Then @kbd{M-k}
11864 means ``press escape, release escape, press @kbd{k}''. That's much more
11865 work than if you have a meta key, so if that's the case, I respectfully
11866 suggest you get a real keyboard with a meta key. You can't live without
11872 @subsection Emacs Lisp
11874 Emacs is the King of Editors because it's really a Lisp interpreter.
11875 Each and every key you tap runs some Emacs Lisp code snippet, and since
11876 Emacs Lisp is an interpreted language, that means that you can configure
11877 any key to run any random code. You just, like, do it.
11879 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
11880 functions. (These are byte-compiled for speed, but it's still
11881 interpreted.) If you decide that you don't like the way Gnus does
11882 certain things, it's trivial to have it do something a different way.
11883 (Well, at least if you know how to write Lisp code.) However, that's
11884 beyond the scope of this manual, so we are simply going to talk about
11885 some common constructs that you normally use in your @file{.emacs} file
11888 If you want to set the variable @code{gnus-florgbnize} to four (4), you
11889 write the following:
11892 (setq gnus-florgbnize 4)
11895 This function (really ``special form'') @code{setq} is the one that can
11896 set a variable to some value. This is really all you need to know. Now
11897 you can go and fill your @code{.emacs} file with lots of these to change
11900 If you have put that thing in your @code{.emacs} file, it will be read
11901 and @code{eval}ed (which is lisp-ese for ``run'') the next time you start
11902 Emacs. If you want to change the variable right away, simply say
11903 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
11904 previous ``form'', which here is a simple @code{setq} statement.
11906 Go ahead---just try it, if you're located at your Emacs. After you
11907 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
11908 is the return value of the form you @code{eval}ed.
11912 If the manual says ``set @code{gnus-read-active-file} to @code{some}'',
11916 (setq gnus-read-active-file 'some)
11919 On the other hand, if the manual says ``set @code{gnus-nntp-server} to
11920 @samp{"nntp.ifi.uio.no"}'', that means:
11923 (setq gnus-nntp-server "nntp.ifi.uio.no")
11926 So be careful not to mix up strings (the latter) with symbols (the
11927 former). The manual is unambiguous, but it can be confusing.
11930 @include gnus-faq.texi