2 \input texinfo @c -*-texinfo-*-
6 @settitle September Gnus Manual
13 @setchapternewpage odd
17 \documentclass[twoside,a4paper,openright]{book}
18 \usepackage[latin1]{inputenc}
19 % \usepackage{fontenc}
21 \usepackage{pagestyle}
23 \fontfamily{bembo}\selectfont
28 \newcommand{\gnuschaptername}{}
29 \newcommand{\gnussectionname}{}
31 \newcommand{\gnusbackslash}{/}
33 \newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}}
34 \newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}}
36 \newcommand{\gnuskindex}[1]{\index{#1}}
37 \newcommand{\gnusindex}[1]{\index{#1}}
39 \newcommand{\gnustt}[1]{{\textbf{\textsf{#1}}}}
40 \newcommand{\gnuscode}[1]{\gnustt{#1}}
41 \newcommand{\gnussamp}[1]{`\gnustt{#1}'}
42 \newcommand{\gnuslisp}[1]{\gnustt{#1}}
43 \newcommand{\gnuskbd}[1]{`\gnustt{#1}'}
44 \newcommand{\gnusfile}[1]{`\gnustt{#1}'}
45 \newcommand{\gnusdfn}[1]{\textit{#1}}
46 \newcommand{\gnusi}[1]{\textit{#1}}
47 \newcommand{\gnusstrong}[1]{\textbf{#1}}
48 \newcommand{\gnusemph}[1]{\textit{#1}}
49 \newcommand{\gnusvar}[1]{\textsl{\textsf{#1}}}
50 \newcommand{\gnussc}[1]{\textsc{#1}}
51 \newcommand{\gnustitle}[1]{{\huge\textbf{#1}}}
52 \newcommand{\gnusauthor}[1]{{\large\textbf{#1}}}
54 \newcommand{\gnusbullet}{{${\bullet}$}}
55 \newcommand{\gnusdollar}{\$}
56 \newcommand{\gnusampersand}{\&}
57 \newcommand{\gnuspercent}{\%}
58 \newcommand{\gnushash}{\#}
59 \newcommand{\gnushat}{\%}
60 \newcommand{\gnustilde}{\%}
61 \newcommand{\gnusless}{{$<$}}
62 \newcommand{\gnusgreater}{{$>$}}
64 \newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=gnus-head.eps,height=1cm}}}
65 \newcommand{\gnusinteresting}{
66 \marginpar[\hspace{2.5cm}\gnushead]{\gnushead}
69 \newcommand{\gnuschapter}[1]{
71 \renewcommand{\gnuschaptername}{#1}
73 % \epsfig{figure=gnus-herd-\arabic{chapter}.eps,height=15cm}
77 \newcommand{\gnusitemx}[1]{{\itemsep=0pt\item#1}}
79 \newcommand{\gnussection}[1]{
80 \renewcommand{\gnussectionname}{#1}
84 \newenvironment{codelist}%
89 \newenvironment{kbdlist}%
95 \newenvironment{dfnlist}%
100 \newenvironment{stronglist}%
105 \newenvironment{samplist}%
110 \newenvironment{varlist}%
115 \newenvironment{emphlist}%
120 \newlength{\headrulewidth}
121 \setlength{\headrulewidth}{\headtextwidth}
122 \addtolength{\headrulewidth}{-2.6ex}
123 \newlength{\headwrule}
124 \setlength{\headwrule}{\headrulewidth}
125 \addtolength{\headwrule}{-0ex}
134 \makebox[\headtextwidth]{
136 %\ifnum chapter=0\else
137 \textbf{\arabic{chapter}.\arabic{section}}
139 \textbf{\gnussectionname\hfill\arabic{page}}
141 %\hspace*{-\headrulewidth}
142 %\raisebox{-3pt}{\rule{\headwrule}{0.5pt}}
149 \makebox[\headtextwidth]{
150 \textbf{\arabic{page}\hfill\gnuschaptername}
151 %\hspace*{-\headrulewidth}
152 %\raisebox{-3pt}{\rule{\headwrule}{0.5pt}}
161 \raisebox{-0.5cm}{\epsfig{figure=gnus-big-logo.eps,height=1cm}}
163 \raisebox{-0.5cm}{\epsfig{figure=gnus-big-logo.eps,height=1cm}}
177 %\addtolength{\oddsidemargin}{-5cm}
178 %\addtolength{\evensidemargin}{-5cm}
180 \addtolength{\textheight}{2cm}
182 \gnustitle{\gnustitlename}\\
185 \hspace*{-1cm}\epsfig{figure=gnus-big-logo.eps,height=15cm}
188 \gnusauthor{by Lars Magne Ingebrigtsen}
195 \thispagestyle{empty}
197 Copyright \copyright{} 1995 Free Software Foundation, Inc.
199 Permission is granted to make and distribute verbatim copies of
200 this manual provided the copyright notice and this permission notice
201 are preserved on all copies.
203 Permission is granted to copy and distribute modified versions of this
204 manual under the conditions for verbatim copying, provided that the
205 entire resulting derived work is distributed under the terms of a
206 permission notice identical to this one.
208 Permission is granted to copy and distribute translations of this manual
209 into another language, under the above conditions for modified versions.
218 This file documents Gnus, the GNU Emacs newsreader.
220 Copyright (C) 1995 Free Software Foundation, Inc.
222 Permission is granted to make and distribute verbatim copies of
223 this manual provided the copyright notice and this permission notice
224 are preserved on all copies.
227 Permission is granted to process this file through Tex and print the
228 results, provided the printed document carries copying permission
229 notice identical to this one except for the removal of this paragraph
230 (this paragraph not being relevant to the printed manual).
233 Permission is granted to copy and distribute modified versions of this
234 manual under the conditions for verbatim copying, provided also that the
235 entire resulting derived work is distributed under the terms of a
236 permission notice identical to this one.
238 Permission is granted to copy and distribute translations of this manual
239 into another language, under the above conditions for modified versions.
245 @title September Gnus Manual
247 @author by Lars Magne Ingebrigtsen
250 @vskip 0pt plus 1filll
251 Copyright @copyright{} 1995 Free Software Foundation, Inc.
253 Permission is granted to make and distribute verbatim copies of
254 this manual provided the copyright notice and this permission notice
255 are preserved on all copies.
257 Permission is granted to copy and distribute modified versions of this
258 manual under the conditions for verbatim copying, provided that the
259 entire resulting derived work is distributed under the terms of a
260 permission notice identical to this one.
262 Permission is granted to copy and distribute translations of this manual
263 into another language, under the above conditions for modified versions.
272 @top The Gnus Newsreader
276 You can read news (and mail) from within Emacs by using Gnus. The news
277 can be gotten by any nefarious means you can think of---@sc{nntp}, local
278 spool or your mbox file. All at the same time, if you want to push your
285 Gnus is the advanced, self-documenting, customizable, extensible
286 unreal-time newsreader for GNU Emacs.
288 Oops. That sounds oddly familiar, so let's start over again to avoid
289 being accused of plagiarism:
291 Gnus is a message-reading laboratory. It will let you look at just
292 about anything as if it were a newsgroup. You can read mail with it,
293 you can browse directories with it, you can @code{ftp} with it---you can
294 even read news with it, if you feel like it.
296 Gnus tries to empower people who read news the same way Emacs empowers
297 people who edit text. Gnus sets no limits to what the user should be
298 allowed to do. Users are encouraged to extend Gnus to behave like they
299 want it to behave. A program should not control people; people should
300 be empowered to do what they want by using (or abusing) the program.
306 * History:: How Gnus got where it is today.
307 * Terminology:: We use really difficult, like, words here.
308 * Starting Up:: Finding news can be a pain.
309 * The Group Buffer:: Selecting, subscribing and killing groups.
310 * The Summary Buffer:: Reading, saving and posting articles.
311 * The Article Buffer:: Displaying and handling articles.
312 * The Server Buffer:: Making and editing virtual servers.
313 * Scoring:: Assigning values to articles.
314 * Various:: General purpose settings.
315 * Customization:: Tailoring Gnus to your needs.
316 * Troubleshooting:: What you might try if things do not work.
317 * The End:: Farewell and goodbye.
318 * Appendices:: Technical stuff, Emacs intro, FAQ
319 * Index:: Variable, function and concept index.
320 * Key Index:: Key Index.
328 @sc{gnus} was written by Masanobu UMEDA. When autumn crept up in '94,
329 Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
331 If you want to investigate the person responsible for this outrage, you
332 can point your (feh!) web browser to
333 @file{http://www.ifi.uio.no/~larsi/}. This is also the primary
334 distribution point for the new and spiffy versions of Gnus, also know as
335 The Site That Destroys Newsrcs And Drives People Mad.
337 During the first extended alpha period of develpment, the new Gnus was
338 called ``(ding) Gnus''. @dfn{(ding)}, is, of course, short for @dfn{ding
339 is not Gnus}, which is a total and utter lie, but who cares? (Besides,
340 the ``Gnus'' in this abbreviation should probably be pronounced ``news'' as
341 UMEDA intended, which makes it a more appropriate name, don't you
344 In any case, after spending all that energy with coming up with a new
345 and spiffy name, we decided that the name was @emph{too} spiffy, so we
346 renamamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs.
347 ``@sc{gnus}''. New vs. old.
349 Incidentally, the next Gnus generation will be called ``September Gnus'',
350 and won't be released until February. Confused? You will be.
353 * Why?:: What's the point of Gnus?
354 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
355 * Conformity:: Gnus tries to conform to all standards.
356 * Emacsen:: Gnus can be run on a few modern Emacsen.
357 * Contributors:: Oodles of people.
358 * New Features:: Pointers to some of the new stuff in Gnus.
359 * Newest Features:: Features so new that they haven't been written yet.
366 What's the point of Gnus?
368 I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep''
369 newsreader, that lets you do anything you can think of. That was my
370 original motivation, but while working on Gnus, it has become clear to
371 me that this generation of newsreaders really belong in the stone age.
372 Newsreaders haven't developed much since the infancy of the net. If the
373 volume continues to rise with the current rate of increase, all current
374 newsreaders will be pretty much useless. How do you deal with
375 newsgroups that have hundreds (or thousands) of new articles each day?
377 Gnus offers no real solutions to these questions, but I would very much
378 like to see Gnus being used as a testing ground for new methods of
379 reading and fetching news. Expanding on Umeda-san's wise decision to
380 separate the newsreader from the backends, Gnus now offers a simple
381 interface for anybody who wants to write new backends for fetching mail
382 and news from different sources. I have added hooks for customizations
383 everywhere I can imagine useful. By doing so, I'm inviting every one of
384 you to explore and invent new ways of reading news.
386 May Gnus never be complete. @kbd{C-u 100 M-x hail-emacs}.
390 @section Compatibility
392 @cindex compatibility
393 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
394 bindings have been kept. More key bindings have been added, of course,
395 but only in one or two obscure cases have old bindings been changed.
400 @center In a cloud bones of steel.
404 All commands have kept their names. Some internal functions have changed
407 The @code{gnus-uu} package has changed drastically. @xref{Decoding
410 One major compatibility question is the presence of several summary
411 buffers. All variables that are relevant while reading a group are
412 buffer-local to the summary buffer they belong in. Although most
413 important variables have their values copied into their global
414 counterparts whenever a command is executed in the summary buffer, this
415 change might lead to incorrect values being used unless you are careful.
417 All code that relies on knowledge of @sc{gnus} internals will probably
418 fail. To take two examples: Sorting @code{gnus-newsrc-assoc} (or
419 changing it in any way, as a matter of fact) is strictly verboten. Gnus
420 maintains a hash table that points to the entries in this assoc (which
421 speeds up many functions), and changing the assoc directly will lead to
426 Old hilit19 code does not work at all. In fact, you should probably
427 remove all hilit code from all Gnus hooks
428 (@code{gnus-group-prepare-hook}, @code{gnus-summary-prepare-hook} and
429 @code{gnus-summary-article-hook}). (Well, at the very least the first
430 two.) Gnus provides various integrated functions for highlighting.
431 These are faster and more accurate. To make life easier for everybody,
432 Gnus will by default remove all hilit calls from all hilit hooks.
435 Packages like @code{expire-kill} will no longer work. As a matter of
436 fact, you should probably remove all old @sc{gnus} packages (and other
437 code) when you start using Gnus. More likely than not, Gnus already
438 does what you have written code to make @sc{gnus} do. (Snicker.)
440 Even though old methods of doing things are still supported, only the
441 new methods are documented in this manual. If you detect a new method of
442 doing something while reading this manual, that does not mean you have
443 to stop doing it the old way.
445 Gnus understands all @sc{gnus} startup files.
448 Overall, a casual user who hasn't written much code that depends on
449 @sc{gnus} internals should suffer no problems. If problems occur,
450 please let me know (@kbd{M-x gnus-bug}).
456 No rebels without a clue here, ma'am. We conform to all standards known
457 to (wo)man. Except for those standards and/or conventions we disagree
463 There are no known breaches of this standard.
466 There are no known breaches of this standard, either.
468 @item Usenet Seal of Approval
469 Gnus hasn't been formally through the Seal process, but I have read
470 through the Seal text and I think Gnus would pass.
472 @item Son-of-RFC 1036
473 We do have some breaches to this one.
478 Gnus does no MIME handling, and this standard-to-be seems to think that
479 MIME is the bees' knees, so we have major breakage here.
482 This is considered to be a ``vanity header'', while I consider it to be
483 consumer information. After seeing so many badly formatted articles
484 coming from @code{tin} and @code{Netscape} I know not to use either of
485 those for posting articles. I would not have known that if it wasn't
486 for the @code{X-Newsreader} header.
489 Gnus breaks lines if this header is long. I infer from RFC1036 that
490 being conservative in what you output is not creating 5000-character
491 lines, so it seems like a good idea to me. However, this standard-to-be
492 says that whitespace in the @code{References} header is to be preserved,
493 so... It doesn't matter one way or the other to Gnus, so if somebody
494 tells me what The Way is, I'll change it. Or not.
499 If you ever see Gnus act noncompliantly to the texts mentioned above,
500 don't hesitate to drop a note to Gnus Towers and let us know.
510 Gnus should work on :
521 Mule versions based on Emacs 19.30 and up.
525 Gnus will absolutely not work on any Emacsen older than that. Not
528 There are some vague differences in what Gnus does, though:
533 The mouse-face on Gnus lines under Emacs and Mule is delimited to
534 certain parts of the lines while they cover the entire line under
538 The same with current-article marking---XEmacs puts an underline under
539 the entire summary line while Emacs and Mule are nicer and kinder.
542 XEmacs features more graphics---a logo and a toolbar.
545 Citation highlighting us better under Emacs and Mule than under XEmacs.
548 Emacs 19.26-19.28 have tangible hidden headers, which can be a bit
555 @section Contributors
558 The new Gnus version couldn't have been done without the help of all the
559 people on the (ding) mailing list. Every day for months I have gotten
560 tens of nice bug reports from them, filling me with joy, every single
561 one of them. Smooches. The people on the list have been tried beyond
562 endurance, what with my ``oh, that's a neat idea <type type>, yup, I'll
563 release it right away <ship off> no wait, that doesn't work at all <type
564 type>, yup, I'll ship that one off right away <ship off> no, wait, that
565 absolutely does not work'' policy for releases. Micro$oft---bah.
566 Amateurs. I'm @emph{much} worse. (Or is that ``worser''? ``much worser''?
569 I would like to take this opportunity to thank the Academy for... oops,
574 Of course, GNUS was written by Masanobu UMEDA.
576 Many excellent functions, especially dealing with scoring and
577 highlighting (as well as the @sc{soup} support) was written
580 Design and graphics were done by Luis Fernandes.
582 Innumerable bug fixes were written by Sudish Joseph.
584 @code{gnus-topic} was written by Ilja Weis.
586 Lots and lots of bugs were found and fixed by Steven L. Baur.
588 The refcard was written by Vladimir Alexiev.
590 I stole some pieces from the XGnus distribution by Felix Lee and JWZ.
592 @code{nnfolder} has been much enhanced by Scott Byer.
594 The orphan scoring was written by Peter Mutsaers.
596 GNU XEmacs support has been added by Fabrice Popineau.
598 POP mail support was written by Ken Raeburn.
600 Various bits and pieces, especially dealing with .newsrc files, were
601 suggested and added by Hallvard B Furuseth.
603 Brian Edmonds has written @code{gnus-bbdb}.
605 Ricardo Nassif did the proof-reading.
607 Kevin Davidson came up with the name @dfn{ding}, so blame him.
609 Peter Arius, Stainless Steel Rat, Ulrik Dickow, Jack Vinson, Daniel
610 Quinlan, Frank D. Cringle, Geoffrey T. Dairiki and Andrew Eskilsson have
611 all contributed code and suggestions.
616 @section New Features
622 The look of all buffers can be changed by setting format-like variables
623 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
626 Local spool and several @sc{nntp} servers can be used at once
627 (@pxref{Foreign Groups}).
630 You can combine groups into virtual groups (@pxref{nnvirtual}).
633 You can read a number of different mail formats (@pxref{Reading Mail}).
634 All the mail backends implement a convenient mail expiry scheme
635 (@pxref{Expiring Old Mail Articles}).
638 Gnus can use various strategies for gathering threads that have lost
639 their roots (thereby gathering loose sub-threads into one thread) or it
640 can go back and retrieve enough headers to build a complete thread
641 (@pxref{Customizing Threading}).
644 Killed groups can be displayed in the group buffer, and you can read
648 Gnus can do partial group updates---you do not have to retrieve the
649 entire active file just to check for new articles in a few groups
650 (@pxref{The Active File}).
653 Gnus implements a sliding scale of subscribedness to groups
654 (@pxref{Group Levels}).
657 You can score articles according to any number of criteria
658 (@pxref{Scoring}). You can even get Gnus to find out how to score
659 articles for you (@pxref{Adaptive Scoring}).
662 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
663 manner, so it should be difficult to lose much data on what you have
664 read if your machine should go down (@pxref{Auto Save}).
667 Gnus now has its own startup file to avoid cluttering up the
671 You can set the process mark on both groups and articles and perform
672 operations on all the marked items (@pxref{Process/Prefix}).
675 You can grep through a subset of groups and create a group from the
676 results (@pxref{nnkiboze}).
679 You can list subsets of groups according to, well, anything
680 (@pxref{Listing Groups}).
683 You can browse foreign servers and subscribe to groups from those
684 servers (@pxref{Browse Foreign Server}).
687 Gnus can fetch articles asynchronously on a second connection to the
688 server (@pxref{Asynchronous Fetching}).
691 You can cache articles locally (@pxref{Article Caching}).
694 The uudecode functions have been expanded and generalized
695 (@pxref{Decoding Articles}).
698 You can still post uuencoded articles, which was a little-known feature
702 Fetching parents (and other articles) now actually works without
703 glitches (@pxref{Finding the Parent}).
706 Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
709 Digests (and other files) can be used as the basis for groups
713 Articles can be highlighted and customized (@pxref{Customizing
717 URLs and other external references can be buttonized (@pxref{Article
721 All Gnus buffers can be customized in a difficult fashion
722 (@pxref{Windows Configuration}).
725 You can click on buttons instead of using the keyboard
729 Gnus can use NoCeM files to weed out spam (@pxref{NoCeM}).
733 This is, of course, just a @emph{short} overview of the @emph{most}
734 important new features. No, really. There are tons more. Yes, we have
735 feeping creaturism in full effect, but nothing too gratuitous, I would
739 @node Newest Features
740 @section Newest Features
743 Also known as the @dfn{todo list}. Sure to be implemented before the
746 Be afraid. Be very afraid.
750 Native @sc{mime} support is something that should be done.
752 A better and simpler method for specifying mail composing methods.
754 Allow posting through mail-to-news gateways.
756 Really do unbinhexing.
759 And much, much, much more. There is more to come than has already been
760 implemented. (But that's always true, isn't it?)
762 @code{<URL:http://www.ifi.uio.no/~larsi/sgnus/todo>} is where the actual
763 up-to-the-second todo list is located, so if you're really curious, you
764 could point your Web browser over that-a-way.
775 This is what you are supposed to use this thing for---reading news.
776 News is generally fetched from a nearby @sc{nntp} server, and is
777 generally publicly available to everybody. If you post news, the entire
778 world is likely to read just what you have written, and they'll all
779 snigger mischievously. Behind your back.
783 Everything that's delivered to you personally is mail. Some news/mail
784 readers (like Gnus) blur the distinction between mail and news, but
785 there is a difference. Mail is private. News is public. Mailing is
786 not posting, and replying is not following up.
789 Send a mail to the person who has written what you are reading.
792 Post an article to the current newsgroup responding to the article you
796 Gnus gets fed articles from a number of backends, both news and mail
797 backends. Gnus does not handle the underlying media, so to speak---this
798 is all done by the backends.
801 Gnus will always use one method (and backend) as the @dfn{native}, or
802 default, way of getting news.
805 You can also have any number of foreign groups at the same time. These
806 are groups that use different backends for getting news.
810 The top part of an article, where administration information (etc.) is
815 The rest of an article. Everything that is not in the head is in the
820 A line from the head of an article.
824 A collection of such lines, or a collection of heads. Or even a
825 collection of @sc{nov} lines.
829 When Gnus enters a group, it asks the backend for the headers for all
830 the unread articles in the group. Most servers support the News OverView
831 format, which is much smaller and much faster to read than the normal
836 Each group is subscribed at some @dfn{level} or other (1-9). The ones
837 that have a lower level are ``more'' subscribed than the groups with a
838 higher level. In fact, groups on levels 1-5 are considered
839 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
840 are @dfn{killed}. Commands for listing groups and scanning for new
841 articles will all use the numeric prefix as @dfn{working level}.
844 @cindex killed groups
845 No information on killed groups is stored or updated, which makes killed
846 groups much easier to handle than subscribed groups.
849 @cindex zombie groups
850 Just like killed groups, only slightly less dead.
854 The news server has to keep track of what articles it carries, and what
855 groups exist. All this information in stored in the active file, which
856 is rather large, as you might surmise.
860 A group that exists in the @file{.newsrc} file, but isn't known to the
861 server (i. e., it isn't in the active file), is a @emph{bogus group}.
862 This means that the group probably doesn't exist (any more).
867 @chapter Starting Gnus
872 If your system administrator has set things up properly, starting Gnus
873 and reading news is extremely easy---you just type @kbd{M-x gnus}.
875 @findex gnus-other-frame
876 @kindex M-x gnus-other-frame
877 If you want to start Gnus in a different frame, you can use the command
878 @kbd{M-x gnus-other-frame} instead.
880 If things do not go smoothly at startup, you have to twiddle some
884 * Finding the News:: Choosing a method for getting news.
885 * The First Time:: What does Gnus do the first time you start it?
886 * The Server is Down:: How can I read my mail then?
887 * Slave Gnusii:: You can have more than one Gnus active at a time.
888 * Fetching a Group:: Starting Gnus just to read a group.
889 * New Groups:: What is Gnus supposed to do with new groups?
890 * Startup Files:: Those pesky startup files---@file{.newsrc}.
891 * Auto Save:: Recovering from a crash.
892 * The Active File:: Reading the active file over a slow line Takes Time.
893 * Startup Variables:: Other variables you might change.
896 @node Finding the News
897 @section Finding the News
899 @vindex gnus-select-method
901 The @code{gnus-select-method} variable controls how Gnus finds news.
902 This variable should be a list where the first element says @dfn{how}
903 and the second element says @dfn{where}. This method is your native
904 method. All groups that are not fetched with this method are foreign
907 For instance, if you want to get your daily dosage of news from the
908 @samp{news.somewhere.edu} @sc{nntp} server, you'd say:
911 (setq gnus-select-method '(nntp "news.somewhere.edu"))
914 If you want to read directly from the local spool, say:
917 (setq gnus-select-method '(nnspool ""))
920 If you can use a local spool, you probably should, as it will almost
921 certainly be much faster.
923 @vindex gnus-nntpserver-file
925 @cindex @sc{nntp} server
926 If this variable is not set, Gnus will take a look at the
927 @code{NNTPSERVER} environment variable. If that variable isn't set,
928 Gnus will see whether @code{gnus-nntpserver-file} (default
929 @file{/etc/nntpserver}) has any opinions in the matter. It that fails
930 as well, Gnus will will try to use the machine that is running Emacs as
931 an @sc{nntp} server. That's a longshot, though.
933 @vindex gnus-nntp-server
934 If @code{gnus-nntp-server} is set, this variable will override
935 @code{gnus-select-method}. You should therefore set
936 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
938 @vindex gnus-secondary-servers
939 You can also make Gnus prompt you interactively for the name of an
940 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
941 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
942 in the @code{gnus-secondary-servers} list (if any). You can also just
943 type in the name of any server you feel like visiting.
945 However, if you use one @sc{nntp} server regularly, and are just
946 interested in a couple of groups from a different server, you would be
947 better served by using the @code{gnus-group-browse-foreign-server}
948 command from the group buffer. It will let you have a look at what
949 groups are available, and you can subscribe to any of the groups you
950 want to. This also makes @file{.newsrc} maintenance much tidier.
951 @xref{Foreign Groups}.
953 @vindex gnus-secondary-select-methods
955 A slightly different approach to foreign groups is to set the
956 @code{gnus-secondary-select-methods} variable. The select methods
957 listed in this variable are in many ways just as native as the
958 @code{gnus-select-method} server. They will also be queried for active
959 files during startup (if that's required), and new newsgroups that
960 appear on these servers will be subscribed (or not) just as native
963 For instance, if you use the @code{nnmbox} backend to read you mail, you
964 would typically set this variable to
967 (setq gnus-secondary-select-methods '((nnmbox "")))
971 @section The First Time
972 @cindex first time usage
974 If no startup files exist, Gnus will try to determine what groups should
975 be subscribed by default.
977 @vindex gnus-default-subscribed-newsgroups
978 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
979 will subscribe you to just those groups in that list, leaving the rest
980 killed. Your system administrator should have set this variable to
983 Since she hasn't, Gnus will just subscribe you to a few randomly picked
984 groups (i.e., @samp{*.newusers}). (@dfn{Random} is here defined as
985 ``whatever Lars thinks you should read''.)
987 You'll also be subscribed to the Gnus documentation group, which should
988 help you with most common problems.
990 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
991 use the normal functions for handling new groups, and not do anything
994 @node The Server is Down
995 @section The Server is Down
996 @cindex server errors
998 If the default server is down, Gnus will understandably have some
999 problems starting. However, if you have some mail groups in addition to
1000 the news groups, you may want to start Gnus anyway.
1002 Gnus, being the trusting sort of program, will ask whether to proceed
1003 without a native select method if that server can't be contacted. This
1004 will happen whether the server doesn't actually exist (i.e., you have
1005 given the wrong address) or the server has just momentarily taken ill
1006 for some reason or other.
1008 If Gnus says ``nntp server on <your server> can't be opened. Continue?'',
1009 you do not want to continue unless you have some foreign groups that you
1010 want to read. Even if you don't, Gnus will let you continue, but you'll
1011 find it difficult to actually do anything in the group buffer. But,
1012 hey, that's your problem. Blllrph!
1014 @findex gnus-no-server
1016 If you know that the server is definitely down, or you just want to read
1017 your mail without bothering with the server at all, you can use the
1018 @code{gnus-no-server} command to start Gnus. That might come in handy
1019 if you're in a hurry as well.
1023 @section Slave Gnusiï
1026 You might want to run more than one Emacs with more than one Gnus at the
1027 same time. If you are using different @file{.newsrc} files (eg., if you
1028 are using the two different Gnusiï to read from two different servers),
1029 that is no problem whatsoever. You just do it.
1031 The problem appears when you want to run two Gnusiï that use the same
1032 @code{.newsrc} file.
1034 To work around that problem some, we here at the Think-Tank at the Gnus
1035 Towers have come up with a new concept: @dfn{Masters} and
1036 @dfn{servants}. (We have applied for a patent on this concept, and have
1037 taken out a copyright on those words. If you wish to use those words in
1038 conjunction with each other, you have to send $1 per usage instance to
1039 me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
1040 Applications}) will be much more expensive, of course.)
1042 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
1043 however you do it). Each subsequent slave Gnusiï should be started with
1044 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
1045 files, but some slave files that contains information only on what
1046 groups have been read in the slave session. When a master Gnus starts,
1047 it will read (and delete) these slave files, incorporating all
1048 information from all of them. (The slave files will be read in the
1049 sequence they were created, so the latest changes will have precedence.)
1051 Information from the slave files has, of course, presedence over the
1052 information in the normal (i. e., master) @code{.newsrc} file.
1055 @node Fetching a Group
1056 @section Fetching a Group
1058 @findex gnus-fetch-group
1059 It it sometime convenient to be able to just say ``I want to read this
1060 group and I don't care whether Gnus has been started or not''. This is
1061 perhaps more useful for people who write code than for users, but the
1062 command @code{gnus-fetch-group} provides this functionality in any
1063 case. It takes the group name as a paramenter.
1070 @vindex gnus-subscribe-newsgroup-method
1071 What Gnus does when it encounters a new group is determined by the
1072 @code{gnus-subscribe-newsgroup-method} variable.
1074 This variable should contain a function. Some handy pre-fab values
1079 @item gnus-subscribe-randomly
1080 @vindex gnus-subscribe-randomly
1081 Subscribe all new groups randomly.
1083 @item gnus-subscribe-alphabetically
1084 @vindex gnus-subscribe-alphabetically
1085 Subscribe all new groups alphabetically.
1087 @item gnus-subscribe-hierarchically
1088 @vindex gnus-subscribe-hierarchically
1089 Subscribe all new groups hierarchically.
1091 @item gnus-subscribe-interactively
1092 @vindex gnus-subscribe-interactively
1093 Subscribe new groups interactively. This means that Gnus will ask
1094 you about @strong{all} new groups.
1096 @item gnus-subscribe-killed
1097 @vindex gnus-subscribe-killed
1098 Kill all new groups.
1100 @item gnus-subscribe-zombies
1101 @vindex gnus-subscribe-zombies
1102 Make all new groups zombies. You can browse the zombies later (with
1103 @kbd{A z}) and either kill them all off properly, or subscribe to them.
1104 This is the default.
1107 @vindex gnus-subscribe-hierarchical-interactive
1108 A closely related variable is
1109 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
1110 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
1111 hierarchical fashion whether to subscribe to new groups or not. Gnus
1112 will ask you for each sub-hierarchy whether you want to descend the
1115 One common way to control which new newsgroups should be subscribed or
1116 ignored is to put an @dfn{options} line at the start of the
1117 @file{.newsrc} file. Here's an example:
1120 options -n !alt.all !rec.all sci.all
1123 @vindex gnus-subscribe-options-newsgroup-method
1124 This line obviously belongs to a serious-minded intellectual scientific
1125 person (or she may just be plain old boring), because it says that all
1126 groups that have names beginning with @samp{alt} and @samp{rec} should
1127 be ignored, and all groups with names beginning with @samp{sci} should
1128 be subscribed. Gnus will not use the normal subscription method for
1129 subscribing these groups.
1130 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
1131 variable defaults to @code{gnus-subscribe-alphabetically}.
1133 @vindex gnus-options-not-subscribe
1134 @vindex gnus-options-subscribe
1135 If you don't want to mess with your @file{.newsrc} file, you can just
1136 set the two variables @code{gnus-options-subscribe} and
1137 @code{gnus-options-not-subscribe}. These two variables do exactly the
1138 same as the @file{.newsrc} options -n trick. Both are regexps, and if
1139 the the new group matches the first, it will be unconditionally
1140 subscribed, and if it matches the latter, it will be ignored.
1142 @vindex gnus-auto-subscribed-groups
1143 Yet another variable that meddles here is
1144 @code{gnus-auto-subscribed-groups}. It works exactly like
1145 @code{gnus-options-subscribe}, and is therefore really superfluos, but I
1146 thought it would be nice to have two of these. This variable is more
1147 meant for setting some ground rules, while the other variable is used
1148 more for user fiddling. By default this variable makes all new groups
1149 that come from mail backends (@code{nnml}, @code{nnbabyl},
1150 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
1151 don't like that, just set this variable to @code{nil}.
1153 @vindex gnus-check-new-newsgroups
1154 If you are satisfied that you really never want to see any new groups,
1155 you could set @code{gnus-check-new-newsgroups} to @code{nil}. This will
1156 also save you some time at startup. Even if this variable is
1157 @code{nil}, you can always subscribe to the new groups just by pressing
1158 @kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
1159 is @code{t} by default.
1161 Gnus normally determines whether a group is new or not by comparing the
1162 list of groups from the active file(s) with the lists of subscribed and
1163 dead groups. This isn't a particularly fast method. If
1164 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
1165 server for new groups since the last time. This is both faster &
1166 cheaper. This also means that you can get rid of the list of killed
1167 groups altogether, so you may set @code{gnus-save-killed-list} to
1168 @code{nil}, which will save time both at startup, at exit, and all over.
1169 Saves disk space, too. Why isn't this the default, then?
1170 Unfortunately, not all servers support this function.
1172 I bet I know what you're thinking now: How do I find out whether my
1173 server supports @code{ask-server}? No? Good, because I don't have a
1174 fail-safe answer. I would suggest just setting this variable to
1175 @code{ask-server} and see whether any new groups appear after a few
1176 days. If they do, then it works. If they don't, then it doesn't work.
1177 I could write a function to make Gnus guess whether the server supports
1178 @code{ask-server}, but it would just be a guess. So I won't. You could
1179 @code{telnet} to the server and say @samp{HELP} and see whether it lists
1180 @samp{NEWGROUPS} among the commands it understands. If it does, then it
1181 might work. (But there are servers that lists @samp{NEWGROUPS} without
1182 supporting the function properly.)
1184 This variable can also be a list of select methods. If so, Gnus will
1185 issue an @code{ask-server} command to each of the select methods, and
1186 subscribe them (or not) using the normal methods. This might be handy
1187 if you are monitoring a few servers for new groups. A side effect is
1188 that startup will take much longer, so you can meditate while waiting.
1189 Use the mantra ``dingnusdingnusdingnus'' to achieve permanent happiness.
1192 @section Startup Files
1193 @cindex startup files
1196 Now, you all know about the @file{.newsrc} file. All subscription
1197 information is traditionally stored in this file.
1199 Things got a bit more complicated with @sc{gnus}. In addition to
1200 keeping the @file{.newsrc} file updated, it also used a file called
1201 @file{.newsrc.el} for storing all the information that didn't fit into
1202 the @file{.newsrc} file. (Actually, it duplicated everything in the
1203 @file{.newsrc} file.) @sc{gnus} would read whichever one of these files
1204 that were the most recently saved, which enabled people to swap between
1205 @sc{gnus} and other newsreaders.
1207 That was kinda silly, so Gnus went one better: In addition to the
1208 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
1209 @file{.newsrc.eld}. It will read whichever of these files that are most
1210 recent, but it will never write a @file{.newsrc.el} file.
1212 @vindex gnus-save-newsrc-file
1213 You can also turn off writing the @file{.newsrc} file by setting
1214 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
1215 the file and save some space, as well as making exit from Gnus faster.
1216 However, this will make it impossible to use other newsreaders than
1217 Gnus. But hey, who would want to, right?
1219 @vindex gnus-save-killed-list
1220 If @code{gnus-save-killed-list} is @code{nil}, Gnus will not save the
1221 list of killed groups to the startup file. This will save both time
1222 (when starting and quitting) and space (on disk). It will also means
1223 that Gnus has no record of what groups are new or old, so the automatic
1224 new groups subscription methods become meaningless. You should always
1225 set @code{gnus-check-new-newsgroups} to @code{nil} or @code{ask-server}
1226 if you set this variable to @code{nil} (@pxref{New Groups}).
1228 @vindex gnus-startup-file
1229 The @code{gnus-startup-file} variable says where the startup files are.
1230 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
1231 file being whatever that one is with a @samp{.eld} appended.
1233 @vindex gnus-save-newsrc-hook
1234 @vindex gnus-save-quick-newsrc-hook
1235 @vindex gnus-save-standard-newsrc-hook
1236 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
1237 files, while @code{gnus-save-quick-newsrc-hook} is called just before
1238 saving the @file{.newsrc.eld} file, and
1239 @code{gnus-save-standard-newsrc-hook} is called just before saving the
1240 @file{.newsrc} file. The latter two are commonly used to turn version
1241 control on or off. Version control is off by default when saving.
1245 @cindex dribble file
1248 Whenever you do something that changes the Gnus data (reading articles,
1249 catching up, killing/subscribing groups), the change is added to a
1250 special @dfn{dribble buffer}. This buffer is auto-saved the normal
1251 Emacs way. If your Emacs should crash before you have saved the
1252 @file{.newsrc} files, all changes you have made can be recovered from
1255 If Gnus detects this file at startup, it will ask the user whether to
1256 read it. The auto save file is deleted whenever the real startup file is
1259 @vindex gnus-use-dribble-file
1260 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
1261 maintain a dribble buffer. The default is @code{t}.
1263 @vindex gnus-dribble-directory
1264 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
1265 this variable is @code{nil}, which it is by default, Gnus will dribble
1266 into the same directory as the @file{.newsrc} file is located. (This is
1267 normally the user's home directory.)
1269 @node The Active File
1270 @section The Active File
1272 @cindex ignored groups
1274 When Gnus starts, or indeed whenever it tries to determine whether new
1275 articles have arrived, it reads the active file. This is a very large
1276 file that lists all the active groups and articles on the @sc{nntp}
1279 @vindex gnus-ignored-newsgroups
1280 Before examining the active file, Gnus deletes all lines that match the
1281 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
1282 any groups with bogus names, but you can use this variable to make Gnus
1283 ignore hierarchies you aren't ever interested in.
1285 @c @code{nil} by default, and will slow down active file handling somewhat
1286 @c if you set it to anything else.
1288 @vindex gnus-read-active-file
1290 The active file can be rather Huge, so if you have a slow network, you
1291 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
1292 reading the active file. This variable is @code{t} by default.
1294 Gnus will try to make do by just getting information on the groups
1295 that you actually subscribe to.
1297 Note that if you subscribe to lots and lots of groups, setting this
1298 variable to @code{nil} will probably make Gnus slower, not faster. At
1299 present, having this variable @code{nil} will slow Gnus down
1300 considerably, unless you read news over a 2400 baud modem.
1302 This variable can also have the value @code{some}. Gnus will then
1303 attempt to read active info only on the subscribed groups. On some
1304 servers this is quite fast (on sparkling, brand new INN servers that
1305 support the @samp{LIST ACTIVE group} command), on others this is not
1306 fast at all. In any case, @code{some} should be faster than @code{nil},
1307 and is certainly faster than @code{t} over slow lines.
1309 If this variable is @code{nil}, Gnus will as for group info in total
1310 lock-step, which isn't very fast. If it is @code{some} and you use an
1311 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
1312 read all the replies in one swoop. This will normally result in better
1313 performance, but if the server does not support the aforementioned
1314 @samp{LIST ACTIVE group} command, this isn't very nice to the server.
1316 In any case, if you use @code{some} or @code{nil}, you should kill all
1317 groups that you aren't interested in.
1319 @node Startup Variables
1320 @section Startup Variables
1324 @item gnus-load-hook
1325 @vindex gnus-load-hook
1326 A hook that is run while Gnus is being loaded. Note that this hook will
1327 normally be run just once in each Emacs session, no matter how many
1328 times you start Gnus.
1330 @item gnus-startup-hook
1331 @vindex gnus-startup-hook
1332 A hook that is run after starting up Gnus successfully.
1334 @item gnus-check-bogus-newsgroups
1335 @vindex gnus-check-bogus-newsgroups
1336 If non-@code{nil}, Gnus will check for and delete all bogus groups at
1337 startup. A @dfn{bogus group} is a group that you have in your
1338 @file{.newsrc} file, but doesn't exist on the news server. Checking for
1339 bogus groups isn't very quick, so to save time and resources, it's best
1340 to leave this option off, and instead do the checking for bogus groups
1341 once in a while from the group buffer (@pxref{Group Maintenance}).
1343 @item gnus-inhibit-startup-message
1344 @vindex gnus-inhibit-startup-message
1345 If non-@code{nil}, the startup message won't be displayed. That way,
1346 your boss might not notice that you are reading news instead of doing
1349 @item gnus-no-groups-message
1350 @vindex gnus-no-groups-message
1351 Message displayed by Gnus when no groups are available.
1354 @node The Group Buffer
1355 @chapter The Group Buffer
1356 @cindex group buffer
1358 The @dfn{group buffer} lists all (or parts) of the available groups. It
1359 is the first buffer shown when Gnus starts, and will never be killed as
1360 long as Gnus is active.
1363 * Group Buffer Format:: Information listed and how you can change it.
1364 * Group Maneuvering:: Commands for moving in the group buffer.
1365 * Selecting a Group:: Actually reading news.
1366 * Subscription Commands:: Unsubscribing, killing, subscribing.
1367 * Group Levels:: Levels? What are those, then?
1368 * Group Score:: A mechanism for finding out what groups you like.
1369 * Marking Groups:: You can mark groups for later processing.
1370 * Foreign Groups:: How to create foreign groups.
1371 * Group Parameters:: Each group may have different parameters set.
1372 * Listing Groups:: Gnus can list various subsets of the groups.
1373 * Sorting Groups:: Re-arrange the group order.
1374 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
1375 * Browse Foreign Server:: You can browse a server. See what if has to offer.
1376 * Exiting Gnus:: Stop reading news and get some work done.
1377 * Group Topics:: A folding group mode divided into topics.
1378 * Misc Group Stuff:: Other stuff that you can to do.
1381 @node Group Buffer Format
1382 @section Group Buffer Format
1383 @cindex group buffer format
1385 The default format of the group buffer is nice and dull, but you can
1386 make it as exciting and ugly as you feel like.
1388 Here's a couple of example group lines:
1391 25: news.announce.newusers
1392 * 0: alt.fan.andrea-dworkin
1397 You can see that there are 25 unread articles in
1398 @samp{news.announce.newusers}. There are no unread articles, but some
1399 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1400 asterisk at the beginning of the line?)
1402 @vindex gnus-group-line-format
1403 You can fuck that up to your heart's delight by fiddling with the
1404 @code{gnus-group-line-format} variable. This variable works along the
1405 lines of a @code{format} specification, which is pretty much the same as
1406 a @code{printf} specifications, for those of you who use (feh!) C.
1407 @xref{Formatting Variables}.
1409 The default value that produced those lines above is
1410 @samp{"%M%S%5y: %(%g%)\n"}.
1412 There should always be a colon on the line; the cursor always moves to
1413 the colon after performing an operation. Nothing else is required---not
1414 even the group name. All displayed text is just window dressing, and is
1415 never examined by Gnus. Gnus stores all real information it needs using
1418 (Note that if you make a really strange, wonderful, spreadsheet-like
1419 layout, everybody will believe you are hard at work with the accounting
1420 instead of wasting time reading news.)
1422 Here's a list of all available format characters:
1427 Only marked articles.
1430 Whether the group is subscribed.
1433 Level of subscribedness.
1436 Number of unread articles.
1439 Number of dormant articles.
1442 Number of ticked articles.
1445 Number of read articles.
1448 Total number of articles.
1451 Number of unread, unticked, non-dormant articles.
1454 Number of ticked and dormant articles.
1463 Newsgroup description.
1466 @samp{m} if moderated.
1469 @samp{(m)} if moderated.
1478 A string that looks like @samp{<%s:%n>} if a foreign select method is
1482 Indentation based on the level of the topic (@pxref{Group Topics}).
1485 @vindex gnus-group-uncollapsed-levels
1486 Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels}
1487 variable says how many levels to leave at the end of the group name.
1488 The default is @samp{1}.
1491 User defined specifier. The next character in the format string should
1492 be a letter. @sc{gnus} will call the function
1493 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1494 following @samp{%u}. The function will be passed the current headers as
1495 argument. The function should return a string, which will be inserted
1496 into the buffer just like information from any other specifier.
1500 All the ``number-of'' specs will be filled with an asterisk (@samp{*}) if
1501 no info is available---for instance, if it is a non-activated foreign
1502 group, or a bogus (or semi-bogus) native group.
1504 @vindex gnus-group-mode-line-format
1505 The mode line can be changed by setting
1506 (@code{gnus-group-mode-line-format}). It doesn't understand that many
1511 The native news server.
1513 The native select method.
1516 @node Group Maneuvering
1517 @section Group Maneuvering
1518 @cindex group movement
1520 All movement commands understand the numeric prefix and will behave as
1521 expected, hopefully.
1527 @findex gnus-group-next-unread-group
1528 Go to the next group that has unread articles
1529 (@code{gnus-group-next-unread-group}).
1536 @findex gnus-group-prev-unread-group
1537 Go to the previous group group that has unread articles
1538 (@code{gnus-group-prev-unread-group}).
1542 @findex gnus-group-next-group
1543 Go to the next group (@code{gnus-group-next-group}).
1547 @findex gnus-group-prev-group
1548 Go to the previous group (@code{gnus-group-prev-group}).
1552 @findex gnus-group-next-unread-group-same-level
1553 Go to the next unread group on the same level (or lower)
1554 (@code{gnus-group-next-unread-group-same-level}).
1558 @findex gnus-group-prev-unread-group-same-level
1559 Go to the previous unread group on the same level (or lower)
1560 (@code{gnus-group-prev-unread-group-same-level}).
1563 Three commands for jumping to groups:
1569 @findex gnus-group-jump-to-group
1570 Jump to a group (and make it visible if it isn't already)
1571 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1576 @findex gnus-group-best-unread-group
1577 Jump to the unread group with the lowest level
1578 (@code{gnus-group-best-unread-group}).
1582 @findex gnus-group-first-unread-group
1583 Jump to the first group with unread articles
1584 (@code{gnus-group-first-unread-group}).
1587 @vindex gnus-group-goto-unread
1588 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1589 commands will move to the next group, not the next unread group. Even
1590 the commands that say they move to the next unread group. The default
1594 @node Selecting a Group
1595 @section Selecting a Group
1596 @cindex group selection
1601 @kindex SPACE (Group)
1602 @findex gnus-group-read-group
1603 Select the current group, switch to the summary buffer and display the
1604 first unread article (@code{gnus-group-read-group}). If there are no
1605 unread articles in the group, or if you give a non-numerical prefix to
1606 this command, Gnus will offer to fetch all the old articles in this
1607 group from the server. If you give a numerical prefix @var{N}, Gnus
1608 will fetch @var{N} number of articles. If @var{N} is positive, fetch
1609 the @var{N} newest articles, if @var{N} is negative, fetch the
1610 @var{abs(N)} oldest articles.
1614 @findex gnus-group-select-group
1615 Select the current group and switch to the summary buffer
1616 (@code{gnus-group-select-group}). Takes the same arguments as
1617 @code{gnus-group-read-group}---the only difference is that this command
1618 does not display the first unread article automatically upon group
1622 @kindex M-RET (Group)
1623 @findex gnus-group-quick-select-group
1624 This does the same as the command above, but tries to do it with the
1625 minimum amount off fuzz (@code{gnus-group-quick-select-group}). No
1626 scoring/killing will be performed, there will be no highlights and no
1627 expunging. This might be useful if you're in a real hurry and have to
1628 enter some humongous groups.
1631 @kindex M-RET (Group)
1632 @findex gnus-group-visible-select-group
1633 This is yet one more command that does the same as the one above, but
1634 this one does it without expunging and hiding dormants
1635 (@code{gnus-group-visible-select-group}).
1639 @findex gnus-group-catchup-current
1640 Mark all unticked articles in this group as read
1641 (@code{gnus-group-catchup-current}).
1645 @findex gnus-group-catchup-current-all
1646 Mark all articles in this group, even the ticked ones, as read
1647 (@code{gnus-group-catchup-current-all}).
1650 @vindex gnus-large-newsgroup
1651 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1652 to be a big group. This is 200 by default. If the group has more
1653 unread articles than this, Gnus will query the user before entering the
1654 group. The user can then specify how many articles should be fetched
1655 from the server. If the user specifies a negative number (@samp{-n}),
1656 the @samp{n} oldest articles will be fetched. If it is positive, the
1657 @samp{n} articles that have arrived most recently will be fetched.
1659 @vindex gnus-select-group-hook
1660 @vindex gnus-auto-select-first
1661 @code{gnus-auto-select-first} control whether any articles are selected
1662 automatically when entering a group.
1667 Don't select any articles when entering the group. Just display the
1668 full summary buffer.
1671 Select the first unread article when entering the group.
1674 Select the most high-scored article in the group when entering the
1678 If you want to prevent automatic selection in some group (say, in a
1679 binary group with Huge articles) you can set this variable to @code{nil}
1680 in @code{gnus-select-group-hook}, which is called when a group is
1683 @findex gnus-thread-sort-by-total-score
1684 @findex gnus-thread-sort-by-date
1685 @findex gnus-thread-sort-by-score
1686 @findex gnus-thread-sort-by-subject
1687 @findex gnus-thread-sort-by-author
1688 @findex gnus-thread-sort-by-number
1689 @vindex gnus-thread-sort-functions
1690 If you are using a threaded summary display, you can sort the threads by
1691 setting @code{gnus-thread-sort-functions}, which is a list of functions.
1692 By default, sorting is done on article numbers. Ready-made sorting
1693 predicate functions include @code{gnus-thread-sort-by-number},
1694 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
1695 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
1696 @code{gnus-thread-sort-by-total-score}.
1698 Each function takes two threads and return non-@code{nil} if the first
1699 thread should be sorted before the other. Note that sorting really is
1700 normally done by looking only at the roots of each thread. If you use
1701 more than one function, the primary sort key should be the last function
1702 in the list. You should probably always include
1703 @code{gnus-thread-sort-by-number} in the list of sorting
1704 functions---preferably first. This will ensure that threads that are
1705 equal with respect to the other sort criteria will be displayed in
1706 ascending article order.
1708 If you would like to sort by score, then by subject, and finally by
1709 number, you could do something like:
1712 (setq gnus-thread-sort-functions
1713 '(gnus-thread-sort-by-number
1714 gnus-thread-sort-by-subject
1715 gnus-thread-sort-by-score))
1718 The threads that have highest score will be displayed first in the
1719 summary buffer. When threads have the same score, they will be sorted
1720 alphabetically. The threads that have the same score and the same
1721 subject will be sorted by number, which is (normally) the sequence in
1722 which the articles arrived.
1724 If you want to sort by score and then reverse arrival order, you could
1728 (setq gnus-thread-sort-functions
1730 (not (gnus-thread-sort-by-number t1 t2)))
1731 gnus-thread-sort-by-score))
1734 @vindex gnus-thread-score-function
1735 The function in the @code{gnus-thread-score-function} variable (default
1736 @code{+}) is used for calculating the total score of a thread. Useful
1737 functions might be @code{max}, @code{min}, or squared means, or whatever
1740 @findex gnus-article-sort-functions
1741 @findex gnus-article-sort-by-date
1742 @findex gnus-article-sort-by-score
1743 @findex gnus-article-sort-by-subject
1744 @findex gnus-article-sort-by-author
1745 @findex gnus-article-sort-by-number
1746 If you are using an unthreaded display for some strange reason or other,
1747 you have to fiddle with the @code{gnus-article-sort-functions} variable.
1748 It is very similar to the @code{gnus-thread-sort-functions}, except that
1749 is uses slightly different functions for article comparison. Available
1750 sorting predicate functions are @code{gnus-article-sort-by-number},
1751 @code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
1752 @code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
1754 If you want to sort an unthreaded summary display by subject, you could
1758 (setq gnus-article-sort-functions
1759 '(gnus-article-sort-by-number
1760 gnus-article-sort-by-subject))
1764 @node Subscription Commands
1765 @section Subscription Commands
1774 @findex gnus-group-unsubscribe-current-group
1775 Toggle subscription to the current group
1776 (@code{gnus-group-unsubscribe-current-group}).
1782 @findex gnus-group-unsubscribe-group
1783 Prompt for a group to subscribe, and then subscribe it. If it was
1784 subscribed already, unsubscribe it instead
1785 (@code{gnus-group-unsubscribe-group}).
1791 @findex gnus-group-kill-group
1792 Kill the current group (@code{gnus-group-kill-group}).
1798 @findex gnus-group-yank-group
1799 Yank the last killed group (@code{gnus-group-yank-group}).
1805 @findex gnus-group-kill-region
1806 Kill all groups in the region (@code{gnus-group-kill-region}).
1810 @findex gnus-group-kill-all-zombies
1811 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1814 @kindex S C-k (Group)
1815 @findex gnus-group-kill-level
1816 Kill all groups on a certain level (@code{gnus-group-kill-level}).
1817 These groups can't be yanked back after killing, so this command should
1818 be used with some caution. The only thing where this command comes in
1819 really handy is when you have a @file{.newsrc} with lots of unsubscribed
1820 groups that you want to get rid off. @kbd{S C-k} on level @code{7} will
1821 kill off all unsubscribed groups that do not have message numbers in the
1822 @file{.newsrc} file.
1826 Also @xref{Group Levels}.
1829 @section Group Levels
1832 All groups have a level of @dfn{subscribedness}. For instance, if a
1833 group is on level 2, it is more subscribed than a group on level 5. You
1834 can ask Gnus to just list groups on a given level or lower
1835 (@pxref{Listing Groups}), or to just check for new articles in groups on
1836 a given level or lower (@pxref{Misc Group Stuff}).
1842 @findex gnus-group-set-current-level
1843 Set the level of the current group. If a numeric prefix is given, the
1844 next @var{n} groups will have their levels set. The user will be
1845 prompted for a level.
1848 @vindex gnus-level-killed
1849 @vindex gnus-level-zombie
1850 @vindex gnus-level-unsubscribed
1851 @vindex gnus-level-subscribed
1852 Gnus considers groups on between levels 1 and
1853 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
1854 @code{gnus-level-subscribed} (exclusive) and
1855 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
1856 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
1857 (default 8) and @code{gnus-level-killed} to be killed (default 9),
1858 completely dead. Gnus treats subscribed and unsubscribed groups exactly
1859 the same, but zombie and killed groups have no information on what
1860 articles you have read, etc, stored. This distinction between dead and
1861 living groups isn't done because it is nice or clever, it is done purely
1862 for reasons of efficiency.
1864 It is recommended that you keep all your mail groups (if any) on quite
1865 low levels (eg. 1 or 2).
1867 If you want to play with the level variables, you should show some care.
1868 Set them once, and don't touch them ever again. Better yet, don't touch
1869 them at all unless you know exactly what you're doing.
1871 @vindex gnus-level-default-unsubscribed
1872 @vindex gnus-level-default-subscribed
1873 Two closely related variables are @code{gnus-level-default-subscribed}
1874 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
1875 which are the levels that new groups will be put on if they are
1876 (un)subscribed. These two variables should, of course, be inside the
1877 relevant legal ranges.
1879 @vindex gnus-keep-same-level
1880 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1881 will only move to groups that are of the same level (or lower). In
1882 particular, going from the last article in one group to the next group
1883 will go to the next group of the same level (or lower). This might be
1884 handy if you want to read the most important groups before you read the
1887 @vindex gnus-group-default-list-level
1888 All groups with a level less than or equal to
1889 @code{gnus-group-default-list-level} will be listed in the group buffer
1892 @vindex gnus-group-list-inactive-groups
1893 If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
1894 groups will be listed along with the unread groups. This variable is
1895 @code{t} by default. If it is @code{nil}, inactive groups won't be
1898 @vindex gnus-group-use-permament-levels
1899 If @code{gnus-group-use-permament-levels} is non-@code{nil}, once you
1900 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1901 use this level as the ``work'' level.
1903 @vindex gnus-activate-level
1904 Gnus will normally just activate groups that are on level
1905 @code{gnus-activate-level} or less. If you don't want to activate
1906 unsubscribed groups, for instance, you might set this variable to
1911 @section Group Score
1914 You would normally keep important groups on high levels, but that scheme
1915 is somewhat restrictive. Don't you wish you could have Gnus sort the
1916 group buffer according to how often you read groups, perhaps? Within
1919 This is what @dfn{group score} is for. You can assign a score to each
1920 group. You can then sort the group buffer based on this score.
1921 Alternatively, you can sort on score and then level. (Taken together,
1922 the level and the score is called the @dfn{rank} of the group. A group
1923 that is on level 4 and has a score of 1 has a higher rank than a group
1924 on level 5 that has a score of 300. (The level is the most significant
1925 part and the score is the least significant part.)
1927 @findex gnus-summary-bubble-group
1928 If you want groups you read often to get higher scores than groups you
1929 read seldom you can add the @code{gnus-summary-bubble-group} function to
1930 the @code{gnus-summary-exit-hook} hook. This will result (after
1931 sorting) in a bubbling sort of action. If you want to see that in
1932 action after each summary exit, you can add
1933 @code{gnus-group-sort-groups-by-rank} or
1934 @code{gnus-group-sort-groups-by-score} to the same hook, but that will
1935 slow things down somewhat.
1938 @node Marking Groups
1939 @section Marking Groups
1940 @cindex marking groups
1942 If you want to perform some command on several groups, and they appear
1943 subsequently in the group buffer, you would normally just give a
1944 numerical prefix to the command. Most group commands will then do your
1945 bidding on those groups.
1947 However, if the groups are not in sequential order, you can still
1948 perform a command on several groups. You simply mark the groups first
1949 with the process mark and then execute the command.
1957 @findex gnus-group-mark-group
1958 Set the mark on the current group (@code{gnus-group-mark-group}).
1964 @findex gnus-group-unmark-group
1965 Remove the mark from the current group
1966 (@code{gnus-group-unmark-group}).
1970 @findex gnus-group-unmark-all-groups
1971 Remove the mark from all groups (@code{gnus-group-unmark-all-groups}).
1975 @findex gnus-group-mark-region
1976 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1980 @findex gnus-group-mark-buffer
1981 Mark all groups in the buffer (@code{gnus-group-mark-buffer}).
1985 @findex gnus-group-mark-regexp
1986 Mark all groups that match some regular expression
1987 (@code{gnus-group-mark-regexp}).
1990 Also @xref{Process/Prefix}.
1992 If you want to execute some command on all groups that have been marked
1993 with the process mark, you can use the @kbd{M-&}
1994 (@code{gnus-group-universal-argument}) command. It will prompt you for
1995 the command to be executed.
1999 @node Foreign Groups
2000 @section Foreign Groups
2001 @cindex foreign groups
2003 A @dfn{foreign group} is a group that is not read by the usual (or
2004 default) means. It could be, for instance, a group from a different
2005 @sc{nntp} server, it could be a virtual group, or it could be your own
2006 personal mail group.
2008 A foreign group (or any group, really) is specified by a @dfn{name} and
2009 a @dfn{select method}. To take the latter first, a select method is a
2010 list where the first element says what backend to use (eg. @code{nntp},
2011 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
2012 name}. There may be additional elements in the select method, where the
2013 value may have special meaning for the backend in question.
2015 One could say that a select method defines a @dfn{virtual server}---so
2016 we do just that (@pxref{The Server Buffer}).
2018 The @dfn{name} of the group is the name the backend will recognize the
2021 For instance, the group @samp{soc.motss} on the @sc{nntp} server
2022 @samp{some.where.edu} will have the name @samp{soc.motss} and select
2023 method @code{(nntp "some.where.edu")}. Gnus will call this group, in
2024 all circumstances, @samp{nntp+some.where.edu:soc.motss}, even though the
2025 @code{nntp} backend just knows this group as @samp{soc.motss}.
2027 Here are some commands for making and editing general foreign groups,
2028 and some commands to ease the creation of some special-purpose groups:
2034 @findex gnus-group-make-group
2035 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
2036 for a name, a method and possibly an @dfn{address}. For an easier way
2037 to subscribe to @sc{nntp} groups, @xref{Browse Foreign Server}.
2041 @findex gnus-group-rename-group
2042 Rename the current group to something else
2043 (@code{gnus-group-rename-group}). This is legal only on some groups --
2044 mail groups mostly. This command might very well be quite slow on some
2049 @findex gnus-group-edit-group-method
2050 Enter a buffer where you can edit the select method of the current
2051 group (@code{gnus-group-edit-group-method}).
2055 @findex gnus-group-edit-group-parameters
2056 Enter a buffer where you can edit the group parameters
2057 (@code{gnus-group-edit-group-parameters}).
2061 @findex gnus-group-edit-group
2062 Enter a buffer where you can edit the group info
2063 (@code{gnus-group-edit-group}).
2067 @findex gnus-group-make-directory-group
2068 Make a directory group. You will be prompted for a directory name
2069 (@code{gnus-group-make-directory-group}).
2073 @findex gnus-group-make-help-group
2074 Make the Gnus help group (@code{gnus-group-make-help-group}).
2078 @findex gnus-group-make-archive-group
2079 @vindex gnus-group-archive-directory
2080 @vindex gnus-group-recent-archive-directory
2081 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
2082 default a group pointing to the most recent articles will be created
2083 (@code{gnus-group-recent-archibe-directory}), but given a prefix, a full
2084 group will be created from from @code{gnus-group-archive-directory}.
2088 @findex gnus-group-make-kiboze-group
2089 Make a kiboze group. You will be prompted for a name, for a regexp to
2090 match groups to be ``included'' in the kiboze group, and a series of
2091 strings to match on headers (@code{gnus-group-make-kiboze-group}).
2095 @findex gnus-group-enter-directory
2096 Read a random directory as if with were a newsgroup with the
2097 @code{nneething} backend (@code{gnus-group-enter-directory}).
2101 @findex gnus-group-make-doc-group
2102 Make a group based on some file or other
2103 (@code{gnus-group-make-doc-group}). If you give a prefix to this
2104 command, you will be prompted for a file name and a file type.
2105 Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
2106 @code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs}, and
2107 @code{forward}. If you run this command without a prefix, Gnus will
2108 guess at the file type.
2111 @kindex G DEL (Group)
2112 @findex gnus-group-delete-group
2113 This function will delete the current group
2114 (@code{gnus-group-delete-group}). If given a prefix, this function will
2115 actually delete all the articles in the group, and forcibly remove the
2116 group itself from the face of the Earth. Use a prefix only if you are
2117 sure of what you are doing.
2121 @findex gnus-group-make-empty-virtual
2122 Make a new, fresh, empty @code{nnvirtual} group
2123 (@code{gnus-group-make-empty-virtual}).
2127 @findex gnus-group-add-to-virtual
2128 Add the current group to an @code{nnvirtual} group
2129 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
2132 The different methods all have their peculiarities, of course.
2135 * nntp:: Reading news from a different @sc{nntp} server.
2136 * nnspool:: Reading news from the local spool.
2137 * nnvirtual:: Combining articles from many groups.
2138 * nnkiboze:: Looking through parts of the newsfeed for articles.
2139 * nndir:: You can read a directory as if it was a newsgroup.
2140 * nneething:: Dired? Who needs dired?
2141 * nndoc:: Single files can be the basis of a group.
2142 * SOUP:: Reading @sc{SOUP} packets ``offline''.
2143 * Reading Mail:: Reading your personal mail with Gnus.
2146 @vindex gnus-activate-foreign-newsgroups
2147 If the @code{gnus-activate-foreign-newsgroups} is a positive number,
2148 Gnus will check all foreign groups with this level or lower at startup.
2149 This might take quite a while, especially if you subscribe to lots of
2150 groups from different @sc{nntp} servers.
2156 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
2157 You just specify @code{nntp} as method and the address of the @sc{nntp}
2158 server as the, uhm, address.
2160 If the @sc{nntp} server is located at a non-standard port, setting the
2161 third element of the select method to this port number should allow you
2162 to connect to the right port. You'll have to edit the group info for
2163 that (@pxref{Foreign Groups}).
2165 The name of the foreign group can be the same as a native group. In
2166 fact, you can subscribe to the same group from as many different servers
2167 you feel like. There will be no name collisions.
2169 The following variables can be used to create a virtual @code{nntp}
2174 @item nntp-server-opened-hook
2175 @vindex nntp-server-opened-hook
2176 @cindex @sc{mode reader}
2178 @cindex authentification
2179 @cindex nntp authentification
2180 @findex nntp-send-authinfo
2181 @findex nntp-send-mode-reader
2182 @code{nntp-server-opened-hook} is run after a connection has been made.
2183 It can be used to send commands to the @sc{nntp} server after it has
2184 been contacted. By default is sends the command @samp{MODE READER} to
2185 the server with the @code{nntp-send-mode-reader} function. Another
2186 popular function is @code{nntp-send-authinfo}, which will prompt you for
2187 an @sc{nntp} password and stuff.
2189 @item nntp-server-action-alist
2190 @vindex nntp-server-action-alist
2191 This is an list of regexps to match on server types and actions to be
2192 taken when matches are made. For instance, if you want Gnus to beep
2193 every time you connect to innd, you could say something like:
2196 (setq nntp-server-action-alist
2200 You probably don't want to do that, though.
2202 The default value is
2205 '(("nntpd 1\\.5\\.11t"
2206 (remove-hook 'nntp-server-opened-hook nntp-send-mode-reader)))
2209 This ensures that Gnus doesn't send the @samp{MODE READER} command to
2210 nntpd 1.5.11t, since that command chokes that server, I've been told.
2212 @item nntp-maximum-request
2213 @vindex nntp-maximum-request
2214 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
2215 will collect headers by sending a series of @code{head} commands. To
2216 speed things up, the backend sends lots of these commands without
2217 waiting for reply, and then reads all the replies. This is controlled
2218 by the @code{nntp-maximum-request} variable, and is 400 by default. If
2219 your network is buggy, you should set this to 1.
2221 @item nntp-connection-timeout
2222 @vindex nntp-connection-timeout
2223 If you have lots of foreign @code{nntp} groups that you connect to
2224 regularly, you're sure to have problems with @sc{nntp} servers not
2225 responding properly, or being too loaded to reply within reasonable
2226 time. This is can lead to awkward problems, which can be helped
2227 somewhat by setting @code{nntp-connection-timeout}. This is an integer
2228 that says how many seconds the @code{nntp} backend should wait for a
2229 connection before giving up. If it is @code{nil}, which is the default,
2230 no timeouts are done.
2232 @item nntp-server-hook
2233 @vindex nntp-server-hook
2234 This hook is run as the last step when connecting to an @sc{nntp}
2237 @c @findex nntp-open-rlogin
2238 @c @findex nntp-open-network-stream
2239 @c @item nntp-open-server-function
2240 @c @vindex nntp-open-server-function
2241 @c This function is used to connect to the remote system. Two pre-made
2242 @c functions are @code{nntp-open-network-stream}, which is the default, and
2243 @c simply connects to some port or other on the remote system. The other
2244 @c is @code{nntp-open-rlogin}, which does an rlogin on the remote system,
2245 @c and then does a telnet to the @sc{nntp} server available there.
2247 @c @item nntp-rlogin-parameters
2248 @c @vindex nntp-rlogin-parameters
2249 @c If you use @code{nntp-open-rlogin} as the
2250 @c @code{nntp-open-server-function}, this list will be used as the
2251 @c parameter list given to @code{rsh}.
2253 @c @item nntp-rlogin-user-name
2254 @c @vindex nntp-rlogin-user-name
2255 @c User name on the remote system when using the @code{rlogin} connect
2259 @vindex nntp-address
2260 The address of the remote system running the @sc{nntp} server.
2262 @item nntp-port-number
2263 @vindex nntp-port-number
2264 Port number to connect to when using the @code{nntp-open-network-stream}
2267 @item nntp-buggy-select
2268 @vindex nntp-buggy-select
2269 Set this to non-@code{nil} if your select routine is buggy.
2271 @item nntp-nov-is-evil
2272 @vindex nntp-nov-is-evil
2273 If the @sc{nntp} server does not support @sc{nov}, you could set this
2274 variable to @code{t}, but @code{nntp} usually checks whether @sc{nov}
2275 can be used automatically.
2277 @item nntp-xover-commands
2278 @vindex nntp-xover-commands
2279 List of strings that are used as commands to fetch @sc{nov} lines from a
2280 server. The default value of this variable is @code{("XOVER"
2284 @vindex nntp-nov-gap
2285 @code{nntp} normally sends just one big request for @sc{nov} lines to
2286 the server. The server responds with one huge list of lines. However,
2287 if you have read articles 2-5000 in the group, and only want to read
2288 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
2289 lines that you do not want, and will not use. This variable says how
2290 big a gap between two consecutive articles is allowed to be before the
2291 @code{XOVER} request is split into several request. Note that if your
2292 network is fast, setting this variable to a really small number means
2293 that fetching will probably be slower. If this variable is @code{nil},
2294 @code{nntp} will never split requests.
2296 @item nntp-prepare-server-hook
2297 @vindex nntp-prepare-server-hook
2298 A hook run before attempting to connect to an @sc{nntp} server.
2300 @item nntp-async-number
2301 @vindex nntp-async-number
2302 How many articles should be pre-fetched when in asynchronous mode. If
2303 this variable is @code{t}, @code{nntp} will pre-fetch all the articles
2304 that it can without bound. If it is @code{nil}, no pre-fetching will be
2307 @item nntp-warn-about-losing-connection
2308 @vindex nntp-warn-about-losing-connection
2309 If this variable is non-@code{nil}, some noise will be made when a
2310 server closes connection.
2317 @cindex @code{nnspool}
2320 Subscribing to a foreign group from the local spool is extremely easy,
2321 and might be useful, for instance, to speed up reading groups like
2322 @samp{alt.binaries.pictures.furniture}.
2324 Anyways, you just specify @code{nnspool} as the method and @samp{""} (or
2325 anything else) as the address.
2327 If you have access to a local spool, you should probably use that as the
2328 native select method (@pxref{Finding the News}). It is normally faster
2329 than using an @code{nntp} select method, but might not be. It depends.
2330 You just have to try to find out what's best at your site.
2334 @item nnspool-inews-program
2335 @vindex nnspool-inews-program
2336 Program used to post an article.
2338 @item nnspool-inews-switches
2339 @vindex nnspool-inews-switches
2340 Parameters given to the inews program when posting an article.
2342 @item nnspool-spool-directory
2343 @vindex nnspool-spool-directory
2344 Where @code{nnspool} looks for the articles. This is normally
2345 @file{/usr/spool/news/}.
2347 @item nnspool-nov-directory
2348 @vindex nnspool-nov-directory
2349 Where @code{nnspool} will look for @sc{nov} files. This is normally
2350 @file{/usr/spool/news/over.view/}.
2352 @item nnspool-lib-dir
2353 @vindex nnspool-lib-dir
2354 Where the news lib dir is (@file{/usr/lib/news/} by default).
2356 @item nnspool-active-file
2357 @vindex nnspool-active-file
2358 The path of the active file.
2360 @item nnspool-newsgroups-file
2361 @vindex nnspool-newsgroups-file
2362 The path of the group descriptions file.
2364 @item nnspool-history-file
2365 @vindex nnspool-history-file
2366 The path of the news history file.
2368 @item nnspool-active-times-file
2369 @vindex nnspool-active-times-file
2370 The path of the active date file.
2372 @item nnspool-nov-is-evil
2373 @vindex nnspool-nov-is-evil
2374 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
2377 @item nnspool-sift-nov-with-sed
2378 @vindex nnspool-sift-nov-with-sed
2379 If non-@code{nil}, which is the default, use @code{sed} to get the
2380 relevant portion from the overview file. If nil, @code{nnspool} will
2381 load the entire file into a buffer and process it there.
2387 @subsection nnvirtual
2388 @cindex @code{nnvirtual}
2389 @cindex virtual groups
2391 An @dfn{nnvirtual group} is really nothing more than a collection of
2394 For instance, if you are tired of reading many small group, you can
2395 put them all in one big group, and then grow tired of reading one
2396 big, unwieldy group. The joys of computing!
2398 You specify @code{nnvirtual} as the method. The address should be a
2399 regexp to match component groups.
2401 All marks in the virtual group will stick to the articles in the
2402 component groups. So if you tick an article in a virtual group, the
2403 article will also be ticked in the component group from whence it came.
2404 (And vice versa---marks from the component groups will also be shown in
2407 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
2408 newsgroups into one, big, happy newsgroup:
2411 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
2414 The component groups can be native or foreign; everything should work
2415 smoothly, but if your computer explodes, it was probably my fault.
2417 Collecting the same group from several servers might actually be a good
2418 idea if users have set the Distribution header to limit distribution.
2419 If you would like to read @samp{soc.motss} both from a server in Japan
2420 and a server in Norway, you could use the following as the group regexp:
2423 "^nntp+some.server.jp:soc.motss$\\|^nntp+some.server.no:soc.motss$"
2426 This should work kinda smoothly---all articles from both groups should
2427 end up in this one, and there should be no duplicates. Threading (and
2428 the rest) will still work as usual, but there might be problems with the
2429 sequence of articles. Sorting on date might be an option here
2430 (@pxref{Selecting a Group}.
2432 One limitation, however---all groups that are included in a virtual
2433 group has to be alive (i.e., subscribed or unsubscribed). Killed or
2434 zombie groups can't be component groups for @code{nnvirtual} groups.
2436 @vindex nnvirtual-always-rescan
2437 If the @code{nnvirtual-always-rescan} is non-@code{nil},
2438 @code{nnvirtual} will always scan groups for unread articles when
2439 entering a virtual group. If this variable is @code{nil} (which is the
2440 default) and you read articles in a component group after the virtual
2441 group has been activated, the read articles from the component group
2442 will show up when you enter the virtual group. You'll also see this
2443 effect if you have two virtual groups that contain the same component
2444 group. If that's the case, you should set this variable to @code{t}.
2445 Or you can just tap @code{M-g} on the virtual group every time before
2446 you enter it---it'll have much the same effect.
2450 @subsection nnkiboze
2451 @cindex @code{nnkiboze}
2454 @dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of)
2455 the news feed''. @code{nnkiboze} is a backend that will do this for you. Oh
2456 joy! Now you can grind any @sc{nntp} server down to a halt with useless
2457 requests! Oh happiness!
2459 The address field of the @code{nnkiboze} method is, as with
2460 @code{nnvirtual}, a regexp to match groups to be ``included'' in the
2461 @code{nnkiboze} group. There most similarities between @code{nnkiboze}
2462 and @code{nnvirtual} ends.
2464 In addition to this regexp detailing component groups, an @code{nnkiboze} group
2465 must have a score file to say what articles that are to be included in
2466 the group (@pxref{Scoring}).
2468 @kindex M-x nnkiboze-generate-groups
2469 @findex nnkiboze-generate-groups
2470 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
2471 @code{nnkiboze} groups you want to have. This command will take time. Lots of
2472 time. Oodles and oodles of time. Gnus has to fetch the headers from
2473 all the articles in all the components groups and run them through the
2474 scoring process to determine if there are any articles in the groups
2475 that are to be part of the @code{nnkiboze} groups.
2477 Please limit the number of component groups by using restrictive
2478 regexps. Otherwise your sysadmin may become annoyed with you, and the
2479 @sc{nntp} site may throw you off and never let you back in again.
2480 Stranger things have happened.
2482 @code{nnkiboze} component groups do not have to be alive---they can be dead,
2483 and they can be foreign. No restrictions.
2485 @vindex nnkiboze-directory
2486 The generation of an @code{nnkiboze} group means writing two files in
2487 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
2488 contains the @sc{nov} header lines for all the articles in the group,
2489 and the other is an additional @file{.newsrc} file to store information
2490 on what groups that have been searched through to find component
2493 Articles that are marked as read in the @code{nnkiboze} group will have their
2494 @sc{nov} lines removed from the @sc{nov} file.
2499 @cindex @code{nndir}
2500 @cindex directory groups
2502 If you have a directory that has lots of articles in separate files in
2503 it, you might treat it as a newsgroup. The files have to have numerical
2506 This might be an opportune moment to mention @code{ange-ftp}, that most
2507 wonderful of all wonderful Emacs packages. When I wrote @code{nndir}, I
2508 didn't think much about it---a backend to read directories. Big deal.
2510 @code{ange-ftp} changes that picture dramatically. For instance, if you
2511 enter @file{"/ftp@@sina.tcamc.uh.edu:/pub/emacs/ding-list/"} as the the
2512 directory name, ange-ftp will actually allow you to read this directory
2513 over at @samp{sina} as a newsgroup. Distributed news ahoy!
2515 @code{nndir} will use @sc{nov} files if they are present.
2517 @code{nndir} is a ``read-only'' backend---you can't delete or expire
2518 articles with this method. You can use @code{nnmh} or @code{nnml} for
2519 whatever you use @code{nndir} for, so you could switch to any of those
2520 methods if you feel the need to have a non-read-only @code{nndir}.
2524 @subsection nneething
2525 @cindex @code{nneething}
2527 From the @code{nndir} backend (which reads a single spool-like
2528 directory), it's just a hop and a skip to @code{nneething}, which
2529 pretends that any random directory is a newsgroup. Strange, but true.
2531 When @code{nneething} is presented with a directory, it will scan this
2532 directory and assign article numbers to each file. When you enter such a
2533 group, @code{nneething} must create ``headers'' that Gnus can use. After
2534 all, Gnus is a newsreader, in case you're forgetting. @code{nneething}
2535 does this in a two-step process. First, it snoops each file in question.
2536 If the file looks like an article (i.e., the first few lines look like
2537 headers), it will use this as the head. If this is just some random file
2538 without a head (eg. a C source file), @code{nneething} will cobble up a
2539 header out of thin air. It will use file ownership, name and date and do
2540 whatever it can with these elements.
2542 All this should happen automatically for you, and you will be presented
2543 with something that looks very much like a newsgroup. Totally like a
2544 newsgroup, to be precise. If you select an article, it will be displayed
2545 in the article buffer, just as usual.
2547 If you select a line that represents a directory, Gnus will pop you into
2548 a new summary buffer for this @code{nneething} group. And so on. You can
2549 traverse the entire disk this way, if you feel like, but remember that
2550 Gnus is not dired, really, and does not intend to be, either.
2552 There are two overall modes to this action---ephemeral or solid. When
2553 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
2554 will not store information on what files you have read, and what files
2555 are new, and so on. If you create a solid @code{nneething} group the
2556 normal way with @kbd{G m}, Gnus will store a mapping table between
2557 article numbers and file names, and you can treat this group like any
2558 other groups. When you activate a solid @code{nneething} group, you will
2559 be told how many unread articles it contains, etc., etc.
2564 @item nneething-map-file-directory
2565 @vindex nneething-map-file-directory
2566 All the mapping files for solid @code{nneething} groups will be stored
2567 in this directory, which defaults to @file{~/.nneething/}.
2569 @item nneething-exclude-files
2570 @vindex nneething-exclude-files
2571 All files that match this regexp will be ignored. Nice to use to exclude
2572 auto-save files and the like, which is what it does by default.
2574 @item nneething-map-file
2575 @vindex nneething-map-file
2576 Name of the map files.
2582 @cindex @code{nndoc}
2583 @cindex documentation group
2586 @code{nndoc} is a cute little thing that will let you read a single file
2587 as a newsgroup. Several files types are supported:
2594 The babyl (rmail) mail box.
2599 The standard Unix mbox file.
2601 @cindex MMDF mail box
2603 The MMDF mail box format.
2606 Several news articles appended into a file.
2609 @cindex rnews batch files
2610 The rnews batch transport format.
2611 @cindex forwarded messages
2620 @cindex RFC 1153 digest
2621 @cindex RFC 341 digest
2622 MIME (RFC 1341) digest format.
2624 @item standard-digest
2625 The standard (RFC 1153) digest format.
2628 Non-standard digest format---matches most things, but does it badly.
2631 You can also use the special ``file type'' @code{guess}, which means that
2632 @code{nndoc} will try to guess what file type it is looking at.
2633 @code{digest} means that @code{nndoc} should guess what digest type the
2636 @code{nndoc} will not try to change the file or insert any extra headers into
2637 it---it will simply, like, let you use the file as the basis for a
2638 group. And that's it.
2640 If you have some old archived articles that you want to insert into your
2641 new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
2642 that. Say you have an old @file{RMAIL} file with mail that you now want
2643 to split into your new @code{nnml} groups. You look at that file using
2644 @code{nndoc}, set the process mark on all the articles in the buffer
2645 (@kbd{M P b}, for instance), and then respool (@kbd{B r}) using
2646 @code{nnml}. If all goes well, all the mail in the @file{RMAIL} file is
2647 now also stored in lots of @code{nnml} directories, and you can delete
2648 that pesky @file{RMAIL} file. If you have the guts!
2650 Virtual server variables:
2653 @item nndoc-article-type
2654 @vindex nndoc-article-type
2655 This should be one of @code{mbox}, @code{babyl}, @code{digest},
2656 @code{mmdf}, @code{forward}, @code{news}, @code{rnews},
2657 @code{mime-difest}, @code{clari-briefs}, or @code{guess}.
2659 @item nndoc-post-type
2660 @vindex nndoc-post-type
2661 This variable says whether Gnus is to consider the group a news group or
2662 a mail group. There are two legal values: @code{mail} (the default)
2672 In the PC world people often talk about ``offline'' newsreaders. These
2673 are thingies that are combined reader/news transport monstrosities.
2674 With built-in modem programs. Yecchh!
2676 Of course, us Unix Weenie types of human beans use things like
2677 @code{uucp} and, like, @code{nntpd} and set up proper news and mail
2678 transport things like Ghod inteded. And then we just use normal
2681 However, it can sometimes be convenient to do something a that's a bit
2682 easier on the brain if you have a very slow modem, and you're not really
2683 that interested in doing things properly.
2685 A file format called @sc{soup} has been developed for transporting news
2686 and mail from servers to home machines and back again. It can be a bit
2692 You log in on the server and create a @sc{soup} packet. You can either
2693 use a dedicated @sc{soup} thingie, or you can use Gnus to create the
2694 packet with the @kbd{O s} command.
2697 You transfer the packet home. Rail, boat, car or modem will do fine.
2700 You put the packet in your home directory.
2703 You fire up Gnus using the @code{nnsoup} backend as the native server.
2706 You read articles and mail and answer and followup to the things you
2710 You do the @kbd{G s r} command to pack these replies into a @sc{soup}
2714 You transfer this packet to the server.
2717 You use Gnus to mail this packet out with the @kbd{G s s} command.
2720 You then repeat until you die.
2724 So you basically have a bipartite system---you use @code{nnsoup} for
2725 reading and Gnus for packing/sending these @sc{soup} packets.
2728 * SOUP Commands:: Commands for creating and sending @sc{soup} packets
2729 * nnsoup:: A backend for reading @sc{soup} packets.
2730 * SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
2735 @subsubsection SOUP Commands
2739 @kindex G s b (Group)
2740 @findex gnus-group-brew-soup
2741 Pack all unread articles in the current group
2742 (@code{gnus-group-brew-soup}). This command understands the
2743 process/prefix convention.
2746 @kindex G s w (Group)
2747 @findex gnus-soup-save-areas
2748 Save all data files (@code{gnus-soup-save-areas}).
2751 @kindex G s s (Group)
2752 @findex gnus-soup-send-replies
2753 Send all replies from the replies packet
2754 (@code{gnus-soup-send-replies}).
2757 @kindex G s p (Group)
2758 @findex gnus-soup-pack-packet
2759 Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
2762 @kindex G s r (Group)
2763 @findex nnsoup-pack-replies
2764 Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
2767 @kindex O s (Summary)
2768 @findex gnus-soup-add-article
2769 This summary-mode command adds the current article to a @sc{soup} packet
2770 (@code{gnus-soup-add-article}). It understands the process/prefix
2776 There are a few variables to customize where Gnus will put all these
2781 @item gnus-soup-directory
2782 @vindex gnus-soup-directory
2783 Directory where Gnus will save intermediate files while composing
2784 @sc{soup} packets. The default is @file{~/SoupBrew/}.
2786 @item gnus-soup-replies-directory
2787 @vindex gnus-soup-replies-directory
2788 This is what Gnus will use as a temporary directory while sending our
2789 reply packets. The default is @file{~/SoupBrew/SoupReplies/}.
2791 @item gnus-soup-prefix-file
2792 @vindex gnus-soup-prefix-file
2793 Name of the file where Gnus stores the last used prefix. The default is
2794 @samp{"gnus-prefix"}.
2796 @item gnus-soup-packer
2797 @vindex gnus-soup-packer
2798 A format string command for packing a @sc{soup} packet. The default is
2799 @samp{ "tar cf - %s | gzip > $HOME/Soupout%d.tgz"}.
2801 @item gnus-soup-unpacker
2802 @vindex gnus-soup-unpacker
2803 Format string command for unpacking a @sc{soup} packet. The default is
2804 @samp{"gunzip -c %s | tar xvf -"}.
2806 @item gnus-soup-packet-directory
2807 @vindex gnus-soup-packet-directory
2808 Wehre Gnus will look for reply packets. The default is @file{~/}.
2810 @item gnus-soup-packet-regexp
2811 @vindex gnus-soup-packet-regexp
2812 Regular expression matching @sc{soup} reply packets in
2813 @code{gnus-soup-packet-directory}.
2819 @subsubsection nnsoup
2820 @cindex @code{nnsoup}
2822 @code{nnsoup} is the backend for reading @sc{soup} packets. It will
2823 read incoming packets, unpack them, and put them in a directory where
2824 you can read them at leisure.
2826 These are the variables you can use to customize its behavior:
2830 @item nnsoup-directory
2831 @vindex nnsoup-directory
2832 @code{nnsoup} will move all incoming @sc{soup} packets to this directory
2833 and unpack them there. The default is @file{~/SOUP/}.
2835 @item nnsoup-replies-directory
2836 @vindex nnsoup-replies-directory
2837 All replies will stored in this directory before being packed into a
2838 reply packet. The default is @file{~/SOUP/replies/"}.
2840 @item nnsoup-replies-format-type
2841 @vindex nnsoup-replies-format-type
2842 The @sc{soup} format of the replies packets. The default is @samp{?n}
2843 (rnews), and I don't think you should touch that variable. I probaly
2844 shouldn't even have documented it. Drats! Too late!
2846 @item nnsoup-replies-index-type
2847 @vindex nnsoup-replies-index-type
2848 The index type of the replies packet. The is @samp{?n}, which means
2849 ``none''. Don't fiddle with this one either!
2851 @item nnsoup-active-file
2852 @vindex nnsoup-active-file
2853 Where @code{nnsoup} stores lots of information. This is not an ``active
2854 file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
2855 this file or mess it up in any way, you're dead. The default is
2856 @file{~/SOUP/active}.
2859 @vindex nnsoup-packer
2860 Format string command for packing a reply @sc{soup} packet. The default
2861 is @samp{"tar cf - %s | gzip > $HOME/Soupin%d.tgz"}.
2863 @item nnsoup-unpacker
2864 @vindex nnsoup-unpacker
2865 Format string command for unpacking incoming @sc{soup} packets. The
2866 default is @samp{"gunzip -c %s | tar xvf -"}.
2868 @item nnsoup-packet-directory
2869 @vindex nnsoup-packet-directory
2870 Where @code{nnsoup} will look for incoming packets. The default is
2873 @item nnsoup-packet-regexp
2874 @vindex nnsoup-packet-regexp
2875 Regular expression matching incoming @sc{soup} packets. The default is
2882 @subsubsection SOUP Replies
2884 Just using @code{nnsoup} won't mean that your postings and mailings end
2885 up in @sc{soup} reply packets automagically. You have to work a bit
2886 more for that to happen.
2888 @findex nnsoup-set-variables
2889 The @code{nnsoup-set-variables} command will set the appropriate
2890 variables to ensure that all your followups and replies end up in the
2893 In specific, this is what it does:
2896 (setq gnus-inews-article-function 'nnsoup-request-post)
2897 (setq send-mail-function 'nnsoup-request-mail)
2900 And that's it, really. If you only want news to go into the @sc{soup}
2901 system you just use the first line. If you only want mail to be
2902 @sc{soup}ed you use the second.
2906 @subsection Reading Mail
2907 @cindex reading mail
2910 Reading mail with a newsreader---isn't that just plain WeIrD? But of
2913 Gnus will read the mail spool when you activate a mail group. The mail
2914 file is first copied to your home directory. What happens after that
2915 depends on what format you want to store your mail in.
2918 * Creating Mail Groups:: How to create mail groups.
2919 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
2920 * Mail and Procmail:: Reading mail groups that procmail create.
2921 * Expiring Old Mail Articles:: Getting rid of unwanted mail.
2922 * Not Reading Mail:: Using mail backends for reading other files.
2923 * nnmbox:: Using the (quite) standard Un*x mbox.
2924 * nnbabyl:: Emacs programs use the rmail babyl format.
2925 * nnml:: Store your mail in a private spool?
2926 * nnmh:: An mhspool-like backend.
2927 * nnfolder:: Having one file for each group.
2930 @vindex nnmail-read-incoming-hook
2931 The mail backends all call @code{nnmail-read-incoming-hook} after
2932 reading new mail. You can use this hook to notify any mail watch
2933 programs, if you want to.
2935 @vindex nnmail-spool-file
2938 @code{nnmail-spool-file} says where to look for new mail. If this
2939 variable is @code{nil}, the mail backends will never attempt to fetch
2940 mail by themselves. If you are using a POP mail server and your name is
2941 @samp{"larsi"}, you should set this variable to @samp{"po:larsi"}. If
2942 your name is not @samp{"larsi"}, you should probably modify that
2943 slightly, but you may have guessed that already, you smart & handsome
2944 devil! You can also set this variable to @code{pop}, and Gnus will try
2945 to figure out the POP mail string by itself. In any case, Gnus will
2946 call @code{movemail} which will contact the POP server named in the
2947 @samp{MAILHOST} environment variable.
2949 When you use a mail backend, Gnus will slurp all your mail from your
2950 inbox and plonk it down in your home directory. Gnus doesn't move any
2951 mail if you're not using a mail backend---you have to do a lot of magic
2952 invocations first. At the time when you have finished drawing the
2953 pentagram, lightened the candles, and sacrificed the goat, you really
2954 shouldn't be too suprised when Gnus moves your mail.
2956 @vindex nnmail-use-procmail
2957 If @code{nnmail-use-procmail} is non-@code{nil}, the mail backends will
2958 look in @code{nnmail-procmail-directory} for incoming mail. All the
2959 files in that directory that have names ending in
2960 @code{gnus-procmail-suffix} will be considered incoming mailboxes, and
2961 will be searched for new mail.
2963 @vindex nnmail-prepare-incoming-hook
2964 @code{nnmail-prepare-incoming-hook} is run in a buffer that holds all
2965 the new incoming mail, and can be used for, well, anything, really.
2967 @vindex nnmail-pre-get-new-mail-hook
2968 @vindex nnmail-post-get-new-mail-hook
2969 There are two more useful hooks executed when treating new incoming
2970 mail---@code{nnmail-pre-get-new-mail-hook} (which is called just before
2971 starting to handle the new mail) and
2972 @code{nnmail-post-get-new-mail-hook} (which is called when the mail
2973 handling is done). Here's and example of using these two hooks to
2974 change the default file modes the new mail files get:
2977 (add-hook 'gnus-pre-get-new-mail-hook
2978 (lambda () (set-default-file-modes 511)))
2980 (add-hook 'gnus-post-get-new-mail-hook
2981 (lambda () (set-default-file-modes 551)))
2984 @vindex nnmail-tmp-directory
2985 @code{nnmail-tmp-directory} says where to move the incoming mail to
2986 while processing it. This is usually done in the same directory that
2987 the mail backend inhabits (i.e., @file{~/Mail/}), but if this variable is
2988 non-@code{nil}, it will be used instead.
2990 @vindex nnmail-movemail-program
2991 @code{nnmail-movemail-program} is executed to move mail from the user's
2992 inbox to her home directory. The default is @samp{"movemail"}.
2994 @vindex nnmail-delete-incoming
2995 If @code{nnmail-delete-incoming} is non-@code{nil}, the mail backends
2996 will delete the temporary incoming file after splitting mail into the
2997 proper groups. This is @code{nil} by default for reasons of security.
2999 @vindex nnmail-use-long-file-names
3000 If @code{nnmail-use-long-file-names} is non-@code{nil} the mail backends
3001 will use long file and directory names. Groups like @samp{mail.misc}
3002 will end up in directories like @file{mail.misc/}. If it is @code{nil},
3003 the same group will end up in @file{mail/misc/}.
3005 @vindex nnmail-message-id-cache-length
3006 @vindex nnmail-message-id-cache-file
3007 @vindex nnmail-treat-duplicates
3008 @cindex duplicate mails
3009 If you are a member of a couple of mailing list, you will sometime
3010 receive two copies of the same mail. This can be quite annoying, so
3011 @code{nnmail} checks for and treats any duplicates it might find. To do
3012 this, it keeps a cache of old @code{Message-ID}s -
3013 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
3014 default. The approximate maximum number of @code{Message-ID}s stored
3015 there is controlled by the @code{nnmail-message-id-cache-length}
3016 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
3017 stored.) If all this sounds scary to you, you can set
3018 @code{nnmail-delete-duplicates} to @code{warn} (which is what it is by
3019 default), and @code{nnmail} won't delete duplicate mails. Instead it
3020 will generate a brand new @code{Message-ID} for the mail and insert a
3021 warning into the head of the mail saying that it thinks that this is a
3022 duplicate of a different message.
3024 This variable can also be a function. If that's the case, the function
3025 will be called from a buffer narrowed to the message in question with
3026 the @code{Message-ID} as a parameter. The function must return either
3027 @code{nil}, @code{warn}, or @code{delete}.
3029 You can turn this feature off completely by setting the variable to
3032 If you want all the duplicate mails to be put into a special
3033 @dfn{duplicates} group, you could do that using the normal mail split
3037 (setq nnmail-split-fancy
3038 '(| ;; Messages duplicates go to a separate group.
3039 ("gnus-warning" "duplication of message" "duplicate")
3040 ;; Message from deamons, postmaster, and the like to another.
3041 (any mail "mail.misc")
3048 (setq nnmail-split-methods
3049 '(("duplicates" "^Gnus-Warning:")
3054 Here's a neat feature: If you know that the recipient reads her mail
3055 with Gnus, and that she has @code{nnmail-treat-duplicates} set to
3056 @code{delete}, you can send her as many insults as you like, just by
3057 using a @code{Message-ID} of a mail that you know that she's already
3058 received. Think of all the fun! She'll never see any of it! Whee!
3060 Gnus gives you all the opportunity you could possibly want for shooting
3061 yourself in the foot. Let's say you create a group that will contain
3062 all the mail you get from your boss. And then you accidentally
3063 unsubscribe from the group. Gnus will still put all the mail from your
3064 boss in the unsubscribed group, and so, when your boss mails you ``Have
3065 that report ready by Monday or you're fired!'', you'll never see it and,
3066 come Tuesday, you'll still believe that you're gainfully employed while
3067 you really should be out collecting empty bottles to save up for next
3070 @node Creating Mail Groups
3071 @subsubsection Creating Mail Groups
3072 @cindex creating mail groups
3074 You can make Gnus read your personal, private, secret mail.
3076 You should first set @code{gnus-secondary-select-methods} to, for
3077 instance, @code{((nnmbox ""))}. When you start up Gnus, Gnus will ask
3078 this backend for what groups it carries (@samp{mail.misc} by default)
3079 and subscribe it the normal way. (Which means you may have to look for
3080 it among the zombie groups, I guess, all depending on your
3081 @code{gnus-subscribe-newsgroup-method} variable.)
3083 @vindex nnmail-split-methods
3084 Then you should set the variable @code{nnmail-split-methods} to specify
3085 how the incoming mail is to be split into groups.
3088 (setq nnmail-split-methods
3089 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
3090 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
3094 This variable is a list of lists, where the first element of each of
3095 these lists is the name of the mail group (they do not have to be called
3096 something beginning with @samp{mail}, by the way), and the second
3097 element is a regular expression used on the header of each mail to
3098 determine if it belongs in this mail group.
3100 The second element can also be a function. In that case, it will be
3101 called narrowed to the headers with the first element of the rule as the
3102 argument. It should return a non-@code{nil} value if it thinks that the
3103 mail belongs in that group.
3105 The last of these groups should always be a general one, and the regular
3106 expression should @emph{always} be @samp{""} so that it matches any
3107 mails that haven't been matched by any of the other regexps.
3109 If you like to tinker with this yourself, you can set this variable to a
3110 function of your choice. This function will be called without any
3111 arguments in a buffer narrowed to the headers of an incoming mail
3112 message. The function should return a list of groups names that it
3113 thinks should carry this mail message.
3115 Note that the mail backends are free to maul the poor, innocent
3116 incoming headers all they want to. They all add @code{Lines} headers;
3117 some add @code{X-Gnus-Group} headers; most rename the Unix mbox
3118 @code{From<SPC>} line to something else.
3120 @vindex nnmail-crosspost
3121 The mail backends all support cross-posting. If several regexps match,
3122 the mail will be ``cross-posted'' to all those groups.
3123 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
3124 that no articles are crossposted to the general (@samp{""}) group.
3126 @vindex nnmail-crosspost-link-function
3129 @code{nnmh} and @code{nnml} makes crossposts by creating hard links to
3130 the crossposted articles. However, not all files systems support hard
3131 links. If that's the case for you, set
3132 @code{nnmail-crosspost-link-function} to @code{copy-file}. (This
3133 variable is @code{add-name-to-file} by default.)
3136 @node Fancy Mail Splitting
3137 @subsubsection Fancy Mail Splitting
3138 @cindex mail splitting
3139 @cindex fancy mail splitting
3141 @vindex nnmail-split-fancy
3142 @findex nnmail-split-fancy
3143 If the rather simple, standard method for specifying how to split mail
3144 doesn't allow you to do what you want, you can set
3145 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
3146 play with the @code{nnmail-split-fancy} variable.
3148 Let's look at an example value of this variable first:
3151 ;; Messages from the mailer daemon are not crossposted to any of
3152 ;; the ordinary groups. Warnings are put in a separate group
3153 ;; from real errors.
3154 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
3156 ;; Non-error messages are crossposted to all relevant
3157 ;; groups, but we don't crosspost between the group for the
3158 ;; (ding) list and the group for other (ding) related mail.
3159 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
3160 ("subject" "ding" "ding.misc"))
3161 ;; Other mailing lists...
3162 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
3163 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
3165 (any "larsi@@ifi\\.uio\\.no" "people.Lars Magne Ingebrigtsen"))
3166 ;; Unmatched mail goes to the catch all group.
3170 This variable has the format of a @dfn{split}. A split is a (possibly)
3171 recursive structure where each split may contain other splits. Here are
3172 the four possible split syntaxes:
3177 If the split is a string, that will be taken as a group name.
3179 @item (FIELD VALUE SPLIT)
3180 If the split is a list, and the first element is a string, then that
3181 means that if header FIELD (a regexp) contains VALUE (also a regexp),
3182 then store the message as specified by SPLIT.
3185 If the split is a list, and the first element is @code{|} (vertical
3186 bar), then process each SPLIT until one of them matches. A SPLIT is
3187 said to match if it will cause the mail message to be stored in one or
3191 If the split is a list, and the first element is @code{&}, then process
3192 all SPLITs in the list.
3195 In these splits, FIELD must match a complete field name. VALUE must
3196 match a complete word according to the fundamental mode syntax table.
3197 You can use @code{.*} in the regexps to match partial field names or
3200 @vindex nnmail-split-abbrev-alist
3201 FIELD and VALUE can also be lisp symbols, in that case they are expanded
3202 as specified by the variable @code{nnmail-split-abbrev-alist}. This is
3203 an alist of cons cells, where the car of the cells contains the key, and
3204 the cdr contains a string.
3206 @node Mail and Procmail
3207 @subsubsection Mail and Procmail
3210 Many people use @code{procmail} (or some other mail filter program or
3211 external delivery agent---@code{slocal}, @code{elm}, etc) to split
3212 incoming mail into groups. If you do that, you should set
3213 @code{nnmail-spool-file} to @code{procmail} to ensure that the mail
3214 backends never ever try to fetch mail by themselves.
3216 This also means that you probably don't want to set
3217 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
3220 When a mail backend is queried for what groups it carries, it replies
3221 with the contents of that variable, along with any groups it has figured
3222 out that it carries by other means. None of the backends (except
3223 @code{nnmh}) actually go out to the disk and check what groups actually
3224 exist. (It's not trivial to distinguish between what the user thinks is
3225 a basis for a newsgroup and what is just a plain old file or directory.)
3227 This means that you have to tell Gnus (and the backends) what groups
3230 Let's take the @code{nnmh} backend as an example.
3232 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
3233 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
3235 Go to the group buffer and type @kbd{G m}. When prompted, answer
3236 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
3237 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
3238 to include all your mail groups.
3240 That's it. You are now set to read your mail. An active file for this
3241 method will be created automatically.
3243 @vindex nnmail-procmail-suffix
3244 @vindex nnmail-procmail-directory
3245 If you use @code{nnfolder} or any other backend that store more than a
3246 single article in each file, you should never have procmail add mails to
3247 the file that Gnus sees. Instead, procmail should put all incoming mail
3248 in @code{nnmail-procmail-directory}. To arrive at the file name to put
3249 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
3250 name. The mail backends will read the mail from these files.
3252 @vindex nnmail-resplit-incoming
3253 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
3254 put in the @code{mail.misc}, as one would expect. However, if you want
3255 Gnus to split the mail the normal way, you could set
3256 @code{nnmail-resplit-incoming} to @code{t}.
3258 @vindex nnmail-keep-last-article
3259 If you use @code{procmail} to split things directory into an @code{nnmh}
3260 directory (which you shouldn't do), you should set
3261 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
3262 ever expiring the final article in a mail newsgroup. This is quite,
3266 @node Expiring Old Mail Articles
3267 @subsubsection Expiring Old Mail Articles
3268 @cindex article expiry
3270 Traditional mail readers have a tendency to remove mail articles when
3271 you mark them as read, in some way. Gnus takes a fundamentally
3272 different approach to mail reading.
3274 Gnus basically considers mail just to be news that has been received in
3275 a rather peculiar manner. It does not think that it has the power to
3276 actually change the mail, or delete any mail messages. If you enter a
3277 mail group, and mark articles as ``read'', or kill them in some other
3278 fashion, the mail articles will still exist on the system. I repeat:
3279 Gnus will not delete your old, read mail. Unless you ask it to, of
3282 To make Gnus get rid of your unwanted mail, you have to mark the
3283 articles as @dfn{expirable}. This does not mean that the articles will
3284 disappear right away, however. In general, a mail article will be
3285 deleted from your system if, 1) it is marked as expirable, AND 2) it is
3286 more than one week old. If you do not mark an article as expirable, it
3287 will remain on your system until hell freezes over. This bears
3288 repeating one more time, with some spurious capitalizations: IF you do
3289 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
3291 @vindex gnus-auto-expirable-newsgroups
3292 You do not have to mark articles as expirable by hand. Groups that
3293 match the regular expression @code{gnus-auto-expirable-newsgroups} will
3294 have all articles that you read marked as expirable automatically. All
3295 articles that are marked as expirable have an @samp{E} in the first
3296 column in the summary buffer.
3298 Let's say you subscribe to a couple of mailing lists, and you want the
3299 articles you have read to disappear after a while:
3302 (setq gnus-auto-expirable-newsgroups
3303 "mail.nonsense-list\\|mail.nice-list")
3306 Another way to have auto-expiry happen is to have the element
3307 @code{auto-expire} in the select method of the group.
3309 @vindex nnmail-expiry-wait
3310 The @code{nnmail-expiry-wait} variable supplies the default time an
3311 expirable article has to live. The default is seven days.
3313 Gnus also supplies a function that lets you fine-tune how long articles
3314 are to live, based on what group they are in. Let's say you want to
3315 have one month expiry period in the @samp{mail.private} group, a one day
3316 expiry period in the @samp{mail.junk} group, and a six day expiry period
3320 (setq nnmail-expiry-wait-function
3322 (cond ((string= group "mail.private")
3324 ((string= group "mail.junk")
3326 ((string= group "important")
3332 The group names that this function is fed are ``unadorned'' group
3333 names---no @samp{"nnml:"} prefixes and the like.
3335 The @code{nnmail-expiry-wait} variable and
3336 @code{nnmail-expiry-wait-function} function can be either a number (not
3337 necessarily an integer) or the symbols @code{immediate} or
3340 You can also use the @code{expiry-wait} group parameter to selectively
3341 change the expiry period (@pxref{Group Parameters}).
3343 @vindex nnmail-keep-last-article
3344 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
3345 expire the final article in a mail newsgroup. This is to make life
3346 easier for procmail users.
3348 @vindex gnus-total-expirable-newsgroups
3349 By the way, that line up there about Gnus never expiring non-expirable
3350 articles is a lie. If you put @code{total-expire} in the group
3351 parameters, articles will not be marked as expirable, but all read
3352 articles will be put through the expiry process. Use with extreme
3353 caution. Even more dangerous is the
3354 @code{gnus-total-expirable-newsgroups} variable. All groups that match
3355 this regexp will have all read articles put through the expiry process,
3356 which means that @emph{all} old mail articles in the groups in question
3357 will be deleted after a while. Use with extreme caution, and don't come
3358 crying to me when you discover that the regexp you used matched the
3359 wrong group and all your important mail has disappeared. Be a
3360 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
3364 @node Not Reading Mail
3365 @subsubsection Not Reading Mail
3367 If you start using any of the mail backends, they have the annoying
3368 habit of assuming that you want to read mail with them. This might not
3369 be unreasonable, but it might not be what you want.
3371 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
3372 will ever attempt to read incoming mail, which should help.
3374 @vindex nnbabyl-get-new-mail
3375 @vindex nnmbox-get-new-mail
3376 @vindex nnml-get-new-mail
3377 @vindex nnmh-get-new-mail
3378 @vindex nnfolder-get-new-mail
3379 This might be too much, if, for instance, you are reading mail quite
3380 happily with @code{nnml} and just want to peek at some old @sc{rmail}
3381 file you have stashed away with @code{nnbabyl}. All backends have
3382 variables called backend-@code{get-new-mail}. If you want to disable
3383 the @code{nnbabyl} mail reading, you edit the virtual server for the
3384 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
3386 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
3387 narrowed to the article to be saved before saving it when reading
3391 @subsubsection nnmbox
3392 @cindex @code{nnmbox}
3393 @cindex unix mail box
3395 @vindex nnmbox-active-file
3396 @vindex nnmbox-mbox-file
3397 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
3398 mail. @code{nnmbox} will add extra headers to each mail article to say
3399 which group it belongs in.
3401 Virtual server settings:
3404 @item nnmbox-mbox-file
3405 @vindex nnmbox-mbox-file
3406 The name of the mail box in the user's home directory.
3408 @item nnmbox-active-file
3409 @vindex nnmbox-active-file
3410 The name of the active file for the mail box.
3412 @item nnmbox-get-new-mail
3413 @vindex nnmbox-get-new-mail
3414 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
3419 @subsubsection nnbabyl
3420 @cindex @code{nnbabyl}
3423 @vindex nnbabyl-active-file
3424 @vindex nnbabyl-mbox-file
3425 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
3426 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
3427 article to say which group it belongs in.
3429 Virtual server settings:
3432 @item nnbabyl-mbox-file
3433 @vindex nnbabyl-mbox-file
3434 The name of the rmail mbox file.
3436 @item nnbabyl-active-file
3437 @vindex nnbabyl-active-file
3438 The name of the active file for the rmail box.
3440 @item nnbabyl-get-new-mail
3441 @vindex nnbabyl-get-new-mail
3442 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
3448 @cindex mail @sc{nov} spool
3450 The @dfn{nnml} spool mail format isn't compatible with any other known
3451 format. It should be used with some caution.
3453 @vindex nnml-directory
3454 If you use this backend, Gnus will split all incoming mail into files;
3455 one file for each mail, and put the articles into the correct
3456 directories under the directory specified by the @code{nnml-directory}
3457 variable. The default value is @file{~/Mail/}.
3459 You do not have to create any directories beforehand; Gnus will take
3462 If you have a strict limit as to how many files you are allowed to store
3463 in your account, you should not use this backend. As each mail gets its
3464 own file, you might very well occupy thousands of inodes within a few
3465 weeks. If this is no problem for you, and it isn't a problem for you
3466 having your friendly systems administrator walking around, madly,
3467 shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should
3468 know that this is probably the fastest format to use. You do not have
3469 to trudge through a big mbox file just to read your new mail.
3471 @code{nnml} is probably the slowest backend when it comes to article
3472 splitting. It has to create lots of files, and it also generates
3473 @sc{nov} databases for the incoming mails. This makes is the fastest
3474 backend when it comes to reading mail.
3476 Virtual server settings:
3479 @item nnml-directory
3480 @vindex nnml-directory
3481 All @code{nnml} directories will be placed under this directory.
3483 @item nnml-active-file
3484 @vindex nnml-active-file
3485 The active file for the @code{nnml} server.
3487 @item nnml-newsgroups-file
3488 @vindex nnml-newsgroups-file
3489 The @code{nnml} group descriptions file. @xref{Newsgroups File
3492 @item nnml-get-new-mail
3493 @vindex nnml-get-new-mail
3494 If non-@code{nil}, @code{nnml} will read incoming mail.
3496 @item nnml-nov-is-evil
3497 @vindex nnml-nov-is-evil
3498 If non-@code{nil}, this backend will ignore any @sc{nov} files.
3500 @item nnml-nov-file-name
3501 @vindex nnml-nov-file-name
3502 The name of the @sc{nov} files. The default is @file{.overview}.
3506 @findex nnml-generate-nov-databases
3507 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
3508 you can do a complete update by typing @kbd{M-x
3509 nnml-generate-nov-databases}. This command will trawl through the
3510 entire @code{nnml} hierarchy, looking at each and every article, so it
3511 might take a while to complete.
3516 @cindex mh-e mail spool
3518 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
3519 @sc{nov} databases and it doesn't keep an active file. This makes
3520 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
3521 makes it easier to write procmail scripts for.
3523 Virtual server settings:
3526 @item nnmh-directory
3527 @vindex nnmh-directory
3528 All @code{nnmh} directories will be located under this directory.
3530 @item nnmh-get-new-mail
3531 @vindex nnmh-get-new-mail
3532 If non-@code{nil}, @code{nnmh} will read incoming mail.
3535 @vindex nnmh-be-safe
3536 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
3537 sure that the articles in the folder are actually what Gnus thinks they
3538 are. It will check date stamps and stat everything in sight, so
3539 setting this to @code{t} will mean a serious slow-down. If you never
3540 use anything but Gnus to read the @code{nnmh} articles, you do not have
3541 to set this variable to @code{t}.
3546 @subsubsection nnfolder
3547 @cindex @code{nnfolder}
3548 @cindex mbox folders
3550 @code{nnfolder} is a backend for storing each mail group in a separate
3551 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
3552 will add extra headers to keep track of article numbers and arrival
3555 Virtual server settings:
3558 @item nnfolder-directory
3559 @vindex nnfolder-directory
3560 All the @code{nnfolder} mail boxes will be stored under this directory.
3562 @item nnfolder-active-file
3563 @vindex nnfolder-active-file
3564 The name of the active file.
3566 @item nnfolder-newsgroups-file
3567 @vindex nnfolder-newsgroups-file
3568 The name of the group descriptions file. @xref{Newsgroups File Format}.
3570 @item nnfolder-get-new-mail
3571 @vindex nnfolder-get-new-mail
3572 If non-@code{nil}, @code{nnfolder} will read incoming mail.
3575 @findex nnfolder-generate-active-file
3576 @kindex M-x nnfolder-generate-active-file
3577 If you have lots of @code{nnfolder}-like files you'd like to read with
3578 @code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
3579 command to make @code{nnfolder} aware of all likely files in
3580 @code{nnfolder-directory}.
3583 @node Group Parameters
3584 @section Group Parameters
3585 @cindex group parameters
3587 Gnus stores all information on a group in a list that is usually known
3588 as the @dfn{group info}. This list has from three to six elements.
3589 Here's an example info.
3592 ("nnml:mail.ding" 3 ((1 . 232) 244 (256 . 270)) ((tick 246 249))
3593 (nnml "private") ((to-address . "ding@@ifi.uio.no")))
3596 The first element is the @dfn{group name}, as Gnus knows the group,
3597 anyway. The second element is the @dfn{subscription level}, which
3598 normally is a small integer. The third element is a list of ranges of
3599 read articles. The fourth element is a list of lists of article marks
3600 of various kinds. The fifth element is the select method (or virtual
3601 server, if you like). The sixth element is a list of @dfn{group
3602 parameters}, which is what this section is about.
3604 Any of the last three elements may be missing if they are not required.
3605 In fact, the vast majority of groups will normally only have the first
3606 three elements, which saves quite a lot of cons cells.
3608 The group parameters store information local to a particular group:
3613 If the group parameter list contains an element that looks like
3614 @samp{(to-address . "some@@where.com")}, that address will be used by
3615 the backend when doing followups and posts. This is primarily useful in
3616 mail groups that represent closed mailing lists---mailing lists where
3617 it's expected that everybody that writes to the mailing list is
3618 subscribed to it. Since using this parameter ensures that the mail only
3619 goes to the mailing list itself, it means that members won't receive two
3620 copies of your followups.
3622 Using @code{to-address} will actually work whether the group is foreign
3623 or not. Let's say there's a group on the server that is called
3624 @samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten
3625 the articles from a mail-to-news gateway. Posting directly to this
3626 group is therefore impossible---you have to send mail to the mailing
3627 list address instead.
3631 If the group parameter list has an element that looks like
3632 @code{(to-list . "some@@where.com")}, that address will be used when
3633 doing a @kbd{a} in any group. It is totally ignored when doing a
3634 followup---except that if it is present in a news group, you'll get mail
3635 group semantics when doing @kbd{f}.
3637 @item broken-reply-to
3638 @cindex broken-reply-to
3639 Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To}
3640 headers in this group are to be ignored. This can be useful if you're
3641 reading a mailing list group where the listserv has inserted
3642 @code{Reply-To} headers that point back to the listserv itself. This is
3643 broken behavior. So there!
3647 If the group parameter list contains an element like @code{(to-group
3648 . "some.group.name")}, all posts will be sent to that group.
3652 If this symbol is present in the group parameter list, all articles that
3653 are read will be marked as expirable. For an alternative approach,
3654 @xref{Expiring Old Mail Articles}.
3657 @cindex total-expire
3658 If this symbol is present, all read articles will be put through the
3659 expiry process, even if they are not marked as expirable. Use with
3664 If the group parameter has an element that looks like @samp{(expiry-wait
3665 . 10)}, this value will override any @code{nnmail-expiry-wait} and
3666 @code{nnmail-expiry-wait-functions} when expiring expirable messages.
3667 The value can either be a number of days (not necessarily an integer) or
3668 the symbols @code{never} or @code{immediate}.
3671 Elements that look like @samp{(score-file . "file")} will make
3672 @samp{file} into the current score file for the group in question. This
3673 means that all score commands you issue will end up in that file.
3676 When unsubscribing to a mailing list you should never send the
3677 unsubscription notice to the mailing list itself. Instead, you'd send
3678 messages to the administrative address. This parameter allows you to
3679 put the admin address somewhere convenient.
3682 This parameter allows you to enter a random comment on the group.
3684 @item @var{(variable form)}
3685 You can use the group parameters to set variables local to the group you
3686 are entering. Say you want to turn threading off in
3687 @samp{news.answers}. You'd then put @code{(gnus-show-threads nil)} in
3688 the group parameters of that group. @code{gnus-show-threads} will be
3689 made into a local variable in the summary buffer you enter, and the form
3690 @code{nil} will be @code{eval}ed there.
3692 This can also be used as a group-specific hook function, if you'd like.
3693 If you want to hear a beep when you enter the group
3694 @samp{alt.binaries.pictures.furniture}, you could put something like
3695 @code{(dummy-variable (ding))} in the parameters of that group.
3696 @code{dummy-variable} will be set to the result of the @code{(ding)}
3697 form, but who cares?
3701 If you want to change the group info you can use the @kbd{G E} command
3702 to enter a buffer where you can edit it.
3704 You usually don't want to edit the entire group info, so you'd be better
3705 off using the @kbd{G p} command to just edit the group parameters.
3707 @node Listing Groups
3708 @section Listing Groups
3709 @cindex group listing
3711 These commands all list various slices of the groups that are available.
3719 @findex gnus-group-list-groups
3720 List all groups that have unread articles
3721 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
3722 command will list only groups of level ARG and lower. By default, it
3723 only lists groups of level five or lower (i.e., just subscribed groups).
3729 @findex gnus-group-list-all-groups
3730 List all groups, whether they have unread articles or not
3731 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
3732 this command will list only groups of level ARG and lower. By default,
3733 it lists groups of level seven or lower (i.e., just subscribed and
3734 unsubscribed groups).
3738 @findex gnus-group-list-level
3739 List all unread groups on a specific level
3740 (@code{gnus-group-list-level}). If given a prefix, also list the groups
3741 with no unread articles.
3745 @findex gnus-group-list-killed
3746 List all killed groups (@code{gnus-group-list-killed}). If given a
3747 prefix argument, really list all groups that are available, but aren't
3748 currently (un)subscribed. This could entail reading the active file
3753 @findex gnus-group-list-zombies
3754 List all zombie groups (@code{gnus-group-list-zombies}).
3758 @findex gnus-group-list-matching
3759 List all subscribed groups with unread articles that match a regexp
3760 (@code{gnus-group-list-matching}).
3764 @findex gnus-group-list-all-matching
3765 List groups that match a regexp (@code{gnus-group-list-all-matching}).
3769 @findex gnus-group-list-active
3770 List absolutely all groups that are in the active file(s) of the
3771 server(s) you are connected to (@code{gnus-group-list-active}). This
3772 might very well take quite a while. It might actually be a better idea
3773 to do a @kbd{A m} to list all matching, and just give @samp{.} as the
3778 @vindex gnus-permanently-visible-groups
3779 @cindex visible group paramenter
3780 Groups that match the @code{gnus-permanently-visible-groups} regexp will
3781 always be shown, whether they have unread articles or not. You can also
3782 add the @code{visible} element to the group parameters in question to
3783 get the same effect.
3785 @vindex gnus-list-groups-with-ticked-articles
3786 Groups that have just ticked articles in it are normally listed in the
3787 group buffer. If @code{gnus-list-groups-with-ticked-articles} is
3788 @code{nil}, these groups will be treated just like totally empty
3789 groups. It is @code{t} by default.
3792 @node Sorting Groups
3793 @section Sorting Groups
3794 @cindex sorting groups
3796 @kindex C-c C-s (Group)
3797 @findex gnus-group-sort-groups
3798 @vindex gnus-group-sort-function
3799 The @kbd{C-c C-s} (@code{gnus-group-srot-groups}) command sorts the
3800 group buffer according to the function(s) given by the
3801 @code{gnus-group-sort-function} variable. Available sorting functions
3806 @item gnus-group-sort-by-alphabet
3807 @findex gnus-group-sort-by-alphabet
3808 Sort the group names alphabetically. This is the default.
3810 @item gnus-group-sort-by-level
3811 @findex gnus-group-sort-by-level
3812 Sort by group level.
3814 @item gnus-group-sort-by-score
3815 @findex gnus-group-sort-by-score
3816 Sort by group score.
3818 @item gnus-group-sort-by-rank
3819 @findex gnus-group-sort-by-rank
3820 Sort by group score and then the group level. The level and the score
3821 are, when taken together, the group's @dfn{rank}.
3823 @item gnus-group-sort-by-unread
3824 @findex gnus-group-sort-by-unread
3825 Sort by number of unread articles.
3827 @item gnus-group-sort-by-method
3828 @findex gnus-group-sort-by-method
3829 Sort by alphabetically on the select method.
3834 @code{gnus-group-sort-function} can also be a list of sorting
3835 functions. In that case, the most significant sort key function must be
3839 There are also a number of commands for sorting directly according to
3840 some sorting criteria:
3844 @kindex G S a (Group)
3845 @findex gnus-group-sort-groups-by-alphabet
3846 Sort the group buffer alphabetically by group name
3847 (@code{gnus-group-sort-groups-by-alphabet}).
3850 @kindex G S u (Group)
3851 @findex gnus-group-sort-groups-by-unread
3852 Sort the group buffer by the number of unread articles
3853 (@code{gnus-group-sort-groups-by-unread}).
3856 @kindex G S l (Group)
3857 @findex gnus-group-sort-groups-by-level
3858 Sort the group buffer by group level
3859 (@code{gnus-group-sort-groups-by-level}).
3862 @kindex G S v (Group)
3863 @findex gnus-group-sort-groups-by-score
3864 Sort the group buffer by group score
3865 (@code{gnus-group-sort-groups-by-score}).
3868 @kindex G S r (Group)
3869 @findex gnus-group-sort-groups-by-rank
3870 Sort the group buffer by group level
3871 (@code{gnus-group-sort-groups-by-rank}).
3874 @kindex G S m (Group)
3875 @findex gnus-group-sort-groups-by-method
3876 Sort the group buffer alphabetically by backend name
3877 (@code{gnus-group-sort-groups-by-method}).
3881 When given a prefix, all these commands will sort in reverse order.
3885 @node Group Maintenance
3886 @section Group Maintenance
3887 @cindex bogus groups
3892 @findex gnus-group-check-bogus-groups
3893 Find bogus groups and delete them
3894 (@code{gnus-group-check-bogus-groups}).
3898 @findex gnus-find-new-newsgroups
3899 Find new groups and process them (@code{gnus-find-new-newsgroups}). If
3900 given a prefix, use the @code{ask-server} method to query the server for
3904 @kindex C-c C-x (Group)
3905 @findex gnus-group-expire-articles
3906 Run all expirable articles in the current group through the expiry
3907 process (if any) (@code{gnus-group-expire-articles}).
3910 @kindex C-c M-C-x (Group)
3911 @findex gnus-group-expire-all-groups
3912 Run all articles in all groups through the expiry process
3913 (@code{gnus-group-expire-all-groups}).
3918 @node Browse Foreign Server
3919 @section Browse Foreign Server
3920 @cindex foreign servers
3921 @cindex browsing servers
3926 @findex gnus-group-browse-foreign-server
3927 You will be queried for a select method and a server name. Gnus will
3928 then attempt to contact this server and let you browse the groups there
3929 (@code{gnus-group-browse-foreign-server}).
3932 @findex gnus-browse-server-mode
3933 A new buffer with a list of available groups will appear. This buffer
3934 will be use the @code{gnus-browse-server-mode}. This buffer looks a bit
3935 (well, a lot) like a normal group buffer, but with one major difference
3936 - you can't enter any of the groups. If you want to read any of the
3937 news available on that server, you have to subscribe to the groups you
3938 think may be interesting, and then you have to exit this buffer. The
3939 new groups will be added to the group buffer, and then you can read them
3940 as you would any other group.
3942 Future versions of Gnus may possibly permit reading groups straight from
3945 Here's a list of keystrokes available in the browse mode:
3950 @findex gnus-group-next-group
3951 Go to the next group (@code{gnus-group-next-group}).
3955 @findex gnus-group-prev-group
3956 Go to the previous group (@code{gnus-group-prev-group}).
3959 @kindex SPACE (Browse)
3960 @findex gnus-browse-read-group
3961 Enter the current group and display the first article
3962 (@code{gnus-browse-read-group}).
3965 @kindex RET (Browse)
3966 @findex gnus-browse-select-group
3967 Enter the current group (@code{gnus-browse-select-group}).
3971 @findex gnus-browse-unsubscribe-current-group
3972 Unsubscribe to the current group, or, as will be the case here,
3973 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
3979 @findex gnus-browse-exit
3980 Exit browse mode (@code{gnus-browse-exit}).
3984 @findex gnus-browse-describe-briefly
3985 Describe browse mode briefly (well, there's not much to describe, is
3986 there) (@code{gnus-browse-describe-briefly}).
3990 @section Exiting Gnus
3991 @cindex exiting Gnus
3993 Yes, Gnus is ex(c)iting.
3998 @findex gnus-group-suspend
3999 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
4000 but it kills all buffers except the Group buffer. I'm not sure why this
4001 is a gain, but then who am I to judge?
4005 @findex gnus-group-exit
4006 Quit Gnus (@code{gnus-group-exit}).
4010 @findex gnus-group-quit
4011 Quit Gnus without saving any startup files (@code{gnus-group-quit}).
4014 @vindex gnus-exit-gnus-hook
4015 @vindex gnus-suspend-gnus-hook
4016 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
4017 @code{gnus-exit-gnus-hook} is called when you quit Gnus.
4021 If you wish to completely unload Gnus and all its adherents, you can use
4022 the @code{gnus-unload} command. This command is also very handy when
4023 trying to custoize meta-variables.
4028 Miss Lisa Cannifax, while sitting in English class, feels her feet go
4029 numbly heavy and herself fall into a hazy trance as the boy sitting
4030 behind her drew repeated lines with his pencil across the back of her
4036 @section Group Topics
4039 If you read lots and lots of groups, it might be convenient to group
4040 them hierarchically according to topics. You put your Emacs groups over
4041 here, your sex groups over there, and the rest (what, two groups or so?)
4042 you put in some misc section that you never bother with anyway. You can
4043 even group the Emacs sex groups as a sub-topic to either the Emacs
4044 groups or the sex groups---or both! Go wild!
4046 @findex gnus-topic-mode
4048 To get this @emph{fab} functionality you simply turn on (ooh!) the
4049 @code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
4050 is a toggling command.)
4052 Go ahead, just try it. I'll still be here when you get back. La de
4053 dum... Nice tune, that... la la la... What, you're back? Yes, and now
4054 press @kbd{l}. There. All your groups are now listed under
4055 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
4058 If you want this permanently enabled, you should add that minor mode to
4059 the hook for the group mode:
4062 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
4066 * Topic Variables:: How to customize the topics the Lisp Way.
4067 * Topic Commands:: Interactive E-Z commands.
4068 * Topic Topology:: A map of the world.
4072 @node Topic Variables
4073 @subsection Topic Variables
4074 @cindex topic variables
4077 @vindex gnus-topic-unique
4078 If @code{gnus-topic-unique} is non-@code{nil}, each group will be member
4079 of (tops) one topic each. If this is @code{nil}, each group might end
4080 up being a member of several topics.
4082 Now, if you select a topic, if will fold/unfold that topic, which is
4083 really neat, I think.
4085 @vindex gnus-topic-line-format
4086 The topic lines themselves are created according to the
4087 @code{gnus-topic-line-format} variable. @xref{Formatting Variables}.
4088 Elements allowed are:
4100 Number of groups in the topic.
4102 Number of unread articles in the topic.
4104 Number of unread articles in the topic and all its subtopics.
4107 @vindex gnus-topic-indent-level
4108 Each sub-topic (and the groups in the sub-topics) will be indented with
4109 @code{gnus-topic-indent-level} times the topic level number of spaces.
4110 The default is @samp{2}.
4113 @node Topic Commands
4114 @subsection Topic Commands
4115 @cindex topic commands
4117 When the topic minor mode is turned on, a new @kbd{T} submap will be
4118 available. In addition, a few of the standard keys change their
4119 definitions slightly.
4125 @findex gnus-topic-create-topic
4126 Create a new topic (@code{gnus-topic-create-subtopic}). You will be
4127 prompted for a topic name and the name of the parent topic.
4131 @findex gnus-topic-move-group
4132 Move the current group to some other topic
4133 (@code{gnus-topic-move-group}). This command understands the
4134 process/prefix convention (@pxref{Process/Prefix}).
4138 @findex gnus-topic-copy-group
4139 Copy the current group to some other topic
4140 (@code{gnus-topic-copy-group}). This command understands the
4141 process/prefix convention (@pxref{Process/Prefix}).
4145 @findex gnus-topic-move-matching
4146 Move all groups that match some regular expression to a topic
4147 (@code{gnus-topic-move-matching}).
4151 @findex gnus-topic-copy-matching
4152 Copy all groups that match some regular expression to a topic
4153 (@code{gnus-topic-copy-matching}).
4157 @findex gnus-topic-select-group
4159 Either select a group or fold a topic (@code{gnus-topic-select-group}).
4160 When you perform this command on a group, you'll enter the group, as
4161 usual. When done on a topic line, the topic will be folded (if it was
4162 visible) or unfolded (if it was folded already). So it's basically a
4163 toggling command on topics. In addition, if you give a numerical
4164 prefix, group on that level (and lower) will be displayed.
4168 @findex gnus-topic-indent
4169 ``Indent'' the current topic so that it becomes a sub-topic of the
4170 previous topic (@code{gnus-topic-indent}). If given a prefix,
4171 ``un-indent'' the topic instead.
4175 @findex gnus-topic-kill-group
4176 Kill a group or topic (@code{gnus-topic-kill-group}).
4180 @findex gnus-topic-yank-group
4181 Yank the previosuly killed group or topic (@code{gnus-topic-yank-group}).
4182 Note that all topics will be yanked before all groups.
4186 @findex gnus-topic-rename
4187 Rename a topic (@code{gnus-topic-rename}).
4190 @kindex T DEL (Group)
4191 @findex gnus-topic-delete
4192 Delete an empty topic (@code{gnus-topic-delete}).
4196 @findex gnus-topic-list-active
4197 List all groups that Gnus knows about in a topicsified way
4198 (@code{gnus-topic-list-active}).
4203 @node Topic Topology
4204 @subsection Topic Topology
4205 @cindex topic topology
4208 So, let's have a look at an example group buffer:
4214 2: alt.religion.emacs
4217 0: comp.talk.emacs.recovery
4219 8: comp.binaries.fractals
4220 13: comp.sources.unix
4223 So, here we have one top-level topic, two topics under that, and one
4224 sub-topic under one of the sub-topics. (There is always just one (1)
4225 top-level topic). This topology can be expressed as follows:
4229 (("Emacs -- I wuw it!" visible)
4230 (("Naughty Emacs" visible)))
4234 This is in fact how the variable @code{gnus-topic-topology} would look
4235 for the display above. That variable is saved in the @file{.newsrc.eld}
4236 file, and shouldn't be messed with manually---unless you really want
4237 to. Since this variable is read from the @file{.newsrc.eld} file,
4238 setting it in any other startup files will have no effect.
4240 This topology shows what topics are sub-topics of what topics (right),
4241 and which topics are visible. Two settings are currently
4242 allowed---@code{visible} and @code{invisible}.
4245 @node Misc Group Stuff
4246 @section Misc Group Stuff
4252 @findex gnus-group-get-new-news
4253 Check the server(s) for new articles. If the numerical prefix is used,
4254 this command will check only groups of level @var{arg} and lower
4255 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
4256 command will force a total rereading of the active file(s) from the
4261 @findex gnus-group-get-new-news-this-group
4262 @vindex gnus-goto-next-group-when-activating
4263 Check whether new articles have arrived in the current group
4264 (@code{gnus-group-get-new-news-this-group}). The
4265 @code{gnus-goto-next-group-when-activating} variable controls whether
4266 this command is to move point to the next group or not. It is @code{t}
4269 @findex gnus-activate-all-groups
4271 @kindex C-c M-g (Group)
4272 Activate absolutely all groups (@code{gnus-activate-all-groups}).
4276 @findex gnus-group-enter-server-mode
4277 Enter the server buffer (@code{gnus-group-enter-server-mode}). @xref{The
4282 @findex gnus-group-fetch-faq
4283 Try to fetch the FAQ for the current group
4284 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
4285 @code{gnus-group-faq-directory}, which is usually a directory on a
4286 remote machine. @code{ange-ftp} will be used for fetching the file.
4290 @findex gnus-group-restart
4291 Restart Gnus (@code{gnus-group-restart}).
4295 @findex gnus-group-read-init-file
4296 @vindex gnus-init-file
4297 Read the init file (@code{gnus-init-file}, which defaults to
4298 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
4302 @findex gnus-group-save-newsrc
4303 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
4304 (@code{gnus-group-save-newsrc}). If given a prefix, force saving the
4305 file(s) whether Gnus thinks it is necessary or not.
4309 @findex gnus-group-clear-dribble
4310 Clear the dribble buffer (@code{gnus-group-clear-dribble}).
4314 @findex gnus-group-describe-group
4315 Describe the current group (@code{gnus-group-describe-group}). If given
4316 a prefix, force Gnus to re-read the description from the server.
4320 @findex gnus-group-apropos
4321 List all groups that have names that match a regexp
4322 (@code{gnus-group-apropos}).
4326 @findex gnus-group-description-apropos
4327 List all groups that have names or descriptions that match a regexp
4328 (@code{gnus-group-description-apropos}).
4332 @findex gnus-group-post-news
4333 Post an article to a group (@code{gnus-group-post-news}). The current
4334 group name will be used as the default.
4338 @findex gnus-group-mail
4339 Mail a message somewhere (@code{gnus-group-mail}).
4342 @kindex C-x C-t (Group)
4343 @findex gnus-group-transpose-groups
4344 Transpose two groups (@code{gnus-group-transpose-groups}).
4348 @findex gnus-version
4349 Display current Gnus version numbers (@code{gnus-version}).
4353 @findex gnus-group-describe-all-groups
4354 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
4355 prefix, force Gnus to re-read the description file from the server.
4359 @findex gnus-group-describe-briefly
4360 Give a very short help message (@code{gnus-group-describe-briefly}).
4363 @kindex C-c C-i (Group)
4364 @findex gnus-info-find-node
4365 Go to the Gnus info node (@code{gnus-info-find-node}).
4368 @vindex gnus-group-prepare-hook
4369 @code{gnus-group-prepare-hook} is called after the group buffer is
4370 generated. It may be used to modify the buffer in some strange,
4373 @node The Summary Buffer
4374 @chapter The Summary Buffer
4375 @cindex summary buffer
4377 A line for each article is displayed in the summary buffer. You can
4378 move around, read articles, post articles and reply to articles.
4381 * Summary Buffer Format:: Deciding how the summary buffer is to look.
4382 * Summary Maneuvering:: Moving around the summary buffer.
4383 * Choosing Articles:: Reading articles.
4384 * Paging the Article:: Scrolling the current article.
4385 * Reply Followup and Post:: Posting articles.
4386 * Canceling and Superseding:: ``Whoops, I shouldn't have called him that.''
4387 * Marking Articles:: Marking articles as read, expirable, etc.
4388 * Limiting:: You can limit the summary buffer.
4389 * Threading:: How threads are made.
4390 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
4391 * Article Caching:: You may store articles in a cache.
4392 * Persistent Articles:: Making articles expiry-resistant.
4393 * Article Backlog:: Having already read articles hang around.
4394 * Exiting the Summary Buffer:: Returning to the Group buffer.
4395 * Process/Prefix:: A convention used by many treatment commands.
4396 * Saving Articles:: Ways of customizing article saving.
4397 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
4398 * Article Treatment:: The article buffer can be mangled at will.
4399 * Summary Sorting:: You can sort the summary buffer four ways.
4400 * Finding the Parent:: No child support? Get the parent.
4401 * Alternative Approaches:: Reading using non-default summaries.
4402 * Tree Display:: A more visual display of threads.
4403 * Mail Group Commands:: Some commands can only be used in mail groups.
4404 * Various Summary Stuff:: What didn't fit anywhere else.
4408 @node Summary Buffer Format
4409 @section Summary Buffer Format
4410 @cindex summary buffer format
4413 * Summary Buffer Lines:: You can specify how summary lines should look.
4414 * Summary Buffer Mode Line:: You can say how the mode line should look.
4417 @findex mail-extract-address-components
4418 @findex gnus-extract-address-components
4419 @vindex gnus-extract-address-components
4420 Gnus will use the value of the @code{gnus-extract-address-components}
4421 variable as a function for getting the name and address parts of a
4422 @code{From} header. Two pre-defined function exist:
4423 @code{gnus-extract-address-components}, which is the default, quite
4424 fast, and too simplistic solution; and
4425 @code{mail-extract-address-components}, which works very nicely, but is
4428 @vindex gnus-summary-same-subject
4429 @code{gnus-summary-same-subject} is a string indicating that the current
4430 article has the same subject as the previous. This string will be used
4431 with those specs that require it. The default is @samp{""}.
4433 @node Summary Buffer Lines
4434 @subsection Summary Buffer Lines
4436 @vindex gnus-summary-line-format
4437 You can change the format of the lines in the summary buffer by changing
4438 the @code{gnus-summary-line-format} variable. It works along the same
4439 lines a a normal @code{format} string, with some extensions.
4441 The default string is @samp{"%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n"}.
4443 The following format specification characters are understood:
4451 Subject if the article is the root, @code{gnus-summary-same-subject}
4454 Full @code{From} line.
4456 The name (from the @code{From} header).
4458 The name (from the @code{From} header). This differs from the @code{n}
4459 spec in that it uses @code{gnus-extract-address-components}, which is
4460 slower, but may be more thorough.
4462 The address (from the @code{From} header). This works the same way as
4465 Number of lines in the article.
4467 Number of characters in the article.
4469 Indentation based on thread level (@pxref{Customizing Threading}).
4471 Nothing if the article is a root and lots of spaces if it isn't (it
4472 pushes everything after it off the screen).
4474 Opening bracket, which is normally @samp{\[}, but can also be @samp{<}
4475 for adopted articles.
4477 Closing bracket, which is normally @samp{\]}, but can also be @samp{>}
4478 for adopted articles.
4480 One space for each thread level.
4482 Twenty minus thread level spaces.
4490 @vindex gnus-summary-zcore-fuzz
4491 Zcore, @samp{+} if above the default level and @samp{-} if below the
4492 default level. If the difference between
4493 @code{gnus-summary-default-level} and the score is less than
4494 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
4506 Number of articles in the current sub-thread. Using this spec will slow
4507 down summary buffer generation somewhat.
4509 A single character will be displayed if the article has any children.
4511 User defined specifier. The next character in the format string should
4512 be a letter. @sc{gnus} will call the function
4513 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
4514 following @samp{%u}. The function will be passed the current header as
4515 argument. The function should return a string, which will be inserted
4516 into the summary just like information from any other summary specifier.
4519 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
4520 have to be handled with care. For reasons of efficiency, Gnus will
4521 compute what column these characters will end up in, and ``hard-code''
4522 that. This means that it is illegal to have these specs after a
4523 variable-length spec. Well, you might not be arrested, but your summary
4524 buffer will look strange, which is bad enough.
4526 The smart choice is to have these specs as far to the left as possible.
4527 (Isn't that the case with everything, though? But I digress.)
4529 This restriction may disappear in later versions of Gnus.
4531 @node Summary Buffer Mode Line
4532 @subsection Summary Buffer Mode Line
4534 @vindex gnus-summary-mode-line-format
4535 You can also change the format of the summary mode bar. Set
4536 @code{gnus-summary-mode-line-format} to whatever you like. Here are the
4537 elements you can play with:
4543 Unprefixed group name.
4545 Current article number.
4549 Number of unread articles in this group.
4551 Number of unselected articles in this group.
4553 A string with the number of unread and unselected articles represented
4554 either as @samp{<%U(+%u) more>} if there are both unread and unselected
4555 articles, and just as @samp{<%U more>} if there are just unread articles
4556 and no unselected ones.
4558 Shortish group name. For instance, @samp{rec.arts.anime} will be
4559 shortened to @samp{r.a.anime}.
4561 Subject of the current article.
4565 Name of the current score file.
4567 Number of dormant articles.
4569 Number of ticked articles.
4571 Number of articles that have been marked as read in this session.
4573 Number of articles expunged by the score files.
4577 @node Summary Maneuvering
4578 @section Summary Maneuvering
4579 @cindex summary movement
4581 All the straight movement commands understand the numeric prefix and
4582 behave pretty much as you'd expect.
4584 None of these commands select articles.
4589 @kindex M-n (Summary)
4590 @kindex G M-n (Summary)
4591 @findex gnus-summary-next-unread-subject
4592 Go to the next summary line of an unread article
4593 (@code{gnus-summary-next-unread-subject}).
4597 @kindex M-p (Summary)
4598 @kindex G M-p (Summary)
4599 @findex gnus-summary-prev-unread-subject
4600 Go to the previous summary line of an unread article
4601 (@code{gnus-summary-prev-unread-subject}).
4606 @kindex G g (Summary)
4607 @findex gnus-summary-goto-subject
4608 Ask for an article number and then go to this summary line
4609 (@code{gnus-summary-goto-subject}).
4612 If Gnus asks you to press a key to confirm going to the next group, you
4613 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
4614 buffer, searching for the next group to read without actually returning
4615 to the group buffer.
4617 Variables related to summary movement:
4621 @vindex gnus-auto-select-next
4622 @item gnus-auto-select-next
4623 If you are at the end of the group and issue one of the movement
4624 commands, Gnus will offer to go to the next group. If this variable is
4625 @code{t} and the next group is empty, Gnus will exit summary mode and
4626 return to the group buffer. If this variable is neither @code{t} nor
4627 @code{nil}, Gnus will select the next group, no matter whether it has
4628 any unread articles or not. As a special case, if this variable is
4629 @code{quietly}, Gnus will select the next group without asking for
4630 confirmation. If this variable is @code{almost-quietly}, the same will
4631 happen only if you are located on the last article in the group.
4632 Finally, if this variable is @code{slightly-quietly}, the @kbd{Z n}
4633 command will go to the next group without confirmation. Also
4634 @xref{Group Levels}.
4636 @item gnus-auto-select-same
4637 @vindex gnus-auto-select-same
4638 If non-@code{nil}, all the movement commands will try to go to the next
4639 article with the same subject as the current. This variable is not
4640 particularly useful if you use a threaded display.
4642 @item gnus-summary-check-current
4643 @vindex gnus-summary-check-current
4644 If non-@code{nil}, all the ``unread'' movement commands will not proceed
4645 to the next (or previous) article if the current article is unread.
4646 Instead, they will choose the current article.
4648 @item gnus-auto-center-summary
4649 @vindex gnus-auto-center-summary
4650 If non-@code{nil}, Gnus will keep the point in the summary buffer
4651 centered at all times. This makes things quite tidy, but if you have a
4652 slow network connection, or simply do not like this un-Emacsism, you can
4653 set this variable to @code{nil} to get the normal Emacs scrolling
4654 action. This will also inhibit horizontal recentering of the summary
4655 buffer, which might make it more inconvenient to read extremely long
4661 @node Choosing Articles
4662 @section Choosing Articles
4663 @cindex selecting articles
4665 None of the following movement commands understand the numeric prefix,
4666 and they all select and display an article.
4670 @kindex SPACE (Summary)
4671 @findex gnus-summary-next-page
4672 Select the current article, or, if that one's read already, the next
4673 unread article (@code{gnus-summary-next-page}).
4678 @kindex G n (Summary)
4679 @findex gnus-summary-next-unread-article
4680 Go to next unread article (@code{gnus-summary-next-unread-article}).
4685 @findex gnus-summary-prev-unread-article
4686 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
4691 @kindex G N (Summary)
4692 @findex gnus-summary-next-article
4693 Go to the next article (@code{gnus-summary-next-article}).
4698 @kindex G P (Summary)
4699 @findex gnus-summary-prev-article
4700 Go to the previous article (@code{gnus-summary-prev-article}).
4703 @kindex G C-n (Summary)
4704 @findex gnus-summary-next-same-subject
4705 Go to the next article with the same subject
4706 (@code{gnus-summary-next-same-subject}).
4709 @kindex G C-p (Summary)
4710 @findex gnus-summary-prev-same-subject
4711 Go to the previous article with the same subject
4712 (@code{gnus-summary-prev-same-subject}).
4716 @kindex G f (Summary)
4718 @findex gnus-summary-first-unread-article
4719 Go to the first unread article
4720 (@code{gnus-summary-first-unread-article}).
4724 @kindex G b (Summary)
4726 Go to the article with the highest score
4727 (@code{gnus-summary-best-unread-article}).
4732 @kindex G l (Summary)
4733 @findex gnus-summary-goto-last-article
4734 Go to the previous article read (@code{gnus-summary-goto-last-article}).
4737 @kindex G p (Summary)
4738 @findex gnus-summary-pop-article
4739 Pop an article off the summary history and go to this article
4740 (@code{gnus-summary-pop-article}). This command differs from the
4741 command above in that you can pop as many previous articles off the
4742 history as you like.
4745 Some variables that are relevant for moving and selecting articles:
4748 @item gnus-auto-extend-newsgroup
4749 @vindex gnus-auto-extend-newsgroup
4750 All the movement commands will try to go to the previous (or next)
4751 article, even if that article isn't displayed in the Summary buffer if
4752 this variable is non-@code{nil}. Gnus will then fetch the article from
4753 the server and display it in the article buffer.
4755 @item gnus-select-article-hook
4756 @vindex gnus-select-article-hook
4757 This hook is called whenever an article is selected. By default it
4758 exposes any threads hidden under the selected article.
4760 @item gnus-mark-article-hook
4761 @vindex gnus-mark-article-hook
4762 This hook is called whenever an article is selected. It is intended to
4763 be used for marking articles as read.
4765 @item gnus-visual-mark-article-hook
4766 @vindex gnus-visual-mark-article-hook
4767 This hook is run after selecting an article. It is meant to be used for
4768 highlighting the article in some way. It is not run if
4769 @code{gnus-visual} is @code{nil}.
4771 @item gnus-summary-update-hook
4772 @vindex gnus-summary-update-hook
4773 This hook is called when a summary line is changed. It is not run if
4774 @code{gnus-visual} is @code{nil}.
4776 @item gnus-summary-selected-face
4777 @vindex gnus-summary-selected-face
4778 This is the face (or @dfn{font} as some people call it) that is used to
4779 highlight the current article in the summary buffer.
4781 @item gnus-summary-highlight
4782 @vindex gnus-summary-highlight
4783 Summary lines are highlighted according to this variable, which is a
4784 list where the elements are on the format @code{(FORM . FACE)}. If you
4785 would, for instance, like ticked articles to be italic and high-scored
4786 articles to be bold, you could set this variable to something like
4788 (((eq mark gnus-ticked-mark) . italic)
4789 ((> score default) . bold))
4791 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
4792 @var{FACE} will be applied to the line.
4795 @node Paging the Article
4796 @section Scrolling the Article
4797 @cindex article scrolling
4802 @kindex SPACE (Summary)
4803 @findex gnus-summary-next-page
4804 Pressing @kbd{SPACE} will scroll the current article forward one page,
4805 or, if you have come to the end of the current article, will choose the
4806 next article (@code{gnus-summary-next-page}).
4809 @kindex DEL (Summary)
4810 @findex gnus-summary-prev-page
4811 Scroll the current article back one page (@code{gnus-summary-prev-page}).
4814 @kindex RET (Summary)
4815 @findex gnus-summary-scroll-up
4816 Scroll the current article one line forward
4817 (@code{gnus-summary-scroll-up}).
4822 @kindex A < (Summary)
4823 @findex gnus-summary-beginning-of-article
4824 Scroll to the beginning of the article
4825 (@code{gnus-summary-beginning-of-article}).
4830 @kindex A > (Summary)
4831 @findex gnus-summary-end-of-article
4832 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
4835 @kindex A s (Summary)
4836 @findex gnus-summary-isearch-article
4837 Perform an isearch in the article buffer
4838 (@code{gnus-summary-isearch-article}).
4842 @node Reply Followup and Post
4843 @section Reply, Followup and Post
4848 @kindex C-c C-c (Post)
4849 All the commands for posting and mailing will put you in a post or mail
4850 buffer where you can edit the article all you like, before you send the
4851 article by pressing @kbd{C-c C-c}. If you are in a foreign news group,
4852 and you wish to post the article using the foreign server, you can give
4853 a prefix to @kbd{C-c C-c} to make Gnus try to post using the foreign
4857 * Mail:: Mailing & replying.
4858 * Post:: Posting and following up.
4859 * Posting Server:: What server should you post via?
4860 * Mail and Post:: Mailing and posting at the same time.
4861 * Archived Messages:: Where Gnus stores the messages you've sent.
4862 * Posting Styles:: An easier way to configure some key elements.
4863 * Drafts:: Postponing messages and rejected messages.
4864 * Rejected Articles:: What happens if the server doesn't like your article?
4870 Commands for composing a mail message:
4876 @kindex S r (Summary)
4878 @findex gnus-summary-reply
4879 Mail a reply to the author of the current article
4880 (@code{gnus-summary-reply}).
4885 @kindex S R (Summary)
4886 @findex gnus-summary-reply-with-original
4887 Mail a reply to the author of the current article and include the
4888 original message (@code{gnus-summary-reply-with-original}). This
4889 command uses the process/prefix convention.
4892 @kindex S o m (Summary)
4893 @findex gnus-summary-mail-forward
4894 Forward the current article to some other person
4895 (@code{gnus-summary-mail-forward}).
4898 @kindex S o p (Summary)
4899 @findex gnus-summary-post-forward
4900 Forward the current article to a newsgroup
4901 (@code{gnus-summary-post-forward}).
4906 @kindex S m (Summary)
4907 @findex gnus-summary-mail-other-window
4908 Send a mail to some other person
4909 (@code{gnus-summary-mail-other-window}).
4912 @kindex S D b (Summary)
4913 @findex gnus-summary-resend-bounced-mail
4914 If you have sent a mail, but the mail was bounced back to you for some
4915 reason (wrong address, transient failure), you can use this command to
4916 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
4917 will be popped into a mail buffer where you can edit the headers before
4918 sending the mail off again. The headers that match the regexp
4919 @code{gnus-bounced-headers-junk} (default @samp{^Received:}) are
4920 automatically deleted first. If you give a prefix to this command, and
4921 the bounced mail is a reply to some other mail, Gnus will try to fetch
4922 that mail and display it for easy perusal of its headers. This might
4923 very well fail, though.
4926 @kindex S D r (Summary)
4927 @findex gnus-summary-resend-message
4928 Not to be confused with the previous command,
4929 @code{gnus-summary-resend-message} will prompt you for an address to
4930 send the current message off to, and then send it to that place. The
4931 headers of the message won't be altered---but lots of headers that say
4932 @samp{Resent-To}, @samp{Resent-From} and so on will be added. This
4933 means that you actually send a mail to someone that has a @samp{To}
4934 header that (proabbly) points to yourself. This will confuse people.
4935 So, natcherly you'll only do that if you're really eVIl.
4937 This command is mainly used if you have several accounts and want to
4938 ship a mail to a different account of yours. (If you're both
4939 @samp{root} and @samp{postmaster} and get a mail for @samp{postmaster}
4940 to the @samp{root} account, you may want to resend it to
4941 @samp{postmaster}. Ordnung muss sein!
4944 @kindex S O m (Summary)
4945 @findex gnus-uu-digest-mail-forward
4946 Digest the current series and forward the result using mail
4947 (@code{gnus-uu-digest-mail-forward}). This command uses the
4948 process/prefix convention (@pxref{Process/Prefix}).
4951 @kindex S O p (Summary)
4952 @findex gnus-uu-digest-post-forward
4953 Digest the current series and forward the result to a newsgroup
4954 (@code{gnus-uu-digest-mail-forward}).
4957 Variables for customizing outgoing mail:
4960 @item gnus-reply-to-function
4961 @vindex gnus-reply-to-function
4962 Gnus uses the normal methods to determine where replies are to go, but
4963 you can change the behavior to suit your needs by fiddling with this
4966 If you want the replies to go to the @samp{Sender} instead of the
4967 @samp{From} in the group @samp{mail.stupid-list}, you could do something
4971 (setq gnus-reply-to-function
4973 (cond ((string= group "mail.stupid-list")
4974 (mail-fetch-field "sender"))
4979 This function will be called narrowed to the head of the article that is
4982 As you can see, this function should return a string if it has an
4983 opinion as to what the To header should be. If it does not, it should
4984 just return @code{nil}, and the normal methods for determining the To
4985 header will be used.
4987 This function can also return a list. In that case, each list element
4988 should be a cons, where the car should be the name of an header
4989 (eg. @samp{Cc}) and the cdr should be the header value
4990 (eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
4991 the head of the outgoing mail.
4993 @item gnus-mail-send-method
4994 @vindex gnus-mail-send-method
4995 This variable says how a mail should be mailed. It uses the function in
4996 the @code{send-mail-function} variable as the default.
4998 @item gnus-uu-digest-headers
4999 @vindex gnus-uu-digest-headers
5000 List of regexps to match headers included in digested messages. The
5001 headers will be included in the sequence they are matched.
5003 @item gnus-mail-hook
5004 @vindex gnus-mail-hook
5005 Hook called as the last thing after setting up a mail buffer.
5007 @item gnus-required-mail-headers
5008 @vindex gnus-required-mail-headers
5009 Gnus will generate headers in all outgoing mail instead of letting
5010 @code{sendmail} do it for us. This makes it possible to do more neat
5011 stuff, like putting mail without sending it, do hairy @code{Fcc}
5012 handling, and much more. This variable controls what headers Gnus will
5013 generate, and is of the exact same form as @code{gnus-required-headers},
5014 which does the same for news articles (@pxref{Post}).
5016 The @code{Newsgroups} header is illegal in this list, while @code{To} is
5017 required, and @code{X-Mailer} can be added if you so should want.
5019 @findex gnus-forward-start-separator
5020 @item gnus-forward-start-separator
5021 Delimiter inserted before forwarded messages.
5023 @findex gnus-forward-end-separator
5024 @item gnus-forward-end-separator
5025 Delimiter inserted after forwarded messages.
5027 @vindex gnus-signature-before-forwarded-message
5028 @item gnus-signature-before-forwarded-message
5029 If this variable is @code{t}, which it is by default, your personal
5030 signature will be inserted before the forwarded message. If not, the
5031 forwarded message will be inserted first in the new mail.
5033 @item gnus-forward-included-headers
5034 @vindex gnus-forward-included-headers
5035 Regexp matching header lines to be included in forwarded messages. It
5036 usese the same regexp as @code{gnus-visible-headers} by default.
5040 @kindex C-c C-c (Mail)
5041 @kindex C-c C-p (Mail)
5042 @findex gnus-put-message
5043 You normally send a mail message by pressing @kbd{C-c C-c}. However,
5044 you may wish to just put the mail message you have just written in your
5045 own local mail group instead of sending it. Sounds quite unlikely, but
5046 I found that useful, so you can now also press @kbd{C-c C-p} to
5047 @dfn{put} the article in the current mail group, or, if there is no such
5048 thing, you will be prompted for a mail group, and then the article will
5049 be put there. This means that the article is @dfn{not} mailed.
5051 @findex gnus-kill-message-buffer
5052 @cindex kill mail buffer
5053 @kindex C-x k (Mail)
5054 @kindex C-x k (Post)
5055 If enter a mail (or post) buffer and then decide not to compose a
5056 message after all, you'd normally just kill the buffer with @kbd{C-x k}.
5057 However, since the mail and post buffers are associated with articles in
5058 the draft group, this will leave lots of rubbish articles in the draft
5059 group. To avoid that problem, kill mail and post buffer with @kbd{C-c
5060 C-k} (@code{gnus-kill-message-buffer}) instead. This will make sure
5061 that everything is properly cleaned up before the buffer is killed.
5063 There are three ``methods'' for handling all mail. The default is
5064 @code{sendmail}. Some people like what @code{mh} does better, and some
5065 people prefer @code{vm}.
5067 Three variables for customizing what to use when:
5071 @vindex gnus-mail-reply-method
5072 @item gnus-mail-reply-method
5073 This function is used to compose replies. The three functions avaibale
5076 @findex gnus-mail-reply-using-vm
5077 @findex gnus-mail-reply-using-mhe
5078 @findex gnus-mail-reply-using-mail
5081 @code{gnus-mail-reply-using-mail} (sendmail)
5083 @code{gnus-mail-reply-using-mhe} (mh)
5085 @code{gnus-mail-reply-using-vm} (vm)
5088 @vindex gnus-mail-forward-method
5089 @item gnus-mail-forward-method
5090 This function is used to forward messages. The three functions avaibale
5093 @findex gnus-mail-forward-using-vm
5094 @findex gnus-mail-forward-using-mhe
5095 @findex gnus-mail-forward-using-mail
5098 @code{gnus-mail-forward-using-mail} (sendmail)
5100 @code{gnus-mail-forward-using-mhe} (mh)
5102 @code{gnus-mail-forward-using-vm} (vm)
5105 @vindex gnus-mail-other-window-method
5106 @item gnus-mail-other-window-method
5107 This function is used to send mails. The three functions avaibale are:
5109 @findex gnus-mail-other-window-using-vm
5110 @findex gnus-mail-other-window-using-mhe
5111 @findex gnus-mail-other-window-using-mail
5114 @code{gnus-mail-other-window-using-mail} (sendmail)
5116 @code{gnus-mail-other-window-using-mhe} (mh)
5118 @code{gnus-mail-other-window-using-vm} (vm)
5127 Commands for posting an article:
5133 @kindex S p (Summary)
5134 @findex gnus-summary-post-news
5135 Post an article to the current group
5136 (@code{gnus-summary-post-news}).
5141 @kindex S f (Summary)
5142 @findex gnus-summary-followup
5143 Post a followup to the current article (@code{gnus-summary-followup}).
5147 @kindex S F (Summary)
5149 @findex gnus-summary-followup-with-original
5150 Post a followup to the current article and include the original message
5151 (@code{gnus-summary-followup-with-original}). This command uses the
5152 process/prefix convention.
5155 @kindex S u (Summary)
5156 @findex gnus-uu-post-news
5157 Uuencode a file, split it into parts, and post it as a series
5158 (@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}).
5161 @vindex gnus-required-headers
5162 @code{gnus-required-headers} a list of header symbols. These headers
5163 will either be automatically generated, or, if that's impossible, they
5164 will be prompted for. The following symbols are legal:
5169 This required header will be filled out with the result of the
5170 @code{gnus-inews-user-name} function, which depends on the
5171 @code{gnus-user-from-line}, @code{gnus-user-login-name},
5172 @code{gnus-local-domain} and @code{user-mail-address} variables.
5175 This required header will be prompted for if not present already.
5178 This required header says which newsgroups the article is to be posted
5179 to. If it isn't present already, it will be prompted for.
5182 @cindex organization
5183 @vindex gnus-local-organization
5184 @vindex gnus-organization-file
5185 This optional header will be filled out depending on the
5186 @code{gnus-local-organization} variable. @code{gnus-organization-file}
5187 will be used if that variable is nil.
5190 This optional header will be computed by Gnus.
5194 This required header will be generated by Gnus. A unique ID will be
5195 created based on date, time, user name and system name.
5198 @cindex X-Newsreader
5199 This optional header will be filled out with the Gnus version numbers.
5202 @vindex gnus-article-expires
5204 This extremely optional header will be inserted according to the
5205 @code{gnus-article-expires} variable. It is highly deprecated and
5206 shouldn't be used unless you know what you're doing.
5209 This optional header is filled out according to the
5210 @code{gnus-distribution-function} variable. It is a deprecated and much
5211 misunderstood header.
5214 In addition, you can enter conses into this list. The car of this cons
5215 should be a symbol. This symbol's name is the name of the header, and
5216 the cdr can either be a string to be entered verbatim as the value of
5217 this header, or it can be a function to be called. This function should
5218 return a string to be inserted. For instance, if you want to insert
5219 @samp{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
5220 into the list. If you want to insert a funny quote, you could enter
5221 something like @code{(X-Yow . yow)} into the list. The function
5222 @code{yow} will then be called without any arguments.
5224 The list contains a cons where the car of the cons is @code{optional},
5225 the cdr of this cons will only be inserted if it is non-@code{nil}.
5227 Other variables for customizing outgoing articles:
5230 @item nntp-news-default-headers
5231 @vindex nntp-news-default-headers
5232 If non-@code{nil}, this variable will override
5233 @code{mail-default-headers} when posting. This variable should then be
5234 a string. This string will be inserted, as is, in the head of all
5237 @item gnus-use-followup-to
5238 @vindex gnus-use-followup-to
5239 If @code{nil}, always ignore the Followup-To header. If it is @code{t},
5240 use its value, but ignore the special value @samp{poster}, which will
5241 send the followup as a reply mail to the person you are responding to.
5242 If it is the symbol @code{ask}, query the user before posting.
5243 If it is the symbol @code{use}, always use the value.
5245 @item gnus-followup-to-function
5246 @vindex gnus-followup-to-function
5247 This variable is most useful in mail groups, where ``following up'' really
5248 means sending a mail to a list address. Gnus uses the normal methods to
5249 determine where follow-ups are to go, but you can change the behavior
5250 to suit your needs by fiddling with this variable.
5252 If you want the followups to go to the @samp{Sender} instead of the
5253 @samp{From} in the group @samp{mail.stupid-list}, you could do something
5257 (setq gnus-followup-to-function
5259 (cond ((string= group "mail.stupid-list")
5260 (mail-fetch-field "sender"))
5265 This function will be called narrowed to header of the article that is
5268 @item gnus-removable-headers
5269 @vindex gnus-removable-headers
5270 Some headers that are generated are toxic to the @sc{nntp} server.
5271 These include the @code{NNTP-Posting-Host}, @code{Bcc} and @code{Xref},
5272 so these headers are deleted if they are present in this list of
5275 @item gnus-deletable-headers
5276 @vindex gnus-deletable-headers
5277 Headers in this list that were previously generated by Gnus will be
5278 deleted before posting. Let's say you post an article. Then you decide
5279 to post it again to some other group, you naughty boy, so you jump back
5280 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
5281 ship it off again. By default, this variable makes sure that the old
5282 generated @code{Message-ID} is deleted, and a new one generated. If
5283 this isn't done, the entire empire would probably crumble, anarchy would
5284 prevail, and cats would start walking on two legs and rule the world.
5287 @item gnus-signature-function
5288 @vindex gnus-signature-function
5289 If non-@code{nil}, this variable should be a function that returns a
5290 signature file name. The function will be called with the name of the
5291 group being posted to. If the function returns a string that doesn't
5292 correspond to a file, the string itself is inserted. If the function
5293 returns @code{nil}, the @code{gnus-signature-file} variable will be used
5296 @item gnus-post-prepare-function
5297 @vindex gnus-post-prepare-function
5298 This function is called with the name of the current group after the
5299 post buffer has been initialized, and can be used for inserting a
5300 signature. Nice if you use different signatures in different groups.
5302 @item gnus-post-prepare-hook
5303 @vindex gnus-post-prepare-hook
5304 This hook is called after a post buffer has been prepared. If you want
5305 to insert a signature at this point, you could put
5306 @code{gnus-inews-insert-signature} into this hook.
5308 @item news-reply-header-hook
5309 @vindex news-reply-header-hook
5310 A related variable when following up and replying is this variable,
5311 which inserts the @dfn{quote line}. The default value is:
5314 (defvar news-reply-header-hook
5316 (insert "In article " news-reply-yank-message-id
5317 " " news-reply-yank-from " writes:\n\n")))
5320 This will create lines like:
5323 In article <zngay8jrql@@eyesore.no> Lars Mars <lars@@eyesore.no> writes:
5326 Having the @code{Message-ID} in this line is probably overkill, so I
5327 would suggest this hook instead:
5330 (setq news-reply-header-hook
5331 (lambda () (insert news-reply-yank-from " writes:\n\n")))
5334 @item gnus-prepare-article-hook
5335 @vindex gnus-prepare-article-hook
5336 This hook is called before the headers have been prepared.
5338 @item gnus-inews-article-function
5339 @vindex gnus-inews-article-function
5340 This function is used to do the actual article processing and header
5341 checking/generation.
5343 @item gnus-inews-article-hook
5344 @vindex gnus-inews-article-hook
5345 This hook is called right before the article is posted. By default it
5346 handles FCC processing (i.e., saving the article to a file.) You can
5347 also have this hook add a score to all followups to the article you've
5348 written (@pxref{Followups To Yourself}).
5350 @item gnus-inews-article-header-hook
5351 @vindex gnus-inews-article-header-hook
5352 This hook is called after inserting the required headers in an article
5353 to be posted. The hook is called from the @code{*post-news*} buffer,
5354 narrowed to the head, and is intended for people who would like to
5355 insert additional headers, or just change headers in some way or other.
5357 @item gnus-check-before-posting
5358 @vindex gnus-check-before-posting
5359 If non-@code{nil}, Gnus will attempt to check the legality of the
5360 headers, as well as some other stuff, before posting. You can control
5361 the granularity of the check by adding or removing elements from this
5362 list. Legal elements are:
5366 Check the subject for commands.
5368 Insert a new @code{Sender} header if the @code{From} header looks odd.
5369 @item multiple-headers
5370 Check for the existence of multiple equal headers.
5372 Check for the existence of version and sendsys commands.
5374 Check whether the @code{Message-ID} looks ok.
5376 Check whether the @code{From} header seems nice.
5378 Check for too long lines.
5380 Check for illegal characters.
5382 Check for excessive size.
5384 Check whether there is any new text in the messages.
5386 Check the length of the signature.
5388 Check whether the article has an @code{Approved} header, which is
5389 something only moderators should include.
5391 Check whether the article is empty.
5398 @node Posting Server
5399 @subsection Posting Server
5401 When you press those magical @kbd{C-c C-c} keys to ship off your latest
5402 (extremely intelligent, of course) article, where does it go?
5404 Thank you for asking. I hate you.
5406 @vindex gnus-post-method
5408 It can be quite complicated. Normally, Gnus will use the same native
5409 server. However. If your native server doesn't allow posting, just
5410 reading, you probably want to use some other server to post your
5411 (extremely intelligent and fabulously interesting) articles. You can
5412 then set the @code{gnus-post-method} to some other method:
5415 (setq gnus-post-method '(nnspool ""))
5418 Now, if you've done this, and then this server rejects your article, or
5419 this server is down, what do you do then? To override this variable you
5420 can use a non-zero prefix to the @kbd{C-c C-c} command to force using
5421 the ``current'' server for posting.
5423 If you give a zero prefix (i. e., @kbd{C-u 0 C-c C-c}) to that command,
5424 Gnus will prompt you for what method to use for posting.
5426 You can also set @code{gnus-post-method} to a list of select methods.
5427 If that's the case, Gnus will always prompt you for what method to use
5432 @subsection Mail and Post
5434 Commands for sending mail and post at the same time:
5438 @kindex S b (Summary)
5439 @findex gnus-summary-followup-and-reply
5440 Post a followup and send a reply to the current article
5441 (@code{gnus-summary-followup-and-reply}).
5444 @kindex S B (Summary)
5445 @findex gnus-summary-followup-and-reply-with-original
5446 Post a followup and send a reply to the current article and include the
5447 original message (@code{gnus-summary-followup-and-reply-with-original}).
5448 This command uses the process/prefix convention.
5451 Here's a list of variables that are relevant to both mailing and
5455 @item gnus-signature-file
5456 @itemx mail-signature
5457 @vindex mail-signature
5458 @vindex gnus-signature-file
5459 @cindex double signature
5461 If @code{gnus-signature-file} is non-@code{nil}, it should be the name
5462 of a file containing a signature (@samp{~/.signature} by default). This
5463 signature will be appended to all outgoing post. Most people find it
5464 more convenient to use @code{mail-signature}, which (sort of) does the
5465 same, but inserts the signature into the buffer before you start editing
5466 the post (or mail). So---if you have both of these variables set, you
5467 will get two signatures. Note that @code{mail-signature} does not work
5468 the same way as @code{gnus-signature-file}, which is a bit confusing.
5469 If @code{mail-signature} is @code{t}, it will insert
5470 @file{~/.signature}. If it is a string, this string will be inserted.
5472 Note that RFC1036 says that a signature should be preceded by the three
5473 characters @samp{-- } on a line by themselves. This is to make it
5474 easier for the recipient to automatically recognize and process the
5475 signature. So don't remove those characters, even though you might feel
5476 that they ruin you beautiful design, like, totally.
5478 Also note that no signature should be more than four lines long.
5479 Including ASCII graphics is an efficient way to get everybody to believe
5480 that you are silly and have nothing important to say.
5482 @item mail-yank-prefix
5483 @vindex mail-yank-prefix
5486 When you are replying to or following up an article, you normally want
5487 to quote the person you are answering. Inserting quoted text is done by
5488 @dfn{yanking}, and each quoted line you yank will have
5489 @code{mail-yank-prefix} prepended to it. This is @code{nil} by default,
5490 which isn't very pretty---the prefix will just be some spaces. Most
5491 everybody prefers that lines are prepended with @samp{> }, so
5492 @code{(setq mail-yank-prefix "> ")} in your @file{.emacs} file.
5494 @item mail-yank-ignored-headers
5495 @vindex mail-yank-ignored-headers
5496 When you yank a message, you do not want to quote any headers, so
5497 @code{(setq mail-yank-ignored-headers "^")}.
5499 @item user-mail-address
5500 @vindex user-mail-address
5501 If all of @code{gnus-user-login-name}, @code{gnus-use-generic-from} and
5502 @code{gnus-local-domain} are @code{nil}, Gnus will use
5503 @code{user-mail-address} as the address part of the @code{From} header.
5505 @item gnus-local-domain
5506 @vindex gnus-local-domain
5508 The local doman name excluding the host name. If your host is called
5509 @samp{"narfi.ifi.uio.no"}, then this variable should be
5510 @samp{"ifi.uio.no"}.
5512 @item gnus-local-domain
5513 @vindex gnus-local-domain
5515 The local doman name excluding the host name. If your host is called
5516 @samp{"narfi.ifi.uio.no"}, then this variable should be
5517 @samp{"ifi.uio.no"}.
5519 @item gnus-user-from-line
5520 @vindex gnus-user-from-line
5521 Your full, complete e-mail address with name. This variable overrides
5522 the other Gnus variables if it is non-@code{nil}.
5524 Here are two example values of this variable: @samp{"larsi@@ifi.uio.no
5525 (Lars Magne Ingebrigtsen)"} and @samp{"Lars Magne Ingebrigtsen
5526 <larsi@@ifi.uio.no>"}. The latter version is recommended in news (and is
5527 probably illegal in mail), but the name has to be quoted if it contains
5528 non-alpha-numerical characters---@samp{"\"Lars M. Ingebrigtsen\"
5529 <larsi@@ifi.uio.no>"}.
5531 @item mail-default-headers
5532 @vindex mail-default-headers
5533 This is a string that will be inserted into the header of all outgoing
5534 mail messages and news articles. Convenient to use to insert standard
5535 headers. If @code{nntp-news-default-headers} is non-@code{nil}, that
5536 variable will override this one when posting articles.
5538 @item gnus-auto-mail-to-author
5539 @vindex gnus-auto-mail-to-author
5540 If @code{ask}, you will be prompted for whether you want to send a mail
5541 copy to the author of the article you are following up. If
5542 non-@code{nil} and not @code{ask}, Gnus will send a mail with a copy of
5543 all follow-ups to the authors of the articles you follow up. It's nice
5544 in one way---you make sure that the person you are responding to gets
5545 your response. Other people loathe this method and will hate you dearly
5546 for it, because it means that they will first get a mail, and then have
5547 to read the same article later when they read the news. It is
5548 @code{nil} by default.
5550 @item gnus-mail-courtesy-message
5551 @vindex gnus-mail-courtesy-message
5552 This is a string that will be prepended to all mails that are the result
5553 of using the variable described above.
5555 @item gnus-mailing-list-groups
5556 @findex gnus-mailing-list-groups
5557 @cindex mailing lists
5559 If your newsserver offer groups that are really mailing lists that are
5560 gatewayed to the @sc{nntp} server, you can read those groups without
5561 problems, but you can't post/followup to them without some difficulty.
5562 One solution is to add a @code{to-address} to the group parameters
5563 (@pxref{Group Parameters}). An easier thing to do is set the
5564 @code{gnus-mailing-list-groups} to a regexp that match the groups that
5565 really are mailing lists. Then, at least, followups to the mailing
5566 lists will work most of the time. Posting to these groups (@kbd{a}) is
5567 still a pain, though.
5572 You may want to do spell-checking on messages that you send out. Or, if
5573 you don't want to spell-check by hand, you could add automatic
5574 spell-checking via the @code{ispell} package:
5576 @vindex news-inews-hook
5578 (add-hook 'news-inews-hook 'ispell-message) ;For news posts
5579 (add-hook 'mail-send-hook 'ispell-message) ;for mail posts via sendmail
5582 @findex gnus-inews-insert-mime-headers
5583 If you want to insert some @sc{mime} headers into the articles you post,
5584 without doing any actual encoding, you could add
5585 @code{gnus-inews-insert-mime-headers} to @code{gnus-inews-article-hook}.
5589 @node Archived Messages
5590 @subsection Archived Messages
5591 @cindex archived messages
5592 @cindex sent messages
5594 Gnus provides a few different methods for storing the mail you send.
5595 The default method is to use the @dfn{archive virtual server} to store
5598 @vindex gnus-message-archive-method
5599 @code{gnus-message-archive-method} says what virtual server Gnus is to
5600 use to store sent messages. It is @code{(nnfolder "archive"
5601 (nnfolder-directory "~/Mail/archive/"))} by default, but you can use any
5602 mail select method (@code{nnml}, @code{nnmbox}, etc.). However,
5603 @code{nnfolder} is a quite likable select method for doing this sort of
5604 thing. If you don't like the default directory chosen, you could say
5608 (setq gnus-message-archive-method
5609 '((nnfolder "archive"
5610 (nnfolder-inhibit-expiry t)
5611 (nnfolder-active-file "~/Mail/sent-mail/active")
5612 (nnfolder-directory "~/News/sent-mail/"))))
5615 @vindex gnus-message-archive-group
5616 Gnus will insert @code{Gcc} headers in all outgoing messages that point
5617 to one or more group(s) on that server. Which group to use is
5618 determined by the @code{gnus-message-archive-group} variable.
5620 This variable can be:
5624 Messages will be saved in that group.
5625 @item a list of strings
5626 Messages will be saved in all those groups.
5627 @item an alist of regexps, functions and forms
5628 When a key ``matches'', the result is used.
5633 Just saving to a single group called @samp{"MisK"}:
5635 (setq gnus-message-archive-group "MisK")
5638 Saving to two groups, @samp{"MisK"} and @samp{"safe"}:
5640 (setq gnus-message-archive-group '("MisK" "safe"))
5643 Save to different groups based on what group you are in:
5645 (setq gnus-message-archive-group
5646 '(("^alt" "sent-to-alt")
5647 ("mail" "sent-to-mail")
5648 (".*" "sent-to-misc")))
5653 (setq gnus-message-archive-group
5654 '((if (eq major-mode news-reply-mode) "misc-news" "misc-mail")))
5657 This last one is the default.
5659 Now, when you send a message off, it will be stored in the appropriate
5660 group. (If you want to disable storing for just one particular article,
5661 you can just remove the @code{Gcc} header that has been inserted.) The
5662 archive group will appear in the group buffer the next time you start
5663 Gnus, or the next time you press @kbd{F} in the group buffer. You can
5664 enter it and read the articles in it just like you'd read any other
5665 group. If the group gets really big and annoying, you can simply rename
5666 if (using @kbd{G r} in the group buffer) to something nice --
5667 @samp{"misc-mail-september-1995"}, or whatever. New messages will
5668 continue to be stored in the old (now empty) group.
5671 That's the default method of archiving sent mail. Gnus also offers two
5672 other variables for the people who don't like the default method. In
5673 that case you should set @code{gnus-message-archive-group} to
5674 @code{nil}; this will disable archiving.
5677 @item gnus-author-copy
5678 @vindex gnus-author-copy
5679 This is a file name, and all outgoing articles will be saved in that
5680 file. Initialized from the @code{AUTHORCOPY} environment variable.
5682 If this variable begins with the character @samp{"|"}, outgoing articles
5683 will be piped to the named program. It is possible to save an article in
5684 an MH folder as follows:
5687 (setq gnus-author-copy
5688 "|/usr/local/lib/mh/rcvstore +Article")
5691 If the first character is not a pipe, articles are saved using the
5692 function specified by the @code{gnus-author-copy-saver} variable.
5694 @item gnus-author-copy-saver
5695 @vindex gnus-author-copy-saver
5696 A function called to save outgoing articles. This function will be
5697 called with the same of the file to store the article in. The default
5698 function is @code{rmail-output} which saves in the Unix mailbox format.
5700 @item gnus-mail-self-blind
5701 @vindex gnus-mail-self-blind
5702 Non-@code{nil} means insert a BCC header in all outgoing articles
5703 pointing to yourself. This will result you receiving a copy of the
5704 article mailed to yourself. The BCC header is inserted when the post
5705 buffer is initialized, so you can remove or alter the BCC header to
5706 override the default.
5708 @item gnus-outgoing-message-group
5709 @vindex gnus-outgoing-message-group
5710 All outgoing messages will be put in this group. If you want to store
5711 all your outgoing mail and articles in the group @samp{nnml:archive},
5712 you set this variable to that value. This variable can also be a list of
5715 If you want to have greater control over what group to put each
5716 message in, you can set this variable to a function that checks the
5717 current newsgroup name and then returns a suitable group name (or list
5722 @node Posting Styles
5723 @subsection Posting Styles
5724 @cindex posting styles
5727 All them variables, they make my head swim.
5729 So what if you want a different @code{Organization} and signature based
5730 on what groups you post to? And you post both from your home machine
5731 and your work machine, and you want different @code{From} lines, and so
5734 @vindex gnus-posting-styles
5735 One way to do stuff like that is to write clever hooks that change the
5736 variables you need to have changed. That's a bit boring, so somebody
5737 came up with the bright idea of letting the user specify these things in
5738 a handy alist. Here's an example of a @code{gnus-posting-styles}
5742 ((".*" (signature . "Peace and happiness") (organization . "What me?"))
5743 ("^comp" (signature . "Death to everybody"))
5744 ("comp.emacs.i-love-it" (organization . "Emacs is it")))
5747 As you might surmise from this example, this alist consists of several
5748 @dfn{styles}. Each style will be applicable if the first element
5749 ``matches'', in some form or other. The entire alist will be iterated
5750 over, from the beginning towards the end, and each match will be
5751 applied, which means that attributes in later styles that match override
5752 the same attributes in earlier matching styles. So
5753 @samp{comp.programming.literate} will have the @samp{Death to everybody}
5754 signature and the @samp{What me?} @code{Organization} header.
5756 The first element in each style is called the @code{match}. If it's a
5757 string, then Gnus will try to regexp match it against the group name.
5758 If it's a function symbol, that function will be called with no
5759 arguments. If it's a variable symbol, then the variable will be
5760 referenced. If it's a list, then that list will be @code{eval}ed. In
5761 any case, if this returns a non-@code{nil} value, then the style is said
5764 Each style may contain a random amount of @dfn{attributes}. Each
5765 attribute consists of a @var{(name . value)} pair. The attribute name
5766 can be one of @code{signature}, @code{organization} or @code{from}.
5767 The attribute name can also be a string. In that case, this will be
5768 used as a header name, and the value will be inserted in the headers of
5771 The attribute value can be a string (used verbatim), a function (the
5772 return value will be used), a variable (its value will be used) or a
5773 list (it will be @code{eval}ed and the return value will be used).
5775 So here's a new example:
5778 (setq gnus-posting-styles
5780 (signature . "~/.signature")
5781 (from . "user@@foo (user)")
5782 ("X-Home-Page" . (getenv "WWW_HOME"))
5783 (organization . "People's Front Against MWM"))
5785 (signature . my-funny-signature-randomizer))
5786 ((equal (system-name) "gnarly")
5787 (signature . my-quote-randomizer))
5788 (posting-from-work-p
5789 (signature . "~/.work-signature")
5790 (from . "user@@bar.foo (user)")
5791 (organization . "Important Work, Inc"))
5793 (signature . "~/.mail-signature"))))
5802 If you are writing a message (mail or news) and suddenly remember that
5803 you have a steak in the oven (or some pesto in the food processor, you
5804 craazy vegetarians), you'll probably wish there was a method to save the
5805 message you are writing so that you can continue editing it some other
5806 day, and send it when you feel its finished.
5808 Well, don't worry about it. Whenever you start composing a message of
5809 some sort using the Gnus mail and post commands, the buffer you get will
5810 automatically associate to an article in a special @dfn{draft} group.
5811 If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
5812 article will be saved there. (Auto-save files also go to the draft
5815 The draft group is a special group (which is implemented as an
5816 @code{nndraft} group, if you absolutely have to know) called
5817 @samp{nndraft:drafts}. The variable @code{gnus-draft-group-directory}
5818 controls both the name of the group and the location---the leaf element
5819 in the path will be used as the name of the group. What makes this
5820 group special is that you can't tick any articles in it or mark any
5821 articles as read---all articles in the group are permanently unread.
5823 If the group doesn't exist, it will be created and you'll be subscribed
5826 @findex gnus-dissociate-buffer-from-draft
5827 @kindex C-c M-d (Mail)
5828 @kindex C-c M-d (Post)
5829 @findex gnus-associate-buffer-with-draft
5830 @kindex C-c C-d (Mail)
5831 @kindex C-c C-d (Post)
5832 If you're writing some super-secret message that you later want to
5833 encode with PGP before sending, you may wish to turn the auto-saving
5834 (and association with the draft group) off. You never know who might be
5835 interested in reading all your extremely valuable and terribly horrible
5836 and interesting secrets. The @kbd{C-c M-d}
5837 (@code{gnus-dissociate-buffer-from-draft}) command does that for you.
5838 If you change your mind and want to turn the auto-saving back on again,
5839 @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that.
5841 @vindex gnus-use-draft
5842 To leave association with the draft group off by default, set
5843 @code{gnus-use-draft} to @code{nil}. It is @code{t} by default.
5845 @findex gnus-summary-send-draft
5846 @kindex S D c (Summary)
5847 When you want to continue editing the article, you simply enter the
5848 draft group and push @kbd{S D c} (@code{gnus-summary-send-draft}) to do
5849 that. You will be placed in a buffer where you left off.
5851 Rejected articles will also be put in this draft group (@pxref{Rejected
5854 @findex gnus-summary-send-all-drafts
5855 If you have lots of rejected messages you want to post (or mail) without
5856 doing further editing, you can use the @kbd{S D a} command
5857 (@code{gnus-summary-send-all-drafts}). This command understands the
5858 process/prefix convention (@pxref{Process/Prefix}).
5861 @node Rejected Articles
5862 @subsection Rejected Articles
5863 @cindex rejected articles
5865 Sometimes a news server will reject an article. Perhaps the server
5866 doesn't like your face. Perhaps it just feels miserable. Perhaps
5867 @emph{there be demons}. Perhaps you have included too much cited text.
5868 Perhaps the disk is full. Perhaps the server is down.
5870 These situations are, of course, totally beyond the control of Gnus.
5871 (Gnus, of course, loves the way you look, always feels great, has angels
5872 fluttering around inside of it, doesn't care about how much cited text
5873 you include, never runs full and never goes down.) So Gnus saves these
5874 articles until some later time when the server feels better.
5876 The rejected articles will automatically be put in a special draft group
5877 (@pxref{Drafts}). When the server comes back up again, you'd then
5878 typically enter that group and send all the articles off.
5881 @node Canceling and Superseding
5882 @section Canceling Articles
5883 @cindex canceling articles
5884 @cindex superseding articles
5886 Have you ever written something, and then decided that you really,
5887 really, really wish you hadn't posted that?
5889 Well, you can't cancel mail, but you can cancel posts.
5891 @findex gnus-summary-cancel-article
5893 Find the article you wish to cancel (you can only cancel your own
5894 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
5895 c} (@code{gnus-summary-cancel-article}). Your article will be
5896 canceled---machines all over the world will be deleting your article.
5898 Be aware, however, that not all sites honor cancels, so your article may
5899 live on here and there, while most sites will delete the article in
5902 If you discover that you have made some mistakes and want to do some
5903 corrections, you can post a @dfn{superseding} article that will replace
5904 your original article.
5906 @findex gnus-summary-supersede-article
5908 Go to the original article and press @kbd{S s}
5909 (@code{gnus-summary-supersede-article}). You will be put in a buffer
5910 where you can edit the article all you want before sending it off the
5913 @vindex gnus-delete-supersedes-headers
5914 You probably want to delete some of the old headers before sending the
5915 superseding article---@code{Path} and @code{Date} are probably
5916 incorrect. Set @code{gnus-delete-supersedes-headers} to a regexp to
5917 match the lines you want removed. The default is
5918 @samp{"^Path:\\|^Date"}.
5920 The same goes for superseding as for canceling, only more so: Some
5921 sites do not honor superseding. On those sites, it will appear that you
5922 have posted almost the same article twice.
5924 If you have just posted the article, and change your mind right away,
5925 there is a trick you can use to cancel/supersede the article without
5926 waiting for the article to appear on your site first. You simply return
5927 to the post buffer (which is called @code{*post-buf*}). There you will
5928 find the article you just posted, with all the headers intact. Change
5929 the @samp{Message-ID} header to a @samp{Cancel} or @samp{Supersedes}
5930 header by substituting one of those words for @samp{Message-ID}. Then
5931 just press @kbd{C-c C-c} to send the article as you would do normally.
5932 The previous article will be canceled/superseded.
5934 Just remember, kids: There is no 'c' in 'supersede'.
5936 @node Marking Articles
5937 @section Marking Articles
5938 @cindex article marking
5939 @cindex article ticking
5942 There are several marks you can set on an article.
5944 You have marks that decide the @dfn{readed-ness} (whoo, neato-keano
5945 neologism ohoy!) of the article. Alphabetic marks generally mean
5946 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
5948 In addition, you also have marks that do not affect readedness.
5951 * Unread Articles:: Marks for unread articles.
5952 * Read Articles:: Marks for read articles.
5953 * Other Marks:: Marks that do not affect readedness.
5957 There's a plethora of commands for manipulating these marks:
5961 * Setting Marks:: How to set and remove marks.
5962 * Setting Process Marks:: How to mark articles for later processing.
5965 @node Unread Articles
5966 @subsection Unread Articles
5968 The following marks mark articles as unread, in one form or other.
5970 @vindex gnus-dormant-mark
5971 @vindex gnus-ticked-mark
5974 @dfn{Ticked articles} are articles that will remain visible always. If
5975 you see an article that you find interesting, or you want to put off
5976 reading it, or replying to it, until sometime later, you'd typically
5977 tick it. However, articles can be expired, so if you want to keep an
5978 article forever, you'll have to save it. Ticked articles have a
5979 @samp{!} (@code{gnus-ticked-mark}) in the first column.
5982 A @dfn{dormant} article is marked with a @samp{?}
5983 (@code{gnus-dormant-mark}), and will only appear in the summary buffer
5984 if there are followups to it.
5987 An @dfn{unread} article is marked with a @samp{SPC}
5988 (@code{gnus-unread-mark}). These are articles that haven't been read at
5993 @subsection Read Articles
5994 @cindex expirable mark
5996 All the following marks mark articles as read.
6001 Articles that are marked as read. They have a @samp{r}
6002 (@code{gnus-del-mark}) in the first column. These are articles that the
6003 user has marked as read more or less manually.
6006 Articles that are actually read are marked with @samp{R}
6007 (@code{gnus-read-mark}).
6010 Articles that were marked as read in previous sessions are now
6011 @dfn{old} and marked with @samp{O} (@code{gnus-ancient-mark}).
6014 Marked as killed (@code{gnus-killed-mark}).
6017 Marked as killed by kill files (@code{gnus-kill-file-mark}).
6020 Marked as read by having a too low score (@code{gnus-low-score-mark}).
6023 Marked as read by a catchup (@code{gnus-catchup-mark}).
6026 Canceled article (@code{gnus-cancelled-mark})
6029 All these marks just mean that the article is marked as read, really.
6030 They are interpreted differently by the adaptive scoring scheme,
6033 One more special mark, though:
6037 You can also mark articles as @dfn{expirable} (or have them marked as
6038 such automatically). That doesn't make much sense in normal groups,
6039 because a user does not control the expiring of news articles, but in
6040 mail groups, for instance, articles that are marked as @dfn{expirable}
6041 can be deleted by Gnus at any time. Expirable articles are marked with
6042 @samp{E} (@code{gnus-expirable-mark}).
6046 @subsection Other Marks
6047 @cindex process mark
6050 There are some marks that have nothing to do with whether the article is
6056 You can set a bookmark in the current article. Say you are reading a
6057 long thesis on cats' urinary tracts, and have to go home for dinner
6058 before you've finished reading the thesis. You can then set a bookmark
6059 in the article, and Gnus will jump to this bookmark the next time it
6060 encounters the article.
6063 All articles that you have replied to or made a followup to (i.e., have
6064 answered) will be marked with an @samp{A} in the second column
6065 (@code{gnus-replied-mark}).
6068 Articles that are stored in the article cache will be marked with an
6069 @samp{*} in the second column (@code{gnus-cached-mark}).
6072 Articles that are ``saved'' (in some manner or other; not necessarily
6073 religously) are marked with an @samp{S} in the second column
6074 (@code{gnus-saved-mark}.
6077 @vindex gnus-not-empty-thread-mark
6078 @vindex gnus-empty-thread-mark
6079 It the @samp{%e} spec is used, the presence of threads or not will be
6080 marked with @code{gnus-not-empty-thread-mark} and
6081 @code{gnus-empty-thread-mark} in the third column, respectively.
6084 @vindex gnus-process-mark
6085 Finally we have the @dfn{process mark} (@code{gnus-process-mark}. A
6086 variety of commands react to the presence of the process mark. For
6087 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
6088 all articles that have been marked with the process mark. Articles
6089 marked with the process mark have a @samp{#} in the second column.
6093 You might have noticed that most of these ``non-readedness'' marks appear
6094 in the second column by default. So if you have a cached, saved,
6095 replied article that you have process-marked, what will that look like?
6097 Nothing much. The presedence rules go as follows: process -> cache ->
6098 replied -> saved. So if the article is in the cache and is replied,
6099 you'll only see the cache mark and not the replied mark.
6103 @subsection Setting Marks
6104 @cindex setting marks
6106 All the marking commands understand the numeric prefix.
6112 @kindex M t (Summary)
6113 @findex gnus-summary-tick-article-forward
6114 Tick the current article (@code{gnus-summary-tick-article-forward}).
6119 @kindex M ? (Summary)
6120 @findex gnus-summary-mark-as-dormant
6121 Mark the current article as dormant
6122 (@code{gnus-summary-mark-as-dormant}).
6126 @kindex M d (Summary)
6128 @findex gnus-summary-mark-as-read-forward
6129 Mark the current article as read
6130 (@code{gnus-summary-mark-as-read-forward}).
6135 @kindex M k (Summary)
6136 @findex gnus-summary-kill-same-subject-and-select
6137 Mark all articles that have the same subject as the current one as read,
6138 and then select the next unread article
6139 (@code{gnus-summary-kill-same-subject-and-select}).
6143 @kindex M K (Summary)
6144 @kindex C-k (Summary)
6145 @findex gnus-summary-kill-same-subject
6146 Mark all articles that have the same subject as the current one as read
6147 (@code{gnus-summary-kill-same-subject}).
6150 @kindex M C (Summary)
6151 @findex gnus-summary-catchup
6152 Mark all unread articles in the group as read
6153 (@code{gnus-summary-catchup}).
6156 @kindex M C-c (Summary)
6157 @findex gnus-summary-catchup-all
6158 Mark all articles in the group as read---even the ticked and dormant
6159 articles (@code{gnus-summary-catchup-all}).
6162 @kindex M H (Summary)
6163 @findex gnus-summary-catchup-to-here
6164 Catchup the current group to point
6165 (@code{gnus-summary-catchup-to-here}).
6168 @kindex C-w (Summary)
6169 @findex gnus-summary-mark-region-as-read
6170 Mark all articles between point and mark as read
6171 (@code{gnus-summary-mark-region-as-read}).
6174 @kindex M V k (Summary)
6175 @findex gnus-summary-kill-below
6176 Kill all articles with scores below the default score (or below the
6177 numeric prefix) (@code{gnus-summary-kill-below}).
6181 @kindex M c (Summary)
6182 @kindex M-u (Summary)
6183 @findex gnus-summary-clear-mark-forward
6184 Clear all readedness-marks from the current article
6185 (@code{gnus-summary-clear-mark-forward}).
6189 @kindex M e (Summary)
6191 @findex gnus-summary-mark-as-expirable
6192 Mark the current article as expirable
6193 (@code{gnus-summary-mark-as-expirable}).
6196 @kindex M b (Summary)
6197 @findex gnus-summary-set-bookmark
6198 Set a bookmark in the current article
6199 (@code{gnus-summary-set-bookmark}).
6202 @kindex M B (Summary)
6203 @findex gnus-summary-remove-bookmark
6204 Remove the bookmark from the current article
6205 (@code{gnus-summary-remove-bookmark}).
6208 @kindex M V c (Summary)
6209 @findex gnus-summary-clear-above
6210 Clear all marks from articles with scores over the default score (or
6211 over the numeric prefix) (@code{gnus-summary-clear-above}).
6214 @kindex M V u (Summary)
6215 @findex gnus-summary-tick-above
6216 Tick all articles with scores over the default score (or over the
6217 numeric prefix) (@code{gnus-summary-tick-above}).
6220 @kindex M V m (Summary)
6221 @findex gnus-summary-mark-above
6222 Prompt for a mark, and mark all articles with scores over the default
6223 score (or over the numeric prefix) with this mark
6224 (@code{gnus-summary-clear-above}).
6227 @code{gnus-summary-goto-unread} The @code{gnus-summary-goto-unread}
6228 variable controls what action should be taken after setting a mark. If
6229 non-@code{nil}, point will move to the next/previous unread article. If
6230 @code{nil}, point will just move one line up or down. As a special
6231 case, if this variable is @code{never}, all the marking commands as well
6232 as other commands (like @kbd{SPC}) will move to the next article,
6233 whether it is unread or not. The default is @code{t}.
6236 @node Setting Process Marks
6237 @subsection Setting Process Marks
6238 @cindex setting process marks
6245 @kindex M P p (Summary)
6246 @findex gnus-summary-mark-as-processable
6247 Mark the current article with the process mark
6248 (@code{gnus-summary-mark-as-processable}).
6249 @findex gnus-summary-unmark-as-processable
6253 @kindex M P u (Summary)
6254 @kindex M-# (Summary)
6255 Remove the process mark, if any, from the current article
6256 (@code{gnus-summary-unmark-as-processable}).
6259 @kindex M P U (Summary)
6260 @findex gnus-summary-unmark-all-processable
6261 Remove the process mark from all articles
6262 (@code{gnus-summary-unmark-all-processable}).
6265 @kindex M P R (Summary)
6266 @findex gnus-uu-mark-by-regexp
6267 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
6270 @kindex M P r (Summary)
6271 @findex gnus-uu-mark-region
6272 Mark articles in region (@code{gnus-uu-mark-region}).
6275 @kindex M P t (Summary)
6276 @findex gnus-uu-mark-thread
6277 Mark all articles in the current (sub)thread
6278 (@code{gnus-uu-mark-thread}).
6281 @kindex M P T (Summary)
6282 @findex gnus-uu-unmark-thread
6283 Unmark all articles in the current (sub)thread
6284 (@code{gnus-uu-unmark-thread}).
6287 @kindex M P v (Summary)
6288 @findex gnus-uu-mark-over
6289 Mark all articles that have a score above the prefix argumnet
6290 (@code{gnus-uu-mark-over}).
6293 @kindex M P s (Summary)
6294 @findex gnus-uu-mark-series
6295 Mark all articles in the current series (@code{gnus-uu-mark-series}).
6298 @kindex M P S (Summary)
6299 @findex gnus-uu-mark-sparse
6300 Mark all series that have already had some articles marked
6301 (@code{gnus-uu-mark-sparse}).
6304 @kindex M P a (Summary)
6305 @findex gnus-uu-mark-all
6306 Mark all articles in series order (@code{gnus-uu-mark-series}).
6309 @kindex M P b (Summary)
6310 @findex gnus-uu-mark-buffer
6311 Mark all articles in the buffer in the order they appear
6312 (@code{gnus-uu-mark-buffer}).
6320 It can be convenient to limit the summary buffer to just show some
6321 subset of the articles currently in the group. The effect most limit
6322 commands have is to remove a few (or many) articles from the summary
6329 @kindex / / (Summary)
6330 @findex gnus-summary-limit-to-subject
6331 Limit the summary buffer to articles that match some subject
6332 (@code{gnus-summary-limit-to-subject}).
6335 @kindex / a (Summary)
6336 @findex gnus-summary-limit-to-author
6337 Limit the summary buffer to articles that match some author
6338 (@code{gnus-summary-limit-to-author}).
6342 @kindex / u (Summary)
6344 @findex gnus-summary-limit-to-unread
6345 Limit the summary buffer to articles that are not marked as read
6346 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
6347 buffer to articles that are strictly unread. This means that ticked and
6348 dormant articles will also be excluded.
6351 @kindex / m (Summary)
6352 @findex gnus-summary-limit-to-marks
6353 Ask for a mark and then limit to all articles that have not been marked
6354 with that mark (@code{gnus-summary-limit-to-marks}).
6357 @kindex / n (Summary)
6358 @findex gnus-summary-limit-to-articles
6359 Limit the summary buffer to the current article
6360 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
6361 convention (@pxref{Process/Prefix}).
6364 @kindex / w (Summary)
6365 @findex gnus-summary-pop-limit
6366 Pop the previous limit off the stack and restore it
6367 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
6371 @kindex / v (Summary)
6372 @findex gnus-summary-limit-to-score
6373 Limit the summary buffer to articles that have a score at or above some
6374 score (@code{gnus-summary-limit-to-score}).
6378 @kindex M S (Summary)
6379 @kindex / E (Summary)
6380 @findex gnus-summary-limit-include-expunged
6381 Display all expunged articles
6382 (@code{gnus-summary-limit-include-expunged}).
6385 @kindex / D (Summary)
6386 @findex gnus-summary-limit-include-dormant
6387 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
6390 @kindex / d (Summary)
6391 @findex gnus-summary-limit-exclude-dormant
6392 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
6395 @kindex / c (Summary)
6396 @findex gnus-summary-limit-exclude-childless-dormant
6397 Hide all dormant articles that have no children
6398 (@code{gnus-summary-limit-exclude-childless-dormant}).
6401 @kindex / C (Summary)
6402 @findex gnus-summary-limit-mark-excluded-as-read
6403 Mark all excluded unread articles as read
6404 (@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix,
6405 also mark exluded ticked and dormant articles as read.
6413 @cindex article threading
6415 Gnus threads articles by default. @dfn{To thread} is to put replies to
6416 articles directly after the articles they reply to---in a hierarchical
6420 * Customizing Threading:: Variables you can change to affect the threading.
6421 * Thread Commands:: Thread based commands in the summary buffer.
6424 @node Customizing Threading
6425 @subsection Customizing Threading
6426 @cindex customizing threading
6432 @item gnus-show-threads
6433 @vindex gnus-show-threads
6434 If this variable is @code{nil}, no threading will be done, and all of
6435 the rest of the variables here will have no effect. Turning threading
6436 off will speed group selection up a bit, but it is sure to make reading
6437 slower and more awkward.
6439 @item gnus-fetch-old-headers
6440 @vindex gnus-fetch-old-headers
6441 If non-@code{nil}, Gnus will attempt to build old threads by fetching
6442 more old headers---headers to articles that are marked as read. If you
6443 would like to display as few summary lines as possible, but still
6444 connect as many loose threads as possible, you should set this variable
6445 to @code{some} or a number. If you set it to a number, no more than
6446 that number of extra old headers will be fetched. In either case,
6447 fetching old headers only works if the backend you are using carries
6448 overview files---this would normally be @code{nntp}, @code{nnspool} and
6449 @code{nnml}. Also remember that if the root of the thread has been
6450 expired by the server, there's not much Gnus can do about that.
6452 @item gnus-build-sparse-threads
6453 @vindex gnus-build-sparse-threads
6454 Fetching old headers can be slow. A low-rent similar effect can be
6455 gotten by setting this variable to @code{some}. Gnus will then look at
6456 the complete @code{References} headers of all articles and try to string
6457 articles that belong in the same thread together. This will leave
6458 @dfn{gaps} in the threading display where Gnus guesses that an article
6459 is missing from the thread. (These gaps appear like normal summary
6460 lines. If you select a gap, Gnus will try to fetch the article in
6461 question.) If this variable is @code{t}, Gnus will display all these
6462 ``gaps'' without regard for whether they are useful for completing the
6463 thread or not. Finally, if this variable is @code{more}, Gnus won't cut
6464 off sparse leaf nodes that don't lead anywhere. This variable is
6465 @code{nil} by default.
6467 @item gnus-summary-gather-subject-limit
6468 @vindex gnus-summary-gather-subject-limit
6469 Loose threads are gathered by comparing subjects of articles. If this
6470 variable is @code{nil}, Gnus requires an exact match between the
6471 subjects of the loose threads before gathering them into one big
6472 super-thread. This might be too strict a requirement, what with the
6473 presence of stupid newsreaders that chop off long subjects lines. If
6474 you think so, set this variable to, say, 20 to require that only the
6475 first 20 characters of the subjects have to match. If you set this
6476 variable to a really low number, you'll find that Gnus will gather
6477 everything in sight into one thread, which isn't very helpful.
6479 @cindex fuzzy article gathering
6480 If you set this variable to the special value @code{fuzzy}, Gnus will
6481 use a fuzzy string comparison algorithm on the subjects.
6483 @item gnus-simplify-ignored-prefixes
6484 @vindex gnus-simplify-ignored-prefixes
6485 If you set @code{gnus-summary-gather-subject-limit} to something as low
6486 as 10, you might consider setting this variable to something sensible:
6488 @c Written by Michael Ernst <mernst@cs.rice.edu>
6490 (setq gnus-simplify-ignored-prefixes
6493 (mapconcat 'identity
6495 "wanted" "followup" "summary\\( of\\)?"
6496 "help" "query" "problem" "question"
6497 "answer" "reference" "announce"
6498 "How can I" "How to" "Comparison of"
6503 (mapconcat 'identity
6504 '("for" "for reference" "with" "about")
6506 "\\)?\\]?:?[ \t]*"))
6509 All words that match this regexp will be removed before comparing two
6512 @item gnus-summary-gather-exclude-subject
6513 @vindex gnus-summary-gather-exclude-subject
6514 Since loose thread gathering is done on subjects only, that might lead
6515 to many false hits, especially with certain common subjects like
6516 @samp{""} and @samp{"(none)"}. To make the situation slightly better,
6517 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
6518 what subjects should be excluded from the gathering process. The
6519 default is @samp{"^ *$\\|^(none)$"}.
6521 @item gnus-summary-thread-gathering-function
6522 @vindex gnus-summary-thread-gathering-function
6523 Gnus gathers threads by looking at @code{Subject} headers. This means
6524 that totally unrelated articles may end up in the same ``thread'', which
6525 is confusing. An alternate approach is to look at all the
6526 @code{Message-ID}s in all the @code{References} headers to find
6527 matches. This will ensure that no gathered threads ever includes
6528 unrelated articles, but it's also means that people who have posted with
6529 broken newsreaders won't be gathered properly. The choice is
6530 yours---plague or cholera:
6533 @item gnus-summary-gather-threads-by-subject
6534 @findex gnus-summary-gather-threads-by-subject
6535 This function is the default gathering function and looks at
6536 @code{Subject}s exclusively.
6538 @item gnus-summary-gather-threads-by-references
6539 @findex gnus-summary-gather-threads-by-references
6540 This function looks at @code{References} headers exclusively.
6543 If you want to test gathering by @code{References}, you could say
6547 (setq gnus-summary-thread-gathering-function
6548 'gnus-summary-gather-threads-by-references)
6551 @item gnus-summary-make-false-root
6552 @vindex gnus-summary-make-false-root
6553 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
6554 and create a dummy root at the top. (Wait a minute. Root at the top?
6555 Yup.) Loose subtrees occur when the real root has expired, or you've
6556 read or killed the root in a previous session.
6558 When there is no real root of a thread, Gnus will have to fudge
6559 something. This variable says what fudging method Gnus should use.
6560 There are four possible values:
6562 @cindex adopting articles
6567 Gnus will make the first of the orphaned articles the parent. This
6568 parent will adopt all the other articles. The adopted articles will be
6569 marked as such by pointy brackets (@samp{<>}) instead of the standard
6570 square brackets (@samp{[]}). This is the default method.
6573 Gnus will create a dummy summary line that will pretend to be the
6574 parent. This dummy line does not correspond to any real article, so
6575 selecting it will just select the first real article after the dummy
6579 Gnus won't actually make any article the parent, but simply leave the
6580 subject field of all orphans except the first empty. (Actually, it will
6581 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
6585 Don't make any article parent at all. Just gather the threads and
6586 display them after one another.
6589 Don't gather loose threads.
6592 @item gnus-thread-hide-subtree
6593 @vindex gnus-thread-hide-subtree
6594 If non-@code{nil}, all threads will be hidden when the summary buffer is
6597 @item gnus-thread-hide-killed
6598 @vindex gnus-thread-hide-killed
6599 if you kill a thread and this variable is non-@code{nil}, the subtree
6602 @item gnus-thread-ignore-subject
6603 @vindex gnus-thread-ignore-subject
6604 Sometimes somebody changes the subject in the middle of a thread. If
6605 this variable is non-@code{nil}, the subject change is ignored. If it
6606 is @code{nil}, which is the default, a change in the subject will result
6609 @item gnus-thread-indent-level
6610 @vindex gnus-thread-indent-level
6611 This is a number that says how much each sub-thread should be indented.
6612 The default is @samp{4}.
6615 @node Thread Commands
6616 @subsection Thread Commands
6617 @cindex thread commands
6623 @kindex T k (Summary)
6624 @kindex M-C-k (Summary)
6625 @findex gnus-summary-kill-thread
6626 Mark all articles in the current sub-thread as read
6627 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
6628 remove all marks instead. If the prefix argument is negative, tick
6633 @kindex T l (Summary)
6634 @kindex M-C-l (Summary)
6635 @findex gnus-summary-lower-thread
6636 Lower the score of the current thread
6637 (@code{gnus-summary-lower-thread}).
6640 @kindex T i (Summary)
6641 @findex gnus-summary-raise-thread
6642 Increase the score of the current thread
6643 (@code{gnus-summary-raise-thread}).
6646 @kindex T # (Summary)
6647 @findex gnus-uu-mark-thread
6648 Set the process mark on the current thread
6649 (@code{gnus-uu-mark-thread}).
6652 @kindex T M-# (Summary)
6653 @findex gnus-uu-unmark-thread
6654 Remove the process mark from the current thread
6655 (@code{gnus-uu-unmark-thread}).
6658 @kindex T T (Summary)
6659 @findex gnus-summary-toggle-threads
6660 Toggle threading (@code{gnus-summary-toggle-threads}).
6663 @kindex T s (Summary)
6664 @findex gnus-summary-show-thread
6665 Expose the thread hidden under the current article, if any
6666 (@code{gnus-summary-show-thread}).
6669 @kindex T h (Summary)
6670 @findex gnus-summary-hide-thread
6671 Hide the current (sub)thread (@code{gnus-summary-hide-thread}).
6674 @kindex T S (Summary)
6675 @findex gnus-summary-show-all-threads
6676 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
6679 @kindex T H (Summary)
6680 @findex gnus-summary-hide-all-threads
6681 Hide all threads (@code{gnus-summary-hide-all-threads}).
6684 @kindex T t (Summary)
6685 @findex gnus-summary-rethread-current
6686 Re-thread the thread the current article is part of
6687 (@code{gnus-summary-rethread-current}). This works even when the
6688 summary buffer is otherwise unthreaded.
6691 @kindex T ^ (Summary)
6692 @findex gnus-summary-reparent-thread
6693 Make the current article the child of the marked (or previous) article
6694 (@code{gnus-summary-reparent-thread}.
6698 The following commands are thread movement commands. They all
6699 understand the numeric prefix.
6704 @kindex T n (Summary)
6705 @findex gnus-summary-next-thread
6706 Go to the next thread (@code{gnus-summary-next-thread}).
6709 @kindex T p (Summary)
6710 @findex gnus-summary-prev-thread
6711 Go to the previous thread (@code{gnus-summary-prev-thread}).
6714 @kindex T d (Summary)
6715 @findex gnus-summary-down-thread
6716 Descend the thread (@code{gnus-summary-down-thread}).
6719 @kindex T u (Summary)
6720 @findex gnus-summary-up-thread
6721 Ascend the thread (@code{gnus-summary-up-thread}).
6724 @kindex T o (Summary)
6725 @findex gnus-summary-top-thread
6726 Go to the top of the thread (@code{gnus-summary-top-thread}).
6729 @vindex gnus-thread-operation-ignore-subject
6730 If you ignore subject while threading, you'll naturally end up with
6731 threads that have several different subjects in them. If you then issue
6732 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
6733 wish to kill the entire thread, but just those parts of the thread that
6734 have the same subject as the current article. If you like this idea,
6735 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If is
6736 is non-@code{nil} (which it is by default), subjects will be ignored
6737 when doing thread commands. If this variable is @code{nil}, articles in
6738 the same thread with different subjects will not be included in the
6739 operation in question. If this variable is @code{fuzzy}, only articles
6740 that have subjects that are fuzzily equal will be included.
6743 @node Asynchronous Fetching
6744 @section Asynchronous Article Fetching
6745 @cindex asynchronous article fetching
6747 If you read your news from an @sc{nntp} server that's far away, the
6748 network latencies may make reading articles a chore. You have to wait
6749 for a while after pressing @kbd{n} to go to the next article before the
6750 article appears. Why can't Gnus just go ahead and fetch the article
6751 while you are reading the previous one? Why not, indeed.
6753 First, some caveats. There are some pitfalls to using asynchronous
6754 article fetching, especially the way Gnus does it.
6756 Let's say you are reading article 1, which is short, and article 2 is
6757 quite long, and you are not interested in reading that. Gnus does not
6758 know this, so it goes ahead and fetches article 2. You decide to read
6759 article 3, but since Gnus is in the process of fetching article 2, the
6760 connection is blocked.
6762 To avoid these situations, Gnus will open two (count 'em two)
6763 connections to the server. Some people may think this isn't a very nice
6764 thing to do, but I don't see any real alternatives. Setting up that
6765 extra connection takes some time, so Gnus startup will be slower.
6767 Gnus will fetch more articles than you will read. This will mean that
6768 the link between your machine and the @sc{nntp} server will become more
6769 loaded than if you didn't use article pre-fetch. The server itself will
6770 also become more loaded---both with the extra article requests, and the
6773 Ok, so now you know that you shouldn't really use this thing... unless
6776 @vindex gnus-asynchronous
6777 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
6778 happen automatically.
6780 @vindex nntp-async-number
6781 You can control how many articles that are to be pre-fetched by setting
6782 @code{nntp-async-number}. This is five by default, which means that when
6783 you read an article in the group, @code{nntp} will pre-fetch the next
6784 five articles. If this variable is @code{t}, @code{nntp} will pre-fetch
6785 all the articles that it can without bound. If it is @code{nil}, no
6786 pre-fetching will be made.
6788 @vindex gnus-asynchronous-article-function
6789 You may wish to create some sort of scheme for choosing which articles
6790 that @code{nntp} should consider as candidates for pre-fetching. For
6791 instance, you may wish to pre-fetch all articles with high scores, and
6792 not pre-fetch low-scored articles. You can do that by setting the
6793 @code{gnus-asynchronous-article-function}, which will be called with an
6794 alist where the keys are the article numbers. Your function should
6795 return an alist where the articles you are not interested in have been
6796 removed. You could also do sorting on article score and the like.
6798 @node Article Caching
6799 @section Article Caching
6800 @cindex article caching
6803 If you have an @emph{extremely} slow @sc{nntp} connection, you may
6804 consider turning article caching on. Each article will then be stored
6805 locally under your home directory. As you may surmise, this could
6806 potentially use @emph{huge} amounts of disk space, as well as eat up all
6807 your inodes so fast it will make your head swim. In vodka.
6809 Used carefully, though, it could be just an easier way to save articles.
6811 @vindex gnus-use-long-file-name
6812 @vindex gnus-cache-directory
6813 @vindex gnus-use-cache
6814 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
6815 all articles that are ticked or marked as dormant will then be copied
6816 over to your local cache (@code{gnus-cache-directory}). Whether this
6817 cache is flat or hierarchal is controlled by the
6818 @code{gnus-use-long-file-name} variable, as usual.
6820 When re-select a ticked or dormant article, it will be fetched from the
6821 cache instead of from the server. As articles in your cache will never
6822 expire, this might serve as a method of saving articles while still
6823 keeping them where they belong. Just mark all articles you want to save
6824 as dormant, and don't worry.
6826 When an article is marked as read, is it removed from the cache.
6828 @vindex gnus-cache-remove-articles
6829 @vindex gnus-cache-enter-articles
6830 The entering/removal of articles from the cache is controlled by the
6831 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
6832 variables. Both are lists of symbols. The first is @code{(ticked
6833 dormant)} by default, meaning that ticked and dormant articles will be
6834 put in the cache. The latter is @code{(read)} by default, meaning that
6835 articles that are marked as read are removed from the cache. Possibly
6836 symbols in these two lists are @code{ticked}, @code{dormant},
6837 @code{unread} and @code{read}.
6839 @findex gnus-jog-cache
6840 So where does the massive article-fetching and storing come into the
6841 picture? The @code{gnus-jog-cache} command will go through all
6842 subscribed newsgroups, request all unread articles, and store them in
6843 the cache. You should only ever, ever ever ever, use this command if 1)
6844 your connection to the @sc{nntp} server is really, really, really slow
6845 and 2) you have a really, really, really huge disk. Seriously.
6847 @vindex gnus-uncacheable-groups
6848 It is likely that you do not want caching on some groups. For instance,
6849 if your @code{nnml} mail is located under your home directory, it makes no
6850 sense to cache it somewhere else under your home directory. Unless you
6851 feel that it's neat to use twice as much space. To limit the caching,
6852 you could set the @code{gnus-uncacheable-groups} regexp to
6853 @samp{"^nnml"}, for instance. This variable is @code{nil} by
6856 @findex gnus-cache-generate-nov-databases
6857 @findex gnus-cache-generate-active
6858 If your cache becomes all messed up for some reason or other, Gnus
6859 offers two functions that will try to set things right. @kbd{M-x
6860 gnus-cache-generate-nov-databases} will (re)build all the @sc{nov}
6861 files, and @kbd{gnus-cache-generate-active} will (re)generate the active
6865 @node Persistent Articles
6866 @section Persistent Articles
6867 @cindex persistent articles
6869 Closely related to article caching, we have @dfn{persistent articles}.
6870 In fact, it's just a different way of looking at caching, and much more
6871 useful in my opinion.
6873 Say you're reading a newsgroup, and you happen on to some valuable gem
6874 that you want to keep and treasure forever. You'd normally just save it
6875 (using one of the many saving commands) in some file. The problem with
6876 that is that it's just, well, yucky. Ideally you'd prefer just having
6877 the article remain in the group where you found it forever; untouched by
6878 the expiry going on at the news server.
6880 This is what a @dfn{persistent article} is---an article that just won't
6881 be deleted. It's implemented using the normal cache functions, but
6882 you use two explicit commands for managing persistent articles:
6888 @findex gnus-cache-enter-article
6889 Make the current article persistent (@code{gnus-cache-enter-article}).
6892 @kindex M-* (Summary)
6893 @findex gnus-cache-remove-article
6894 Remove the current article from the persistent articles
6895 (@code{gnus-cache-remove-article}). This will normally delete the
6899 Both these commands understand the process/prefix convention.
6901 To avoid having all ticked articles (and stuff) entered into the cache,
6902 you should set @code{gnus-use-cache} to @code{passive} if you're just
6903 interested in persistent articles:
6906 (setq gnus-use-cache 'passive)
6910 @node Article Backlog
6911 @section Article Backlog
6913 @cindex article backlog
6915 If you have a slow connection, but the idea of using caching seems
6916 unappealing to you (and it is, really), you can help the situation some
6917 by switching on the @dfn{backlog}. This is where Gnus will buffer
6918 already read articles so that it doesn't have to re-fetch articles
6919 you've already read. This only helps if you are in the habit of
6920 re-selecting articles you've recently read, of course. If you never do
6921 that, turning the backlog on will slow Gnus down a little bit, and
6922 increase memory usage some.
6924 @vindex gnus-keep-backlog
6925 If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
6926 at most @var{n} old articles in a buffer for later re-fetching. If this
6927 variable is non-@code{nil} and is not a number, Gnus will store
6928 @emph{all} read articles, which means that your Emacs will group without
6929 bound before exploding and taking your machine down with you. I put
6930 that in there just to keep y'all on your toes.
6932 This variable is @code{nil} by default.
6935 @node Exiting the Summary Buffer
6936 @section Exiting the Summary Buffer
6937 @cindex summary exit
6939 Exiting from the summary buffer will normally update all info on the
6940 group and return you to the group buffer.
6946 @kindex Z Z (Summary)
6948 @findex gnus-summary-exit
6949 @vindex gnus-summary-exit-hook
6950 @vindex gnus-summary-prepare-exit-hook
6951 Exit the current group and update all information on the group
6952 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
6953 called before doing much of the exiting, and calls
6954 @code{gnus-summary-expire-articles} by default.
6955 @code{gnus-summary-exit-hook} is called after finishing the exiting
6960 @kindex Z E (Summary)
6962 @findex gnus-summary-exit-no-update
6963 Exit the current group without updating any information on the group
6964 (@code{gnus-summary-exit-no-update}).
6968 @kindex Z c (Summary)
6970 @findex gnus-summary-catchup-and-exit
6971 Mark all unticked articles in the group as read and then exit
6972 (@code{gnus-summary-catchup-and-exit}).
6975 @kindex Z C (Summary)
6976 @findex gnus-summary-catchup-all-and-exit
6977 Mark all articles, even the ticked ones, as read and then exit
6978 (@code{gnus-summary-catchup-all-and-exit}).
6981 @kindex Z n (Summary)
6982 @findex gnus-summary-catchup-and-goto-next-group
6983 Mark all articles as read and go to the next group
6984 (@code{gnus-summary-catchup-and-goto-next-group}).
6987 @kindex Z R (Summary)
6988 @findex gnus-summary-reselect-current-group
6989 Exit this group, and then enter it again
6990 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
6991 all articles, both read and unread.
6995 @kindex Z G (Summary)
6996 @kindex M-g (Summary)
6997 @findex gnus-summary-rescan-group
6998 Exit the group, check for new articles in the group, and select the
6999 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
7000 articles, both read and unread.
7003 @kindex Z N (Summary)
7004 @findex gnus-summary-next-group
7005 Exit the group and go to the next group
7006 (@code{gnus-summary-next-group}).
7009 @kindex Z P (Summary)
7010 @findex gnus-summary-prev-group
7011 Exit the group and go to the previous group
7012 (@code{gnus-summary-prev-group}).
7015 @vindex gnus-exit-group-hook
7016 @code{gnus-exit-group-hook} is called when you exit the current
7019 @findex gnus-summary-wake-up-the-dead
7020 @findex gnus-dead-summary-mode
7021 @vindex gnus-kill-summary-on-exit
7022 If you're in the habit of exiting groups, and then changing your mind
7023 about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}.
7024 If you do that, Gnus won't kill the summary buffer when you exit it.
7025 (Quelle surprise!) Instead it will change the name of the buffer to
7026 something like @samp{"*Dead Summary ... *"} and install a minor mode
7027 called @code{gnus-dead-summary-mode}. Now, if you switch back to this
7028 buffer, you'll find that all keys are mapped to a function called
7029 @code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead
7030 summary buffer will result in a live, normal summary buffer.
7032 There will never be more than one dead summary buffer at any one time.
7034 @vindex gnus-use-cross-reference
7035 The data on the current group will be updated (which articles you have
7036 read, which articles you have replied to, etc.) when you exit the
7037 summary buffer. If the @code{gnus-use-cross-reference} variable is
7038 @code{t} (which is the default), articles that are cross-referenced to
7039 this group and are marked as read, will also be marked as read in the
7040 other subscribed groups they were cross-posted to. If this variable is
7041 neither @code{nil} nor @code{t}, the article will be marked as read in
7042 both subscribed and unsubscribed groups.
7044 Marking cross-posted articles as read ensures that you'll never have to
7045 read the same article more than once. Unless, of course, somebody has
7046 posted it to several groups separately. Posting the same article to
7047 several groups (not cross-posting) is called @dfn{spamming}, and you are
7048 by law required to send nasty-grams to anyone who perpetrates such a
7051 Remember: Cross-posting is kinda ok, but posting the same article
7052 separately to several groups is not.
7054 One thing that may cause Gnus to not do the cross-posting thing
7055 correctly is if you use an @sc{nntp} server that supports @sc{xover}
7056 (which is very nice, because it speeds things up considerably) which
7057 does not include the @code{Xref} header in its @sc{nov} lines. This is
7058 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
7059 even with @sc{xover} by registering the @code{Xref} lines of all
7060 articles you actually read, but if you kill the articles, or just mark
7061 them as read without reading them, Gnus will not get a chance to snoop
7062 the @code{Xref} lines out of these articles, and will be unable to use
7063 the cross reference mechanism.
7065 @vindex gnus-nov-is-evil
7066 If you want Gnus to get the @code{Xref}s right all the time, you have to
7067 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
7073 @node Process/Prefix
7074 @section Process/Prefix
7075 @cindex process/prefix convention
7077 Many functions, among them functions for moving, decoding and saving
7078 articles, use what is known as the @dfn{Process/Prefix convention}.
7080 This is a method for figuring out what articles that the user wants the
7081 command to be performed on.
7085 If the numeric prefix is N, perform the operation on the next N
7086 articles, starting with the current one. If the numeric prefix is
7087 negative, perform the operation on the previous N articles, starting
7088 with the current one.
7090 If @code{transient-mark-mode} in non-@code{nil} and the region is
7091 active, all articles in the region will be worked upon.
7093 If there is no numeric prefix, but some articles are marked with the
7094 process mark, perform the operation on the articles that are marked with
7097 If there is neither a numeric prefix nor any articles marked with the
7098 process mark, just perform the operation on the current article.
7100 Quite simple, really, but it needs to be made clear so that surprises
7103 @vindex gnus-summary-goto-unread
7104 One thing that seems to shock & horrify lots of people is that, for
7105 instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
7106 Since each @kbd{d} (which marks the current article as read) by default
7107 goes to the next unread article after marking, this means that @kbd{3 d}
7108 will mark the next three unread articles as read, no matter what the
7109 summary buffer looks like. Set @code{gnus-summary-goto-unread} to
7110 @code{nil} for a more straightforward action.
7113 @node Saving Articles
7114 @section Saving Articles
7115 @cindex saving articles
7117 Gnus can save articles in a number of ways. Below is the documentation
7118 for saving articles in a fairly straight-forward fashion (i.e., little
7119 processing of the article is done before it is saved). For a different
7120 approach (uudecoding, unsharing) you should use @code{gnus-uu}
7121 (@pxref{Decoding Articles}).
7123 @vindex gnus-save-all-headers
7124 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
7125 unwanted headers before saving the article.
7127 @vindex gnus-saved-headers
7128 If the preceeding variable is @code{nil}, all headers that match the
7129 @code{gnus-saved-headers} regexp will be kept, while the rest will be
7130 deleted before saving.
7136 @kindex O o (Summary)
7138 @findex gnus-summary-save-article
7139 Save the current article using the default article saver
7140 (@code{gnus-summary-save-article}).
7143 @kindex O m (Summary)
7144 @findex gnus-summary-save-article-mail
7145 Save the current article in mail format
7146 (@code{gnus-summary-save-article-mail}).
7149 @kindex O r (Summary)
7150 @findex gnus-summary-save-article-mail
7151 Save the current article in rmail format
7152 (@code{gnus-summary-save-article-rmail}).
7155 @kindex O f (Summary)
7156 @findex gnus-summary-save-article-file
7157 Save the current article in plain file format
7158 (@code{gnus-summary-save-article-file}).
7161 @kindex O b (Summary)
7162 @findex gnus-summary-save-article-body-file
7163 Save the current article body in plain file format
7164 (@code{gnus-summary-save-article-body-file}).
7167 @kindex O h (Summary)
7168 @findex gnus-summary-save-article-folder
7169 Save the current article in mh folder format
7170 (@code{gnus-summary-save-article-folder}).
7173 @kindex O p (Summary)
7174 @findex gnus-summary-pipe-output
7175 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
7176 the current article to a process (@code{gnus-summary-pipe-output}).
7179 @vindex gnus-prompt-before-saving
7180 All these commands use the process/prefix convention
7181 (@pxref{Process/Prefix}). If you save bunches of articles using these
7182 functions, you might get tired of being prompted for files to save each
7183 and every article in. The prompting action is controlled by
7184 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
7185 default, giving you that excessive prompting action you know and
7186 loathe. If you set this variable to @code{t} instead, you'll be promted
7187 just once for each series of articles you save. If you like to really
7188 have Gnus do all your thinking for you, you can even set this variable
7189 to @code{nil}, which means that you will never be prompted for files to
7190 save articles in. Gnus will simply save all the articles in the default
7194 @vindex gnus-default-article-saver
7195 You can customize the @code{gnus-default-article-saver} variable to make
7196 Gnus do what you want it to. You can use any of the four ready-made
7197 functions below, or you can create your own.
7201 @item gnus-summary-save-in-rmail
7202 @findex gnus-summary-save-in-rmail
7203 This is the default format, @dfn{babyl}. Uses the function in the
7204 @code{gnus-rmail-save-name} variable to get a file name to save the
7205 article in. The default is @code{gnus-plain-save-name}.
7207 @item gnus-summary-save-in-mail
7208 @findex gnus-summary-save-in-mail
7209 Save in a Unix mail (mbox) file. Uses the function in the
7210 @code{gnus-mail-save-name} variable to get a file name to save the
7211 article in. The default is @code{gnus-plain-save-name}.
7213 @item gnus-summary-save-in-file
7214 @findex gnus-summary-save-in-file
7215 Append the article straight to an ordinary file. Uses the function in
7216 the @code{gnus-file-save-name} variable to get a file name to save the
7217 article in. The default is @code{gnus-numeric-save-name}.
7219 @item gnus-summary-save-body-in-file
7220 @findex gnus-summary-save-body-in-file
7221 Append the article body to an ordinary file. Uses the function in the
7222 @code{gnus-file-save-name} variable to get a file name to save the
7223 article in. The default is @code{gnus-numeric-save-name}.
7225 @item gnus-summary-save-in-folder
7226 @findex gnus-summary-save-in-folder
7227 Save the article to an MH folder using @code{rcvstore} from the MH
7230 @item gnus-summary-save-in-vm
7231 @findex gnus-summary-save-in-vm
7232 Save the article in a VM folder. You have to have the VM mail
7233 reader to use this setting.
7236 All of these functions, except for the last one, will save the article
7237 in the @code{gnus-article-save-directory}, which is initialized from the
7238 @samp{SAVEDIR} environment variable. This is @file{~/News/} by
7241 As you can see above, the functions use different functions to find a
7242 suitable name of a file to save the article in. Below is a list of
7243 available functions that generate names:
7247 @item gnus-Numeric-save-name
7248 @findex gnus-Numeric-save-name
7249 Generates file names that look like @samp{~/News/Alt.andrea-dworkin/45}.
7251 @item gnus-numeric-save-name
7252 @findex gnus-numeric-save-name
7253 Generates file names that look like @samp{~/News/alt.andrea-dworkin/45}.
7255 @item gnus-Plain-save-name
7256 @findex gnus-Plain-save-name
7257 Generates file names that look like @samp{~/News/Alt.andrea-dworkin}.
7259 @item gnus-plain-save-name
7260 @findex gnus-plain-save-name
7261 Generates file names that look like @samp{~/News/alt.andrea-dworkin}.
7264 @vindex gnus-split-methods
7265 You can have Gnus suggest where to save articles by plonking regexp into
7266 the @code{gnus-split-methods} alist. For instance, if you would like to
7267 save articles related to Gnus in the file @file{gnus-stuff}, and articles
7268 related to VM in @code{vm-stuff}, you could set this variable to something
7272 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
7273 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
7274 (my-choosing-function "../other-dir/my-stuff")
7275 ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
7278 We see that this is a list where each element is a list that has two
7279 elements---the @dfn{match} and the @dfn{file}. The match can either be
7280 a string (in which case it is used as a regexp to match on the article
7281 head); it can be a symbol (which will be called as a function); or it
7282 can be a list (which will be @code{eval}ed). If any of these actions
7283 have a non-@code{nil} result, the @dfn{file} will be used as a default
7284 prompt. In addition, the result of the operation itself will be used if
7285 the function or form called returns a string or a list of strings.
7287 You basically end up with a list of file names that might be used when
7288 saving the current article. (All ``matches'' will be used.) You will
7289 then be prompted for what you really want to use as a name, with file
7290 name completion over the results from applying this variable.
7292 This variable is @code{((gnus-article-archive-name))} by default, which
7293 means that Gnus will look at the articles it saves for an
7294 @samp{Archive-name} line and use that as a suggestion for the file
7297 @vindex gnus-use-long-file-name
7298 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
7299 @code{nil}, all the preceding functions will replace all periods
7300 (@samp{.}) in the group names with slashes (@samp{/})---which means that
7301 the functions will generate hierarchies of directories instead of having
7302 all the files in the toplevel directory
7303 (@samp{~/News/alt/andrea-dworkin} instead of
7304 @samp{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
7305 on most systems. However, for historical reasons, this is @code{nil} on
7306 Xenix and usg-unix-v machines by default.
7308 This function also affects kill and score file names. If this variable
7309 is a list, and the list contains the element @code{not-score}, long file
7310 names will not be used for score files, if it contains the element
7311 @code{not-save}, long file names will not be used for saving, and if it
7312 contains the element @code{not-kill}, long file names will not be used
7315 If you'd like to save articles in a hierarchy that looks something like
7319 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
7320 (setq gnus-default-article-save 'gnus-summary-save-in-file) ; no encoding
7323 Then just save with @kbd{o}. You'd then read this hierarchy with
7324 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
7325 the toplevel directory as the argument (@file{~/News/}). Then just walk
7326 around to the groups/directories with @code{nneething}.
7329 @node Decoding Articles
7330 @section Decoding Articles
7331 @cindex decoding articles
7333 Sometime users post articles (or series of articles) that have been
7334 encoded in some way or other. Gnus can decode them for you.
7337 * Uuencoded Articles:: Uudecode articles.
7338 * Shared Articles:: Unshar articles.
7339 * PostScript Files:: Split PostScript.
7340 * Decoding Variables:: Variables for a happy decoding.
7341 * Viewing Files:: You want to look at the result of the decoding?
7344 All these functions use the process/prefix convention
7345 (@pxref{Process/Prefix}) for finding out what articles to work on, with
7346 the extension that a ``single article'' means ``a single series''. Gnus can
7347 find out by itself what articles belong to a series, decode all the
7348 articles and unpack/view/save the resulting file(s).
7350 Gnus guesses what articles are in the series according to the following
7351 simplish rule: The subjects must be (nearly) identical, except for the
7352 last two numbers of the line. (Spaces are largely ignored, however.)
7354 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
7355 will find all the articles that match the regexp @samp{^cat.gif
7356 ([0-9]+/[0-9]+).*$}.
7358 Subjects that are nonstandard, like @samp{cat.gif (2/3) Part 6 of a
7359 series}, will not be properly recognized by any of the automatic viewing
7360 commands, and you have to mark the articles manually with @kbd{#}.
7362 @node Uuencoded Articles
7363 @subsection Uuencoded Articles
7365 @cindex uuencoded articles
7370 @kindex X u (Summary)
7371 @findex gnus-uu-decode-uu
7372 Uudecodes the current series (@code{gnus-uu-decode-uu}).
7375 @kindex X U (Summary)
7376 @findex gnus-uu-decode-uu-and-save
7377 Uudecodes and saves the current series
7378 (@code{gnus-uu-decode-uu-and-save}).
7381 @kindex X v u (Summary)
7382 @findex gnus-uu-decode-uu-view
7383 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
7386 @kindex X v U (Summary)
7387 @findex gnus-uu-decode-uu-and-save-view
7388 Uudecodes, views and saves the current series
7389 (@code{gnus-uu-decode-uu-and-save-view}).
7392 Remember that these all react to the presence of articles marked with
7393 the process mark. If, for instance, you'd like to uncode and save an
7394 entire newsgroup, you'd typically do @kbd{M P a}
7395 (@code{gnus-uu-mark-all}) and then @kbd{X U}
7396 (@code{gnus-uu-decode-uu-and-save}).
7398 All this is very much different from how @code{gnus-uu} worked with
7399 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
7400 the sun. This version of @code{gnus-uu} generally assumes that you mark
7401 articles in some way (@pxref{Setting Process Marks}) and then press
7404 Note: When trying to decode articles that have names matching
7405 @code{gnus-uu-notify-files}, which is hard-coded to
7406 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
7407 automatically post an article on @samp{comp.unix.wizards} saying that
7408 you have just viewed the file in question. This feature can't be turned
7411 @node Shared Articles
7412 @subsection Shared Articles
7414 @cindex shared articles
7419 @kindex X s (Summary)
7420 @findex gnus-uu-decode-unshar
7421 Unshars the current series (@code{gnus-uu-decode-unshar}).
7424 @kindex X S (Summary)
7425 @findex gnus-uu-decode-unshar-and-save
7426 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
7429 @kindex X v s (Summary)
7430 @findex gnus-uu-decode-unshar-view
7431 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
7434 @kindex X v S (Summary)
7435 @findex gnus-uu-decode-unshar-and-save-view
7436 Unshars, views and saves the current series
7437 (@code{gnus-uu-decode-unshar-and-save-view}).
7440 @node PostScript Files
7441 @subsection PostScript Files
7447 @kindex X p (Summary)
7448 @findex gnus-uu-decode-postscript
7449 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
7452 @kindex X P (Summary)
7453 @findex gnus-uu-decode-postscript-and-save
7454 Unpack and save the current PostScript series
7455 (@code{gnus-uu-decode-postscript-and-save}).
7458 @kindex X v p (Summary)
7459 @findex gnus-uu-decode-postscript-view
7460 View the current PostScript series
7461 (@code{gnus-uu-decode-postscript-view}).
7464 @kindex X v P (Summary)
7465 @findex gnus-uu-decode-postscript-and-save-view
7466 View and save the current PostScript series
7467 (@code{gnus-uu-decode-postscript-and-save-view}).
7470 @node Decoding Variables
7471 @subsection Decoding Variables
7473 Adjective, not verb.
7476 * Rule Variables:: Variables that say how a file is to be viewed.
7477 * Other Decode Variables:: Other decode variables.
7478 * Uuencoding and Posting:: Variables for customizing uuencoding.
7481 @node Rule Variables
7482 @subsubsection Rule Variables
7483 @cindex rule variables
7485 Gnus uses @dfn{rule variables} to decide how to view a file. All these
7486 variables are on the form
7489 (list '(regexp1 command2)
7496 @item gnus-uu-user-view-rules
7497 @vindex gnus-uu-user-view-rules
7498 This variable is consulted first when viewing files. If you wish to use,
7499 for instance, @code{sox} to convert an @samp{.au} sound file, you could
7502 (setq gnus-uu-user-view-rules
7503 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
7506 @item gnus-uu-user-view-rules-end
7507 @vindex gnus-uu-user-view-rules-end
7508 This variable is consulted if Gnus couldn't make any matches from the
7509 user and default view rules.
7511 @item gnus-uu-user-archive-rules
7512 @vindex gnus-uu-user-archive-rules
7513 This variable can be used to say what commands should be used to unpack
7518 @node Other Decode Variables
7519 @subsubsection Other Decode Variables
7522 @vindex gnus-uu-grabbed-file-functions
7524 @item gnus-uu-grabbed-file-functions
7525 All functions in this list will be called right each file has been
7526 successfully decoded---so that you can move or view files right away,
7527 and don't have to wait for all files to be decoded before you can do
7528 anything. Ready-made functions you can put in this list are:
7532 @item gnus-uu-grab-view
7533 @findex gnus-uu-grab-view
7536 @item gnus-uu-grab-move
7537 @findex gnus-uu-grab-move
7538 Move the file (if you're using a saving function.)
7541 @item gnus-uu-ignore-files-by-name
7542 @vindex gnus-uu-ignore-files-by-name
7543 Files with name matching this regular expression won't be viewed.
7545 @item gnus-uu-ignore-files-by-type
7546 @vindex gnus-uu-ignore-files-by-type
7547 Files with a @sc{mime} type matching this variable won't be viewed.
7548 Note that Gnus tries to guess what type the file is based on the name.
7549 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
7552 @item gnus-uu-tmp-dir
7553 @vindex gnus-uu-tmp-dir
7554 Where @code{gnus-uu} does its work.
7556 @item gnus-uu-do-not-unpack-archives
7557 @vindex gnus-uu-do-not-unpack-archives
7558 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
7559 looking for files to display.
7561 @item gnus-uu-view-and-save
7562 @vindex gnus-uu-view-and-save
7563 Non-@code{nil} means that the user will always be asked to save a file
7566 @item gnus-uu-ignore-default-view-rules
7567 @vindex gnus-uu-ignore-default-view-rules
7568 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
7571 @item gnus-uu-ignore-default-archive-rules
7572 @vindex gnus-uu-ignore-default-archive-rules
7573 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
7576 @item gnus-uu-kill-carriage-return
7577 @vindex gnus-uu-kill-carriage-return
7578 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
7581 @item gnus-uu-unmark-articles-not-decoded
7582 @vindex gnus-uu-unmark-articles-not-decoded
7583 Non-@code{nil} means that @code{gnus-uu} will mark articles that were
7584 unsuccessfully decoded as unread.
7586 @item gnus-uu-correct-stripped-uucode
7587 @vindex gnus-uu-correct-stripped-uucode
7588 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
7589 uuencoded files that have had trailing spaces deleted.
7591 @item gnus-uu-view-with-metamail
7592 @vindex gnus-uu-view-with-metamail
7593 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
7594 commands defined by the rule variables and just fudge a @sc{mime}
7595 content type based on the file name. The result will be fed to
7596 @code{metamail} for viewing.
7598 @item gnus-uu-save-in-digest
7599 @vindex gnus-uu-save-in-digest
7600 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
7601 decoding, will save in digests. If this variable is @code{nil},
7602 @code{gnus-uu} will just save everything in a file without any
7603 embellishments. The digesting almost conforms to RFC1153---no easy way
7604 to specify any meaningful volume and issue numbers were found, so I
7605 simply dropped them.
7609 @node Uuencoding and Posting
7610 @subsubsection Uuencoding and Posting
7614 @item gnus-uu-post-include-before-composing
7615 @vindex gnus-uu-post-include-before-composing
7616 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
7617 before you compose the article. If this variable is @code{t}, you can
7618 either include an encoded file with @kbd{C-c C-i} or have one included
7619 for you when you post the article.
7621 @item gnus-uu-post-length
7622 @vindex gnus-uu-post-length
7623 Maximum length of an article. The encoded file will be split into how
7624 many articles it takes to post the entire file.
7626 @item gnus-uu-post-threaded
7627 @vindex gnus-uu-post-threaded
7628 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
7629 thread. This may not be smart, as no other decoder I have seen are able
7630 to follow threads when collecting uuencoded articles. (Well, I have
7631 seen one package that does that---@code{gnus-uu}, but somehow, I don't
7632 think that counts...) Default is @code{nil}.
7634 @item gnus-uu-post-separate-description
7635 @vindex gnus-uu-post-separate-description
7636 Non-@code{nil} means that the description will be posted in a separate
7637 article. The first article will typically be numbered (0/x). If this
7638 variable is @code{nil}, the description the user enters will be included
7639 at the beginning of the first article, which will be numbered (1/x).
7640 Default is @code{t}.
7645 @subsection Viewing Files
7646 @cindex viewing files
7647 @cindex pseudo-articles
7649 After decoding, if the file is some sort of archive, Gnus will attempt
7650 to unpack the archive and see if any of the files in the archive can be
7651 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
7652 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
7653 uncompress and detar the main file, and then view the two pictures.
7654 This unpacking process is recursive, so if the archive contains archives
7655 of archives, it'll all be unpacked.
7657 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
7658 extracted file into the summary buffer. If you go to these ``articles'',
7659 you will be prompted for a command to run (usually Gnus will make a
7660 suggestion), and then the command will be run.
7662 @vindex gnus-view-pseudo-asynchronously
7663 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
7664 until the viewing is done before proceeding.
7666 @vindex gnus-view-pseudos
7667 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
7668 the pseudo-articles into the summary buffer, but view them
7669 immediately. If this variable is @code{not-confirm}, the user won't even
7670 be asked for a confirmation before viewing is done.
7672 @vindex gnus-view-pseudos-separately
7673 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
7674 pseudo-article will be created for each file to be viewed. If
7675 @code{nil}, all files that use the same viewing command will be given as
7676 a list of parameters to that command.
7678 If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert
7679 pseudo-articles when decoding. It is @code{t} by default.
7681 So; there you are, reading your @emph{pseudo-articles} in your
7682 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
7683 Why isn't anything real anymore? How did we get here?
7686 @node Article Treatment
7687 @section Article Treatment
7689 Reading through this huge manual, you may have quite forgotten that the
7690 object of newsreaders are to actually, like, read what people have
7691 written. Reading articles. Unfortunately, people are quite bad at
7692 writing, so there are tons of functions and variables to make reading
7693 these articles easier.
7696 * Article Highlighting:: You want to make the article look like fruit salad.
7697 * Article Hiding:: You also want to make certain info go away.
7698 * Article Washing:: Lots of way-neat functions to make life better.
7699 * Article Buttons:: Clcik on URLs, Message-IDs, addresses and the like.
7700 * Article Date:: Grumble, UT!
7704 @node Article Highlighting
7705 @subsection Article Highlighting
7708 Not only do you want your article buffer to look like fruit salad, but
7709 you want it to look like technicolor fruit salad.
7714 @kindex W H a (Summary)
7715 @findex gnus-article-highlight
7716 Highlight the current article (@code{gnus-article-highlight}).
7719 @kindex W H h (Summary)
7720 @findex gnus-article-highlight-headers
7721 @vindex gnus-header-face-alist
7722 Highlight the headers (@code{gnus-article-highlight-headers}). The
7723 highlighting will be done according to the @code{gnus-header-face-alist}
7724 variable, which is a list where each element has the form @var{(regexp
7725 name content)}. @var{regexp} is a regular expression for matching the
7726 header, @var{name} is the face used for highlighting the header name and
7727 @var{content} is the face for highlighting the header value. The first
7728 match made will be used. Note that @var{regexp} shouldn't have @samp{^}
7729 prepended---Gnus will add one.
7732 @kindex W H c (Summary)
7733 @findex gnus-article-highlight-citation
7734 Highlight cited text (@code{gnus-article-highlight-citation}).
7736 Some variables to customize the citation highlights:
7739 @vindex gnus-cite-parse-max-size
7741 @item gnus-cite-parse-max-size
7742 If the article size if bigger than this variable (which is 25000 by
7743 default), no citation highlighting will be performed.
7745 @item gnus-cite-prefix-regexp
7746 @vindex gnus-cite-prefix-regexp
7747 Regexp mathcing the longest possible citation prefix on a line.
7749 @item gnus-cite-max-prefix
7750 @vindex gnus-cite-max-prefix
7751 Maximum possible length for a citation prefix (default 20).
7753 @item gnus-supercite-regexp
7754 @vindex gnus-supercite-regexp
7755 Regexp matching normal SuperCite attribution lines.
7757 @item gnus-supercite-secondary-regexp
7758 @vindex gnus-supercite-secondary-regexp
7759 Regexp matching mangled SuperCite attribution lines.
7761 @item gnus-cite-minimum-match-count
7762 @vindex gnus-cite-minimum-match-count
7763 Minimum number of identical prefixes we have to see before we believe
7764 that it's a citation.
7766 @item gnus-cite-attribution-prefix
7767 @vindex gnus-cite-attribution-prefix
7768 Regexp matching the beginning of an attribution line.
7770 @item gnus-cite-addtribution-suffix
7771 @vindex gnus-cite-addtribution-suffix
7772 Regexp matching the end of an attribution line.
7774 @item gnus-cite-attribution-face
7775 @vindex gnus-cite-attribution-face
7776 Face used for attribution lines. It is merged with the face for the
7777 cited text belonging to the attribution.
7783 @kindex W H s (Summary)
7784 @vindex gnus-signature-separator
7785 @findex gnus-article-highlight-signature
7786 Highlight the signature (@code{gnus-article-highlight-signature}).
7787 Everything after @code{gnus-signature-separator} in an article will be
7788 considered a signature.
7793 @node Article Hiding
7794 @subsection Article Hiding
7795 @cindex article hiding
7797 Or rather, hiding certain things in each article. There usually is much
7798 too much gruft in most articles.
7803 @kindex W W a (Summary)
7804 @findex gnus-article-hide
7805 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
7808 @kindex W W h (Summary)
7809 @findex gnus-article-hide-headers
7810 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
7814 @kindex W W b (Summary)
7815 @findex gnus-article-hide-boring-headers
7816 Hide headers that aren't particularly interesting
7817 (@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}.
7820 @kindex W W s (Summary)
7821 @findex gnus-article-hide-signature
7822 Hide signature (@code{gnus-article-hide-signature}).
7825 @kindex W W p (Summary)
7826 @findex gnus-article-hide-pgp
7827 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}).
7830 @kindex W W c (Summary)
7831 @findex gnus-article-hide-citation
7832 Hide citation (@code{gnus-article-hide-citation}). Some variables for
7833 customizing the hiding:
7837 @item gnus-cite-hide-percentage
7838 @vindex gnus-cite-hide-percentage
7839 If the cited text is of a bigger percentage than this variable (default
7840 50), hide the cited text.
7842 @item gnus-cite-hide-absolute
7843 @vindex gnus-cite-hide-absolute
7844 The cited text must be have at least this length (default 10) before it
7847 @item gnus-cited-text-button-line-format
7848 @vindex gnus-cited-text-button-line-format
7849 Gnus adds buttons show where the cited text has been hidden, and to
7850 allow toggle hiding the text. The format of the variable is specified
7851 by this format-like variable. These specs are legal:
7855 Start point of the hidden text.
7857 End point of the hidden text.
7859 Length of the hidden text.
7862 @item gnus-cited-lines-visible
7863 @vindex gnus-cited-lines-visible
7864 The number of lines at the beginning of the cited text to leave shown.
7869 @kindex W W C (Summary)
7870 @findex gnus-article-hide-citation-in-followups
7871 Hide cited text in articles that aren't roots
7872 (@code{gnus-article-hide-citation-in-followups}). This isn't very
7873 useful as an interactive command, but might be a handy function to stick
7874 in @code{gnus-article-display-hook} (@pxref{Customizing Articles}).
7878 All these ``hiding'' commands are toggles, but if you give a negative
7879 prefix to these commands, they will show what they have previously
7880 hidden. If you give a positive prefix, they will always hide.
7882 Also see @xref{Article Highlighting} for further variables for
7883 citation customization.
7885 @vindex gnus-signature-limit
7886 @code{gnus-signature-limit} provides a limit to what is considered a
7887 signature. If it is a number, no signature may not be longer (in
7888 characters) than that number. If it is a function, the function will be
7889 called without any parameters, and if it returns @code{nil}, there is no
7890 signature in the buffer. If it is a string, it will be used as a
7891 regexp. If it matches, the text in question is not a signature.
7894 @node Article Washing
7895 @subsection Article Washing
7897 @cindex article washing
7899 We call this ``article washing'' for a really good reason. Namely, the
7900 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
7902 @dfn{Washing} is defined by us as ``changing something from something to
7903 something else'', but normally results in something looking better.
7909 @kindex W l (Summary)
7910 @findex gnus-summary-stop-page-breaking
7911 Remove page breaks from the current article
7912 (@code{gnus-summary-stop-page-breaking}).
7915 @kindex W r (Summary)
7916 @findex gnus-summary-caesar-message
7917 Do a Caesar rotate (rot13) on the article buffer
7918 (@code{gnus-summary-caesar-message}).
7921 @kindex A g (Summary)
7922 @findex gnus-summary-show-article
7923 (Re)fetch the current article (@code{gnus-summary-show-article}). If
7924 given a prefix, fetch the current article, but don't run any of the
7925 article treatment functions. This will give you a ``raw'' article, just
7926 the way it came from the server.
7929 @kindex W t (Summary)
7930 @findex gnus-summary-toggle-header
7931 Toggle whether to display all headers in the article buffer
7932 (@code{gnus-summary-toggle-header}).
7935 @kindex W m (Summary)
7936 @findex gnus-summary-toggle-mime
7937 Toggle whether to run the article through @sc{mime} before displaying
7938 (@code{gnus-summary-toggle-mime}).
7941 @kindex W o (Summary)
7942 @findex gnus-article-treat-overstrike
7943 Treat overstrike (@code{gnus-article-treat-overstrike}).
7946 @kindex W w (Summary)
7947 @findex gnus-article-word-wrap
7948 Do word wrap (@code{gnus-article-word-wrap}).
7951 @kindex W c (Summary)
7952 @findex gnus-article-remove-cr
7953 Remove CR (@code{gnus-article-remove-cr}).
7956 @kindex W L (Summary)
7957 @findex gnus-article-remove-trailing-blank-lines
7958 Remove all blank lines at the end of the article
7959 (@code{gnus-article-remove-trailing-blank-lines}).
7962 @kindex W q (Summary)
7963 @findex gnus-article-de-quoted-unreadable
7964 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
7967 @kindex W f (Summary)
7969 @findex gnus-article-display-x-face
7970 @findex gnus-article-x-face-command
7971 @vindex gnus-article-x-face-command
7972 @vindex gnus-article-x-face-too-ugly
7973 Look for and display any X-Face headers
7974 (@code{gnus-article-display-x-face}). The command executed by this
7975 function is given by the @code{gnus-article-x-face-command} variable. If
7976 this variable is a string, this string will be executed in a sub-shell.
7977 If it is a function, this function will be called with the face as the
7978 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
7979 matches the @code{From} header, the face will not be shown.
7982 @kindex W b (Summary)
7983 @findex gnus-article-add-buttons
7984 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
7987 @kindex W B (Summary)
7988 @findex gnus-article-add-buttons-to-head
7989 Add clickable buttons to the article headers
7990 (@code{gnus-article-add-buttons-to-head}).
7995 @node Article Buttons
7996 @subsection Article Buttons
7999 People often include references to other stuff in articles, and it would
8000 be nice if Gnus could just fetch whatever it is that people talk about
8001 with the minimum of fuzz.
8003 Gnus adds @dfn{buttons} to certain standard references by default:
8004 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
8005 two variables, one that handles article bodies and one that handles
8010 @item gnus-button-alist
8011 @vindex gnus-header-button-alist
8012 This is an alist where each entry has this form:
8015 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
8021 All text that match this regular expression will be considered an
8022 external reference. Here's a typical regexp that match embedded URLs:
8023 @samp{"<URL:\\([^\n\r>]*\\)>"}.
8026 Gnus has to know which parts of the match is to be highlighted. This is
8027 a number that says what sub-expression of the regexp that is to be
8028 highlighted. If you want it all highlighted, you use @samp{0} here.
8031 This form will be @code{eval}ed, and if the result is non-@code{nil},
8032 this is considered a match. This is useful if you want extra sifting to
8033 avoid false matches.
8036 This function will be called when you click on this button.
8039 As with @var{button-par}, this is a sub-expression number, but this one
8040 says which part of the match is to be sent as data to @var{function}.
8044 So the full entry for buttonizing URLs is then
8047 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
8050 @item gnus-header-button-alist
8051 @vindex gnus-header-button-alist
8052 This is just like the other alist, except that it is applied to the
8053 article head only, and that each entry has an additional element that is
8054 used to say what headers to apply the buttonize coding to:
8057 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
8060 @var{header} is a regular expression.
8064 @vindex gnus-article-button-face
8065 @vindex gnus-article-mouse-face
8066 Buttons are highlighted with @code{gnus-article-button-face}, while
8067 @code{gnus-article-mouse-face} is used when the mouse cursor is over the
8072 @subsection Article Date
8074 The date is most likely generated in some obscure timezone you've never
8075 heard of, so it's quite nice to be able to find out what the time was
8076 when the article was sent.
8081 @kindex W T u (Summary)
8082 @findex gnus-article-date-ut
8083 Display the date in UT (aka. GMT, aka ZULU)
8084 (@code{gnus-article-date-ut}).
8087 @kindex W T l (Summary)
8088 @findex gnus-article-date-local
8089 Display the date in the local timezone (@code{gnus-article-date-local}).
8092 @kindex W T e (Summary)
8093 @findex gnus-article-date-lapsed
8094 Say how much time has (e)lapsed between the article was posted and now
8095 (@code{gnus-article-date-lapsed}).
8098 @kindex W T o (Summary)
8099 @findex gnus-article-date-original
8100 Display the original date (@code{gnus-article-date-original}). This can
8101 be useful if you normally use some other conversion function and is
8102 worried that it might be doing something totally wrong. Say, claiming
8103 that the article was posted in 1854. Although something like that is
8104 @emph{totally} impossible. Don't you trust me? *titter*
8109 @node Summary Sorting
8110 @section Summary Sorting
8111 @cindex summary sorting
8113 You can have the summary buffer sorted in various ways, even though I
8114 can't really see why you'd want that.
8119 @kindex C-c C-s C-n (Summary)
8120 @findex gnus-summary-sort-by-number
8121 Sort by article number (@code{gnus-summary-sort-by-number}).
8124 @kindex C-c C-s C-a (Summary)
8125 @findex gnus-summary-sort-by-author
8126 Sort by author (@code{gnus-summary-sort-by-author}).
8129 @kindex C-c C-s C-s (Summary)
8130 @findex gnus-summary-sort-by-subject
8131 Sort by subject (@code{gnus-summary-sort-by-subject}).
8134 @kindex C-c C-s C-d (Summary)
8135 @findex gnus-summary-sort-by-date
8136 Sort by date (@code{gnus-summary-sort-by-date}).
8139 @kindex C-c C-s C-i (Summary)
8140 @findex gnus-summary-sort-by-score
8141 Sort by score (@code{gnus-summary-sort-by-score}).
8144 These functions will work both when you use threading and when you don't
8145 use threading. In the latter case, all summary lines will be sorted,
8146 line by line. In the former case, sorting will be done on a
8147 root-by-root basis, which might not be what you were looking for. To
8148 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
8152 @node Finding the Parent
8153 @section Finding the Parent
8154 @cindex parent articles
8155 @cindex referring articles
8157 @findex gnus-summary-refer-parent-article
8159 If you'd like to read the parent of the current article, and it is not
8160 displayed in the article buffer, you might still be able to. That is,
8161 if the current group is fetched by @sc{nntp}, the parent hasn't expired
8162 and the @code{References} in the current article are not mangled, you
8163 can just press @kbd{^} or @kbd{A r}
8164 (@code{gnus-summary-refer-parent-article}). If everything goes well,
8165 you'll get the parent. If the parent is already displayed in the
8166 summary buffer, point will just move to this article.
8168 @findex gnus-summary-refer-references
8169 @kindex A R (Summary)
8170 You can have Gnus fetch all articles mentioned in the @code{References}
8171 header of the article by pushing @kbd{A R}
8172 (@code{gnus-summary-refer-references}).
8174 @findex gnus-summary-refer-article
8175 @kindex M-^ (Summary)
8176 You can also ask the @sc{nntp} server for an arbitrary article, no
8177 matter what group it belongs to. @kbd{M-^}
8178 (@code{gnus-summary-refer-article}) will ask you for a
8179 @code{Message-ID}, which is one of those long thingies that look
8180 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
8181 it all exactly right. No fuzzy searches, I'm afraid.
8183 @vindex gnus-refer-article-method
8184 If the group you are reading is located on a backend that does not
8185 support fetching by @code{Message-ID} very well (like @code{nnspool}),
8186 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
8187 would, perhaps, be best if the @sc{nntp} server you consult is the same
8188 as the one that keeps the spool you are reading from updated, but that's
8189 not really necessary.
8191 Most of the mail backends support fetching by @code{Message-ID}, but do
8192 not do a particularly excellent job of it. That is, @code{nnmbox} and
8193 @code{nnbabyl} are able to locate articles from any groups, while
8194 @code{nnml} and @code{nnfolder} are only able to locate articles that
8195 have been posted to the current group. (Anything else would be too time
8196 consuming.) @code{nnmh} does not support this at all.
8199 @node Alternative Approaches
8200 @section Alternative Approaches
8202 Different people like to read news using different methods. This being
8203 Gnus, we offer a small selection of minor modes for the summary buffers.
8206 * Pick and Read:: First mark articles and then read them.
8207 * Binary Groups:: Auto-decode all articles.
8212 @subsection Pick and Read
8213 @cindex pick and read
8215 Some newsreaders (like @code{nn} and, uhm, @code{nn}) use a two-phased
8216 reading interface. The user first marks the articles she wants to read
8217 from a summary buffer. Then she starts reading the articles with just
8218 an article buffer displayed.
8220 @findex gnus-pick-mode
8221 @kindex M-x gnus-pick-mode
8222 Gnus provides a summary buffer minor mode that allows
8223 this---@code{gnus-pick-mode}. This basically means that a few process
8224 mark commands becode one-keystroke commands to allow easy marking, and
8225 it makes one additional command for switching to the summary buffer
8228 Here are the available keystrokes when using pick mode:
8232 Pick the article (@code{gnus-summary-mark-as-processable}).
8235 Unpick the article (@code{gnus-summary-unmark-as-processable}).
8238 Unpick all articles (@code{gnus-summary-unmark-all-processable}).
8241 Pick the thread (@code{gnus-uu-mark-thread}).
8244 Unpick the thread (@code{gnus-uu-unmark-thread}).
8247 Pick the region (@code{gnus-uu-mark-region}).
8250 Unpick the region (@code{gnus-uu-unmark-region}).
8253 Pick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
8256 Unpick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
8259 Pick the buffer (@code{gnus-uu-mark-buffer}).
8262 Unpick the buffer (@code{gnus-uu-unmark-buffer}).
8265 @vindex gnus-pick-display-summary
8266 Start reading the picked articles (@code{gnus-pick-start-reading}). If
8267 given a prefix, mark all unpicked articles as read first. If
8268 @code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer
8269 will still be visible when you are reading.
8273 If this sounds like a good idea to you, you could say:
8276 (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
8281 @subsection Binary Groups
8282 @cindex binary groups
8284 @findex gnus-binary-mode
8285 @kindex M-x gnus-binary-mode
8286 If you spend much time in binary groups, you may grow tired of hitting
8287 @kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode}
8288 is a minor mode for summary buffers that makes all ordinary Gnus article
8289 selection functions uudecode series of articles and display the result
8290 instead of just displaying the articles the normal way.
8293 @findex gnus-binary-show-article
8294 In fact, the only way to see the actual articles if you have turned this
8295 mode on is the @kbd{g} command (@code{gnus-binary-show-article}).
8299 @section Tree Display
8302 @vindex gnus-use-trees
8303 If you don't like the normal Gnus summary display, you might try setting
8304 @code{gnus-use-trees} to @code{t}. This will create (by default) an
8305 additional @dfn{tree buffer}. You can execute all summary mode commands
8308 There are a few variables to customize the tree display, of course:
8311 @item gnus-tree-mode-hook
8312 @vindex gnus-tree-mode-hook
8313 A hook called in all tree mode buffers.
8315 @item gnus-tree-mode-line-format
8316 @vindex gnus-tree-mode-line-format
8317 A format string for the mode bar in the tree mode buffers. The default
8318 is @samp{"Gnus: %%b [%A] %Z"}. For a list of legal specs, @xref{Summary
8321 @item gnus-selected-tree-face
8322 @vindex gnus-selected-tree-face
8323 Face used for highlighting the selected article in the tree buffer. The
8324 default is @code{modeline}.
8326 @item gnus-tree-line-format
8327 @vindex gnus-tree-line-format
8328 A format string for the tree nodes. The name is a bit of a misnomer,
8329 though---it doesn't define a line, but just the node. The default value
8330 is @samp{"%(%[%3,3n%]%)"}, which displays the first three characters of
8331 the name of the poster. It is vital that all nodes are of the same
8332 length, so you @emph{must} use @samp{%4,4n}-like specifiers.
8338 The name of the poster.
8340 The @code{From} header.
8342 The number of the article.
8344 The opening bracket.
8346 The closing bracket.
8351 @xref{Formatting Variables}.
8353 Variables related to the display are:
8356 @item gnus-tree-brackets
8357 @vindex gnus-tree-brackets
8358 This is used for differentiating between ``real'' articles and ``sparse''
8359 articles. The format is @var{((real-open . real-close) (sparse-open
8360 . sparse-close) (dummy-open . dummy-close))}, and the default is
8361 @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}))}.
8363 @item gnus-tree-parent-child-edges
8364 @vindex gnus-tree-parent-child-edges
8365 This is a list that contains the characters used for connecting parent
8366 nodes to their children. The default is @code{(?- ?\\ ?|)}.
8370 @item gnus-tree-minimize-window
8371 @vindex gnus-tree-minimize-window
8372 If this variable is non-@code{nil}, Gnus will try to keep the tree
8373 buffer as small as possible to allow more room for the other Gnus
8374 windows. If this variable is a number, the tree buffer will never be
8375 higher than that number. The default is @code{t}.
8377 @item gnus-generate-tree-function
8378 @vindex gnus-generate-tree-function
8379 @findex gnus-generate-horizontal-tree
8380 @findex gnus-generate-vertical-tree
8381 The function that actually generates the thread tree. Two predefined
8382 functions are available: @code{gnus-generate-horizontal-tree} and
8383 @code{gnus-generate-vertical-tree} (which is the default).
8387 Here's and example from a horizontal tree buffer:
8390 @{***@}-(***)-[odd]-[Gun]
8400 Here's the same thread displayed in a vertical tree buffer:
8404 |--------------------------\-----\-----\
8405 (***) [Bjo] [Gun] [Gun]
8407 [odd] [Jan] [odd] (***) [Jor]
8409 [Gun] [Eri] [Eri] [odd]
8415 @node Mail Group Commands
8416 @section Mail Group Commands
8417 @cindex mail group commands
8419 Some commands only make sense in mail groups. If these commands are
8420 illegal in the current group, they will raise a hell and let you know.
8422 All these commands (except the expiry and edit commands) use the
8423 process/prefix convention (@pxref{Process/Prefix}).
8428 @kindex B e (Summary)
8429 @findex gnus-summary-expire-articles
8430 Expire all expirable articles in the group
8431 (@code{gnus-summary-expire-articles}).
8434 @kindex B M-C-e (Summary)
8435 @findex gnus-summary-expire-articles-now
8436 Expunge all the expirable articles in the group
8437 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
8438 articles that are eligeble for expiry in the current group will
8439 disappear forever into that big @file{/dev/null} in the sky.
8442 @kindex B DEL (Summary)
8443 @findex gnus-summary-delete-articles
8444 Delete the mail article. This is ``delete'' as in ``delete it from your
8445 disk forever and ever, never to return again.'' Use with caution.
8446 (@code{gnus-summary-delete-article}).
8449 @kindex B m (Summary)
8451 @findex gnus-summary-move-article
8452 Move the article from one mail group to another
8453 (@code{gnus-summary-move-article}).
8456 @kindex B c (Summary)
8458 @findex gnus-summary-copy-article
8459 Copy the article from one group (mail group or not) to a mail group
8460 (@code{gnus-summary-copy-article}).
8463 @kindex B C (Summary)
8464 @cindex crosspost mail
8465 @findex gnus-summary-crosspost-article
8466 Crosspost the current article to some other group
8467 (@code{gnus-summary-crosspost-article}). This will create a new copy of
8468 the article in the other group, and the Xref headers of the article will
8469 be properly updated.
8472 @kindex B i (Summary)
8473 @findex gnus-summary-import-article
8474 Import a random file into the current mail newsgroup
8475 (@code{gnus-summary-import-article}). You will be prompted for a file
8476 name, a @code{From} header and a @code{Subject} header.
8478 Something similar can be done by just starting to compose a mail
8479 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
8480 @kbd{C-c C-p} instead. This will put the message you have just created
8481 into the current mail group.
8484 @kindex B r (Summary)
8485 @findex gnus-summary-respool-article
8486 Respool the mail article (@code{gnus-summary-move-article}).
8490 @kindex B w (Summary)
8492 @findex gnus-summary-edit-article
8493 @kindex C-c C-c (Article)
8494 Edit the current article (@code{gnus-summary-edit-article}). To finish
8495 editing and make the changes permanent, type @kbd{C-c C-c}
8496 (@kbd{gnus-summary-edit-article-done}).
8499 @kindex B q (Summary)
8500 @findex gnus-summary-respool-query
8501 If you want to respool an article, you might be curious as to what group
8502 the article will end up in before you do the respooling. This command
8503 will tell you (@code{gnus-summary-fancy-query}).
8506 If you move (or copy) articles regularly, you might wish to have Gnus
8507 suggest where to put the articles. @code{gnus-move-split-methods} is a
8508 variable that uses the same syntax as @code{gnus-split-methods}
8509 (@pxref{Saving Articles}). You may customize that variable to create
8510 suggestions you find reasonable.
8513 @node Various Summary Stuff
8514 @section Various Summary Stuff
8517 * Group Information:: Information oriented commands.
8518 * Searching for Articles:: Multiple article commands.
8519 * Really Various Summary Commands:: Those pesky non-conformant commands.
8522 @vindex gnus-summary-generate-hook
8523 @code{gnus-summary-generate-hook} is called as the last thing before
8524 doing the threading and the generation of the summary buffer. It's
8525 quite convenient for customizing the threading variables based on what
8526 data the newsgroup has. This hook is called from the summary buffer
8527 after most summary buffer variables has been set.
8529 @vindex gnus-summary-prepare-hook
8530 @code{gnus-summary-prepare-hook} is called after the summary buffer has
8531 been generated. You might use it to, for instance, highlight lines or
8532 modify the look of the buffer in some other ungodly manner. I don't
8535 @node Group Information
8536 @subsection Group Information
8541 @kindex H f (Summary)
8542 @findex gnus-summary-fetch-faq
8543 @vindex gnus-group-faq-directory
8544 Try to fetch the FAQ (list of frequently asked questions) for the
8545 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
8546 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
8547 on a remote machine. This variable can also be a list of directories.
8548 In that case, giving a prefix to this command will allow you to choose
8549 between the various sites. @code{ange-ftp} probably will be used for
8553 @kindex H d (Summary)
8554 @findex gnus-summary-describe-group
8555 Give a brief description of the current group
8556 (@code{gnus-summary-describe-group}). If given a prefix, force
8557 rereading the description from the server.
8560 @kindex H h (Summary)
8561 @findex gnus-summary-describe-briefly
8562 Give a very brief description of the most important summary keystrokes
8563 (@code{gnus-summary-describe-briefly}).
8566 @kindex H i (Summary)
8567 @findex gnus-info-find-node
8568 Go to the Gnus info node (@code{gnus-info-find-node}).
8571 @node Searching for Articles
8572 @subsection Searching for Articles
8577 @kindex M-s (Summary)
8578 @findex gnus-summary-search-article-forward
8579 Search through all subsequent articles for a regexp
8580 (@code{gnus-summary-search-article-forward}).
8583 @kindex M-r (Summary)
8584 @findex gnus-summary-search-article-backward
8585 Search through all previous articles for a regexp
8586 (@code{gnus-summary-search-article-backward}).
8590 @findex gnus-summary-execute-command
8591 This command will prompt you for a header field, a regular expression to
8592 match on this field, and a command to be executed if the match is made
8593 (@code{gnus-summary-execute-command}).
8596 @kindex M-& (Summary)
8597 @findex gnus-summary-universal-argument
8598 Perform any operation on all articles that have been marked with
8599 the process mark (@code{gnus-summary-universal-argument}).
8602 @node Really Various Summary Commands
8603 @subsection Really Various Summary Commands
8608 @kindex A D (Summary)
8609 @findex gnus-summary-enter-digest-group
8610 If the current article is a collection of other articles (for instance,
8611 a digest), you might use this command to enter a group based on the that
8612 article (@code{gnus-summary-enter-digest-group}). Gnus will try to
8613 guess what article type is currently displayed unless you give a prefix
8614 to this command, which forces a ``digest'' interpretation. Basically,
8615 whenever you see a message that is a collection of other messages on
8616 some format, you @kbd{A D} and read these messages in a more convenient
8620 @kindex C-t (Summary)
8621 @findex gnus-summary-toggle-truncation
8622 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
8626 @findex gnus-summary-expand-window
8627 Expand the summary buffer window (@code{gnus-summary-expand-window}).
8628 If given a prefix, force an @code{article} window configuration.
8632 @node The Article Buffer
8633 @chapter The Article Buffer
8634 @cindex article buffer
8636 The articles are displayed in the article buffer, of which there is only
8637 one. All the summary buffers share the same article buffer unless you
8638 tell Gnus otherwise.
8641 * Hiding Headers:: Deciding what headers should be displayed.
8642 * Using MIME:: Pushing articles through @sc{mime} before reading them.
8643 * Customizing Articles:: Tailoring the look of the articles.
8644 * Article Keymap:: Keystrokes available in the article buffer
8645 * Misc Article:: Other stuff.
8649 @node Hiding Headers
8650 @section Hiding Headers
8651 @cindex hiding headers
8652 @cindex deleting headers
8654 The top section of each article is the @dfn{head}. (The rest is the
8655 @dfn{body}, but you may have guessed that already.)
8657 @vindex gnus-show-all-headers
8658 There is a lot of useful information in the head: the name of the person
8659 who wrote the article, the date it was written and the subject of the
8660 article. That's well and nice, but there's also lots of information
8661 most people do not want to see---what systems the article has passed
8662 through before reaching you, the @code{Message-ID}, the
8663 @code{References}, etc. ad nauseum---and you'll probably want to get rid
8664 of some of those lines. If you want to keep all those lines in the
8665 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
8667 Gnus provides you with two variables for sifting headers:
8671 @item gnus-visible-headers
8672 @vindex gnus-visible-headers
8673 If this variable is non-@code{nil}, it should be a regular expression
8674 that says what headers you wish to keep in the article buffer. All
8675 headers that do not match this variable will be hidden.
8677 For instance, if you only want to see the name of the person who wrote
8678 the article and the subject, you'd say:
8681 (setq gnus-visible-headers "^From:\\|^Subject:")
8684 This variable can also be a list of regexps to match headers that are to
8687 @item gnus-ignored-headers
8688 @vindex gnus-ignored-headers
8689 This variable is the reverse of @code{gnus-visible-headers}. If this
8690 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
8691 should be a regular expression that matches all lines that you want to
8692 hide. All lines that do not match this variable will remain visible.
8694 For instance, if you just want to get rid of the @code{References} line
8695 and the @code{Xref} line, you might say:
8698 (setq gnus-ignored-headers "^References:\\|^Xref:")
8701 This variable can also be a list of regexps to match headers that are to
8704 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
8705 variable will have no effect.
8709 @vindex gnus-sorted-header-list
8710 Gnus can also sort the headers for you. (It does this by default.) You
8711 can control the sorting by setting the @code{gnus-sorted-header-list}
8712 variable. It is a list of regular expressions that says in what order
8713 the headers are to be displayed.
8715 For instance, if you want the name of the author of the article first,
8716 and then the subject, you might say something like:
8719 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
8722 Any headers that are to remain visible, but are not listed in this
8723 variable, will be displayed in random order after all the headers that
8724 are listed in this variable.
8726 @findex gnus-article-hide-boring-headers
8727 @vindex gnus-article-display-hook
8728 @vindex gnus-boring-article-headers
8729 You can hide further boring headers by entering
8730 @code{gnus-article-hide-boring-headers} into
8731 @code{gnus-article-display-hook}. What this function does depends on
8732 the @code{gnus-boring-article-headers} variable. It's a list, but this
8733 list doesn't actually contain header names. Instead is lists various
8734 @dfn{boring conditions} that Gnus can check and remove from sight.
8736 These conditions are:
8739 Remove all empty headers.
8741 Remove the @code{Newsgroups} header if it only contains the current group
8744 Remove the @code{Followup-To} header if it is identical to the
8745 @code{Newsgroups} header.
8747 Remove the @code{Reply-To} header if it lists the same address as the
8750 Remove the @code{Date} header if the article is less than three days
8754 To include the four first elements, you could say something like;
8757 (setq gnus-boring-article-headers
8758 '(empty newsgroups followup-to reply-to))
8761 This is also the default value for this variable.
8765 @section Using @sc{mime}
8768 Mime is a standard for waving your hands through the air, aimlessly,
8769 while people stand around yawning.
8771 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
8772 while all newsreaders die of fear.
8774 @sc{mime} may specify what character set the article uses, the encoding
8775 of the characters, and it also makes it possible to embed pictures and
8776 other naughty stuff in innocent-looking articles.
8778 @vindex gnus-show-mime
8779 @vindex gnus-show-mime-method
8780 @vindex gnus-strict-mime
8781 Gnus handles @sc{mime} by shoving the articles through
8782 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
8783 default. Set @code{gnus-show-mime} to @code{t} if you want to use
8784 @sc{mime} all the time. However, if @code{gnus-strict-mime} is
8785 non-@code{nil}, the @sc{mime} method will only be used if there are
8786 @sc{mime} headers in the article.
8788 It might be best to just use the toggling functions from the summary
8789 buffer to avoid getting nasty surprises. (For instance, you enter the
8790 group @samp{alt.sing-a-long} and, before you know it, @sc{mime} has
8791 decoded the sound file in the article and some horrible sing-a-long song
8792 comes streaming out out your speakers, and you can't find the volume
8793 button, because there isn't one, and people are starting to look at you,
8794 and you try to stop the program, but you can't, and you can't find the
8795 program to control the volume, and everybody else in the room suddenly
8796 decides to look at you disdainfully, and you'll feel rather stupid.)
8798 Any similarity to real events and people is purely coincidental. Ahem.
8801 @node Customizing Articles
8802 @section Customizing Articles
8803 @cindex article customization
8805 @vindex gnus-article-display-hook
8806 The @code{gnus-article-display-hook} is called after the article has
8807 been inserted into the article buffer. It is meant to handle all
8808 treatment of the article before it is displayed.
8810 By default it contains @code{gnus-article-hide-headers},
8811 @code{gnus-article-treat-overstrike}, and
8812 @code{gnus-article-maybe-highlight}, but there are thousands, nay
8813 millions, of functions you can put in this hook. For an overview of
8814 functions @xref{Article Highlighting}, @xref{Article Hiding},
8815 @xref{Article Washing}, @xref{Article Buttons} and @xref{Article Date}.
8817 You can, of course, write your own functions. The functions are called
8818 from the article buffer, and you can do anything you like, pretty much.
8819 There is no information that you have to keep in the buffer---you can
8820 change everything. However, you shouldn't delete any headers. Instead
8821 make them invisible if you want to make them go away.
8824 @node Article Keymap
8825 @section Article Keymap
8827 Most of the keystrokes in the summary buffer can also be used in the
8828 article buffer. They should behave as if you typed them in the summary
8829 buffer, which means that you don't actually have to have a summary
8830 buffer displayed while reading. You can do it all from the article
8833 A few additional keystrokes are available:
8838 @kindex SPACE (Article)
8839 @findex gnus-article-next-page
8840 Scroll forwards one page (@code{gnus-article-next-page}).
8843 @kindex DEL (Article)
8844 @findex gnus-article-prev-page
8845 Scroll backwards one page (@code{gnus-article-prev-page}).
8848 @kindex C-c ^ (Article)
8849 @findex gnus-article-refer-article
8850 If point is in the neighborhood of a @code{Message-ID} and you press
8851 @kbd{r}, Gnus will try to get that article from the server
8852 (@code{gnus-article-refer-article}).
8855 @kindex C-c C-m (Article)
8856 @findex gnus-article-mail
8857 Send a reply to the address near point (@code{gnus-article-mail}). If
8858 given a prefix, include the mail.
8862 @findex gnus-article-show-summary
8863 Reconfigure the buffers so that the summary buffer becomes visible
8864 (@code{gnus-article-show-summary}).
8868 @findex gnus-article-describe-briefly
8869 Give a very brief description of the available keystrokes
8870 (@code{gnus-article-describe-briefly}).
8873 @kindex TAB (Article)
8874 @findex gnus-article-next-button
8875 Go to the next button, if any (@code{gnus-article-next-button}. This
8876 only makes sense if you have buttonizing turned on.
8879 @kindex M-TAB (Article)
8880 @findex gnus-article-prev-button
8881 Go to the previous button, if any (@code{gnus-article-prev-button}.
8887 @section Misc Article
8891 @item gnus-single-article-buffer
8892 @vindex gnus-single-article-buffer
8893 If non-@code{nil}, use the same article buffer for all the groups.
8894 (This is the default.) If @code{nil}, each group will have its own
8897 @vindex gnus-article-prepare-hook
8899 @item gnus-article-prepare-hook
8900 This hook is called right after the article has been inserted into the
8901 article buffer. It is mainly intended for functions that do something
8902 depending on the contents; it should probably not be used for changing
8903 the contents of the article buffer.
8904 @vindex gnus-article-display-hook
8906 @item gnus-article-display-hook
8907 This hook is called as the last thing when displaying an article, and is
8908 intended for modifying the contents of the buffer, doing highlights,
8909 hiding headers, and the like.
8910 @vindex gnus-article-mode-line-format
8912 @item gnus-article-mode-line-format
8913 This variable is a format string along the same lines as
8914 @code{gnus-summary-mode-line-format}. It accepts exactly the same
8915 format specifications as that variable.
8916 @vindex gnus-break-pages
8918 @item gnus-break-pages
8919 Controls whether @dfn{page breaking} is to take place. If this variable
8920 is non-@code{nil}, the articles will be divided into pages whenever a
8921 page delimiter appears in the article. If this variable is @code{nil},
8922 paging will not be done.
8924 @item gnus-page-delimiter
8925 @vindex gnus-page-delimiter
8926 This is the delimiter mentioned above. By default, it is @samp{^L}
8930 @node The Server Buffer
8931 @chapter The Server Buffer
8933 Traditionally, a @dfn{server} is a machine or a piece of software that
8934 one connects to, and then requests information from. Gnus does not
8935 connect directly to any real servers, but does all transactions through
8936 one backend or other. But that's just putting one layer more between
8937 the actual media and Gnus, so we might just as well say that each
8938 backend represents a virtual server.
8940 For instance, the @code{nntp} backend may be used to connect to several
8941 different actual @sc{nntp} servers, or, perhaps, to many different ports
8942 on the same actual @sc{nntp} server. You tell Gnus which backend to
8943 use, and what parameters to set by specifying a @dfn{select method}.
8945 These select methods specifications can sometimes become quite
8946 complicated---say, for instance, that you want to read from the
8947 @sc{nntp} server @samp{news.funet.fi} on port number @samp{13}, which
8948 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
8949 Anyways, if you had to specify that for each group that used this
8950 server, that would be too much work, so Gnus offers a way of putting
8951 names to methods, which is what you do in the server buffer.
8953 To enter the server buffer, user the @kbd{^}
8954 (@code{gnus-group-enter-server-mode}) command in the group buffer.
8957 * Server Buffer Format:: You can customize the look of this buffer.
8958 * Server Commands:: Commands to manipulate servers.
8959 * Example Methods:: Examples server specifications.
8960 * Servers ant Methods:: You can use server names as select methods.
8961 * Unavailable Servers:: Some servers you try to contact may be down.
8964 @node Server Buffer Format
8965 @section Server Buffer Format
8966 @cindex server buffer format
8968 @vindex gnus-server-line-format
8969 You can change the look of the server buffer lines by changing the
8970 @code{gnus-server-line-format} variable. This is a @code{format}-like
8971 variable, with some simple extensions:
8976 How the news is fetched---the backend name.
8979 The name of this server.
8982 Where the news is to be fetched from---the address.
8985 @node Server Commands
8986 @section Server Commands
8987 @cindex server commands
8992 Browse the current server (@code{gnus-server-read-server}).
8995 Return to the group buffer (@code{gnus-server-exit}).
8998 List all servers (@code{gnus-server-list-servers}).
9001 Kill the current server (@code{gnus-server-kill-server}).
9004 Yank the previously killed server (@code{gnus-server-yank-server}).
9007 Copy the current server (@code{gnus-server-copy-server}).
9010 Add a new server (@code{gnus-server-add-server}).
9013 Edit a server (@code{gnus-server-edit-server}).
9016 @node Example Methods
9017 @section Example Methods
9019 Most select methods are pretty simple and self-explanatory:
9022 (nntp "news.funet.fi")
9025 Reading directly from the spool is even simpler:
9031 As you can see, the first element in a select method is the name of the
9032 backend, and the second is the @dfn{address}, or @dfn{name}, if you
9035 After these two elements, there may be a random number of @var{(variable
9038 To go back to the first example---imagine that you want to read from
9039 port @code{15} from that machine. This is what the select method should
9043 (nntp "news.funet.fi" (nntp-port-number 15))
9046 You should read the documentation to each backend to find out what
9047 variables are relevant, but here's an @code{nnmh} example.
9049 @code{nnmh} is a mail backend that reads a spool-like structure. Say
9050 you have two structures that you wish to access: One is your private
9051 mail spool, and the other is a public one. Here's the possible spec for
9055 (nnmh "private" (nnmh-directory "~/private/mail/"))
9058 (This server is then called @samp{private}, but you may have guessed
9061 Here's the method for the public spool:
9065 (nnmh-directory "/usr/information/spool/")
9066 (nnmh-get-new-mail nil))
9069 @node Servers and Methods
9070 @section Servers and Methods
9072 Wherever you would normally use a select method
9073 (eg. @code{gnus-secondary-select-method}, in the group select method,
9074 when browsing a foreign server) you can use a virtual server name
9075 instead. This could potentially save lots of typing. And it's nice all
9079 @node Unavailable Servers
9080 @section Unavailable Servers
9082 If a server seems to be unreachable, Gnus will mark that server as
9083 @code{denied}. That means that any subsequent attempt to make contact
9084 with that server will just be ignored. ``It can't be opened,'' Gnus will
9085 tell you, without making the least effort to see whether that is
9086 actually the case or not.
9088 That might seem quite naughty, but it does make sense most of the time.
9089 Let's say you have 10 groups subscribed to the server
9090 @samp{nepholococcygia.com}. This server is located somewhere quite far
9091 away from you, the machine is quite, so it takes 1 minute just to find
9092 out that it refuses connection from you today. If Gnus were to attempt
9093 to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
9094 that. Once it has gotten a single ``connection refused'', it will regard
9095 that server as ``down''.
9097 So, what happens if the machine was only feeling unwell temporarily?
9098 How do you test to see whether the machine has come up again?
9100 You jump to the server buffer (@pxref{The Server Buffer}) and poke ut
9101 with the following commands:
9107 @findex gnus-server-open-server
9108 Try to establish connection to the server on the current line
9109 (@code{gnus-server-open-server}).
9113 @findex gnus-server-close-server
9114 Close the connection (if any) to the server
9115 (@code{gnus-server-close-server}).
9119 @findex gnus-server-deny-server
9120 Mark the current server as unreachable
9121 (@code{gnus-server-deny-server}).
9125 @findex gnus-server-remove-denials
9126 Remove all marks to whether Gnus was denied connection from all servers
9127 (@code{gnus-server-remove-denials}).
9136 Other people use @dfn{kill files}, but we here at Gnus Towers like
9137 scoring better than killing, so we'd rather switch than fight. They do
9138 something completely different as well, so sit up straight and pay
9141 @vindex gnus-summary-mark-below
9142 All articles have a default score (@code{gnus-summary-default-score}),
9143 which is 0 by default. This score may be raised or lowered either
9144 interactively or by score files. Articles that have a score lower than
9145 @code{gnus-summary-mark-below} are marked as read.
9147 Gnus will read any @dfn{score files} that apply to the current group
9148 before generating the summary buffer.
9150 There are several commands in the summary buffer that insert score
9151 entries based on the current article. You can, for instance, ask Gnus to
9152 lower or increase the score of all articles with a certain subject.
9154 There are two sorts of scoring entries: Permanent and temporary.
9155 Temporary score entries are self-expiring entries. Any entries that are
9156 temporary and have not been used for, say, a week, will be removed
9157 silently to help keep the sizes of the score files down.
9160 * Summary Score Commands:: Adding score entries for the current group.
9161 * Group Score Commands:: General score commands.
9162 * Score Variables:: Customize your scoring. (My, what terminology).
9163 * Score File Format:: What a score file may contain.
9164 * Score File Editing:: You can edit score files by hand as well.
9165 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
9166 * Followups To Yourself:: Having Gnus notice when people answer you.
9167 * Scoring Tips:: How to score effectively.
9168 * Reverse Scoring:: That problem child of old is not problem.
9169 * Global Score Files:: Earth-spanning, ear-splitting score files.
9170 * Kill Files:: They are still here, but they can be ignored.
9173 @node Summary Score Commands
9174 @section Summary Score Commands
9175 @cindex score commands
9177 The score commands that alter score entries do not actually modify real
9178 score files. That would be too inefficient. Gnus maintains a cache of
9179 previously loaded score files, one of which is considered the
9180 @dfn{current score file alist}. The score commands simply insert
9181 entries into this list, and upon group exit, this list is saved.
9183 The current score file is by default the group's local score file, even
9184 if no such score file actually exists. To insert score commands into
9185 some other score file (eg. @file{all.SCORE}), you must first make this
9186 score file the current one.
9188 General score commands that don't actually change the score file:
9193 @kindex V s (Summary)
9194 @findex gnus-summary-set-score
9195 Set the score of the current article (@code{gnus-summary-set-score}).
9198 @kindex V S (Summary)
9199 @findex gnus-summary-current-score
9200 Display the score of the current article
9201 (@code{gnus-summary-current-score}).
9204 @kindex V t (Summary)
9205 @findex gnus-score-find-trace
9206 Display all score rules that have been used on the current article
9207 (@code{gnus-score-find-trace}).
9211 @findex gnus-summary-rescore
9212 Run the current summary through the scoring process
9213 (@code{gnus-summary-rescore}). This might be useful if you're playing
9214 around with your score files behind Gnus' back and want to see the
9215 effect you're having.
9218 @kindex V a (Summary)
9219 @findex gnus-summary-score-entry
9220 Add a new score entry, and allow specifying all elements
9221 (@code{gnus-summary-score-entry}).
9224 @kindex V c (Summary)
9225 @findex gnus-score-change-score-file
9226 Make a different score file the current
9227 (@code{gnus-score-change-score-file}).
9230 @kindex V e (Summary)
9231 @findex gnus-score-edit-alist
9232 Edit the current score file (@code{gnus-score-edit-alist}). You will be
9233 popped into a @code{gnus-score-mode} buffer (@pxref{Score File
9237 @kindex V f (Summary)
9238 @findex gnus-score-edit-file
9239 Edit a score file and make this score file the current one
9240 (@code{gnus-score-edit-file}).
9243 @kindex V C (Summary)
9244 @findex gnus-score-customize
9245 Customize a score file in a visually pleasing manner
9246 (@code{gnus-score-customize}).
9249 @kindex I C-i (Summary)
9250 @findex gnus-summary-raise-score
9251 Increase the score of the current article
9252 (@code{gnus-summary-raise-score}).
9255 @kindex L C-l (Summary)
9256 @findex gnus-summary-lower-score
9257 Lower the score of the current article
9258 (@code{gnus-summary-lower-score}).
9261 The rest of these commands modify the local score file.
9266 @kindex V m (Summary)
9267 @findex gnus-score-set-mark-below
9268 Prompt for a score, and mark all articles with a score below this as
9269 read (@code{gnus-score-set-mark-below}).
9272 @kindex V E (Summary)
9273 @findex gnus-score-set-expunge-below
9274 Expunge all articles with a score below the default score (or the
9275 numeric prefix) (@code{gnus-score-set-expunge-below}).
9278 The keystrokes for actually making score entries follow a very regular
9279 pattern, so there's no need to list all the commands. (Hundreds of
9284 The first key is either @kbd{I} (upper case i) for increasing the score
9285 or @kbd{L} for lowering the score.
9287 The second key says what header you want to score on. The following
9292 Score on the author name.
9295 Score on the subject line.
9298 Score on the Xref line---i.e., the cross-posting line.
9301 Score on thread---the References line.
9307 Score on the number of lines.
9310 Score on the Message-ID.
9323 The third key is the match type. Which match types are legal depends on
9324 what headers you are scoring on.
9368 Greater than number.
9373 The fourth and final key says whether this is a temporary (i.e., expiring)
9374 score entry, or a permanent (i.e., non-expiring) score entry, or whether
9375 it is to be done immediately, without adding to the score file.
9379 Temporary score entry.
9382 Permanent score entry.
9385 Immediately scoring.
9390 So, let's say you want to increase the score on the current author with
9391 exact matching permanently: @kbd{I a e p}. If you want to lower the
9392 score based on the subject line, using substring matching, and make a
9393 temporary score entry: @kbd{L s s t}. Pretty easy.
9395 To make things a bit more complicated, there are shortcuts. If you use
9396 a capital letter on either the second or third keys, Gnus will use
9397 defaults for the remaining one or two keystrokes. The defaults are
9398 ``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s t},
9399 and @kbd{I a R} is the same as @kbd{I a r t}.
9401 @vindex gnus-score-mimic-keymap
9402 The @code{gnus-score-mimic-keymap} says whether these commands will
9403 pretend they are keymaps or not.
9406 @node Group Score Commands
9407 @section Group Score Commands
9408 @cindex group score commands
9410 There aren't many of these as yet, I'm afraid.
9416 @findex gnus-score-flush-cache
9417 Gnus maintains a cache of score alists to avoid having to reload them
9418 all the time. This command will flush the cache
9419 (@code{gnus-score-flush-cache}).
9424 @node Score Variables
9425 @section Score Variables
9426 @cindex score variables
9430 @item gnus-use-scoring
9431 @vindex gnus-use-scoring
9432 If @code{nil}, Gnus will not check for score files, and will not, in
9433 general, do any score-related work. This is @code{t} by default.
9435 @item gnus-kill-killed
9436 @vindex gnus-kill-killed
9437 If this variable is @code{nil}, Gnus will never apply score files to
9438 articles that have already been through the kill process. While this
9439 may save you lots of time, it also means that if you apply a kill file
9440 to a group, and then change the kill file and want to run it over you
9441 group again to kill more articles, it won't work. You have to set this
9442 variable to @code{t} to do that. (It is @code{t} by default.)
9444 @item gnus-kill-files-directory
9445 @vindex gnus-kill-files-directory
9446 All kill and score files will be stored in this directory, which is
9447 initialized from the @samp{SAVEDIR} environment variable by default.
9448 This is @file{~/News/} by default.
9450 @item gnus-score-file-suffix
9451 @vindex gnus-score-file-suffix
9452 Suffix to add to the group name to arrive at the score file name
9453 (@samp{SCORE} by default.)
9455 @item gnus-score-uncacheable-files
9456 @vindex gnus-score-uncacheable-files
9458 All score files are normally cached to avoid excessive re-loading of
9459 score files. However, if this might make you Emacs grow big and
9460 bloated, so this regexp can be used to weed out score files that are
9461 unlikely to be needed again. It would be a bad idea to deny caching of
9462 @file{all.SCORE}, while it might be a good idea to not cache
9463 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
9464 variable is @samp{"ADAPT$"} by default, so no adaptive score files will
9467 @item gnus-save-score
9468 @vindex gnus-save-score
9469 If you have really complicated score files, and do lots of batch
9470 scoring, then you might set this variable to @code{t}. This will make
9471 Gnus save the scores into the @file{.newsrc.eld} file.
9473 @item gnus-score-interactive-default-score
9474 @vindex gnus-score-interactive-default-score
9475 Score used by all the interactive raise/lower commands to raise/lower
9476 score with. Default is 1000, which may seem excessive, but this is to
9477 ensure that the adaptive scoring scheme gets enough room to play with.
9478 We don't want the small changes from the adaptive scoring to overwrite
9479 manually entered data.
9481 @item gnus-summary-default-score
9482 @vindex gnus-summary-default-score
9483 Default score of an article, which is 0 by default.
9485 @item gnus-score-over-mark
9486 @vindex gnus-score-over-mark
9487 Mark (in the third column) used for articles with a score over the
9488 default. Default is @samp{+}.
9490 @item gnus-score-below-mark
9491 @vindex gnus-score-below-mark
9492 Mark (in the third column) used for articles with a score below the
9493 default. Default is @samp{-}.
9495 @item gnus-score-find-score-files-function
9496 @vindex gnus-score-find-score-files-function
9497 Function used to find score files for the current group. This function
9498 is called with the name of the group as the argument.
9500 Predefined functions available are:
9503 @item gnus-score-find-single
9504 @findex gnus-score-find-single
9505 Only apply the group's own score file.
9507 @item gnus-score-find-bnews
9508 @findex gnus-score-find-bnews
9509 Apply all score files that match, using bnews syntax. This is the
9510 default. For instance, if the current group is @samp{gnu.emacs.gnus},
9511 @samp{all.emacs.all.SCORE}, @samp{not.alt.all.SCORE} and
9512 @samp{gnu.all.SCORE} would all apply. In short, the instances of
9513 @samp{all} in the score file names are translated into @samp{.*}, and
9514 then a regexp match is done.
9516 This means that if you have some score entries that you want to apply to
9517 all groups, then you put those entries in the @file{all.SCORE} file.
9519 If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
9520 very will. It will find stuff like @file{gnu/all/SCORE}, but will not
9521 find files like @file{not/gnu/all/SCORE}.
9523 @item gnus-score-find-hierarchical
9524 @findex gnus-score-find-hierarchical
9525 Apply all score files from all the parent groups. This means that you
9526 can't have score files like @file{all.SCORE} or @file{all.emacs.SCORE},
9527 but you can have @file{SCORE}, @file{comp.SCORE} and
9528 @file{comp.emacs.SCORE}.
9531 This variable can also be a list of functions. In that case, all these
9532 functions will be called, and all the returned lists of score files will
9533 be applied. These functions can also return lists of score alists
9534 directly. In that case, the functions that return these non-file score
9535 alists should probably be placed before the ``real'' score file functions,
9536 to ensure that the last score file returned is the local score file.
9539 @item gnus-score-expiry-days
9540 @vindex gnus-score-expiry-days
9541 This variable says how many days should pass before an unused score file
9542 entry is expired. If this variable is @code{nil}, no score file entries
9543 are expired. It's 7 by default.
9545 @item gnus-update-score-entry-dates
9546 @vindex gnus-update-score-entry-dates
9547 If this variable is non-@code{nil}, matching score entries will have
9548 their dates updated. (This is how Gnus controls expiry---all
9549 non-matching entries will become too old while matching entries will
9550 stay fresh and young.) However, if you set this variable to @code{nil},
9551 even matching entries will grow old and will have to face that oh-so
9557 @node Score File Format
9558 @section Score File Format
9559 @cindex score file format
9561 A score file is an @code{emacs-lisp} file that normally contains just a
9562 single form. Casual users are not expected to edit these files;
9563 everything can be changed from the summary buffer.
9565 Anyway, if you'd like to dig into it yourself, here's an example:
9569 ("Lars Ingebrigtsen" -10000)
9571 ("larsi\\|lmi" -50000 nil R))
9573 ("Ding is Badd" nil 728373))
9575 ("alt.politics" -1000 728372 s))
9580 (mark-and-expunge -10)
9584 (files "/hom/larsi/News/gnu.SCORE")
9585 (exclude-files "all.SCORE")
9586 (local (gnus-newsgroup-auto-expire t)
9587 (gnus-summary-make-false-root 'empty))
9591 This example demonstrates absolutely everything about a score file.
9593 Even though this looks much like lisp code, nothing here is actually
9594 @code{eval}ed. The lisp reader is used to read this form, though, so it
9595 has to be legal syntactically, if not semantically.
9597 Six keys are supported by this alist:
9602 If the key is a string, it is the name of the header to perform the
9603 match on. Scoring can only be performed on these eight headers:
9604 @samp{From}, @samp{Subject}, @samp{References}, @samp{Message-ID},
9605 @samp{Xref}, @samp{Lines}, @samp{Chars} and @samp{Date}. In addition to
9606 these headers, there are three strings to tell Gnus to fetch the entire
9607 article and do the match on larger parts of the article: @samp{Body}
9608 will perform the match on the body of the article, @samp{Head} will
9609 perform the match on the head of the article, and @samp{All} will
9610 perform the match on the entire article. Note that using any of these
9611 last three keys will slow down group entry @emph{considerably}. The
9612 final ``header'' you can score on is @samp{Followup}. These score entries
9613 will result in new score entries being added for all follow-ups to
9614 articles that matches these score entries.
9616 Following this key is a random number of score entries, where each score
9617 entry has one to four elements.
9621 The first element is the @dfn{match element}. On most headers this will
9622 be a string, but on the Lines and Chars headers, this must be an
9626 If the second element is present, it should be a number---the @dfn{score
9627 element}. This number should be an integer in the neginf to posinf
9628 interval. This number is added to the score of the article if the match
9629 is successful. If this element is not present, the
9630 @code{gnus-score-interactive-default-score} number will be used
9631 instead. This is 1000 by default.
9634 If the third element is present, it should be a number---the @dfn{date
9635 element}. This date says when the last time this score entry matched,
9636 which provides a mechanism for expiring the score entries. It this
9637 element is not present, the score entry is permanent. The date is
9638 represented by the number of days since December 31, 1 ce.
9641 If the fourth element is present, it should be a symbol---the @dfn{type
9642 element}. This element specifies what function should be used to see
9643 whether this score entry matches the article. What match types that can
9644 be used depends on what header you wish to perform the match on.
9647 @item From, Subject, References, Xref, Message-ID
9648 For most header types, there are the @code{r} and @code{R} (regexp) as
9649 well as @code{s} and @code{S} (substring) types and @code{e} and
9650 @code{E} (exact match) types. If this element is not present, Gnus will
9651 assume that substring matching should be used. @code{R} and @code{S}
9652 differ from the other two in that the matches will be done in a
9653 case-sensitive manner. All these one-letter types are really just
9654 abbreviations for the @code{regexp}, @code{string} and @code{exact}
9655 types, which you can use instead, if you feel like.
9658 These two headers use different match types: @code{<}, @code{>},
9659 @code{=}, @code{>=} and @code{<=}.
9662 For the Date header we have three match types: @code{before}, @code{at}
9663 and @code{after}. I can't really imagine this ever being useful, but,
9664 like, it would feel kinda silly not to provide this function. Just in
9665 case. You never know. Better safe than sorry. Once burnt, twice shy.
9666 Don't judge a book by its cover. Never not have sex on a first date.
9668 @item Head, Body, All
9669 These three match keys use the same match types as the @code{From} (etc)
9673 This match key will add a score entry on all articles that followup to
9674 some author. Uses the same match types as the @code{From} header uses.
9677 This match key will add a ascore entry on all articles that are part of
9678 a thread. Uses the same match types as the @code{References} header
9684 The value of this entry should be a number. Any articles with a score
9685 lower than this number will be marked as read.
9688 The value of this entry should be a number. Any articles with a score
9689 lower than this number will be removed from the summary buffer.
9691 @item mark-and-expunge
9692 The value of this entry should be a number. Any articles with a score
9693 lower than this number will be marked as read and removed from the
9696 @item thread-mark-and-expunge
9697 The value of this entry should be a number. All articles that belong to
9698 a thread that has a total score below this number will be marked as read
9699 and removed from the summary buffer. @code{gnus-thread-score-function}
9700 says how to compute the total score for a thread.
9703 The value of this entry should be any number of file names. These files
9704 are assumed to be score files as well, and will be loaded the same way
9708 The clue of this entry should be any number of files. This files will
9709 not be loaded, even though they would normally be so, for some reason or
9713 The value of this entry will be @code{eval}el. This element will be
9714 ignored when handling global score files.
9717 Read-only score files will not be updated or saved. Global score files
9718 should feature this atom (@pxref{Global Score Files}).
9721 The value of this entry should be a number. Articles that do not have
9722 parents will get this number added to their scores.
9725 This entry controls the adaptive scoring. If it is @code{t}, the
9726 default adaptive scoring rules will be used. If it is @code{ignore}, no
9727 adaptive scoring will be performed on this group. If it is a list, this
9728 list will be used as the adaptive scoring rules. If it isn't present,
9729 or is something other than @code{t} or @code{ignore}, the default
9730 adaptive scoring rules will be used. If you want to use adaptive
9731 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
9732 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
9733 not want adaptive scoring. If you only want adaptive scoring in a few
9734 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
9735 insert @code{(adapt t)} in the score files of the groups where you want
9739 All adaptive score entries will go to the file named by this entry. It
9740 will also be applied when entering the group. This atom might be handy
9741 if you want to adapt on several groups at once, using the same adaptive
9742 file for a number of groups.
9745 @cindex local variables
9746 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
9747 Each @var{var} will be made buffer-local to the current summary buffer,
9748 and set to the value specified. This is a convenient, if somewhat
9749 strange, way of setting variables in some groups if you don't like hooks
9753 @node Score File Editing
9754 @section Score File Editing
9756 You normally enter all scoring commands from the summary buffer, but you
9757 might feel the urge to edit them by hand as well, so we've supplied you
9758 with a mode for that.
9760 It's simply a slightly customized @code{emacs-lisp} mode, with these
9761 additional commands:
9766 @kindex C-c C-c (Score)
9767 @findex gnus-score-edit-done
9768 Save the changes you have made and return to the summary buffer
9769 (@code{gnus-score-edit-done}).
9772 @kindex C-c C-d (Score)
9773 @findex gnus-score-edit-insert-date
9774 Insert the current date in numerical format
9775 (@code{gnus-score-edit-insert-date}). This is really the day number, if
9779 @kindex C-c C-p (Score)
9780 @findex gnus-score-pretty-print
9781 The adaptive score files are saved in an unformatted fashion. If you
9782 intend to read one of these files, you want to @dfn{pretty print} it
9783 first. This command (@code{gnus-score-pretty-print}) does that for
9788 @node Adaptive Scoring
9789 @section Adaptive Scoring
9790 @cindex adaptive scoring
9792 If all this scoring is getting you down, Gnus has a way of making it all
9793 happen automatically---as if by magic. Or rather, as if by artificial
9794 stupidity, to be precise.
9796 @vindex gnus-use-adaptive-scoring
9797 When you read an article, or mark an article as read, or kill an
9798 article, you leave marks behind. On exit from the group, Gnus can sniff
9799 these marks and add score elements depending on what marks it finds.
9800 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
9803 @vindex gnus-default-adaptive-score-alist
9804 To give you complete control over the scoring process, you can customize
9805 the @code{gnus-default-adaptive-score-alist} variable. By default, it
9806 looks something like this:
9809 (defvar gnus-default-adaptive-score-alist
9810 '((gnus-unread-mark)
9811 (gnus-ticked-mark (from 4))
9812 (gnus-dormant-mark (from 5))
9813 (gnus-del-mark (from -4) (subject -1))
9814 (gnus-read-mark (from 4) (subject 2))
9815 (gnus-expirable-mark (from -1) (subject -1))
9816 (gnus-killed-mark (from -1) (subject -3))
9817 (gnus-kill-file-mark)
9818 (gnus-catchup-mark (from -1) (subject -1))))
9821 As you see, each element in this alist has a mark as a key (either a
9822 variable name or a ``real'' mark---a character). Following this key is a
9823 random number of header/score pairs.
9825 To take @code{gnus-del-mark} as an example---this alist says that all
9826 articles that have that mark (i.e., are marked with @samp{D}) will have a
9827 score entry added to lower based on the @code{From} header by -4, and
9828 lowered by @code{Subject} by -1. Change this to fit your prejudices.
9830 The headers you can score on are @code{from}, @code{subject},
9831 @code{message-id}, @code{references}, @code{xref}, @code{lines},
9832 @code{chars} and @code{date}. In addition, you can score on
9833 @code{followup}, which will create an adaptive score entry that matches
9834 on the @code{References} header using the @code{Message-ID} of the
9835 current article, thereby matching the following thread.
9837 You can also score on @code{thread}, which will try to score all
9838 articles that appear in a thread. @code{thread} matches uses a
9839 @code{Message-ID} to match on the @code{References} header of the
9840 article. If the match is made, the @code{Message-ID} of the article is
9841 added to the @code{thread} rule. (Think about it. I'd recommend two
9842 aspirins afterwards.)
9844 If you use this scheme, you should set @code{mark-below} to something
9845 small---like -300, perhaps, to avoid having small random changes result
9846 in articles getting marked as read.
9848 After using adaptive scoring for a week or so, Gnus should start to
9849 become properly trained and enhance the authors you like best, and kill
9850 the authors you like least, without you having to say so explicitly.
9852 You can control what groups the adaptive scoring is to be performed on
9853 by using the score files (@pxref{Score File Format}). This will also
9854 let you use different rules in different groups.
9856 @vindex gnus-adaptive-file-suffix
9857 The adaptive score entries will be put into a file where the name is the
9858 group name with @code{gnus-adaptive-file-suffix} appended. The default
9861 @vindex gnus-score-exact-adapt-limit
9862 When doing adaptive scoring, substring or fuzzy matching would probably
9863 give you the best results in most cases. However, if the header one
9864 matches is short, the possibility for false positives is great, so if
9865 the length of the match is less than
9866 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
9867 this variable is @code{nil}, exact matching will always be used to avoid
9871 @node Followups To Yourself
9872 @section Followups To Yourself
9874 Gnus offers two commands for picking out the @code{Message-ID} header in
9875 the current buffer. Gnus will then add a score rule that scores using
9876 this @code{Message-ID} on the @code{References} header of other
9877 articles. This will, in effect, increase the score of all articles that
9878 respond to the article in the current buffer. Quite useful if you want
9879 to easily note when people answer what you've said.
9883 @item gnus-score-followup-article
9884 @findex gnus-score-followup-article
9885 This will add a score to articles that directly follow up your own
9888 @item gnus-score-followup-thread
9889 @findex gnus-score-followup-thread
9890 This will add a score to all articles that appear in a thread ``below''
9894 @vindex gnus-inews-article-hook
9895 These two functions are both primarily meant to be used in hooks like
9896 @code{gnus-inews-article-hook}.
9900 @section Scoring Tips
9901 @cindex scoring tips
9906 If you want to lower the score of crossposts, the line to match on is
9907 the @code{Xref} header.
9909 ("xref" (" talk.politics.misc:" -1000))
9912 @item Multiple crossposts
9913 If you want to lower the score of articles that have been crossposted to
9914 more than, say, 3 groups:
9916 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
9919 @item Matching on the body
9920 This is generally not a very good idea---it takes a very long time.
9921 Gnus actually has to fetch each individual article from the server. But
9922 you might want to anyway, I guess. Even though there are three match
9923 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
9924 and stick with it in each score file. If you use any two, each article
9925 will be fetched @emph{twice}. If you want to match a bit on the
9926 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
9929 @item Marking as read
9930 You will probably want to mark articles that has a score below a certain
9931 number as read. This is most easily achieved by putting the following
9932 in your @file{all.SCORE} file:
9936 You may also consider doing something similar with @code{expunge}.
9938 @item Negated charater classes
9939 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
9940 That will match newlines, which might lead to, well, The Unknown. Say
9941 @code{[^abcd\n]*} instead.
9944 @node Reverse Scoring
9945 @section Reverse Scoring
9946 @cindex reverse scoring
9948 If you want to keep just articles that have @samp{Sex with Emacs} in the
9949 subject header, and expunge all other articles, you could put something
9950 like this in your score file:
9954 ("Sex with Emacs" 2))
9959 So, you raise all articles that match @samp{Sex with Emacs} and mark the
9960 rest as read, and expunge them to boot.
9962 @node Global Score Files
9963 @section Global Score Files
9964 @cindex global score files
9966 Sure, other newsreaders have ``global kill files''. These are usually
9967 nothing more than a single kill file that applies to all groups, stored
9968 in the user's home directory. Bah! Puny, weak newsreaders!
9970 What I'm talking about here are Global Score Files. Score files from
9971 all over the world, from users everywhere, uniting all nations in one
9972 big, happy score file union! Ange-score! New and untested!
9974 @vindex gnus-global-score-files
9975 All you have to do to use other people's score files is to set the
9976 @code{gnus-global-score-files} variable. One entry for each score file,
9977 or each score file directory. Gnus will decide by itself what score
9978 files are applicable to which group.
9980 Say you want to use all score files in the
9981 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
9982 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
9985 (setq gnus-global-score-files
9986 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
9987 "/ftp@@ftp.some-where:/pub/score/"))
9990 @findex gnus-score-search-global-directories
9991 Simple, eh? Directory names must end with a @samp{/}. These
9992 directories are typically scanned only once during each Gnus session.
9993 If you feel the need to manually re-scan the remote directories, you can
9994 use the @code{gnus-score-search-global-directories} command.
9996 Note that, at present, using this option will slow down group entry
9997 somewhat. (That is---a lot.)
9999 If you want to start maintaining score files for other people to use,
10000 just put your score file up for anonymous ftp and announce it to the
10001 world. Become a retro-moderator! Participate in the retro-moderator
10002 wars sure to ensue, where retro-moderators battle it out for the
10003 sympathy of the people, luring them to use their score files on false
10004 premises! Yay! The net is saved!
10006 Here are some tips for the would-be retro-moderator, off the top of my
10012 Articles that are heavily crossposted are probably junk.
10014 To lower a single inappropriate article, lower by @code{Message-ID}.
10016 Particularly brilliant authors can be raised on a permanent basis.
10018 Authors that repeatedly post off-charter for the group can safely be
10019 lowered out of existence.
10021 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
10022 articles completely.
10025 Use expiring score entries to keep the size of the file down. You
10026 should probably have a long expiry period, though, as some sites keep
10027 old articles for a long time.
10030 ... I wonder whether other newsreaders will support global score files
10031 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
10032 Wave, xrn and 1stReader are bound to implement scoring. Should we start
10033 holding our breath yet?
10037 @section Kill Files
10040 Gnus still supports those pesky old kill files. In fact, the kill file
10041 entries can now be expiring, which is something I wrote before Daniel
10042 Quinlan thought of doing score files, so I've left the code in there.
10044 In short, kill processing is a lot slower (and I do mean @emph{a lot})
10045 than score processing, so it might be a good idea to rewrite your kill
10046 files into score files.
10048 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
10049 forms into this file, which means that you can use kill files as some
10050 sort of primitive hook function to be run on group entry, even though
10051 that isn't a very good idea.
10053 XCNormal kill files look like this:
10056 (gnus-kill "From" "Lars Ingebrigtsen")
10057 (gnus-kill "Subject" "ding")
10061 This will mark every article written by me as read, and remove them from
10062 the summary buffer. Very useful, you'll agree.
10064 Other programs use a totally different kill file syntax. If Gnus
10065 encounters what looks like a @code{rn} kill file, it will take a stab at
10068 Two functions for editing a GNUS kill file:
10073 @kindex M-k (Summary)
10074 @findex gnus-summary-edit-local-kill
10075 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
10078 @kindex M-K (Summary)
10079 @findex gnus-summary-edit-global-kill
10080 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
10083 @vindex gnus-kill-file-name
10084 A kill file for the group @samp{soc.motss} is normally called
10085 @file{soc.motss.KILL}. The suffix appended to the group name to get
10086 this file name is detailed by the @code{gnus-kill-file-name} variable.
10087 The ``global'' kill file (not in the score file sense of ``global'', of
10088 course) is called just @file{KILL}.
10090 @vindex gnus-kill-save-kill-file
10091 If @code{gnus-kill-save-kill-file} is non-@code{nil}, Gnus will save the
10092 kill file after processing, which is necessary if you use expiring
10102 * Interactive:: Making Gnus ask you many questions.
10103 * Formatting Variables:: How to control the look of the buffers.
10104 * Windows Configuration:: Configuring the Gnus buffer windows.
10105 * Buttons:: Get tendonitis in ten easy steps!
10106 * Compilation and Init File:: How to speed Gnus up.
10107 * Daemons:: Gnus can do things behind your back.
10108 * NoCeM:: How to avoid spam and other fatty foods.
10109 * Various Various:: Things that are really various.
10113 @section Interactive
10114 @cindex interaction
10118 @item gnus-novice-user
10119 @vindex gnus-novice-user
10120 If this variable is non-@code{nil}, you are either a newcomer to the
10121 World of Usenet, or you are very cautious, which is a nice thing to be,
10122 really. You will be given questions of the type ``Are you sure you want
10123 to do this?'' before doing anything dangerous. This is @code{t} by
10126 @item gnus-expert-user
10127 @vindex gnus-expert-user
10128 If this variable is non-@code{nil}, you will never ever be asked any
10129 questions by Gnus. It will simply assume you know what you're doing, no
10130 matter how strange.
10132 @item gnus-interactive-catchup
10133 @vindex gnus-interactive-catchup
10134 Require confirmation before catching up a group if non-@code{nil}. It
10135 is @code{t} by default.
10137 @item gnus-interactive-post
10138 @vindex gnus-interactive-post
10139 If non-@code{nil}, the user will be prompted for a group name when
10140 posting an article. It is @code{t} by default.
10142 @item gnus-interactive-exit
10143 @vindex gnus-interactive-exit
10144 Require confirmation before exiting Gnus. This variable is @code{t} by
10149 @node Formatting Variables
10150 @section Formatting Variables
10151 @cindex formatting variables
10153 Throughout this manual you've probably noticed lots of variables that
10154 are called things like @code{gnus-group-line-format} and
10155 @code{gnus-summary-mode-line-format}. These control how Gnus is to
10156 output lines in the various buffers. There's quite a lot of them.
10157 Fortunately, they all use the same syntax, so there's not that much to
10160 Here's an example format spec (from the group buffer): @samp{"%M%S%5y:
10161 %(%g%)\n"}. We see that it is indeed extremely ugly, and that there are
10162 lots of percentages everywhere.
10164 Each @samp{%} element will be replaced by some string or other when the
10165 buffer in question is generated. @samp{%5y} means ``insert the @samp{y}
10166 spec, and pad with spaces to get a 5-character field''. Just like a
10167 normal format spec, almost.
10169 You can also say @samp{%6,4y}, which means that the field will never be
10170 more than 6 characters wide and never less than 4 characters wide.
10172 There are also specs for highlighting, and these are shared by all the
10173 format variables. Text inside the @samp{%(} and @samp{%)} specifiers
10174 will get the special @code{mouse-face} property set, which means that it
10175 will be highlighted (with @code{gnus-mouse-face}) when you put the mouse
10178 Text inside the @samp{%[} and @samp{%]} specifiers will have their
10179 normal faces set using @code{gnus-face-0}, which is @code{bold} by
10180 default. If you say @samp{%1[} instead, you'll get @code{gnus-face-1}
10181 instead, and so on. Create as many faces as you wish. The same goes
10182 for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
10183 @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
10185 Here's an alternative recipe for the group buffer:
10188 ;; Create three face types.
10189 (setq gnus-face-1 'bold)
10190 (setq gnus-face-3 'italic)
10192 ;; We want the article count to be in
10193 ;; a bold and green face. So we create
10194 ;; a new face called `my-green-bold'.
10195 (copy-face 'bold 'my-green-bold)
10197 (set-face-foreground 'my-green-bold "ForestGreen")
10198 (setq gnus-face-2 'my-green-bold)
10200 ;; Set the new & fancy format.
10201 (setq gnus-group-line-format
10202 "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
10205 I'm sure you'll be able to use this scheme to create totally unreadable
10206 and extremely vulgar displays. Have fun!
10208 Currently Gnus uses the following formatting variables:
10209 @code{gnus-group-line-format}, @code{gnus-summary-line-format},
10210 @code{gnus-server-line-format}, @code{gnus-topic-line-format},
10211 @code{gnus-group-mode-line-format},
10212 @code{gnus-summary-mode-line-format},
10213 @code{gnus-article-mode-line-format},
10214 @code{gnus-server-mode-line-format}.
10216 Note that the @samp{%(} specs (and friends) do not make any sense on the
10217 mode-line variables.
10219 All these format variables can also be random elisp forms. In that
10220 case, they will be @code{eval}ed to insert the required lines.
10222 @kindex M-x gnus-update-format
10223 @findex gnus-update-format
10224 Gnus includes a command to help you while creating your own format
10225 specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
10226 update the spec in question and pop you to a buffer where you can
10227 examine the resulting lisp code to be run to generate the line.
10230 @node Windows Configuration
10231 @section Windows Configuration
10232 @cindex windows configuration
10234 No, there's nothing here about X, so be quiet.
10236 @vindex gnus-use-full-window
10237 If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
10238 other windows and occupy the entire Emacs screen by itself. It is
10239 @code{t} by default.
10241 @code{gnus-buffer-configuration} describes how much space each Gnus
10242 buffer should be given. Here's an excerpt of this variable:
10245 ((group (vertical 1.0 (group 1.0 point)
10246 (if gnus-carpal (group-carpal 4))))
10247 (article (vertical 1.0 (summary 0.25 point)
10251 This is an alist. The @dfn{key} is a symbol that names some action or
10252 other. For instance, when displaying the group buffer, the window
10253 configuration function will use @code{group} as the key. A full list of
10254 possible names is listed below.
10256 The @dfn{value} (i. e., the @dfn{split}) says how much space each buffer
10257 should occupy. To take the @code{article} split as an example -
10260 (article (vertical 1.0 (summary 0.25 point)
10264 This @dfn{split} says that the summary buffer should occupy 25% of upper
10265 half of the screen, and that it is placed over the article buffer. As
10266 you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
10267 reaching for that calculator there). However, the special number
10268 @code{1.0} is used to signal that this buffer should soak up all the
10269 rest of the space avaiable after the rest of the buffers have taken
10270 whatever they need. There should be only one buffer with the @code{1.0}
10271 size spec per split.
10273 Point will be put in the buffer that has the optional third element
10276 Here's a more complicated example:
10279 (article (vertical 1.0 (group 4)
10280 (summary 0.25 point)
10281 (if gnus-carpal (summary-carpal 4))
10285 If the size spec is an integer instead of a floating point number,
10286 then that number will be used to say how many lines a buffer should
10287 occupy, not a percentage.
10289 If the @dfn{split} looks like something that can be @code{eval}ed (to be
10290 precise---if the @code{car} of the split is a function or a subr), this
10291 split will be @code{eval}ed. If the result is non-@code{nil}, it will
10292 be used as a split. This means that there will be three buffers if
10293 @code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
10296 Not complicated enough for you? Well, try this on for size:
10299 (article (horizontal 1.0
10304 (summary 0.25 point)
10309 Whoops. Two buffers with the mystery 100% tag. And what's that
10310 @code{horizontal} thingie?
10312 If the first element in one of the split is @code{horizontal}, Gnus will
10313 split the window horizontally, giving you two windows side-by-side.
10314 Inside each of these strips you may carry on all you like in the normal
10315 fashion. The number following @code{horizontal} says what percentage of
10316 the screen is to be given to this strip.
10318 For each split, there @emph{must} be one element that has the 100% tag.
10319 The splitting is never accurate, and this buffer will eat any leftover
10320 lines from the splits.
10322 To be slightly more formal, here's a definition of what a legal split
10326 split = frame | horizontal | vertical | buffer | form
10327 frame = "(frame " size *split ")"
10328 horizontal = "(horizontal " size *split ")"
10329 vertical = "(vertical " size *split ")"
10330 buffer = "(" buffer-name " " size *[ "point" ] ")"
10331 size = number | frame-params
10332 buffer-name = group | article | summary ...
10335 The limitations are that the @samp{frame} split can only appear as the
10336 top-level split. @samp{form} should be an Emacs Lisp form that should
10337 return a valid split. We see that each split is fully recursive, and
10338 may contain any number of @samp{vertical} and @samp{horizontal} splits.
10340 @vindex gnus-window-min-width
10341 @vindex gnus-window-min-height
10342 @cindex window height
10343 @cindex window width
10344 Finding the right sizes can be a bit complicated. No window may be less
10345 than @code{gnus-window-min-height} (default 2) characters high, and all
10346 windows must be at least @code{gnus-window-min-wide} (default 1)
10347 characters wide. Gnus will try to enforce this before applying the
10348 splits. If you want to use the normal Emacs window width/height limit,
10349 you can just set these two variables to @code{nil}.
10351 If you're not familiar with Emacs terminology, @samp{horizontal} and
10352 @samp{vertical} splits may work the opposite way of what you'd expect.
10353 Windows inside a @samp{horizontal} split are shown side-by-side, and
10354 windows within a @samp{vertical} split are shown above each other.
10356 @findex gnus-configure-frame
10357 If you want to experiment with window placement, a good tip is to call
10358 @code{gnus-configure-frame} directly with a split. This is the function
10359 that does all the real work when splitting buffers. Below is a pretty
10360 nonsensical configuration with 5 windows; two for the group buffer and
10361 three for the article buffer. (I said it was nonsensical.) If you
10362 @code{eval} the statement below, you can get an idea of how that would
10363 look straight away, without going through the normal Gnus channels.
10364 Play with it until you're satisfied, and then use
10365 @code{gnus-add-configuration} to add your new creation to the buffer
10366 configuration list.
10369 (gnus-configure-frame
10373 (article 0.3 point))
10381 You might want to have several frames as well. No prob---just use the
10382 @code{frame} split:
10385 (gnus-configure-frame
10388 (summary 0.25 point)
10390 (vertical ((height . 5) (width . 15)
10391 (user-position . t)
10392 (left . -1) (top . 1))
10397 This split will result in the familiar summary/article window
10398 configuration in the first (or ``main'') frame, while a small additional
10399 frame will be created where picons will be shown. As you can see,
10400 instead of the normal @samp{1.0} top-level spec, each additional split
10401 should have a frame parameter alist as the size spec.
10402 @xref{(elisp)Frame Parameters}.
10404 Here's a list of all possible keys for
10405 @code{gnus-buffer-configuaration}:
10407 @code{group}, @code{summary}, @code{article}, @code{server},
10408 @code{browse}, @code{group-mail}, @code{summary-mail},
10409 @code{summary-reply}, @code{info}, @code{summary-faq},
10410 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
10411 @code{followup}, @code{followup-yank}, @code{edit-score}.
10413 @findex gnus-add-configuration
10414 Since the @code{gnus-buffer-configuration} variable is so long and
10415 complicated, there's a function you can use to ease changing the config
10416 of a single setting: @code{gnus-add-configuration}. If, for instance,
10417 you want to change the @code{article} setting, you could say:
10420 (gnus-add-configuration
10421 '(article (vertical 1.0
10423 (summary .25 point)
10427 You'd typically stick these @code{gnus-add-configuration} calls in your
10428 @file{.gnus} file or in some startup hook -- they should be run after
10429 Gnus has been loaded.
10438 Those new-fangled @dfn{mouse} contraptions is very popular with the
10439 young, hep kids who don't want to learn the proper way to do things
10440 these days. Why, I remember way back in the summer of '89, when I was
10441 using Emacs on a Tops 20 system. Three hundred users on one single
10442 machine, and every user was running Simula compilers. Bah!
10446 @vindex gnus-carpal
10447 Well, you can make Gnus display bufferfuls of buttons you can click to
10448 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
10449 really. Tell the chiropractor I sent you.
10454 @item gnus-carpal-mode-hook
10455 @vindex gnus-carpal-mode-hook
10456 Hook run in all carpal mode buffers.
10458 @item gnus-carpal-button-face
10459 @vindex gnus-carpal-button-face
10460 Face used on buttons.
10462 @item gnus-carpal-group-buffer-buttons
10463 @vindex gnus-carpal-group-buffer-buttons
10464 Buttons in the group buffer.
10466 @item gnus-carpal-summary-buffer-buttons
10467 @vindex gnus-carpal-summary-buffer-buttons
10468 Buttons in the summary buffer.
10470 @item gnus-carpal-server-buffer-buttons
10471 @vindex gnus-carpal-server-buffer-buttons
10472 Buttons in the server buffer.
10474 @item gnus-carpal-browse-buffer-buttons
10475 @vindex gnus-carpal-browse-buffer-buttons
10476 Buttons in the browse buffer.
10479 All the @code{buttons} variables are lists. The elements in these list
10480 is either a cons cell where the car contains a text to be displayed and
10481 the cdr contains a function symbol, or a simple string.
10484 @node Compilation and Init File
10485 @section Compilation and Init File
10486 @cindex compilation
10488 @cindex byte-compilation
10490 @vindex gnus-init-file
10491 @findex gnus-compile
10492 When Gnus starts up, it will read the Gnus init file
10493 @code{gnus-init-file}, which is @file{.gnus} by default. It is
10494 recommended that you keep any Gnus-related functions that you have
10495 written in that file. If you want to byte-compile the file, Gnus offers
10496 the handy @kbd{M-x gnus-compile} function that will do that for you.
10498 That's not really why that function was written, though.
10500 Remember all those line format specification variables?
10501 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
10502 on. Now, Gnus will of course heed whatever these variables are, but,
10503 unfortunately, changing them will mean a quite significant slow-down.
10504 (The default values of these variables have byte-compiled functions
10505 associated with them, while the user-generated versions do not, of
10508 To help with this, you can run @code{gnus-compile} after you've fiddled
10509 around with the variables and feel that you're (kind of) satisfied.
10510 This will result in the new specs being byte-compiled, and you'll get
10513 The result of these byte-compilations will be written to
10514 @file{.gnus.elc} by default.
10516 Note that Gnus will read @file{.gnus.elc} instead of @file{.gnus} if
10517 @file{.gnus.elc} exists, so if you change @file{.gnus}, you should
10518 remove @file{.gnus.elc}.
10526 Gnus, being larger than any program ever written (allegedly), does lots
10527 of strange stuff that you may wish to have done while you're not
10528 present. For instance, you may want it to check for new mail once in a
10529 while. Or you may want it to close down all connections to all servers
10530 when you leave Emacs idle. And stuff like that.
10532 Gnus will let you do stuff like that by defining various
10533 @dfn{handlers}. Each handler consists of three elements: A
10534 @var{function}, a @var{time}, and an @var{idle} parameter.
10536 Here's an example of a handler that closes connections when Emacs has
10537 been idle for thirty minutes:
10540 (gnus-demon-close-connections nil 30)
10543 Here's a handler that scans for PGP headers every hour when Emacs is
10547 (gnus-demon-scan-pgp 60 t)
10550 This @var{time} parameter and than @var{idle} parameter works together
10551 in a strange, but wonderful fashion. Basically, if @var{idle} is
10552 @code{nil}, then the function will be called every @var{time} minutes.
10554 If @var{idle} is @code{t}, then the function will be called after
10555 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
10556 the function will never be called. But once Emacs goes idle, the
10557 function will be called every @var{time} minutes.
10559 If @var{idle} is a number and @var{time} is a number, the function will
10560 be called every @var{time} minutes only when Emacs has been idle for
10561 @var{idle} minutes.
10563 If @var{idle} is a number and @var{time} is @code{nil}, the function
10564 will be called once every time Emacs has been idle for @var{idle}
10567 And if @var{time} is a string, it should look like @samp{"07:31"}, and
10568 the function will then be called once every day somewhere near that
10569 time. Modified by the @var{idle} parameter, of course.
10571 @vindex gnus-demon-timestep
10572 (When I say ``minute'' here, I really mean @code{gnus-demon-timestep}
10573 seconds. This is @samp{60} by default. If you change that variable,
10574 all the timings in the handlers will be affected.)
10576 @vindex gnus-use-demon
10577 To set the whole thing in motion, though, you have to set
10578 @code{gnus-use-demon} to @code{t}.
10580 @vindex gnus-use-demon
10581 To set the whole thing in motion, though, you have to set
10582 @code{gnus-use-demon} to @code{t}.
10584 So, if you want to add a handler, you could put something like this in
10585 your @file{.gnus} file:
10587 @findex gnus-demon-add-handler
10589 (gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
10592 @findex gnus-demon-add-nocem
10593 @findex gnus-demon-add-scanmail
10594 @findex gnus-demon-add-disconnection
10595 Some ready-made functions to do this has been created:
10596 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
10597 @code{gnus-demon-add-scanmail}. Just put those functions in your
10598 @file{.gnus} if you want those abilities.
10600 @findex gnus-demon-init
10601 @findex gnus-demon-cancel
10602 @vindex gnus-demon-handlers
10603 If you add handlers to @code{gnus-demon-handlers} directly, you should
10604 run @code{gnus-demon-init} to make the changes take hold. To cancel all
10605 daemons, you can use the @code{gnus-demon-cancel} function.
10607 Note that adding daemons can be pretty naughty if you overdo it. Adding
10608 functions that scan all news and mail from all servers every two seconds
10609 is a sure-fire way of getting booted off any respectable system. So
10620 @node Various Various
10621 @section Various Various
10628 @vindex gnus-verbose
10629 This variable is an integer between zero and ten. The higher the value,
10630 the more messages will be displayed. If this variable is zero, Gnus
10631 will never flash any messages, if it is seven (which is the default),
10632 most important messages will be shown, and if it is ten, Gnus won't ever
10633 shut up, but will flash so many messages it will make your head swim.
10635 @item gnus-verbose-backends
10636 @vindex gnus-verbose-backends
10637 This variable works the same way as @code{gnus-verbose}, but it applies
10638 to the Gnus backends instead of Gnus proper.
10640 @item gnus-updated-mode-lines
10641 @vindex gnus-updated-mode-lines
10642 This is a list of buffers that should keep their mode lines updated.
10643 The list may contain the symbols @code{group}, @code{article} and
10644 @code{summary}. If the corresponding symbol is present, Gnus will keep
10645 that mode line updated with information that may be pertinent. If this
10646 variable is @code{nil}, screen refresh may be quicker.
10648 @cindex display-time
10650 @item gnus-mode-non-string-length
10651 @vindex gnus-mode-non-string-length
10652 By default, Gnus displays information on the current article in the mode
10653 lines of the summary and article buffers. The information Gnus wishes
10654 to display (eg. the subject of the article) is often longer than the
10655 mode lines, and therefore have to be cut off at some point. This
10656 variable says how long the other elements on the line is (i.e., the
10657 non-info part). If you put additional elements on the mode line (eg. a
10658 clock), you should modify this variable:
10660 @c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
10662 (add-hook 'display-time-hook
10663 (lambda () (setq gnus-mode-non-string-length
10665 (if line-number-mode 5 0)
10666 (if column-number-mode 4 0)
10667 (length display-time-string)))))
10670 If this variable is @code{nil} (which is the default), the mode line
10671 strings won't be chopped off, and they won't be padded either.
10674 @vindex gnus-visual
10676 @cindex highlighting
10679 If @code{nil}, Gnus won't attempt to create menus or use fancy colors
10680 or fonts. This will also inhibit loading the @file{gnus-visual.el}
10683 This variable can also be a list of visual properties that are enabled.
10684 The following elements are legal, and are all set by default:
10688 @item summary-highlight
10689 Perform various highlighting in the summary buffer.
10691 @item article-highlight
10692 Perform various highlighting in the article buffer.
10695 Turn on highlighting in all buffers.
10698 Create menus in the group buffer.
10701 Create menus in the summary buffer.
10704 Create menus in the article buffer.
10707 Create menus in the browse buffer.
10710 Create menus in the server buffer.
10713 Create menus in all buffers.
10717 So if you only want highlighting in the article buffer and menus in all
10718 buffers, you couls say something like:
10721 (setq gnus-visual '(article-highlight menu))
10724 If you want only highlighting and no menus whatsoever, you'd say:
10727 (setq gnus-visual '(highlight))
10730 @item gnus-mouse-face
10731 @vindex gnus-mouse-face
10732 This is the face (i.e., font) used for mouse highlighting in Gnus. No
10733 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
10735 @item gnus-display-type
10736 @vindex gnus-display-type
10737 This variable is symbol indicating the display Emacs is running under.
10738 The symbol should be one of @code{color}, @code{grayscale} or
10739 @code{mono}. If Gnus guesses this display attribute wrongly, either set
10740 this variable in your @file{~/.emacs} or set the resource
10741 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
10743 @item gnus-background-mode
10744 @vindex gnus-background-mode
10745 This is a symbol indicating the Emacs background brightness. The symbol
10746 should be one of @code{light} or @code{dark}. If Gnus guesses this
10747 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
10748 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
10749 `gnus-display-type'.
10751 @item nnheader-max-head-length
10752 @vindex nnheader-max-head-length
10753 When the backends read straight heads of articles, they all try to read
10754 as little as possible. This variable (default @code{4096}) specifies
10755 the absolute max length the backends will try to read before giving up
10756 on finding a separator line between the head and the body. If this
10757 variable is @code{nil}, there is no upper read bound. If it is
10758 @code{t}, the backends won't try to read the articles piece by piece,
10759 but read the entire articles. This makes sense with some versions of
10762 @item nnheader-file-name-translation-alist
10763 @vindex nnheader-file-name-translation-alist
10765 @cindex illegal characters in file names
10766 @cindex characters in file names
10767 This is an alist that says how to translate characters in file names.
10768 For instance, if @samp{:} is illegal as a file character in file names
10769 on your system (you OS/2 user you), you could say something like:
10772 (setq nnheader-file-name-translation-alist
10776 In fact, this is the default value for this variable on OS/2 and MS
10777 Windows (phooey) systems.
10781 @node Customization
10782 @chapter Customization
10783 @cindex general customization
10785 All variables are properly documented elsewhere in this manual. This
10786 section is designed to give general pointers on how to customize Gnus
10787 for some quite common situations.
10790 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
10791 * Slow Terminal Connection:: You run a remote Emacs.
10792 * Little Disk Space:: You feel that having large setup files is icky.
10793 * Slow Machine:: You feel like buying a faster machine.
10796 @node Slow/Expensive Connection
10797 @section Slow/Expensive @sc{nntp} Connection
10799 If you run Emacs on a machine locally, and get your news from a machine
10800 over some very thin strings, you want to cut down on the amount of data
10801 Gnus has to get from the @sc{nntp} server.
10805 @item gnus-read-active-file
10806 Set this to @code{nil}, which will inhibit Gnus from requesting the
10807 entire active file from the server. This file is often v. large. You
10808 also have to set @code{gnus-check-new-news} and
10809 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
10810 doesn't suddenly decide to fetch the active file anyway.
10812 @item gnus-nov-is-evil
10813 This one has to be @code{nil}. If not, grabbing article headers from
10814 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
10815 support @sc{xover}; Gnus will detect this by itself.
10818 @node Slow Terminal Connection
10819 @section Slow Terminal Connection
10821 Let's say you use your home computer for dialing up the system that
10822 runs Emacs and Gnus. If your modem is slow, you want to reduce the
10823 amount of data that is sent over the wires as much as possible.
10827 @item gnus-auto-center-summary
10828 Set this to @code{nil} to inhibit Gnus from recentering the summary
10829 buffer all the time.
10831 @item gnus-visible-headers
10832 Cut down on the headers that are included in the articles to the
10833 minimum. You can, in fact, make do without them altogether---most of the
10834 useful data is in the summary buffer, anyway. Set this variable to
10835 @samp{"^NEVVVVER"} or @samp{"From:"}, or whatever you feel you need.
10837 @item gnus-article-display-hook
10838 Set this hook to all the available hiding commands:
10840 (setq gnus-article-display-hook
10841 '(gnus-article-hide-headers gnus-article-hide-signature
10842 gnus-article-hide-citation))
10845 @item gnus-use-full-window
10846 By setting this to @code{nil}, you can make all the windows smaller.
10847 While this doesn't really cut down much generally, it means that you
10848 have to see smaller portions of articles before deciding that you didn't
10849 want to read them anyway.
10851 @item gnus-thread-hide-subtree
10852 If this is non-@code{nil}, all threads in the summary buffer will be
10855 @item gnus-updated-mode-lines
10856 If this is @code{nil}, Gnus will not put information in the buffer mode
10857 lines, which might save some time.
10860 @node Little Disk Space
10861 @section Little Disk Space
10863 The startup files can get rather large, so you may want to cut their
10864 sizes a bit if you are running out of space.
10868 @item gnus-save-newsrc-file
10869 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
10870 only save @file{.newsrc.eld}. This means that you will not be able to
10871 use any other newsreaders than Gnus. This variable is @code{t} by
10874 @item gnus-save-killed-list
10875 If this is @code{nil}, Gnus will not save the list of dead groups. You
10876 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
10877 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
10878 variable to @code{nil}. This variable is @code{t} by default.
10884 @section Slow Machine
10886 If you have a slow machine, or are just really impatient, there are a
10887 few things you can do to make Gnus run faster.
10889 Set@code{gnus-check-new-newsgroups} and
10890 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
10892 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
10893 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
10894 summary buffer faster.
10896 Set @code{gnus-article-display-hook} to @code{nil} to make article
10897 processing a bit faster.
10900 @node Troubleshooting
10901 @chapter Troubleshooting
10902 @cindex troubleshooting
10904 Gnus works @emph{so} well straight out of the box---I can't imagine any
10912 Make sure your computer is switched on.
10915 Make sure that you really load the current Gnus version. If you have
10916 been running @sc{gnus}, you need to exit Emacs and start it up again before
10920 Try doing an @kbd{M-x gnus-version}. If you get something that looks
10921 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
10922 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
10923 flee}, you have some old @file{.el} files lying around. Delete these.
10926 Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
10930 If all else fails, report the problem as a bug.
10933 @cindex reporting bugs
10935 @kindex M-x gnus-bug
10937 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
10938 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
10939 me the backtrace. I will fix bugs, but I can only fix them if you send
10940 me a precise description as to how to reproduce the bug.
10942 You really can never be too detailed in a bug report. Always use the
10943 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
10944 a 10Kb mail each time you use it, and even if you have sent me your
10945 environment 500 times before. I don't care. I want the full info each
10948 It is also important to remember that I have no memory whatsoever. If
10949 you send a bug report, and I send you a reply, and then you send back
10950 just ``No, it's not! Moron!'', I will have no idea what you are insulting
10951 me about. Always overexplain everything. It's much easier for all of
10952 us---if I don't have all the information I need, I will just mail you
10953 and ask for more info, and everything takes more time.
10955 If you just need help, you are better off asking on
10956 @samp{gnu.emacs.gnus}. I'm not very helpful.
10958 @cindex gnu.emacs.gnus
10959 @cindex ding mailing list
10960 You can also ask on the ding mailing list---@samp{ding@@ifi.uio.no}.
10961 Write to @samp{ding-request@@ifi.uio.no} to subscribe.
10967 Well, that's the manual---you can get on with your life now. Keep in
10968 touch. Say hello to your cats from me.
10970 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
10972 Ol' Charles Reznikoff said it pretty well, so I leave the floor to him:
10977 Not because of victories @*
10980 but for the common sunshine,@*
10982 the largess of the spring.
10985 but for the day's work done@*
10986 as well as I was able;@*
10987 not for a seat upon the dais@*
10988 but at the common table.@*
10992 @chapter Appendices
10995 * A Programmer@'s Guide to Gnus:: Rilly, rilly technical stuff.
10996 * Emacs for Heathens:: A short intruduction to Emacsian terms.
10997 * Frequently Asked Questions:: A question-and-answer session.
11001 @node A Programmer@'s Guide to Gnus
11002 @section A Programmer's Guide to Gnus
11004 It is my hope that other people will figure out smart stuff that Gnus
11005 can do, and that other people will write those smart things as well. To
11006 facilitate that I thought it would be a good idea to describe the inner
11007 workings of Gnus. And some of the not-so-inner workings, while I'm at
11010 You can never expect the internals of a program not to change, but I
11011 will be defining (in some details) the interface between Gnus and its
11012 backends (this is written in stone), the format of the score files
11013 (ditto), data structures (some are less likely to change than others)
11014 and general method of operations.
11017 * Backend Interface:: How Gnus communicates with the servers.
11018 * Score File Syntax:: A BNF definition of the score file standard.
11019 * Headers:: How Gnus stores headers internally.
11020 * Ranges:: A handy format for storing mucho numbers.
11021 * Group Info:: The group info format.
11022 * Various File Formats:: Formats of files that Gnus use.
11026 @node Backend Interface
11027 @subsection Backend Interface
11029 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
11030 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
11031 server is a @dfn{backend} and some @dfn{backend variables}. As examples
11032 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
11033 examples of the latter we have @code{nntp-port-number} and
11034 @code{nnmbox-directory}.
11036 When Gnus asks for information from a backend---say @code{nntp}---on
11037 something, it will normally include a virtual server name in the
11038 function parameters. (If not, the backend should use the ``current''
11039 virtual server.) For instance, @code{nntp-request-list} takes a virtual
11040 server as its only (optional) parameter. If this virtual server hasn't
11041 been opened, the function should fail.
11043 Note that a virtual server name has no relation to some physical server
11044 name. Take this example:
11048 (nntp-address "ifi.uio.no")
11049 (nntp-port-number 4324))
11052 Here the virtual server name is @samp{"odd-one"} while the name of
11053 the physical server is @samp{"ifi.uio.no"}.
11055 The backends should be able to switch between several virtual servers.
11056 The standard backends implement this by keeping an alist of virtual
11057 server environments that it pulls down/pushes up when needed.
11059 There are two groups of interface functions: @dfn{required functions},
11060 which must be present, and @dfn{optional functions}, which Gnus will
11061 always check whether are present before attempting to call.
11063 All these functions are expected to return data in the buffer
11064 @code{nntp-server-buffer} (@samp{" *nntpd*"}), which is somewhat
11065 unfortunately named, but we'll have to live with it. When I talk about
11066 ``resulting data'', I always refer to the data in that buffer. When I
11067 talk about ``return value'', I talk about the function value returned by
11070 Some backends could be said to be @dfn{server-forming} backends, and
11071 some might be said to not be. The latter are backends that generally
11072 only operate on one group at a time, and have no concept of ``server'' --
11073 they have a group, and they deliver info on that group and nothing more.
11075 In the examples and definitions I will refer to the imaginary backend
11078 @cindex @code{nnchoke}
11081 * Required Backend Functions:: Functions that must be implemented.
11082 * Optional Backend Functions:: Functions that need not be implemented.
11086 @node Required Backend Functions
11087 @subsubsection Required Backend Functions
11091 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
11093 @var{articles} is either a range of article numbers or a list of
11094 @code{Message-ID}s. Current backends do not fully support either---only
11095 sequences (lists) of article numbers, and most backends do not support
11096 retrieval of @code{Message-ID}s. But they should try for both.
11098 The result data should either be HEADs or NOV lines, and the result
11099 value should either be @code{headers} or @code{nov} to reflect this.
11100 This might later be expanded to @code{various}, which will be a mixture
11101 of HEADs and NOV lines, but this is currently not supported by Gnus.
11103 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
11104 headers, in some meaning of the word. This is generally done by
11105 fetching (at most) @var{fetch-old} extra headers less than the smallest
11106 article number in @code{articles}, and fill in the gaps as well. The
11107 presence of this parameter can be ignored if the backend finds it
11108 cumbersome to follow the request. If this is non-@code{nil} and not a
11109 number, do maximum fetches.
11111 Here's an example HEAD:
11114 221 1056 Article retrieved.
11115 Path: ifi.uio.no!sturles
11116 From: sturles@@ifi.uio.no (Sturle Sunde)
11117 Newsgroups: ifi.discussion
11118 Subject: Re: Something very droll
11119 Date: 27 Oct 1994 14:02:57 +0100
11120 Organization: Dept. of Informatics, University of Oslo, Norway
11122 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
11123 References: <38jdmq$4qu@@visbur.ifi.uio.no>
11124 NNTP-Posting-Host: holmenkollen.ifi.uio.no
11128 So a @code{headers} return value would imply that there's a number of
11129 these in the data buffer.
11131 Here's a BNF definition of such a buffer:
11135 head = error / valid-head
11136 error-message = [ "4" / "5" ] 2number " " <error message> eol
11137 valid-head = valid-message *header "." eol
11138 valid-message = "221 " <number> " Article retrieved." eol
11139 header = <text> eol
11142 If the return value is @code{nov}, the data buffer should contain
11143 @dfn{network overview database} lines. These are basically fields
11147 nov-buffer = *nov-line
11148 nov-line = 8*9 [ field <TAB> ] eol
11149 field = <text except TAB>
11152 For a closer explanation what should be in those fields,
11156 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
11158 @var{server} is here the virtual server name. @var{definitions} is a
11159 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
11161 If the server can't be opened, no error should be signaled. The backend
11162 may then choose to refuse further attempts at connecting to this
11163 server. In fact, it should do so.
11165 If the server is opened already, this function should return a
11166 non-@code{nil} value. There should be no data returned.
11169 @item (nnchoke-close-server &optional SERVER)
11171 Close connection to @var{server} and free all resources connected
11174 There should be no data returned.
11177 @item (nnchoke-request-close)
11179 Close connection to all servers and free all resources that the backend
11180 have reserved. All buffers that have been created by that backend
11181 should be killed. (Not the @code{nntp-server-buffer}, though.)
11183 There should be no data returned.
11186 @item (nnchoke-server-opened &optional SERVER)
11188 This function should return whether @var{server} is opened, and that the
11189 connection to it is still alive. This function should under no
11190 circumstances attempt to reconnect to a server that is has lost
11193 There should be no data returned.
11196 @item (nnchoke-status-message &optional SERVER)
11198 This function should return the last error message from @var{server}.
11200 There should be no data returned.
11203 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
11205 The result data from this function should be the article specified by
11206 @var{article}. This might either be a @code{Message-ID} or a number.
11207 It is optional whether to implement retrieval by @code{Message-ID}, but
11208 it would be nice if that were possible.
11210 If @var{to-buffer} is non-@code{nil}, the result data should be returned
11211 in this buffer instead of the normal data buffer. This is to make it
11212 possible to avoid copying large amounts of data from one buffer to
11213 another, and Gnus mainly request articles to be inserted directly into
11214 its article buffer.
11217 @item (nnchoke-open-group GROUP &optional SERVER)
11219 Make @var{group} the current group.
11221 There should be no data returned by this function.
11224 @item (nnchoke-request-group GROUP &optional SERVER)
11226 Get data on @var{group}. This function also has the side effect of
11227 making @var{group} the current group.
11229 Here's an example of some result data and a definition of the same:
11232 211 56 1000 1059 ifi.discussion
11235 The first number is the status, which should be @samp{211}. Next is the
11236 total number of articles in the group, the lowest article number, the
11237 highest article number, and finally the group name. Note that the total
11238 number of articles may be less than one might think while just
11239 considering the highest and lowest article numbers, but some articles
11240 may have been cancelled. Gnus just discards the total-number, so
11241 whether one should take the bother to generate it properly (if that is a
11242 problem) is left as an excercise to the reader.
11245 group-status = [ error / info ] eol
11246 error = [ "4" / "5" ] 2<number> " " <Error message>
11247 info = "211 " 3* [ <number> " " ] <string>
11251 @item (nnchoke-close-group GROUP &optional SERVER)
11253 Close @var{group} and free any resources connected to it. This will be
11254 a no-op on most backends.
11256 There should be no data returned.
11259 @item (nnchoke-request-list &optional SERVER)
11261 Return a list of all groups available on @var{server}. And that means
11264 Here's an example from a server that only carries two groups:
11267 ifi.test 0000002200 0000002000 y
11268 ifi.discussion 3324 3300 n
11271 On each line we have a group name, then the highest article number in
11272 that group, the lowest article number, and finally a flag.
11275 active-file = *active-line
11276 active-line = name " " <number> " " <number> " " flags eol
11278 flags = "n" / "y" / "m" / "x" / "j" / "=" name
11281 The flag says whether the group is read-only (@samp{n}), is moderated
11282 (@samp{m}), is dead (@samp{x}), is aliased to some other group
11283 (@samp{=other-group} or none of the above (@samp{y}).
11286 @item (nnchoke-request-post &optional SERVER)
11288 This function should post the current buffer. It might return whether
11289 the posting was successful or not, but that's not required. If, for
11290 instance, the posting is done asynchronously, it has generally not been
11291 completed by the time this function concludes. In that case, this
11292 function should set up some kind of sentinel to beep the user loud and
11293 clear if the posting could not be completed.
11295 There should be no result data from this function.
11298 @item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
11300 This function should return a buffer suitable for composing an article
11301 to be posted by @code{nnchoke-request-post}. If @var{post} is
11302 non-@code{nil}, this is not a followup, but a totally new article.
11303 @var{group} is the name of the group to be posted to. @var{subject} is
11304 the subject of the message. @var{article-buffer} is the buffer being
11305 followed up, if that is the case. @var{info} is the group info.
11306 @var{follow-to} is the group that one is supposed to re-direct the
11307 article ot. If @var{respect-poster} is non-@code{nil}, the special
11308 @samp{"poster"} value of a @code{Followup-To} header is to be respected.
11310 There should be no result data returned.
11314 @node Optional Backend Functions
11315 @subsubsection Optional Backend Functions
11319 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
11321 @var{groups} is a list of groups, and this function should request data
11322 on all those groups. How it does it is of no concern to Gnus, but it
11323 should attempt to do this in a speedy fashion.
11325 The return value of this function can be either @code{active} or
11326 @code{group}, which says what the format of the result data is. The
11327 former is in the same format as the data from
11328 @code{nnchoke-request-list}, while the latter is a buffer full of lines
11329 in the same format as @code{nnchoke-request-group} gives.
11332 group-buffer = *active-line / *group-status
11336 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
11338 A Gnus group info (@pxref{Group Info}) is handed to the backend for
11339 alterations. This comes in handy if the backend really carries all the
11340 information (as is the case with virtual an imap groups). This function
11341 may alter the info in any manner it sees fit, and should return the
11342 (altered) group info. This function may alter the group info
11343 destructively, so no copying is needed before boogeying.
11345 There should be no result data from this function.
11348 @item (nnchoke-request-type GROUP &optional ARTICLE)
11350 When the user issues commands for ``sending news'' (@kbd{F} in the summary
11351 buffer, for instance), Gnus has to know whether the article the user is
11352 following up is news or mail. This function should return @code{news}
11353 if @var{article} in @var{group} is news, @code{mail} if it is mail and
11354 @code{unknown} if the type can't be decided. (The @var{article}
11355 parameter is necessary in @code{nnvirtual} groups which might very well
11356 combine mail groups and news groups.)
11358 There should be no result data from this function.
11361 @item (nnchoke-request-update-mark GROUP ARTICLE MARK)
11363 If the user tries to set a mark that the backend doesn't like, this
11364 function may change the mark. Gnus will use whatever this function
11365 returns as the mark for @var{article} instead of the original
11366 @var{mark}. If the backend doesn't care, it must return the original
11367 @var{mark}, and not @code{nil} or any other type of garbage.
11369 The only use for this that I can see is what @code{nnvirtual} does with
11370 it---if a component group is auto-expirable, marking an article as read
11371 in the virtual group should result in the article being marked as
11374 There should be no result data from this function.
11377 @item (nnchoke-request-scan &optional GROUP SERVER)
11379 This function may be called at any time (by Gnus or anything else) to
11380 request that the backend check for incoming articles, in one way or
11381 another. A mail backend will typically read the spool file or query the
11382 POP server when this function is invoked. The @var{group} doesn't have
11383 to be heeded---if the backend decides that it is too much work just
11384 scanning for a single group, it may do a total scan of all groups. It
11385 would be nice, however, to keep things local if that's practical.
11387 There should be no result data from this function.
11390 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
11392 This is a request to fetch articles asynchronously later.
11393 @var{articles} is an alist of @var{(article-number line-number)}. One
11394 would generally expect that if one later fetches article number 4, for
11395 instance, some sort of asynchronous fetching of the articles after 4
11396 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
11397 alist) would be fetched asynchronouly, but that is left up to the
11398 backend. Gnus doesn't care.
11400 There should be no result data from this function.
11403 @item (nnchoke-request-group-description GROUP &optional SERVER)
11405 The result data from this function should be a description of
11409 description-line = name <TAB> description eol
11411 description = <text>
11414 @item (nnchoke-request-list-newsgroups &optional SERVER)
11416 The result data from this function should be the description of all
11417 groups available on the server.
11420 description-buffer = *description-line
11424 @item (nnchoke-request-newgroups DATE &optional SERVER)
11426 The result data from this function should be all groups that were
11427 created after @samp{date}, which is in normal human-readable date
11428 format. The data should be in the active buffer format.
11431 @item (nnchoke-request-create-groups GROUP &optional SERVER)
11433 This function should create an empty group with name @var{group}.
11435 There should be no return data.
11438 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
11440 This function should run the expiry process on all articles in the
11441 @var{articles} range (which is currently a simple list of article
11442 numbers.) It is left up to the backend to decide how old articles
11443 should be before they are removed by this function. If @var{force} is
11444 non-@code{nil}, all @var{articles} should be deleted, no matter how new
11447 This function should return a list of articles that it did not/was not
11450 There should be no result data returned.
11453 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
11456 This function should move @var{article} (which is a number) from
11457 @var{group} by calling @var{accept-form}.
11459 This function should ready the article in question for moving by
11460 removing any header lines it has added to the article, and generally
11461 should ``tidy up'' the article. Then it should @code{eval}
11462 @var{accept-form} in the buffer where the ``tidy'' article is. This will
11463 do the actual copying. If this @code{eval} returns a non-@code{nil}
11464 value, the article should be removed.
11466 If @var{last} is @code{nil}, that means that there is a high likelihood
11467 that there will be more requests issued shortly, so that allows some
11470 There should be no data returned.
11473 @item (nnchoke-request-accept-article GROUP &optional LAST)
11475 This function takes the current buffer and inserts it into @var{group}.
11476 If @var{last} in @code{nil}, that means that there will be more calls to
11477 this function in short order.
11479 There should be no data returned.
11482 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
11484 This function should remove @var{article} (which is a number) from
11485 @var{group} and insert @var{buffer} there instead.
11487 There should be no data returned.
11490 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
11492 This function should delete @var{group}. If @var{force}, it should
11493 really delete all the articles in the group, and then delete the group
11494 itself. (If there is such a thing as ``the group itself''.)
11496 There should be no data returned.
11499 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
11501 This function should rename @var{group} into @var{new-name}. All
11502 articles that are in @var{group} should move to @var{new-name}.
11504 There should be no data returned.
11510 @node Score File Syntax
11511 @subsection Score File Syntax
11513 Score files are meant to be easily parsable, but yet extremely
11514 mallable. It was decided that something that had the same read syntax
11515 as an Emacs Lisp list would fit that spec.
11517 Here's a typical score file:
11521 ("win95" -10000 nil s)
11528 BNF definition of a score file:
11531 score-file = "" / "(" *element ")"
11532 element = rule / atom
11533 rule = string-rule / number-rule / date-rule
11534 string-rule = "(" quote string-header quote space *string-match ")"
11535 number-rule = "(" quote number-header quote space *number-match ")"
11536 date-rule = "(" quote date-header quote space *date-match ")"
11538 string-header = "subject" / "from" / "references" / "message-id" /
11539 "xref" / "body" / "head" / "all" / "followup"
11540 number-header = "lines" / "chars"
11541 date-header = "date"
11542 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
11543 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
11544 score = "nil" / <integer>
11545 date = "nil" / <natural number>
11546 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
11547 "r" / "regex" / "R" / "Regex" /
11548 "e" / "exact" / "E" / "Exact" /
11549 "f" / "fuzzy" / "F" / "Fuzzy"
11550 number-match = "(" <integer> [ "" / [ space score [ "" /
11551 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
11552 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
11553 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
11554 space date [ "" / [ space date-match-t ] ] ] ] ")"
11555 date-match-t = "nil" / "at" / "before" / "after"
11556 atom = "(" [ required-atom / optional-atom ] ")"
11557 required-atom = mark / expunge / mark-and-expunge / files /
11558 exclude-files / read-only / touched
11559 optional-atom = adapt / local / eval
11560 mark = "mark" space nil-or-number
11561 nil-or-number = "nil" / <integer>
11562 expunge = "expunge" space nil-or-number
11563 mark-and-expunge = "mark-and-expunge" space nil-or-number
11564 files = "files" *[ space <string> ]
11565 exclude-files = "exclude-files" *[ space <string> ]
11566 read-only = "read-only" [ space "nil" / space "t" ]
11567 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
11568 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
11569 local = "local" *[ space "(" <string> space <form> ")" ]
11570 eval = "eval" space <form>
11571 space = *[ " " / <TAB> / <NEWLINE> ]
11574 Any unrecognized elements in a score file should be ignored, but not
11577 As you can see, white space is needed, but the type and amount of white
11578 space is irrelevant. This means that formatting of the score file is
11579 left up to the programmer---if it's simpler to just spew it all out on
11580 one looong line, then that's ok.
11582 The meaning of the various atoms are explained elsewhere in this
11587 @subsection Headers
11589 Gnus uses internally a format for storing article headers that
11590 corresponds to the @sc{nov} format in a mysterious fashion. One could
11591 almost suspect that the author looked at the @sc{nov} specification and
11592 just shamelessly @emph{stole} the entire thing, and one would be right.
11594 @dfn{Header} is a severly overloaded term. ``Header'' is used in RFC1036
11595 to talk about lines in the head of an article (eg., @code{From}). It is
11596 used by many people as a synonym for ``head''---``the header and the
11597 body''. (That should be avoided, in my opinion.) And Gnus uses a format
11598 interanally that it calls ``header'', which is what I'm talking about
11599 here. This is a 9-element vector, basically, with each header (ouch)
11602 These slots are, in order: @code{number}, @code{subject}, @code{from},
11603 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
11604 @code{xref}. There are macros for accessing and setting these slots --
11605 they all have predicatable names beginning with @code{mail-header-} and
11606 @code{mail-header-set-}, respectively.
11608 The @code{xref} slot is really a @code{misc} slot. Any extra info will
11615 @sc{gnus} introduced a concept that I found so useful that I've started
11616 using it a lot and have elaborated on it greatly.
11618 The question is simple: If you have a large amount of objects that are
11619 identified by numbers (say, articles, to take a @emph{wild} example)
11620 that you want to callify as being ``included'', a normal sequence isn't
11621 very useful. (A 200,000 length sequence is a bit long-winded.)
11623 The solution is as simple as the question: You just collapse the
11627 (1 2 3 4 5 6 10 11 12)
11630 is transformed into
11633 ((1 . 6) (10 . 12))
11636 To avoid having those nasty @samp{(13 . 13)} elements to denote a
11637 lonesome object, a @samp{13} is a valid element:
11640 ((1 . 6) 7 (10 . 12))
11643 This means that comparing two ranges to find out whether they are equal
11644 is slightly tricky:
11647 ((1 . 5) 7 8 (10 . 12))
11653 ((1 . 5) (7 . 8) (10 . 12))
11656 are equal. In fact, any non-descending list is a range:
11662 is a perfectly valid range, although a pretty longwinded one. This is
11669 and is equal to the previous range.
11671 Here's a BNF definition of ranges. Of course, one must remember the
11672 semantic requirement that the numbers are non-descending. (Any number
11673 of repetition of the same number is allowed, but apt to disappear in
11677 range = simple-range / normal-range
11678 simple-range = "(" number " . " number ")"
11679 normal-range = "(" start-contents ")"
11680 contents = "" / simple-range *[ " " contents ] /
11681 number *[ " " contents ]
11684 Gnus currently uses ranges to keep track of read articles and article
11685 marks. I plan on implementing a number of range operators in C if The
11686 Powers That Be are willing to let me. (I haven't asked yet, because I
11687 need to do some more thinking on what operators I need to make life
11688 totally range-based without ever having to convert back to normal
11693 @subsection Group Info
11695 Gnus stores all permanent info on groups in a @dfn{group info} list.
11696 This list is from three to six elements (or more) long and exhaustively
11697 describes the group.
11699 Here are two example group infos; one is a very simple group while the
11700 second is a more complex one:
11703 ("no.group" 5 (1 . 54324))
11705 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
11706 ((tick (15 . 19)) (replied 3 6 (19 . 3)))
11708 (auto-expire (to-address "ding@@ifi.uio.no")))
11711 The first element is the group name as Gnus knows the group; the second
11712 is the group level; the third is the read articles in range format; the
11713 fourth is a list of article marks lists; the fifth is the select method;
11714 and the sixth contains the group parameters.
11716 Here's a BNF definition of the group info format:
11719 info = "(" group space level space read
11720 [ "" / [ space marks-list [ "" / [ space method [ "" /
11721 space parameters ] ] ] ] ] ")"
11722 group = quote <string> quote
11723 level = <integer in the range of 1 to inf>
11725 marks-lists = nil / "(" *marks ")"
11726 marks = "(" <string> range ")"
11727 method = "(" <string> *elisp-forms ")"
11728 parameters = "(" *elisp-forms ")"
11731 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
11732 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
11736 @node Various File Formats
11737 @subsection Various File Formats
11740 * Active File Format:: Information on articles and groups available.
11741 * Newsgroups File Format:: Group descriptions.
11745 @node Active File Format
11746 @subsubsection Active File Format
11748 The active file lists all groups that are available on the server in
11749 question. It also lists the highest and lowest current article numbers
11752 Here's an exceprt from a typical active file:
11755 soc.motss 296030 293865 y
11756 alt.binaries.pictures.fractals 3922 3913 n
11757 comp.sources.unix 1605 1593 m
11758 comp.binaries.ibm.pc 5097 5089 y
11759 no.general 1000 900 y
11762 Here's a pseudo-BNF definition of this file:
11765 active = *group-line
11766 group-line = group space high-number space low-number space flag <NEWLINE>
11767 group = <non-white-space string>
11769 high-number = <non-negative integer>
11770 low-number = <positive integer>
11771 flag = "y" / "n" / "m" / "j" / "x" / "=" group
11775 @node Newsgroups File Format
11776 @subsubsection Newsgroups File Format
11778 The newsgroups file lists groups along with their descriptions. Not all
11779 groups on the server have to be listed, and not all groups in the file
11780 have to exist on the server. The file is meant purely as information to
11783 The format is quite simple; a group name, a tab, and the description.
11784 Here's the definition:
11788 line = group tab description <NEWLINE>
11789 group = <non-white-space string>
11791 description = <string>
11795 @node Emacs for Heathens
11796 @section Emacs for Heathens
11798 Believe it or not, but some people who use Gnus haven't really used
11799 Emacs much before they embarked on their journey on the Gnus Love Boat.
11800 If you are one of those unfortunates whom ``@kbd{M-C-a}'', ``kill the
11801 region'', and ``set @code{gnus-flargblossen} to an alist where the key is
11802 a regexp that is used for matching on the group name'' are magical
11803 phrases with little or no meaning, then this appendix is for you. If
11804 you are already familiar with Emacs, just ignore this and go fondle your
11808 * Keystrokes:: Entering text and executing commands.
11809 * Emacs Lisp:: The built-in Emacs programming language.
11814 @subsection Keystrokes
11818 Q: What is an experienced Emacs user?
11821 A: A person who wishes that the terminal had pedals.
11824 Yes, when you use Emacs, you are apt to use the control key, the shift
11825 key and the meta key a lot. This is very annoying to some people
11826 (notably @code{vi}le users), and the rest of us just love the hell out
11827 of it. Just give up and submit. Emacs really does stand for
11828 ``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you may
11829 have heard from other disreputable sources (like the Emacs author).
11831 The shift key is normally located near your pinky fingers, and are
11832 normally used to get capital letters and stuff. You probably use it all
11833 the time. The control key is normally marked ``CTRL'' or something like
11834 that. The meta key is, funnily enough, never marked as such on any
11835 keyboards. The one I'm curretly at has a key that's marked ``Alt'', which
11836 is the meta key on this keyboard. It's usually located somewhere to the
11837 left hand side of the keyboard, usually on the bottom row.
11839 Now, us Emacs people doesn't say ``press the meta-control-m key'', because
11840 that's just too inconvenient. We say ``press the @kbd{M-C-m} key''.
11841 @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the prefix that
11842 means ``control''. So ``press @kbd{C-k}'' means ``press down the control
11843 key, and hold it down while you press @kbd{k}''. ``Press @kbd{M-C-k}''
11844 means ``press down and hold down the meta key and the control key and
11845 then press @kbd{k}''. Simple, ay?
11847 This is somewhat complicated by the fact that not all keyboards have a
11848 meta key. In that case you can use the ``escape'' key. Then @kbd{M-k}
11849 means ``press escape, release escape, press @kbd{k}''. That's much more
11850 work than if you have a meta key, so if that's the case, I respectfully
11851 suggest you get a real keyboard with a meta key. You can't live without
11857 @subsection Emacs Lisp
11859 Emacs is the King of Editors because it's really a Lisp interpreter.
11860 Each and every key you tap runs some Emacs Lisp code snippet, and since
11861 Emacs Lisp is an interpreted language, that means that you can configure
11862 any key to run any random code. You just, like, do it.
11864 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
11865 functions. (These are byte-compiled for speed, but it's still
11866 interpreted.) If you decide that you don't like the way Gnus does
11867 certain things, it's trivial to have it do something a different way.
11868 (Well, at least if you know how to write Lisp code.) However, that's
11869 beyond the scope of this manual, so we are simply going to talk about
11870 some common constructs that you normally use in your @file{.emacs} file
11873 If you want to set the variable @code{gnus-florgbnize} to four (4), you
11874 write the following:
11877 (setq gnus-florgbnize 4)
11880 This function (really ``special form'') @code{setq} is the one that can
11881 set a variable to some value. This is really all you need to know. Now
11882 you can go and fill your @code{.emacs} file with lots of these to change
11885 If you have put that thing in your @code{.emacs} file, it will be read
11886 and @code{eval}ed (which is lispese for ``run'') the next time you start
11887 Emacs. If you want to change the variable right away, simply say
11888 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
11889 previous ``form'', which here is a simple @code{setq} statement.
11891 Go ahead---just try it, if you're located at your Emacs. After you
11892 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
11893 is the return value of the form you @code{eval}ed.
11897 If the manual says ``set @code{gnus-read-active-file} to @code{some}'',
11901 (setq gnus-read-active-file 'some)
11904 On the other hand, if the manual says ``set @code{gnus-nntp-server} to
11905 @samp{"nntp.ifi.uio.no"}'', that means:
11908 (setq gnus-nntp-server "nntp.ifi.uio.no")
11911 So be careful not to mix up strings (the latter) with symbols (the
11912 former). The manual is unambiguous, but it can be confusing.
11915 @include gnus-faq.texi