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 v (Summary)
7936 @findex gnus-summary-verbose-header
7937 Toggle whether to display all headers in the article buffer permanently
7938 (@code{gnus-summary-verbose-header}).
7941 @kindex W m (Summary)
7942 @findex gnus-summary-toggle-mime
7943 Toggle whether to run the article through @sc{mime} before displaying
7944 (@code{gnus-summary-toggle-mime}).
7947 @kindex W o (Summary)
7948 @findex gnus-article-treat-overstrike
7949 Treat overstrike (@code{gnus-article-treat-overstrike}).
7952 @kindex W w (Summary)
7953 @findex gnus-article-word-wrap
7954 Do word wrap (@code{gnus-article-word-wrap}).
7957 @kindex W c (Summary)
7958 @findex gnus-article-remove-cr
7959 Remove CR (@code{gnus-article-remove-cr}).
7962 @kindex W L (Summary)
7963 @findex gnus-article-remove-trailing-blank-lines
7964 Remove all blank lines at the end of the article
7965 (@code{gnus-article-remove-trailing-blank-lines}).
7968 @kindex W q (Summary)
7969 @findex gnus-article-de-quoted-unreadable
7970 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
7973 @kindex W f (Summary)
7975 @findex gnus-article-display-x-face
7976 @findex gnus-article-x-face-command
7977 @vindex gnus-article-x-face-command
7978 @vindex gnus-article-x-face-too-ugly
7979 Look for and display any X-Face headers
7980 (@code{gnus-article-display-x-face}). The command executed by this
7981 function is given by the @code{gnus-article-x-face-command} variable. If
7982 this variable is a string, this string will be executed in a sub-shell.
7983 If it is a function, this function will be called with the face as the
7984 argument. If the @code{gnus-article-x-face-too-ugly} (which is a regexp)
7985 matches the @code{From} header, the face will not be shown.
7988 @kindex W b (Summary)
7989 @findex gnus-article-add-buttons
7990 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
7993 @kindex W B (Summary)
7994 @findex gnus-article-add-buttons-to-head
7995 Add clickable buttons to the article headers
7996 (@code{gnus-article-add-buttons-to-head}).
8001 @node Article Buttons
8002 @subsection Article Buttons
8005 People often include references to other stuff in articles, and it would
8006 be nice if Gnus could just fetch whatever it is that people talk about
8007 with the minimum of fuzz.
8009 Gnus adds @dfn{buttons} to certain standard references by default:
8010 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
8011 two variables, one that handles article bodies and one that handles
8016 @item gnus-button-alist
8017 @vindex gnus-header-button-alist
8018 This is an alist where each entry has this form:
8021 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
8027 All text that match this regular expression will be considered an
8028 external reference. Here's a typical regexp that match embedded URLs:
8029 @samp{"<URL:\\([^\n\r>]*\\)>"}.
8032 Gnus has to know which parts of the match is to be highlighted. This is
8033 a number that says what sub-expression of the regexp that is to be
8034 highlighted. If you want it all highlighted, you use @samp{0} here.
8037 This form will be @code{eval}ed, and if the result is non-@code{nil},
8038 this is considered a match. This is useful if you want extra sifting to
8039 avoid false matches.
8042 This function will be called when you click on this button.
8045 As with @var{button-par}, this is a sub-expression number, but this one
8046 says which part of the match is to be sent as data to @var{function}.
8050 So the full entry for buttonizing URLs is then
8053 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
8056 @item gnus-header-button-alist
8057 @vindex gnus-header-button-alist
8058 This is just like the other alist, except that it is applied to the
8059 article head only, and that each entry has an additional element that is
8060 used to say what headers to apply the buttonize coding to:
8063 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
8066 @var{header} is a regular expression.
8070 @vindex gnus-article-button-face
8071 @vindex gnus-article-mouse-face
8072 Buttons are highlighted with @code{gnus-article-button-face}, while
8073 @code{gnus-article-mouse-face} is used when the mouse cursor is over the
8078 @subsection Article Date
8080 The date is most likely generated in some obscure timezone you've never
8081 heard of, so it's quite nice to be able to find out what the time was
8082 when the article was sent.
8087 @kindex W T u (Summary)
8088 @findex gnus-article-date-ut
8089 Display the date in UT (aka. GMT, aka ZULU)
8090 (@code{gnus-article-date-ut}).
8093 @kindex W T l (Summary)
8094 @findex gnus-article-date-local
8095 Display the date in the local timezone (@code{gnus-article-date-local}).
8098 @kindex W T e (Summary)
8099 @findex gnus-article-date-lapsed
8100 Say how much time has (e)lapsed between the article was posted and now
8101 (@code{gnus-article-date-lapsed}).
8104 @kindex W T o (Summary)
8105 @findex gnus-article-date-original
8106 Display the original date (@code{gnus-article-date-original}). This can
8107 be useful if you normally use some other conversion function and is
8108 worried that it might be doing something totally wrong. Say, claiming
8109 that the article was posted in 1854. Although something like that is
8110 @emph{totally} impossible. Don't you trust me? *titter*
8115 @node Summary Sorting
8116 @section Summary Sorting
8117 @cindex summary sorting
8119 You can have the summary buffer sorted in various ways, even though I
8120 can't really see why you'd want that.
8125 @kindex C-c C-s C-n (Summary)
8126 @findex gnus-summary-sort-by-number
8127 Sort by article number (@code{gnus-summary-sort-by-number}).
8130 @kindex C-c C-s C-a (Summary)
8131 @findex gnus-summary-sort-by-author
8132 Sort by author (@code{gnus-summary-sort-by-author}).
8135 @kindex C-c C-s C-s (Summary)
8136 @findex gnus-summary-sort-by-subject
8137 Sort by subject (@code{gnus-summary-sort-by-subject}).
8140 @kindex C-c C-s C-d (Summary)
8141 @findex gnus-summary-sort-by-date
8142 Sort by date (@code{gnus-summary-sort-by-date}).
8145 @kindex C-c C-s C-i (Summary)
8146 @findex gnus-summary-sort-by-score
8147 Sort by score (@code{gnus-summary-sort-by-score}).
8150 These functions will work both when you use threading and when you don't
8151 use threading. In the latter case, all summary lines will be sorted,
8152 line by line. In the former case, sorting will be done on a
8153 root-by-root basis, which might not be what you were looking for. To
8154 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
8158 @node Finding the Parent
8159 @section Finding the Parent
8160 @cindex parent articles
8161 @cindex referring articles
8163 @findex gnus-summary-refer-parent-article
8165 If you'd like to read the parent of the current article, and it is not
8166 displayed in the article buffer, you might still be able to. That is,
8167 if the current group is fetched by @sc{nntp}, the parent hasn't expired
8168 and the @code{References} in the current article are not mangled, you
8169 can just press @kbd{^} or @kbd{A r}
8170 (@code{gnus-summary-refer-parent-article}). If everything goes well,
8171 you'll get the parent. If the parent is already displayed in the
8172 summary buffer, point will just move to this article.
8174 @findex gnus-summary-refer-references
8175 @kindex A R (Summary)
8176 You can have Gnus fetch all articles mentioned in the @code{References}
8177 header of the article by pushing @kbd{A R}
8178 (@code{gnus-summary-refer-references}).
8180 @findex gnus-summary-refer-article
8181 @kindex M-^ (Summary)
8182 You can also ask the @sc{nntp} server for an arbitrary article, no
8183 matter what group it belongs to. @kbd{M-^}
8184 (@code{gnus-summary-refer-article}) will ask you for a
8185 @code{Message-ID}, which is one of those long thingies that look
8186 something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You have to get
8187 it all exactly right. No fuzzy searches, I'm afraid.
8189 @vindex gnus-refer-article-method
8190 If the group you are reading is located on a backend that does not
8191 support fetching by @code{Message-ID} very well (like @code{nnspool}),
8192 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
8193 would, perhaps, be best if the @sc{nntp} server you consult is the same
8194 as the one that keeps the spool you are reading from updated, but that's
8195 not really necessary.
8197 Most of the mail backends support fetching by @code{Message-ID}, but do
8198 not do a particularly excellent job of it. That is, @code{nnmbox} and
8199 @code{nnbabyl} are able to locate articles from any groups, while
8200 @code{nnml} and @code{nnfolder} are only able to locate articles that
8201 have been posted to the current group. (Anything else would be too time
8202 consuming.) @code{nnmh} does not support this at all.
8205 @node Alternative Approaches
8206 @section Alternative Approaches
8208 Different people like to read news using different methods. This being
8209 Gnus, we offer a small selection of minor modes for the summary buffers.
8212 * Pick and Read:: First mark articles and then read them.
8213 * Binary Groups:: Auto-decode all articles.
8218 @subsection Pick and Read
8219 @cindex pick and read
8221 Some newsreaders (like @code{nn} and, uhm, @code{nn}) use a two-phased
8222 reading interface. The user first marks the articles she wants to read
8223 from a summary buffer. Then she starts reading the articles with just
8224 an article buffer displayed.
8226 @findex gnus-pick-mode
8227 @kindex M-x gnus-pick-mode
8228 Gnus provides a summary buffer minor mode that allows
8229 this---@code{gnus-pick-mode}. This basically means that a few process
8230 mark commands becode one-keystroke commands to allow easy marking, and
8231 it makes one additional command for switching to the summary buffer
8234 Here are the available keystrokes when using pick mode:
8238 Pick the article (@code{gnus-summary-mark-as-processable}).
8241 Unpick the article (@code{gnus-summary-unmark-as-processable}).
8244 Unpick all articles (@code{gnus-summary-unmark-all-processable}).
8247 Pick the thread (@code{gnus-uu-mark-thread}).
8250 Unpick the thread (@code{gnus-uu-unmark-thread}).
8253 Pick the region (@code{gnus-uu-mark-region}).
8256 Unpick the region (@code{gnus-uu-unmark-region}).
8259 Pick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
8262 Unpick articles that match a regexp (@code{gnus-uu-unmark-regexp}).
8265 Pick the buffer (@code{gnus-uu-mark-buffer}).
8268 Unpick the buffer (@code{gnus-uu-unmark-buffer}).
8271 @vindex gnus-pick-display-summary
8272 Start reading the picked articles (@code{gnus-pick-start-reading}). If
8273 given a prefix, mark all unpicked articles as read first. If
8274 @code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer
8275 will still be visible when you are reading.
8279 If this sounds like a good idea to you, you could say:
8282 (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
8287 @subsection Binary Groups
8288 @cindex binary groups
8290 @findex gnus-binary-mode
8291 @kindex M-x gnus-binary-mode
8292 If you spend much time in binary groups, you may grow tired of hitting
8293 @kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode}
8294 is a minor mode for summary buffers that makes all ordinary Gnus article
8295 selection functions uudecode series of articles and display the result
8296 instead of just displaying the articles the normal way.
8299 @findex gnus-binary-show-article
8300 In fact, the only way to see the actual articles if you have turned this
8301 mode on is the @kbd{g} command (@code{gnus-binary-show-article}).
8305 @section Tree Display
8308 @vindex gnus-use-trees
8309 If you don't like the normal Gnus summary display, you might try setting
8310 @code{gnus-use-trees} to @code{t}. This will create (by default) an
8311 additional @dfn{tree buffer}. You can execute all summary mode commands
8314 There are a few variables to customize the tree display, of course:
8317 @item gnus-tree-mode-hook
8318 @vindex gnus-tree-mode-hook
8319 A hook called in all tree mode buffers.
8321 @item gnus-tree-mode-line-format
8322 @vindex gnus-tree-mode-line-format
8323 A format string for the mode bar in the tree mode buffers. The default
8324 is @samp{"Gnus: %%b [%A] %Z"}. For a list of legal specs, @xref{Summary
8327 @item gnus-selected-tree-face
8328 @vindex gnus-selected-tree-face
8329 Face used for highlighting the selected article in the tree buffer. The
8330 default is @code{modeline}.
8332 @item gnus-tree-line-format
8333 @vindex gnus-tree-line-format
8334 A format string for the tree nodes. The name is a bit of a misnomer,
8335 though---it doesn't define a line, but just the node. The default value
8336 is @samp{"%(%[%3,3n%]%)"}, which displays the first three characters of
8337 the name of the poster. It is vital that all nodes are of the same
8338 length, so you @emph{must} use @samp{%4,4n}-like specifiers.
8344 The name of the poster.
8346 The @code{From} header.
8348 The number of the article.
8350 The opening bracket.
8352 The closing bracket.
8357 @xref{Formatting Variables}.
8359 Variables related to the display are:
8362 @item gnus-tree-brackets
8363 @vindex gnus-tree-brackets
8364 This is used for differentiating between ``real'' articles and ``sparse''
8365 articles. The format is @var{((real-open . real-close) (sparse-open
8366 . sparse-close) (dummy-open . dummy-close))}, and the default is
8367 @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}))}.
8369 @item gnus-tree-parent-child-edges
8370 @vindex gnus-tree-parent-child-edges
8371 This is a list that contains the characters used for connecting parent
8372 nodes to their children. The default is @code{(?- ?\\ ?|)}.
8376 @item gnus-tree-minimize-window
8377 @vindex gnus-tree-minimize-window
8378 If this variable is non-@code{nil}, Gnus will try to keep the tree
8379 buffer as small as possible to allow more room for the other Gnus
8380 windows. If this variable is a number, the tree buffer will never be
8381 higher than that number. The default is @code{t}.
8383 @item gnus-generate-tree-function
8384 @vindex gnus-generate-tree-function
8385 @findex gnus-generate-horizontal-tree
8386 @findex gnus-generate-vertical-tree
8387 The function that actually generates the thread tree. Two predefined
8388 functions are available: @code{gnus-generate-horizontal-tree} and
8389 @code{gnus-generate-vertical-tree} (which is the default).
8393 Here's and example from a horizontal tree buffer:
8396 @{***@}-(***)-[odd]-[Gun]
8406 Here's the same thread displayed in a vertical tree buffer:
8410 |--------------------------\-----\-----\
8411 (***) [Bjo] [Gun] [Gun]
8413 [odd] [Jan] [odd] (***) [Jor]
8415 [Gun] [Eri] [Eri] [odd]
8421 @node Mail Group Commands
8422 @section Mail Group Commands
8423 @cindex mail group commands
8425 Some commands only make sense in mail groups. If these commands are
8426 illegal in the current group, they will raise a hell and let you know.
8428 All these commands (except the expiry and edit commands) use the
8429 process/prefix convention (@pxref{Process/Prefix}).
8434 @kindex B e (Summary)
8435 @findex gnus-summary-expire-articles
8436 Expire all expirable articles in the group
8437 (@code{gnus-summary-expire-articles}).
8440 @kindex B M-C-e (Summary)
8441 @findex gnus-summary-expire-articles-now
8442 Expunge all the expirable articles in the group
8443 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
8444 articles that are eligeble for expiry in the current group will
8445 disappear forever into that big @file{/dev/null} in the sky.
8448 @kindex B DEL (Summary)
8449 @findex gnus-summary-delete-articles
8450 Delete the mail article. This is ``delete'' as in ``delete it from your
8451 disk forever and ever, never to return again.'' Use with caution.
8452 (@code{gnus-summary-delete-article}).
8455 @kindex B m (Summary)
8457 @findex gnus-summary-move-article
8458 Move the article from one mail group to another
8459 (@code{gnus-summary-move-article}).
8462 @kindex B c (Summary)
8464 @findex gnus-summary-copy-article
8465 Copy the article from one group (mail group or not) to a mail group
8466 (@code{gnus-summary-copy-article}).
8469 @kindex B C (Summary)
8470 @cindex crosspost mail
8471 @findex gnus-summary-crosspost-article
8472 Crosspost the current article to some other group
8473 (@code{gnus-summary-crosspost-article}). This will create a new copy of
8474 the article in the other group, and the Xref headers of the article will
8475 be properly updated.
8478 @kindex B i (Summary)
8479 @findex gnus-summary-import-article
8480 Import a random file into the current mail newsgroup
8481 (@code{gnus-summary-import-article}). You will be prompted for a file
8482 name, a @code{From} header and a @code{Subject} header.
8484 Something similar can be done by just starting to compose a mail
8485 message. Instead of typing @kbd{C-c C-c} to mail it off, you can type
8486 @kbd{C-c C-p} instead. This will put the message you have just created
8487 into the current mail group.
8490 @kindex B r (Summary)
8491 @findex gnus-summary-respool-article
8492 Respool the mail article (@code{gnus-summary-move-article}).
8496 @kindex B w (Summary)
8498 @findex gnus-summary-edit-article
8499 @kindex C-c C-c (Article)
8500 Edit the current article (@code{gnus-summary-edit-article}). To finish
8501 editing and make the changes permanent, type @kbd{C-c C-c}
8502 (@kbd{gnus-summary-edit-article-done}).
8505 @kindex B q (Summary)
8506 @findex gnus-summary-respool-query
8507 If you want to respool an article, you might be curious as to what group
8508 the article will end up in before you do the respooling. This command
8509 will tell you (@code{gnus-summary-fancy-query}).
8512 If you move (or copy) articles regularly, you might wish to have Gnus
8513 suggest where to put the articles. @code{gnus-move-split-methods} is a
8514 variable that uses the same syntax as @code{gnus-split-methods}
8515 (@pxref{Saving Articles}). You may customize that variable to create
8516 suggestions you find reasonable.
8519 @node Various Summary Stuff
8520 @section Various Summary Stuff
8523 * Group Information:: Information oriented commands.
8524 * Searching for Articles:: Multiple article commands.
8525 * Really Various Summary Commands:: Those pesky non-conformant commands.
8528 @vindex gnus-summary-generate-hook
8529 @code{gnus-summary-generate-hook} is called as the last thing before
8530 doing the threading and the generation of the summary buffer. It's
8531 quite convenient for customizing the threading variables based on what
8532 data the newsgroup has. This hook is called from the summary buffer
8533 after most summary buffer variables has been set.
8535 @vindex gnus-summary-prepare-hook
8536 @code{gnus-summary-prepare-hook} is called after the summary buffer has
8537 been generated. You might use it to, for instance, highlight lines or
8538 modify the look of the buffer in some other ungodly manner. I don't
8541 @node Group Information
8542 @subsection Group Information
8547 @kindex H f (Summary)
8548 @findex gnus-summary-fetch-faq
8549 @vindex gnus-group-faq-directory
8550 Try to fetch the FAQ (list of frequently asked questions) for the
8551 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
8552 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
8553 on a remote machine. This variable can also be a list of directories.
8554 In that case, giving a prefix to this command will allow you to choose
8555 between the various sites. @code{ange-ftp} probably will be used for
8559 @kindex H d (Summary)
8560 @findex gnus-summary-describe-group
8561 Give a brief description of the current group
8562 (@code{gnus-summary-describe-group}). If given a prefix, force
8563 rereading the description from the server.
8566 @kindex H h (Summary)
8567 @findex gnus-summary-describe-briefly
8568 Give a very brief description of the most important summary keystrokes
8569 (@code{gnus-summary-describe-briefly}).
8572 @kindex H i (Summary)
8573 @findex gnus-info-find-node
8574 Go to the Gnus info node (@code{gnus-info-find-node}).
8577 @node Searching for Articles
8578 @subsection Searching for Articles
8583 @kindex M-s (Summary)
8584 @findex gnus-summary-search-article-forward
8585 Search through all subsequent articles for a regexp
8586 (@code{gnus-summary-search-article-forward}).
8589 @kindex M-r (Summary)
8590 @findex gnus-summary-search-article-backward
8591 Search through all previous articles for a regexp
8592 (@code{gnus-summary-search-article-backward}).
8596 @findex gnus-summary-execute-command
8597 This command will prompt you for a header field, a regular expression to
8598 match on this field, and a command to be executed if the match is made
8599 (@code{gnus-summary-execute-command}).
8602 @kindex M-& (Summary)
8603 @findex gnus-summary-universal-argument
8604 Perform any operation on all articles that have been marked with
8605 the process mark (@code{gnus-summary-universal-argument}).
8608 @node Really Various Summary Commands
8609 @subsection Really Various Summary Commands
8614 @kindex A D (Summary)
8615 @findex gnus-summary-enter-digest-group
8616 If the current article is a collection of other articles (for instance,
8617 a digest), you might use this command to enter a group based on the that
8618 article (@code{gnus-summary-enter-digest-group}). Gnus will try to
8619 guess what article type is currently displayed unless you give a prefix
8620 to this command, which forces a ``digest'' interpretation. Basically,
8621 whenever you see a message that is a collection of other messages on
8622 some format, you @kbd{A D} and read these messages in a more convenient
8626 @kindex C-t (Summary)
8627 @findex gnus-summary-toggle-truncation
8628 Toggle truncation of summary lines (@code{gnus-summary-toggle-truncation}).
8632 @findex gnus-summary-expand-window
8633 Expand the summary buffer window (@code{gnus-summary-expand-window}).
8634 If given a prefix, force an @code{article} window configuration.
8638 @node The Article Buffer
8639 @chapter The Article Buffer
8640 @cindex article buffer
8642 The articles are displayed in the article buffer, of which there is only
8643 one. All the summary buffers share the same article buffer unless you
8644 tell Gnus otherwise.
8647 * Hiding Headers:: Deciding what headers should be displayed.
8648 * Using MIME:: Pushing articles through @sc{mime} before reading them.
8649 * Customizing Articles:: Tailoring the look of the articles.
8650 * Article Keymap:: Keystrokes available in the article buffer
8651 * Misc Article:: Other stuff.
8655 @node Hiding Headers
8656 @section Hiding Headers
8657 @cindex hiding headers
8658 @cindex deleting headers
8660 The top section of each article is the @dfn{head}. (The rest is the
8661 @dfn{body}, but you may have guessed that already.)
8663 @vindex gnus-show-all-headers
8664 There is a lot of useful information in the head: the name of the person
8665 who wrote the article, the date it was written and the subject of the
8666 article. That's well and nice, but there's also lots of information
8667 most people do not want to see---what systems the article has passed
8668 through before reaching you, the @code{Message-ID}, the
8669 @code{References}, etc. ad nauseum---and you'll probably want to get rid
8670 of some of those lines. If you want to keep all those lines in the
8671 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
8673 Gnus provides you with two variables for sifting headers:
8677 @item gnus-visible-headers
8678 @vindex gnus-visible-headers
8679 If this variable is non-@code{nil}, it should be a regular expression
8680 that says what headers you wish to keep in the article buffer. All
8681 headers that do not match this variable will be hidden.
8683 For instance, if you only want to see the name of the person who wrote
8684 the article and the subject, you'd say:
8687 (setq gnus-visible-headers "^From:\\|^Subject:")
8690 This variable can also be a list of regexps to match headers that are to
8693 @item gnus-ignored-headers
8694 @vindex gnus-ignored-headers
8695 This variable is the reverse of @code{gnus-visible-headers}. If this
8696 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
8697 should be a regular expression that matches all lines that you want to
8698 hide. All lines that do not match this variable will remain visible.
8700 For instance, if you just want to get rid of the @code{References} line
8701 and the @code{Xref} line, you might say:
8704 (setq gnus-ignored-headers "^References:\\|^Xref:")
8707 This variable can also be a list of regexps to match headers that are to
8710 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
8711 variable will have no effect.
8715 @vindex gnus-sorted-header-list
8716 Gnus can also sort the headers for you. (It does this by default.) You
8717 can control the sorting by setting the @code{gnus-sorted-header-list}
8718 variable. It is a list of regular expressions that says in what order
8719 the headers are to be displayed.
8721 For instance, if you want the name of the author of the article first,
8722 and then the subject, you might say something like:
8725 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
8728 Any headers that are to remain visible, but are not listed in this
8729 variable, will be displayed in random order after all the headers that
8730 are listed in this variable.
8732 @findex gnus-article-hide-boring-headers
8733 @vindex gnus-article-display-hook
8734 @vindex gnus-boring-article-headers
8735 You can hide further boring headers by entering
8736 @code{gnus-article-hide-boring-headers} into
8737 @code{gnus-article-display-hook}. What this function does depends on
8738 the @code{gnus-boring-article-headers} variable. It's a list, but this
8739 list doesn't actually contain header names. Instead is lists various
8740 @dfn{boring conditions} that Gnus can check and remove from sight.
8742 These conditions are:
8745 Remove all empty headers.
8747 Remove the @code{Newsgroups} header if it only contains the current group
8750 Remove the @code{Followup-To} header if it is identical to the
8751 @code{Newsgroups} header.
8753 Remove the @code{Reply-To} header if it lists the same address as the
8756 Remove the @code{Date} header if the article is less than three days
8760 To include the four first elements, you could say something like;
8763 (setq gnus-boring-article-headers
8764 '(empty newsgroups followup-to reply-to))
8767 This is also the default value for this variable.
8771 @section Using @sc{mime}
8774 Mime is a standard for waving your hands through the air, aimlessly,
8775 while people stand around yawning.
8777 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
8778 while all newsreaders die of fear.
8780 @sc{mime} may specify what character set the article uses, the encoding
8781 of the characters, and it also makes it possible to embed pictures and
8782 other naughty stuff in innocent-looking articles.
8784 @vindex gnus-show-mime
8785 @vindex gnus-show-mime-method
8786 @vindex gnus-strict-mime
8787 Gnus handles @sc{mime} by shoving the articles through
8788 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
8789 default. Set @code{gnus-show-mime} to @code{t} if you want to use
8790 @sc{mime} all the time. However, if @code{gnus-strict-mime} is
8791 non-@code{nil}, the @sc{mime} method will only be used if there are
8792 @sc{mime} headers in the article.
8794 It might be best to just use the toggling functions from the summary
8795 buffer to avoid getting nasty surprises. (For instance, you enter the
8796 group @samp{alt.sing-a-long} and, before you know it, @sc{mime} has
8797 decoded the sound file in the article and some horrible sing-a-long song
8798 comes streaming out out your speakers, and you can't find the volume
8799 button, because there isn't one, and people are starting to look at you,
8800 and you try to stop the program, but you can't, and you can't find the
8801 program to control the volume, and everybody else in the room suddenly
8802 decides to look at you disdainfully, and you'll feel rather stupid.)
8804 Any similarity to real events and people is purely coincidental. Ahem.
8807 @node Customizing Articles
8808 @section Customizing Articles
8809 @cindex article customization
8811 @vindex gnus-article-display-hook
8812 The @code{gnus-article-display-hook} is called after the article has
8813 been inserted into the article buffer. It is meant to handle all
8814 treatment of the article before it is displayed.
8816 By default it contains @code{gnus-article-hide-headers},
8817 @code{gnus-article-treat-overstrike}, and
8818 @code{gnus-article-maybe-highlight}, but there are thousands, nay
8819 millions, of functions you can put in this hook. For an overview of
8820 functions @xref{Article Highlighting}, @xref{Article Hiding},
8821 @xref{Article Washing}, @xref{Article Buttons} and @xref{Article Date}.
8823 You can, of course, write your own functions. The functions are called
8824 from the article buffer, and you can do anything you like, pretty much.
8825 There is no information that you have to keep in the buffer---you can
8826 change everything. However, you shouldn't delete any headers. Instead
8827 make them invisible if you want to make them go away.
8830 @node Article Keymap
8831 @section Article Keymap
8833 Most of the keystrokes in the summary buffer can also be used in the
8834 article buffer. They should behave as if you typed them in the summary
8835 buffer, which means that you don't actually have to have a summary
8836 buffer displayed while reading. You can do it all from the article
8839 A few additional keystrokes are available:
8844 @kindex SPACE (Article)
8845 @findex gnus-article-next-page
8846 Scroll forwards one page (@code{gnus-article-next-page}).
8849 @kindex DEL (Article)
8850 @findex gnus-article-prev-page
8851 Scroll backwards one page (@code{gnus-article-prev-page}).
8854 @kindex C-c ^ (Article)
8855 @findex gnus-article-refer-article
8856 If point is in the neighborhood of a @code{Message-ID} and you press
8857 @kbd{r}, Gnus will try to get that article from the server
8858 (@code{gnus-article-refer-article}).
8861 @kindex C-c C-m (Article)
8862 @findex gnus-article-mail
8863 Send a reply to the address near point (@code{gnus-article-mail}). If
8864 given a prefix, include the mail.
8868 @findex gnus-article-show-summary
8869 Reconfigure the buffers so that the summary buffer becomes visible
8870 (@code{gnus-article-show-summary}).
8874 @findex gnus-article-describe-briefly
8875 Give a very brief description of the available keystrokes
8876 (@code{gnus-article-describe-briefly}).
8879 @kindex TAB (Article)
8880 @findex gnus-article-next-button
8881 Go to the next button, if any (@code{gnus-article-next-button}. This
8882 only makes sense if you have buttonizing turned on.
8885 @kindex M-TAB (Article)
8886 @findex gnus-article-prev-button
8887 Go to the previous button, if any (@code{gnus-article-prev-button}.
8893 @section Misc Article
8897 @item gnus-single-article-buffer
8898 @vindex gnus-single-article-buffer
8899 If non-@code{nil}, use the same article buffer for all the groups.
8900 (This is the default.) If @code{nil}, each group will have its own
8903 @vindex gnus-article-prepare-hook
8905 @item gnus-article-prepare-hook
8906 This hook is called right after the article has been inserted into the
8907 article buffer. It is mainly intended for functions that do something
8908 depending on the contents; it should probably not be used for changing
8909 the contents of the article buffer.
8910 @vindex gnus-article-display-hook
8912 @item gnus-article-display-hook
8913 This hook is called as the last thing when displaying an article, and is
8914 intended for modifying the contents of the buffer, doing highlights,
8915 hiding headers, and the like.
8916 @vindex gnus-article-mode-line-format
8918 @item gnus-article-mode-line-format
8919 This variable is a format string along the same lines as
8920 @code{gnus-summary-mode-line-format}. It accepts exactly the same
8921 format specifications as that variable.
8922 @vindex gnus-break-pages
8924 @item gnus-break-pages
8925 Controls whether @dfn{page breaking} is to take place. If this variable
8926 is non-@code{nil}, the articles will be divided into pages whenever a
8927 page delimiter appears in the article. If this variable is @code{nil},
8928 paging will not be done.
8930 @item gnus-page-delimiter
8931 @vindex gnus-page-delimiter
8932 This is the delimiter mentioned above. By default, it is @samp{^L}
8936 @node The Server Buffer
8937 @chapter The Server Buffer
8939 Traditionally, a @dfn{server} is a machine or a piece of software that
8940 one connects to, and then requests information from. Gnus does not
8941 connect directly to any real servers, but does all transactions through
8942 one backend or other. But that's just putting one layer more between
8943 the actual media and Gnus, so we might just as well say that each
8944 backend represents a virtual server.
8946 For instance, the @code{nntp} backend may be used to connect to several
8947 different actual @sc{nntp} servers, or, perhaps, to many different ports
8948 on the same actual @sc{nntp} server. You tell Gnus which backend to
8949 use, and what parameters to set by specifying a @dfn{select method}.
8951 These select methods specifications can sometimes become quite
8952 complicated---say, for instance, that you want to read from the
8953 @sc{nntp} server @samp{news.funet.fi} on port number @samp{13}, which
8954 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
8955 Anyways, if you had to specify that for each group that used this
8956 server, that would be too much work, so Gnus offers a way of putting
8957 names to methods, which is what you do in the server buffer.
8959 To enter the server buffer, user the @kbd{^}
8960 (@code{gnus-group-enter-server-mode}) command in the group buffer.
8963 * Server Buffer Format:: You can customize the look of this buffer.
8964 * Server Commands:: Commands to manipulate servers.
8965 * Example Methods:: Examples server specifications.
8966 * Servers and Methods:: You can use server names as select methods.
8967 * Unavailable Servers:: Some servers you try to contact may be down.
8970 @node Server Buffer Format
8971 @section Server Buffer Format
8972 @cindex server buffer format
8974 @vindex gnus-server-line-format
8975 You can change the look of the server buffer lines by changing the
8976 @code{gnus-server-line-format} variable. This is a @code{format}-like
8977 variable, with some simple extensions:
8982 How the news is fetched---the backend name.
8985 The name of this server.
8988 Where the news is to be fetched from---the address.
8991 @node Server Commands
8992 @section Server Commands
8993 @cindex server commands
8998 Browse the current server (@code{gnus-server-read-server}).
9001 Return to the group buffer (@code{gnus-server-exit}).
9004 List all servers (@code{gnus-server-list-servers}).
9007 Kill the current server (@code{gnus-server-kill-server}).
9010 Yank the previously killed server (@code{gnus-server-yank-server}).
9013 Copy the current server (@code{gnus-server-copy-server}).
9016 Add a new server (@code{gnus-server-add-server}).
9019 Edit a server (@code{gnus-server-edit-server}).
9022 @node Example Methods
9023 @section Example Methods
9025 Most select methods are pretty simple and self-explanatory:
9028 (nntp "news.funet.fi")
9031 Reading directly from the spool is even simpler:
9037 As you can see, the first element in a select method is the name of the
9038 backend, and the second is the @dfn{address}, or @dfn{name}, if you
9041 After these two elements, there may be a random number of @var{(variable
9044 To go back to the first example---imagine that you want to read from
9045 port @code{15} from that machine. This is what the select method should
9049 (nntp "news.funet.fi" (nntp-port-number 15))
9052 You should read the documentation to each backend to find out what
9053 variables are relevant, but here's an @code{nnmh} example.
9055 @code{nnmh} is a mail backend that reads a spool-like structure. Say
9056 you have two structures that you wish to access: One is your private
9057 mail spool, and the other is a public one. Here's the possible spec for
9061 (nnmh "private" (nnmh-directory "~/private/mail/"))
9064 (This server is then called @samp{private}, but you may have guessed
9067 Here's the method for the public spool:
9071 (nnmh-directory "/usr/information/spool/")
9072 (nnmh-get-new-mail nil))
9075 @node Servers and Methods
9076 @section Servers and Methods
9078 Wherever you would normally use a select method
9079 (eg. @code{gnus-secondary-select-method}, in the group select method,
9080 when browsing a foreign server) you can use a virtual server name
9081 instead. This could potentially save lots of typing. And it's nice all
9085 @node Unavailable Servers
9086 @section Unavailable Servers
9088 If a server seems to be unreachable, Gnus will mark that server as
9089 @code{denied}. That means that any subsequent attempt to make contact
9090 with that server will just be ignored. ``It can't be opened,'' Gnus will
9091 tell you, without making the least effort to see whether that is
9092 actually the case or not.
9094 That might seem quite naughty, but it does make sense most of the time.
9095 Let's say you have 10 groups subscribed to the server
9096 @samp{nepholococcygia.com}. This server is located somewhere quite far
9097 away from you, the machine is quite, so it takes 1 minute just to find
9098 out that it refuses connection from you today. If Gnus were to attempt
9099 to do that 10 times, you'd be quite annoyed, so Gnus won't attempt to do
9100 that. Once it has gotten a single ``connection refused'', it will regard
9101 that server as ``down''.
9103 So, what happens if the machine was only feeling unwell temporarily?
9104 How do you test to see whether the machine has come up again?
9106 You jump to the server buffer (@pxref{The Server Buffer}) and poke ut
9107 with the following commands:
9113 @findex gnus-server-open-server
9114 Try to establish connection to the server on the current line
9115 (@code{gnus-server-open-server}).
9119 @findex gnus-server-close-server
9120 Close the connection (if any) to the server
9121 (@code{gnus-server-close-server}).
9125 @findex gnus-server-deny-server
9126 Mark the current server as unreachable
9127 (@code{gnus-server-deny-server}).
9131 @findex gnus-server-remove-denials
9132 Remove all marks to whether Gnus was denied connection from all servers
9133 (@code{gnus-server-remove-denials}).
9142 Other people use @dfn{kill files}, but we here at Gnus Towers like
9143 scoring better than killing, so we'd rather switch than fight. They do
9144 something completely different as well, so sit up straight and pay
9147 @vindex gnus-summary-mark-below
9148 All articles have a default score (@code{gnus-summary-default-score}),
9149 which is 0 by default. This score may be raised or lowered either
9150 interactively or by score files. Articles that have a score lower than
9151 @code{gnus-summary-mark-below} are marked as read.
9153 Gnus will read any @dfn{score files} that apply to the current group
9154 before generating the summary buffer.
9156 There are several commands in the summary buffer that insert score
9157 entries based on the current article. You can, for instance, ask Gnus to
9158 lower or increase the score of all articles with a certain subject.
9160 There are two sorts of scoring entries: Permanent and temporary.
9161 Temporary score entries are self-expiring entries. Any entries that are
9162 temporary and have not been used for, say, a week, will be removed
9163 silently to help keep the sizes of the score files down.
9166 * Summary Score Commands:: Adding score entries for the current group.
9167 * Group Score Commands:: General score commands.
9168 * Score Variables:: Customize your scoring. (My, what terminology).
9169 * Score File Format:: What a score file may contain.
9170 * Score File Editing:: You can edit score files by hand as well.
9171 * Adaptive Scoring:: Big Sister Gnus *knows* what you read.
9172 * Followups To Yourself:: Having Gnus notice when people answer you.
9173 * Scoring Tips:: How to score effectively.
9174 * Reverse Scoring:: That problem child of old is not problem.
9175 * Global Score Files:: Earth-spanning, ear-splitting score files.
9176 * Kill Files:: They are still here, but they can be ignored.
9179 @node Summary Score Commands
9180 @section Summary Score Commands
9181 @cindex score commands
9183 The score commands that alter score entries do not actually modify real
9184 score files. That would be too inefficient. Gnus maintains a cache of
9185 previously loaded score files, one of which is considered the
9186 @dfn{current score file alist}. The score commands simply insert
9187 entries into this list, and upon group exit, this list is saved.
9189 The current score file is by default the group's local score file, even
9190 if no such score file actually exists. To insert score commands into
9191 some other score file (eg. @file{all.SCORE}), you must first make this
9192 score file the current one.
9194 General score commands that don't actually change the score file:
9199 @kindex V s (Summary)
9200 @findex gnus-summary-set-score
9201 Set the score of the current article (@code{gnus-summary-set-score}).
9204 @kindex V S (Summary)
9205 @findex gnus-summary-current-score
9206 Display the score of the current article
9207 (@code{gnus-summary-current-score}).
9210 @kindex V t (Summary)
9211 @findex gnus-score-find-trace
9212 Display all score rules that have been used on the current article
9213 (@code{gnus-score-find-trace}).
9217 @findex gnus-summary-rescore
9218 Run the current summary through the scoring process
9219 (@code{gnus-summary-rescore}). This might be useful if you're playing
9220 around with your score files behind Gnus' back and want to see the
9221 effect you're having.
9224 @kindex V a (Summary)
9225 @findex gnus-summary-score-entry
9226 Add a new score entry, and allow specifying all elements
9227 (@code{gnus-summary-score-entry}).
9230 @kindex V c (Summary)
9231 @findex gnus-score-change-score-file
9232 Make a different score file the current
9233 (@code{gnus-score-change-score-file}).
9236 @kindex V e (Summary)
9237 @findex gnus-score-edit-alist
9238 Edit the current score file (@code{gnus-score-edit-alist}). You will be
9239 popped into a @code{gnus-score-mode} buffer (@pxref{Score File
9243 @kindex V f (Summary)
9244 @findex gnus-score-edit-file
9245 Edit a score file and make this score file the current one
9246 (@code{gnus-score-edit-file}).
9249 @kindex V C (Summary)
9250 @findex gnus-score-customize
9251 Customize a score file in a visually pleasing manner
9252 (@code{gnus-score-customize}).
9255 @kindex I C-i (Summary)
9256 @findex gnus-summary-raise-score
9257 Increase the score of the current article
9258 (@code{gnus-summary-raise-score}).
9261 @kindex L C-l (Summary)
9262 @findex gnus-summary-lower-score
9263 Lower the score of the current article
9264 (@code{gnus-summary-lower-score}).
9267 The rest of these commands modify the local score file.
9272 @kindex V m (Summary)
9273 @findex gnus-score-set-mark-below
9274 Prompt for a score, and mark all articles with a score below this as
9275 read (@code{gnus-score-set-mark-below}).
9278 @kindex V E (Summary)
9279 @findex gnus-score-set-expunge-below
9280 Expunge all articles with a score below the default score (or the
9281 numeric prefix) (@code{gnus-score-set-expunge-below}).
9284 The keystrokes for actually making score entries follow a very regular
9285 pattern, so there's no need to list all the commands. (Hundreds of
9290 The first key is either @kbd{I} (upper case i) for increasing the score
9291 or @kbd{L} for lowering the score.
9293 The second key says what header you want to score on. The following
9298 Score on the author name.
9301 Score on the subject line.
9304 Score on the Xref line---i.e., the cross-posting line.
9307 Score on thread---the References line.
9313 Score on the number of lines.
9316 Score on the Message-ID.
9329 The third key is the match type. Which match types are legal depends on
9330 what headers you are scoring on.
9374 Greater than number.
9379 The fourth and final key says whether this is a temporary (i.e., expiring)
9380 score entry, or a permanent (i.e., non-expiring) score entry, or whether
9381 it is to be done immediately, without adding to the score file.
9385 Temporary score entry.
9388 Permanent score entry.
9391 Immediately scoring.
9396 So, let's say you want to increase the score on the current author with
9397 exact matching permanently: @kbd{I a e p}. If you want to lower the
9398 score based on the subject line, using substring matching, and make a
9399 temporary score entry: @kbd{L s s t}. Pretty easy.
9401 To make things a bit more complicated, there are shortcuts. If you use
9402 a capital letter on either the second or third keys, Gnus will use
9403 defaults for the remaining one or two keystrokes. The defaults are
9404 ``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s t},
9405 and @kbd{I a R} is the same as @kbd{I a r t}.
9407 @vindex gnus-score-mimic-keymap
9408 The @code{gnus-score-mimic-keymap} says whether these commands will
9409 pretend they are keymaps or not.
9412 @node Group Score Commands
9413 @section Group Score Commands
9414 @cindex group score commands
9416 There aren't many of these as yet, I'm afraid.
9422 @findex gnus-score-flush-cache
9423 Gnus maintains a cache of score alists to avoid having to reload them
9424 all the time. This command will flush the cache
9425 (@code{gnus-score-flush-cache}).
9430 @node Score Variables
9431 @section Score Variables
9432 @cindex score variables
9436 @item gnus-use-scoring
9437 @vindex gnus-use-scoring
9438 If @code{nil}, Gnus will not check for score files, and will not, in
9439 general, do any score-related work. This is @code{t} by default.
9441 @item gnus-kill-killed
9442 @vindex gnus-kill-killed
9443 If this variable is @code{nil}, Gnus will never apply score files to
9444 articles that have already been through the kill process. While this
9445 may save you lots of time, it also means that if you apply a kill file
9446 to a group, and then change the kill file and want to run it over you
9447 group again to kill more articles, it won't work. You have to set this
9448 variable to @code{t} to do that. (It is @code{t} by default.)
9450 @item gnus-kill-files-directory
9451 @vindex gnus-kill-files-directory
9452 All kill and score files will be stored in this directory, which is
9453 initialized from the @samp{SAVEDIR} environment variable by default.
9454 This is @file{~/News/} by default.
9456 @item gnus-score-file-suffix
9457 @vindex gnus-score-file-suffix
9458 Suffix to add to the group name to arrive at the score file name
9459 (@samp{SCORE} by default.)
9461 @item gnus-score-uncacheable-files
9462 @vindex gnus-score-uncacheable-files
9464 All score files are normally cached to avoid excessive re-loading of
9465 score files. However, if this might make you Emacs grow big and
9466 bloated, so this regexp can be used to weed out score files that are
9467 unlikely to be needed again. It would be a bad idea to deny caching of
9468 @file{all.SCORE}, while it might be a good idea to not cache
9469 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
9470 variable is @samp{"ADAPT$"} by default, so no adaptive score files will
9473 @item gnus-save-score
9474 @vindex gnus-save-score
9475 If you have really complicated score files, and do lots of batch
9476 scoring, then you might set this variable to @code{t}. This will make
9477 Gnus save the scores into the @file{.newsrc.eld} file.
9479 @item gnus-score-interactive-default-score
9480 @vindex gnus-score-interactive-default-score
9481 Score used by all the interactive raise/lower commands to raise/lower
9482 score with. Default is 1000, which may seem excessive, but this is to
9483 ensure that the adaptive scoring scheme gets enough room to play with.
9484 We don't want the small changes from the adaptive scoring to overwrite
9485 manually entered data.
9487 @item gnus-summary-default-score
9488 @vindex gnus-summary-default-score
9489 Default score of an article, which is 0 by default.
9491 @item gnus-score-over-mark
9492 @vindex gnus-score-over-mark
9493 Mark (in the third column) used for articles with a score over the
9494 default. Default is @samp{+}.
9496 @item gnus-score-below-mark
9497 @vindex gnus-score-below-mark
9498 Mark (in the third column) used for articles with a score below the
9499 default. Default is @samp{-}.
9501 @item gnus-score-find-score-files-function
9502 @vindex gnus-score-find-score-files-function
9503 Function used to find score files for the current group. This function
9504 is called with the name of the group as the argument.
9506 Predefined functions available are:
9509 @item gnus-score-find-single
9510 @findex gnus-score-find-single
9511 Only apply the group's own score file.
9513 @item gnus-score-find-bnews
9514 @findex gnus-score-find-bnews
9515 Apply all score files that match, using bnews syntax. This is the
9516 default. For instance, if the current group is @samp{gnu.emacs.gnus},
9517 @samp{all.emacs.all.SCORE}, @samp{not.alt.all.SCORE} and
9518 @samp{gnu.all.SCORE} would all apply. In short, the instances of
9519 @samp{all} in the score file names are translated into @samp{.*}, and
9520 then a regexp match is done.
9522 This means that if you have some score entries that you want to apply to
9523 all groups, then you put those entries in the @file{all.SCORE} file.
9525 If @code{gnus-use-long-file-name} is non-@code{nil}, this won't work
9526 very will. It will find stuff like @file{gnu/all/SCORE}, but will not
9527 find files like @file{not/gnu/all/SCORE}.
9529 @item gnus-score-find-hierarchical
9530 @findex gnus-score-find-hierarchical
9531 Apply all score files from all the parent groups. This means that you
9532 can't have score files like @file{all.SCORE} or @file{all.emacs.SCORE},
9533 but you can have @file{SCORE}, @file{comp.SCORE} and
9534 @file{comp.emacs.SCORE}.
9537 This variable can also be a list of functions. In that case, all these
9538 functions will be called, and all the returned lists of score files will
9539 be applied. These functions can also return lists of score alists
9540 directly. In that case, the functions that return these non-file score
9541 alists should probably be placed before the ``real'' score file functions,
9542 to ensure that the last score file returned is the local score file.
9545 @item gnus-score-expiry-days
9546 @vindex gnus-score-expiry-days
9547 This variable says how many days should pass before an unused score file
9548 entry is expired. If this variable is @code{nil}, no score file entries
9549 are expired. It's 7 by default.
9551 @item gnus-update-score-entry-dates
9552 @vindex gnus-update-score-entry-dates
9553 If this variable is non-@code{nil}, matching score entries will have
9554 their dates updated. (This is how Gnus controls expiry---all
9555 non-matching entries will become too old while matching entries will
9556 stay fresh and young.) However, if you set this variable to @code{nil},
9557 even matching entries will grow old and will have to face that oh-so
9563 @node Score File Format
9564 @section Score File Format
9565 @cindex score file format
9567 A score file is an @code{emacs-lisp} file that normally contains just a
9568 single form. Casual users are not expected to edit these files;
9569 everything can be changed from the summary buffer.
9571 Anyway, if you'd like to dig into it yourself, here's an example:
9575 ("Lars Ingebrigtsen" -10000)
9577 ("larsi\\|lmi" -50000 nil R))
9579 ("Ding is Badd" nil 728373))
9581 ("alt.politics" -1000 728372 s))
9586 (mark-and-expunge -10)
9590 (files "/hom/larsi/News/gnu.SCORE")
9591 (exclude-files "all.SCORE")
9592 (local (gnus-newsgroup-auto-expire t)
9593 (gnus-summary-make-false-root 'empty))
9597 This example demonstrates absolutely everything about a score file.
9599 Even though this looks much like lisp code, nothing here is actually
9600 @code{eval}ed. The lisp reader is used to read this form, though, so it
9601 has to be legal syntactically, if not semantically.
9603 Six keys are supported by this alist:
9608 If the key is a string, it is the name of the header to perform the
9609 match on. Scoring can only be performed on these eight headers:
9610 @samp{From}, @samp{Subject}, @samp{References}, @samp{Message-ID},
9611 @samp{Xref}, @samp{Lines}, @samp{Chars} and @samp{Date}. In addition to
9612 these headers, there are three strings to tell Gnus to fetch the entire
9613 article and do the match on larger parts of the article: @samp{Body}
9614 will perform the match on the body of the article, @samp{Head} will
9615 perform the match on the head of the article, and @samp{All} will
9616 perform the match on the entire article. Note that using any of these
9617 last three keys will slow down group entry @emph{considerably}. The
9618 final ``header'' you can score on is @samp{Followup}. These score entries
9619 will result in new score entries being added for all follow-ups to
9620 articles that matches these score entries.
9622 Following this key is a random number of score entries, where each score
9623 entry has one to four elements.
9627 The first element is the @dfn{match element}. On most headers this will
9628 be a string, but on the Lines and Chars headers, this must be an
9632 If the second element is present, it should be a number---the @dfn{score
9633 element}. This number should be an integer in the neginf to posinf
9634 interval. This number is added to the score of the article if the match
9635 is successful. If this element is not present, the
9636 @code{gnus-score-interactive-default-score} number will be used
9637 instead. This is 1000 by default.
9640 If the third element is present, it should be a number---the @dfn{date
9641 element}. This date says when the last time this score entry matched,
9642 which provides a mechanism for expiring the score entries. It this
9643 element is not present, the score entry is permanent. The date is
9644 represented by the number of days since December 31, 1 ce.
9647 If the fourth element is present, it should be a symbol---the @dfn{type
9648 element}. This element specifies what function should be used to see
9649 whether this score entry matches the article. What match types that can
9650 be used depends on what header you wish to perform the match on.
9653 @item From, Subject, References, Xref, Message-ID
9654 For most header types, there are the @code{r} and @code{R} (regexp) as
9655 well as @code{s} and @code{S} (substring) types and @code{e} and
9656 @code{E} (exact match) types. If this element is not present, Gnus will
9657 assume that substring matching should be used. @code{R} and @code{S}
9658 differ from the other two in that the matches will be done in a
9659 case-sensitive manner. All these one-letter types are really just
9660 abbreviations for the @code{regexp}, @code{string} and @code{exact}
9661 types, which you can use instead, if you feel like.
9664 These two headers use different match types: @code{<}, @code{>},
9665 @code{=}, @code{>=} and @code{<=}.
9668 For the Date header we have three match types: @code{before}, @code{at}
9669 and @code{after}. I can't really imagine this ever being useful, but,
9670 like, it would feel kinda silly not to provide this function. Just in
9671 case. You never know. Better safe than sorry. Once burnt, twice shy.
9672 Don't judge a book by its cover. Never not have sex on a first date.
9674 @item Head, Body, All
9675 These three match keys use the same match types as the @code{From} (etc)
9679 This match key will add a score entry on all articles that followup to
9680 some author. Uses the same match types as the @code{From} header uses.
9683 This match key will add a ascore entry on all articles that are part of
9684 a thread. Uses the same match types as the @code{References} header
9690 The value of this entry should be a number. Any articles with a score
9691 lower than this number will be marked as read.
9694 The value of this entry should be a number. Any articles with a score
9695 lower than this number will be removed from the summary buffer.
9697 @item mark-and-expunge
9698 The value of this entry should be a number. Any articles with a score
9699 lower than this number will be marked as read and removed from the
9702 @item thread-mark-and-expunge
9703 The value of this entry should be a number. All articles that belong to
9704 a thread that has a total score below this number will be marked as read
9705 and removed from the summary buffer. @code{gnus-thread-score-function}
9706 says how to compute the total score for a thread.
9709 The value of this entry should be any number of file names. These files
9710 are assumed to be score files as well, and will be loaded the same way
9714 The clue of this entry should be any number of files. This files will
9715 not be loaded, even though they would normally be so, for some reason or
9719 The value of this entry will be @code{eval}el. This element will be
9720 ignored when handling global score files.
9723 Read-only score files will not be updated or saved. Global score files
9724 should feature this atom (@pxref{Global Score Files}).
9727 The value of this entry should be a number. Articles that do not have
9728 parents will get this number added to their scores.
9731 This entry controls the adaptive scoring. If it is @code{t}, the
9732 default adaptive scoring rules will be used. If it is @code{ignore}, no
9733 adaptive scoring will be performed on this group. If it is a list, this
9734 list will be used as the adaptive scoring rules. If it isn't present,
9735 or is something other than @code{t} or @code{ignore}, the default
9736 adaptive scoring rules will be used. If you want to use adaptive
9737 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
9738 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
9739 not want adaptive scoring. If you only want adaptive scoring in a few
9740 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
9741 insert @code{(adapt t)} in the score files of the groups where you want
9745 All adaptive score entries will go to the file named by this entry. It
9746 will also be applied when entering the group. This atom might be handy
9747 if you want to adapt on several groups at once, using the same adaptive
9748 file for a number of groups.
9751 @cindex local variables
9752 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
9753 Each @var{var} will be made buffer-local to the current summary buffer,
9754 and set to the value specified. This is a convenient, if somewhat
9755 strange, way of setting variables in some groups if you don't like hooks
9759 @node Score File Editing
9760 @section Score File Editing
9762 You normally enter all scoring commands from the summary buffer, but you
9763 might feel the urge to edit them by hand as well, so we've supplied you
9764 with a mode for that.
9766 It's simply a slightly customized @code{emacs-lisp} mode, with these
9767 additional commands:
9772 @kindex C-c C-c (Score)
9773 @findex gnus-score-edit-done
9774 Save the changes you have made and return to the summary buffer
9775 (@code{gnus-score-edit-done}).
9778 @kindex C-c C-d (Score)
9779 @findex gnus-score-edit-insert-date
9780 Insert the current date in numerical format
9781 (@code{gnus-score-edit-insert-date}). This is really the day number, if
9785 @kindex C-c C-p (Score)
9786 @findex gnus-score-pretty-print
9787 The adaptive score files are saved in an unformatted fashion. If you
9788 intend to read one of these files, you want to @dfn{pretty print} it
9789 first. This command (@code{gnus-score-pretty-print}) does that for
9794 @node Adaptive Scoring
9795 @section Adaptive Scoring
9796 @cindex adaptive scoring
9798 If all this scoring is getting you down, Gnus has a way of making it all
9799 happen automatically---as if by magic. Or rather, as if by artificial
9800 stupidity, to be precise.
9802 @vindex gnus-use-adaptive-scoring
9803 When you read an article, or mark an article as read, or kill an
9804 article, you leave marks behind. On exit from the group, Gnus can sniff
9805 these marks and add score elements depending on what marks it finds.
9806 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
9809 @vindex gnus-default-adaptive-score-alist
9810 To give you complete control over the scoring process, you can customize
9811 the @code{gnus-default-adaptive-score-alist} variable. By default, it
9812 looks something like this:
9815 (defvar gnus-default-adaptive-score-alist
9816 '((gnus-unread-mark)
9817 (gnus-ticked-mark (from 4))
9818 (gnus-dormant-mark (from 5))
9819 (gnus-del-mark (from -4) (subject -1))
9820 (gnus-read-mark (from 4) (subject 2))
9821 (gnus-expirable-mark (from -1) (subject -1))
9822 (gnus-killed-mark (from -1) (subject -3))
9823 (gnus-kill-file-mark)
9824 (gnus-catchup-mark (from -1) (subject -1))))
9827 As you see, each element in this alist has a mark as a key (either a
9828 variable name or a ``real'' mark---a character). Following this key is a
9829 random number of header/score pairs.
9831 To take @code{gnus-del-mark} as an example---this alist says that all
9832 articles that have that mark (i.e., are marked with @samp{D}) will have a
9833 score entry added to lower based on the @code{From} header by -4, and
9834 lowered by @code{Subject} by -1. Change this to fit your prejudices.
9836 The headers you can score on are @code{from}, @code{subject},
9837 @code{message-id}, @code{references}, @code{xref}, @code{lines},
9838 @code{chars} and @code{date}. In addition, you can score on
9839 @code{followup}, which will create an adaptive score entry that matches
9840 on the @code{References} header using the @code{Message-ID} of the
9841 current article, thereby matching the following thread.
9843 You can also score on @code{thread}, which will try to score all
9844 articles that appear in a thread. @code{thread} matches uses a
9845 @code{Message-ID} to match on the @code{References} header of the
9846 article. If the match is made, the @code{Message-ID} of the article is
9847 added to the @code{thread} rule. (Think about it. I'd recommend two
9848 aspirins afterwards.)
9850 If you use this scheme, you should set @code{mark-below} to something
9851 small---like -300, perhaps, to avoid having small random changes result
9852 in articles getting marked as read.
9854 After using adaptive scoring for a week or so, Gnus should start to
9855 become properly trained and enhance the authors you like best, and kill
9856 the authors you like least, without you having to say so explicitly.
9858 You can control what groups the adaptive scoring is to be performed on
9859 by using the score files (@pxref{Score File Format}). This will also
9860 let you use different rules in different groups.
9862 @vindex gnus-adaptive-file-suffix
9863 The adaptive score entries will be put into a file where the name is the
9864 group name with @code{gnus-adaptive-file-suffix} appended. The default
9867 @vindex gnus-score-exact-adapt-limit
9868 When doing adaptive scoring, substring or fuzzy matching would probably
9869 give you the best results in most cases. However, if the header one
9870 matches is short, the possibility for false positives is great, so if
9871 the length of the match is less than
9872 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
9873 this variable is @code{nil}, exact matching will always be used to avoid
9877 @node Followups To Yourself
9878 @section Followups To Yourself
9880 Gnus offers two commands for picking out the @code{Message-ID} header in
9881 the current buffer. Gnus will then add a score rule that scores using
9882 this @code{Message-ID} on the @code{References} header of other
9883 articles. This will, in effect, increase the score of all articles that
9884 respond to the article in the current buffer. Quite useful if you want
9885 to easily note when people answer what you've said.
9889 @item gnus-score-followup-article
9890 @findex gnus-score-followup-article
9891 This will add a score to articles that directly follow up your own
9894 @item gnus-score-followup-thread
9895 @findex gnus-score-followup-thread
9896 This will add a score to all articles that appear in a thread ``below''
9900 @vindex gnus-inews-article-hook
9901 These two functions are both primarily meant to be used in hooks like
9902 @code{gnus-inews-article-hook}.
9906 @section Scoring Tips
9907 @cindex scoring tips
9912 If you want to lower the score of crossposts, the line to match on is
9913 the @code{Xref} header.
9915 ("xref" (" talk.politics.misc:" -1000))
9918 @item Multiple crossposts
9919 If you want to lower the score of articles that have been crossposted to
9920 more than, say, 3 groups:
9922 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
9925 @item Matching on the body
9926 This is generally not a very good idea---it takes a very long time.
9927 Gnus actually has to fetch each individual article from the server. But
9928 you might want to anyway, I guess. Even though there are three match
9929 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
9930 and stick with it in each score file. If you use any two, each article
9931 will be fetched @emph{twice}. If you want to match a bit on the
9932 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
9935 @item Marking as read
9936 You will probably want to mark articles that has a score below a certain
9937 number as read. This is most easily achieved by putting the following
9938 in your @file{all.SCORE} file:
9942 You may also consider doing something similar with @code{expunge}.
9944 @item Negated charater classes
9945 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
9946 That will match newlines, which might lead to, well, The Unknown. Say
9947 @code{[^abcd\n]*} instead.
9950 @node Reverse Scoring
9951 @section Reverse Scoring
9952 @cindex reverse scoring
9954 If you want to keep just articles that have @samp{Sex with Emacs} in the
9955 subject header, and expunge all other articles, you could put something
9956 like this in your score file:
9960 ("Sex with Emacs" 2))
9965 So, you raise all articles that match @samp{Sex with Emacs} and mark the
9966 rest as read, and expunge them to boot.
9968 @node Global Score Files
9969 @section Global Score Files
9970 @cindex global score files
9972 Sure, other newsreaders have ``global kill files''. These are usually
9973 nothing more than a single kill file that applies to all groups, stored
9974 in the user's home directory. Bah! Puny, weak newsreaders!
9976 What I'm talking about here are Global Score Files. Score files from
9977 all over the world, from users everywhere, uniting all nations in one
9978 big, happy score file union! Ange-score! New and untested!
9980 @vindex gnus-global-score-files
9981 All you have to do to use other people's score files is to set the
9982 @code{gnus-global-score-files} variable. One entry for each score file,
9983 or each score file directory. Gnus will decide by itself what score
9984 files are applicable to which group.
9986 Say you want to use all score files in the
9987 @file{/ftp@@ftp.some-where:/pub/score} directory and the single score
9988 file @file{/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE}:
9991 (setq gnus-global-score-files
9992 '("/ftp@@ftp.ifi.uio.no:/pub/larsi/ding/score/soc.motss.SCORE"
9993 "/ftp@@ftp.some-where:/pub/score/"))
9996 @findex gnus-score-search-global-directories
9997 Simple, eh? Directory names must end with a @samp{/}. These
9998 directories are typically scanned only once during each Gnus session.
9999 If you feel the need to manually re-scan the remote directories, you can
10000 use the @code{gnus-score-search-global-directories} command.
10002 Note that, at present, using this option will slow down group entry
10003 somewhat. (That is---a lot.)
10005 If you want to start maintaining score files for other people to use,
10006 just put your score file up for anonymous ftp and announce it to the
10007 world. Become a retro-moderator! Participate in the retro-moderator
10008 wars sure to ensue, where retro-moderators battle it out for the
10009 sympathy of the people, luring them to use their score files on false
10010 premises! Yay! The net is saved!
10012 Here are some tips for the would-be retro-moderator, off the top of my
10018 Articles that are heavily crossposted are probably junk.
10020 To lower a single inappropriate article, lower by @code{Message-ID}.
10022 Particularly brilliant authors can be raised on a permanent basis.
10024 Authors that repeatedly post off-charter for the group can safely be
10025 lowered out of existence.
10027 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
10028 articles completely.
10031 Use expiring score entries to keep the size of the file down. You
10032 should probably have a long expiry period, though, as some sites keep
10033 old articles for a long time.
10036 ... I wonder whether other newsreaders will support global score files
10037 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
10038 Wave, xrn and 1stReader are bound to implement scoring. Should we start
10039 holding our breath yet?
10043 @section Kill Files
10046 Gnus still supports those pesky old kill files. In fact, the kill file
10047 entries can now be expiring, which is something I wrote before Daniel
10048 Quinlan thought of doing score files, so I've left the code in there.
10050 In short, kill processing is a lot slower (and I do mean @emph{a lot})
10051 than score processing, so it might be a good idea to rewrite your kill
10052 files into score files.
10054 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
10055 forms into this file, which means that you can use kill files as some
10056 sort of primitive hook function to be run on group entry, even though
10057 that isn't a very good idea.
10059 XCNormal kill files look like this:
10062 (gnus-kill "From" "Lars Ingebrigtsen")
10063 (gnus-kill "Subject" "ding")
10067 This will mark every article written by me as read, and remove them from
10068 the summary buffer. Very useful, you'll agree.
10070 Other programs use a totally different kill file syntax. If Gnus
10071 encounters what looks like a @code{rn} kill file, it will take a stab at
10074 Two functions for editing a GNUS kill file:
10079 @kindex M-k (Summary)
10080 @findex gnus-summary-edit-local-kill
10081 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
10084 @kindex M-K (Summary)
10085 @findex gnus-summary-edit-global-kill
10086 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
10089 @vindex gnus-kill-file-name
10090 A kill file for the group @samp{soc.motss} is normally called
10091 @file{soc.motss.KILL}. The suffix appended to the group name to get
10092 this file name is detailed by the @code{gnus-kill-file-name} variable.
10093 The ``global'' kill file (not in the score file sense of ``global'', of
10094 course) is called just @file{KILL}.
10096 @vindex gnus-kill-save-kill-file
10097 If @code{gnus-kill-save-kill-file} is non-@code{nil}, Gnus will save the
10098 kill file after processing, which is necessary if you use expiring
10108 * Interactive:: Making Gnus ask you many questions.
10109 * Formatting Variables:: How to control the look of the buffers.
10110 * Windows Configuration:: Configuring the Gnus buffer windows.
10111 * Buttons:: Get tendonitis in ten easy steps!
10112 * Compilation and Init File:: How to speed Gnus up.
10113 * Daemons:: Gnus can do things behind your back.
10114 * NoCeM:: How to avoid spam and other fatty foods.
10115 * Various Various:: Things that are really various.
10119 @section Interactive
10120 @cindex interaction
10124 @item gnus-novice-user
10125 @vindex gnus-novice-user
10126 If this variable is non-@code{nil}, you are either a newcomer to the
10127 World of Usenet, or you are very cautious, which is a nice thing to be,
10128 really. You will be given questions of the type ``Are you sure you want
10129 to do this?'' before doing anything dangerous. This is @code{t} by
10132 @item gnus-expert-user
10133 @vindex gnus-expert-user
10134 If this variable is non-@code{nil}, you will never ever be asked any
10135 questions by Gnus. It will simply assume you know what you're doing, no
10136 matter how strange.
10138 @item gnus-interactive-catchup
10139 @vindex gnus-interactive-catchup
10140 Require confirmation before catching up a group if non-@code{nil}. It
10141 is @code{t} by default.
10143 @item gnus-interactive-post
10144 @vindex gnus-interactive-post
10145 If non-@code{nil}, the user will be prompted for a group name when
10146 posting an article. It is @code{t} by default.
10148 @item gnus-interactive-exit
10149 @vindex gnus-interactive-exit
10150 Require confirmation before exiting Gnus. This variable is @code{t} by
10155 @node Formatting Variables
10156 @section Formatting Variables
10157 @cindex formatting variables
10159 Throughout this manual you've probably noticed lots of variables that
10160 are called things like @code{gnus-group-line-format} and
10161 @code{gnus-summary-mode-line-format}. These control how Gnus is to
10162 output lines in the various buffers. There's quite a lot of them.
10163 Fortunately, they all use the same syntax, so there's not that much to
10166 Here's an example format spec (from the group buffer): @samp{"%M%S%5y:
10167 %(%g%)\n"}. We see that it is indeed extremely ugly, and that there are
10168 lots of percentages everywhere.
10170 Each @samp{%} element will be replaced by some string or other when the
10171 buffer in question is generated. @samp{%5y} means ``insert the @samp{y}
10172 spec, and pad with spaces to get a 5-character field''. Just like a
10173 normal format spec, almost.
10175 You can also say @samp{%6,4y}, which means that the field will never be
10176 more than 6 characters wide and never less than 4 characters wide.
10178 There are also specs for highlighting, and these are shared by all the
10179 format variables. Text inside the @samp{%(} and @samp{%)} specifiers
10180 will get the special @code{mouse-face} property set, which means that it
10181 will be highlighted (with @code{gnus-mouse-face}) when you put the mouse
10184 Text inside the @samp{%[} and @samp{%]} specifiers will have their
10185 normal faces set using @code{gnus-face-0}, which is @code{bold} by
10186 default. If you say @samp{%1[} instead, you'll get @code{gnus-face-1}
10187 instead, and so on. Create as many faces as you wish. The same goes
10188 for the @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
10189 @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
10191 Here's an alternative recipe for the group buffer:
10194 ;; Create three face types.
10195 (setq gnus-face-1 'bold)
10196 (setq gnus-face-3 'italic)
10198 ;; We want the article count to be in
10199 ;; a bold and green face. So we create
10200 ;; a new face called `my-green-bold'.
10201 (copy-face 'bold 'my-green-bold)
10203 (set-face-foreground 'my-green-bold "ForestGreen")
10204 (setq gnus-face-2 'my-green-bold)
10206 ;; Set the new & fancy format.
10207 (setq gnus-group-line-format
10208 "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
10211 I'm sure you'll be able to use this scheme to create totally unreadable
10212 and extremely vulgar displays. Have fun!
10214 Currently Gnus uses the following formatting variables:
10215 @code{gnus-group-line-format}, @code{gnus-summary-line-format},
10216 @code{gnus-server-line-format}, @code{gnus-topic-line-format},
10217 @code{gnus-group-mode-line-format},
10218 @code{gnus-summary-mode-line-format},
10219 @code{gnus-article-mode-line-format},
10220 @code{gnus-server-mode-line-format}.
10222 Note that the @samp{%(} specs (and friends) do not make any sense on the
10223 mode-line variables.
10225 All these format variables can also be random elisp forms. In that
10226 case, they will be @code{eval}ed to insert the required lines.
10228 @kindex M-x gnus-update-format
10229 @findex gnus-update-format
10230 Gnus includes a command to help you while creating your own format
10231 specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
10232 update the spec in question and pop you to a buffer where you can
10233 examine the resulting lisp code to be run to generate the line.
10236 @node Windows Configuration
10237 @section Windows Configuration
10238 @cindex windows configuration
10240 No, there's nothing here about X, so be quiet.
10242 @vindex gnus-use-full-window
10243 If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
10244 other windows and occupy the entire Emacs screen by itself. It is
10245 @code{t} by default.
10247 @code{gnus-buffer-configuration} describes how much space each Gnus
10248 buffer should be given. Here's an excerpt of this variable:
10251 ((group (vertical 1.0 (group 1.0 point)
10252 (if gnus-carpal (group-carpal 4))))
10253 (article (vertical 1.0 (summary 0.25 point)
10257 This is an alist. The @dfn{key} is a symbol that names some action or
10258 other. For instance, when displaying the group buffer, the window
10259 configuration function will use @code{group} as the key. A full list of
10260 possible names is listed below.
10262 The @dfn{value} (i. e., the @dfn{split}) says how much space each buffer
10263 should occupy. To take the @code{article} split as an example -
10266 (article (vertical 1.0 (summary 0.25 point)
10270 This @dfn{split} says that the summary buffer should occupy 25% of upper
10271 half of the screen, and that it is placed over the article buffer. As
10272 you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
10273 reaching for that calculator there). However, the special number
10274 @code{1.0} is used to signal that this buffer should soak up all the
10275 rest of the space avaiable after the rest of the buffers have taken
10276 whatever they need. There should be only one buffer with the @code{1.0}
10277 size spec per split.
10279 Point will be put in the buffer that has the optional third element
10282 Here's a more complicated example:
10285 (article (vertical 1.0 (group 4)
10286 (summary 0.25 point)
10287 (if gnus-carpal (summary-carpal 4))
10291 If the size spec is an integer instead of a floating point number,
10292 then that number will be used to say how many lines a buffer should
10293 occupy, not a percentage.
10295 If the @dfn{split} looks like something that can be @code{eval}ed (to be
10296 precise---if the @code{car} of the split is a function or a subr), this
10297 split will be @code{eval}ed. If the result is non-@code{nil}, it will
10298 be used as a split. This means that there will be three buffers if
10299 @code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
10302 Not complicated enough for you? Well, try this on for size:
10305 (article (horizontal 1.0
10310 (summary 0.25 point)
10315 Whoops. Two buffers with the mystery 100% tag. And what's that
10316 @code{horizontal} thingie?
10318 If the first element in one of the split is @code{horizontal}, Gnus will
10319 split the window horizontally, giving you two windows side-by-side.
10320 Inside each of these strips you may carry on all you like in the normal
10321 fashion. The number following @code{horizontal} says what percentage of
10322 the screen is to be given to this strip.
10324 For each split, there @emph{must} be one element that has the 100% tag.
10325 The splitting is never accurate, and this buffer will eat any leftover
10326 lines from the splits.
10328 To be slightly more formal, here's a definition of what a legal split
10332 split = frame | horizontal | vertical | buffer | form
10333 frame = "(frame " size *split ")"
10334 horizontal = "(horizontal " size *split ")"
10335 vertical = "(vertical " size *split ")"
10336 buffer = "(" buffer-name " " size *[ "point" ] ")"
10337 size = number | frame-params
10338 buffer-name = group | article | summary ...
10341 The limitations are that the @samp{frame} split can only appear as the
10342 top-level split. @samp{form} should be an Emacs Lisp form that should
10343 return a valid split. We see that each split is fully recursive, and
10344 may contain any number of @samp{vertical} and @samp{horizontal} splits.
10346 @vindex gnus-window-min-width
10347 @vindex gnus-window-min-height
10348 @cindex window height
10349 @cindex window width
10350 Finding the right sizes can be a bit complicated. No window may be less
10351 than @code{gnus-window-min-height} (default 2) characters high, and all
10352 windows must be at least @code{gnus-window-min-wide} (default 1)
10353 characters wide. Gnus will try to enforce this before applying the
10354 splits. If you want to use the normal Emacs window width/height limit,
10355 you can just set these two variables to @code{nil}.
10357 If you're not familiar with Emacs terminology, @samp{horizontal} and
10358 @samp{vertical} splits may work the opposite way of what you'd expect.
10359 Windows inside a @samp{horizontal} split are shown side-by-side, and
10360 windows within a @samp{vertical} split are shown above each other.
10362 @findex gnus-configure-frame
10363 If you want to experiment with window placement, a good tip is to call
10364 @code{gnus-configure-frame} directly with a split. This is the function
10365 that does all the real work when splitting buffers. Below is a pretty
10366 nonsensical configuration with 5 windows; two for the group buffer and
10367 three for the article buffer. (I said it was nonsensical.) If you
10368 @code{eval} the statement below, you can get an idea of how that would
10369 look straight away, without going through the normal Gnus channels.
10370 Play with it until you're satisfied, and then use
10371 @code{gnus-add-configuration} to add your new creation to the buffer
10372 configuration list.
10375 (gnus-configure-frame
10379 (article 0.3 point))
10387 You might want to have several frames as well. No prob---just use the
10388 @code{frame} split:
10391 (gnus-configure-frame
10394 (summary 0.25 point)
10396 (vertical ((height . 5) (width . 15)
10397 (user-position . t)
10398 (left . -1) (top . 1))
10403 This split will result in the familiar summary/article window
10404 configuration in the first (or ``main'') frame, while a small additional
10405 frame will be created where picons will be shown. As you can see,
10406 instead of the normal @samp{1.0} top-level spec, each additional split
10407 should have a frame parameter alist as the size spec.
10408 @xref{(elisp)Frame Parameters}.
10410 Here's a list of all possible keys for
10411 @code{gnus-buffer-configuaration}:
10413 @code{group}, @code{summary}, @code{article}, @code{server},
10414 @code{browse}, @code{group-mail}, @code{summary-mail},
10415 @code{summary-reply}, @code{info}, @code{summary-faq},
10416 @code{edit-group}, @code{edit-server}, @code{reply}, @code{reply-yank},
10417 @code{followup}, @code{followup-yank}, @code{edit-score}.
10419 @findex gnus-add-configuration
10420 Since the @code{gnus-buffer-configuration} variable is so long and
10421 complicated, there's a function you can use to ease changing the config
10422 of a single setting: @code{gnus-add-configuration}. If, for instance,
10423 you want to change the @code{article} setting, you could say:
10426 (gnus-add-configuration
10427 '(article (vertical 1.0
10429 (summary .25 point)
10433 You'd typically stick these @code{gnus-add-configuration} calls in your
10434 @file{.gnus} file or in some startup hook -- they should be run after
10435 Gnus has been loaded.
10444 Those new-fangled @dfn{mouse} contraptions is very popular with the
10445 young, hep kids who don't want to learn the proper way to do things
10446 these days. Why, I remember way back in the summer of '89, when I was
10447 using Emacs on a Tops 20 system. Three hundred users on one single
10448 machine, and every user was running Simula compilers. Bah!
10452 @vindex gnus-carpal
10453 Well, you can make Gnus display bufferfuls of buttons you can click to
10454 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
10455 really. Tell the chiropractor I sent you.
10460 @item gnus-carpal-mode-hook
10461 @vindex gnus-carpal-mode-hook
10462 Hook run in all carpal mode buffers.
10464 @item gnus-carpal-button-face
10465 @vindex gnus-carpal-button-face
10466 Face used on buttons.
10468 @item gnus-carpal-group-buffer-buttons
10469 @vindex gnus-carpal-group-buffer-buttons
10470 Buttons in the group buffer.
10472 @item gnus-carpal-summary-buffer-buttons
10473 @vindex gnus-carpal-summary-buffer-buttons
10474 Buttons in the summary buffer.
10476 @item gnus-carpal-server-buffer-buttons
10477 @vindex gnus-carpal-server-buffer-buttons
10478 Buttons in the server buffer.
10480 @item gnus-carpal-browse-buffer-buttons
10481 @vindex gnus-carpal-browse-buffer-buttons
10482 Buttons in the browse buffer.
10485 All the @code{buttons} variables are lists. The elements in these list
10486 is either a cons cell where the car contains a text to be displayed and
10487 the cdr contains a function symbol, or a simple string.
10490 @node Compilation and Init File
10491 @section Compilation and Init File
10492 @cindex compilation
10494 @cindex byte-compilation
10496 @vindex gnus-init-file
10497 @findex gnus-compile
10498 When Gnus starts up, it will read the Gnus init file
10499 @code{gnus-init-file}, which is @file{.gnus} by default. It is
10500 recommended that you keep any Gnus-related functions that you have
10501 written in that file. If you want to byte-compile the file, Gnus offers
10502 the handy @kbd{M-x gnus-compile} function that will do that for you.
10504 That's not really why that function was written, though.
10506 Remember all those line format specification variables?
10507 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
10508 on. Now, Gnus will of course heed whatever these variables are, but,
10509 unfortunately, changing them will mean a quite significant slow-down.
10510 (The default values of these variables have byte-compiled functions
10511 associated with them, while the user-generated versions do not, of
10514 To help with this, you can run @code{gnus-compile} after you've fiddled
10515 around with the variables and feel that you're (kind of) satisfied.
10516 This will result in the new specs being byte-compiled, and you'll get
10519 The result of these byte-compilations will be written to
10520 @file{.gnus.elc} by default.
10522 Note that Gnus will read @file{.gnus.elc} instead of @file{.gnus} if
10523 @file{.gnus.elc} exists, so if you change @file{.gnus}, you should
10524 remove @file{.gnus.elc}.
10532 Gnus, being larger than any program ever written (allegedly), does lots
10533 of strange stuff that you may wish to have done while you're not
10534 present. For instance, you may want it to check for new mail once in a
10535 while. Or you may want it to close down all connections to all servers
10536 when you leave Emacs idle. And stuff like that.
10538 Gnus will let you do stuff like that by defining various
10539 @dfn{handlers}. Each handler consists of three elements: A
10540 @var{function}, a @var{time}, and an @var{idle} parameter.
10542 Here's an example of a handler that closes connections when Emacs has
10543 been idle for thirty minutes:
10546 (gnus-demon-close-connections nil 30)
10549 Here's a handler that scans for PGP headers every hour when Emacs is
10553 (gnus-demon-scan-pgp 60 t)
10556 This @var{time} parameter and than @var{idle} parameter works together
10557 in a strange, but wonderful fashion. Basically, if @var{idle} is
10558 @code{nil}, then the function will be called every @var{time} minutes.
10560 If @var{idle} is @code{t}, then the function will be called after
10561 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
10562 the function will never be called. But once Emacs goes idle, the
10563 function will be called every @var{time} minutes.
10565 If @var{idle} is a number and @var{time} is a number, the function will
10566 be called every @var{time} minutes only when Emacs has been idle for
10567 @var{idle} minutes.
10569 If @var{idle} is a number and @var{time} is @code{nil}, the function
10570 will be called once every time Emacs has been idle for @var{idle}
10573 And if @var{time} is a string, it should look like @samp{"07:31"}, and
10574 the function will then be called once every day somewhere near that
10575 time. Modified by the @var{idle} parameter, of course.
10577 @vindex gnus-demon-timestep
10578 (When I say ``minute'' here, I really mean @code{gnus-demon-timestep}
10579 seconds. This is @samp{60} by default. If you change that variable,
10580 all the timings in the handlers will be affected.)
10582 @vindex gnus-use-demon
10583 To set the whole thing in motion, though, you have to set
10584 @code{gnus-use-demon} to @code{t}.
10586 @vindex gnus-use-demon
10587 To set the whole thing in motion, though, you have to set
10588 @code{gnus-use-demon} to @code{t}.
10590 So, if you want to add a handler, you could put something like this in
10591 your @file{.gnus} file:
10593 @findex gnus-demon-add-handler
10595 (gnus-demon-add-handler 'gnus-demon-close-connections nil 30)
10598 @findex gnus-demon-add-nocem
10599 @findex gnus-demon-add-scanmail
10600 @findex gnus-demon-add-disconnection
10601 Some ready-made functions to do this has been created:
10602 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, and
10603 @code{gnus-demon-add-scanmail}. Just put those functions in your
10604 @file{.gnus} if you want those abilities.
10606 @findex gnus-demon-init
10607 @findex gnus-demon-cancel
10608 @vindex gnus-demon-handlers
10609 If you add handlers to @code{gnus-demon-handlers} directly, you should
10610 run @code{gnus-demon-init} to make the changes take hold. To cancel all
10611 daemons, you can use the @code{gnus-demon-cancel} function.
10613 Note that adding daemons can be pretty naughty if you overdo it. Adding
10614 functions that scan all news and mail from all servers every two seconds
10615 is a sure-fire way of getting booted off any respectable system. So
10626 @node Various Various
10627 @section Various Various
10634 @vindex gnus-verbose
10635 This variable is an integer between zero and ten. The higher the value,
10636 the more messages will be displayed. If this variable is zero, Gnus
10637 will never flash any messages, if it is seven (which is the default),
10638 most important messages will be shown, and if it is ten, Gnus won't ever
10639 shut up, but will flash so many messages it will make your head swim.
10641 @item gnus-verbose-backends
10642 @vindex gnus-verbose-backends
10643 This variable works the same way as @code{gnus-verbose}, but it applies
10644 to the Gnus backends instead of Gnus proper.
10646 @item gnus-updated-mode-lines
10647 @vindex gnus-updated-mode-lines
10648 This is a list of buffers that should keep their mode lines updated.
10649 The list may contain the symbols @code{group}, @code{article} and
10650 @code{summary}. If the corresponding symbol is present, Gnus will keep
10651 that mode line updated with information that may be pertinent. If this
10652 variable is @code{nil}, screen refresh may be quicker.
10654 @cindex display-time
10656 @item gnus-mode-non-string-length
10657 @vindex gnus-mode-non-string-length
10658 By default, Gnus displays information on the current article in the mode
10659 lines of the summary and article buffers. The information Gnus wishes
10660 to display (eg. the subject of the article) is often longer than the
10661 mode lines, and therefore have to be cut off at some point. This
10662 variable says how long the other elements on the line is (i.e., the
10663 non-info part). If you put additional elements on the mode line (eg. a
10664 clock), you should modify this variable:
10666 @c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
10668 (add-hook 'display-time-hook
10669 (lambda () (setq gnus-mode-non-string-length
10671 (if line-number-mode 5 0)
10672 (if column-number-mode 4 0)
10673 (length display-time-string)))))
10676 If this variable is @code{nil} (which is the default), the mode line
10677 strings won't be chopped off, and they won't be padded either.
10680 @vindex gnus-visual
10682 @cindex highlighting
10685 If @code{nil}, Gnus won't attempt to create menus or use fancy colors
10686 or fonts. This will also inhibit loading the @file{gnus-visual.el}
10689 This variable can also be a list of visual properties that are enabled.
10690 The following elements are legal, and are all set by default:
10694 @item summary-highlight
10695 Perform various highlighting in the summary buffer.
10697 @item article-highlight
10698 Perform various highlighting in the article buffer.
10701 Turn on highlighting in all buffers.
10704 Create menus in the group buffer.
10707 Create menus in the summary buffer.
10710 Create menus in the article buffer.
10713 Create menus in the browse buffer.
10716 Create menus in the server buffer.
10719 Create menus in all buffers.
10723 So if you only want highlighting in the article buffer and menus in all
10724 buffers, you couls say something like:
10727 (setq gnus-visual '(article-highlight menu))
10730 If you want only highlighting and no menus whatsoever, you'd say:
10733 (setq gnus-visual '(highlight))
10736 @item gnus-mouse-face
10737 @vindex gnus-mouse-face
10738 This is the face (i.e., font) used for mouse highlighting in Gnus. No
10739 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
10741 @item gnus-display-type
10742 @vindex gnus-display-type
10743 This variable is symbol indicating the display Emacs is running under.
10744 The symbol should be one of @code{color}, @code{grayscale} or
10745 @code{mono}. If Gnus guesses this display attribute wrongly, either set
10746 this variable in your @file{~/.emacs} or set the resource
10747 @code{Emacs.displayType} in your @file{~/.Xdefaults}.
10749 @item gnus-background-mode
10750 @vindex gnus-background-mode
10751 This is a symbol indicating the Emacs background brightness. The symbol
10752 should be one of @code{light} or @code{dark}. If Gnus guesses this
10753 frame attribute wrongly, either set this variable in your @file{~/.emacs} or
10754 set the resource @code{Emacs.backgroundMode} in your @file{~/.Xdefaults}.
10755 `gnus-display-type'.
10757 @item nnheader-max-head-length
10758 @vindex nnheader-max-head-length
10759 When the backends read straight heads of articles, they all try to read
10760 as little as possible. This variable (default @code{4096}) specifies
10761 the absolute max length the backends will try to read before giving up
10762 on finding a separator line between the head and the body. If this
10763 variable is @code{nil}, there is no upper read bound. If it is
10764 @code{t}, the backends won't try to read the articles piece by piece,
10765 but read the entire articles. This makes sense with some versions of
10768 @item nnheader-file-name-translation-alist
10769 @vindex nnheader-file-name-translation-alist
10771 @cindex illegal characters in file names
10772 @cindex characters in file names
10773 This is an alist that says how to translate characters in file names.
10774 For instance, if @samp{:} is illegal as a file character in file names
10775 on your system (you OS/2 user you), you could say something like:
10778 (setq nnheader-file-name-translation-alist
10782 In fact, this is the default value for this variable on OS/2 and MS
10783 Windows (phooey) systems.
10787 @node Customization
10788 @chapter Customization
10789 @cindex general customization
10791 All variables are properly documented elsewhere in this manual. This
10792 section is designed to give general pointers on how to customize Gnus
10793 for some quite common situations.
10796 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
10797 * Slow Terminal Connection:: You run a remote Emacs.
10798 * Little Disk Space:: You feel that having large setup files is icky.
10799 * Slow Machine:: You feel like buying a faster machine.
10802 @node Slow/Expensive Connection
10803 @section Slow/Expensive @sc{nntp} Connection
10805 If you run Emacs on a machine locally, and get your news from a machine
10806 over some very thin strings, you want to cut down on the amount of data
10807 Gnus has to get from the @sc{nntp} server.
10811 @item gnus-read-active-file
10812 Set this to @code{nil}, which will inhibit Gnus from requesting the
10813 entire active file from the server. This file is often v. large. You
10814 also have to set @code{gnus-check-new-news} and
10815 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
10816 doesn't suddenly decide to fetch the active file anyway.
10818 @item gnus-nov-is-evil
10819 This one has to be @code{nil}. If not, grabbing article headers from
10820 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
10821 support @sc{xover}; Gnus will detect this by itself.
10824 @node Slow Terminal Connection
10825 @section Slow Terminal Connection
10827 Let's say you use your home computer for dialing up the system that
10828 runs Emacs and Gnus. If your modem is slow, you want to reduce the
10829 amount of data that is sent over the wires as much as possible.
10833 @item gnus-auto-center-summary
10834 Set this to @code{nil} to inhibit Gnus from recentering the summary
10835 buffer all the time.
10837 @item gnus-visible-headers
10838 Cut down on the headers that are included in the articles to the
10839 minimum. You can, in fact, make do without them altogether---most of the
10840 useful data is in the summary buffer, anyway. Set this variable to
10841 @samp{"^NEVVVVER"} or @samp{"From:"}, or whatever you feel you need.
10843 @item gnus-article-display-hook
10844 Set this hook to all the available hiding commands:
10846 (setq gnus-article-display-hook
10847 '(gnus-article-hide-headers gnus-article-hide-signature
10848 gnus-article-hide-citation))
10851 @item gnus-use-full-window
10852 By setting this to @code{nil}, you can make all the windows smaller.
10853 While this doesn't really cut down much generally, it means that you
10854 have to see smaller portions of articles before deciding that you didn't
10855 want to read them anyway.
10857 @item gnus-thread-hide-subtree
10858 If this is non-@code{nil}, all threads in the summary buffer will be
10861 @item gnus-updated-mode-lines
10862 If this is @code{nil}, Gnus will not put information in the buffer mode
10863 lines, which might save some time.
10866 @node Little Disk Space
10867 @section Little Disk Space
10869 The startup files can get rather large, so you may want to cut their
10870 sizes a bit if you are running out of space.
10874 @item gnus-save-newsrc-file
10875 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
10876 only save @file{.newsrc.eld}. This means that you will not be able to
10877 use any other newsreaders than Gnus. This variable is @code{t} by
10880 @item gnus-save-killed-list
10881 If this is @code{nil}, Gnus will not save the list of dead groups. You
10882 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
10883 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
10884 variable to @code{nil}. This variable is @code{t} by default.
10890 @section Slow Machine
10892 If you have a slow machine, or are just really impatient, there are a
10893 few things you can do to make Gnus run faster.
10895 Set@code{gnus-check-new-newsgroups} and
10896 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
10898 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
10899 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
10900 summary buffer faster.
10902 Set @code{gnus-article-display-hook} to @code{nil} to make article
10903 processing a bit faster.
10906 @node Troubleshooting
10907 @chapter Troubleshooting
10908 @cindex troubleshooting
10910 Gnus works @emph{so} well straight out of the box---I can't imagine any
10918 Make sure your computer is switched on.
10921 Make sure that you really load the current Gnus version. If you have
10922 been running @sc{gnus}, you need to exit Emacs and start it up again before
10926 Try doing an @kbd{M-x gnus-version}. If you get something that looks
10927 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
10928 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
10929 flee}, you have some old @file{.el} files lying around. Delete these.
10932 Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
10936 If all else fails, report the problem as a bug.
10939 @cindex reporting bugs
10941 @kindex M-x gnus-bug
10943 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
10944 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
10945 me the backtrace. I will fix bugs, but I can only fix them if you send
10946 me a precise description as to how to reproduce the bug.
10948 You really can never be too detailed in a bug report. Always use the
10949 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
10950 a 10Kb mail each time you use it, and even if you have sent me your
10951 environment 500 times before. I don't care. I want the full info each
10954 It is also important to remember that I have no memory whatsoever. If
10955 you send a bug report, and I send you a reply, and then you send back
10956 just ``No, it's not! Moron!'', I will have no idea what you are insulting
10957 me about. Always overexplain everything. It's much easier for all of
10958 us---if I don't have all the information I need, I will just mail you
10959 and ask for more info, and everything takes more time.
10961 If you just need help, you are better off asking on
10962 @samp{gnu.emacs.gnus}. I'm not very helpful.
10964 @cindex gnu.emacs.gnus
10965 @cindex ding mailing list
10966 You can also ask on the ding mailing list---@samp{ding@@ifi.uio.no}.
10967 Write to @samp{ding-request@@ifi.uio.no} to subscribe.
10973 Well, that's the manual---you can get on with your life now. Keep in
10974 touch. Say hello to your cats from me.
10976 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
10978 Ol' Charles Reznikoff said it pretty well, so I leave the floor to him:
10983 Not because of victories @*
10986 but for the common sunshine,@*
10988 the largess of the spring.
10991 but for the day's work done@*
10992 as well as I was able;@*
10993 not for a seat upon the dais@*
10994 but at the common table.@*
10998 @chapter Appendices
11001 * A Programmer@'s Guide to Gnus:: Rilly, rilly technical stuff.
11002 * Emacs for Heathens:: A short intruduction to Emacsian terms.
11003 * Frequently Asked Questions:: A question-and-answer session.
11007 @node A Programmer@'s Guide to Gnus
11008 @section A Programmer's Guide to Gnus
11010 It is my hope that other people will figure out smart stuff that Gnus
11011 can do, and that other people will write those smart things as well. To
11012 facilitate that I thought it would be a good idea to describe the inner
11013 workings of Gnus. And some of the not-so-inner workings, while I'm at
11016 You can never expect the internals of a program not to change, but I
11017 will be defining (in some details) the interface between Gnus and its
11018 backends (this is written in stone), the format of the score files
11019 (ditto), data structures (some are less likely to change than others)
11020 and general method of operations.
11023 * Backend Interface:: How Gnus communicates with the servers.
11024 * Score File Syntax:: A BNF definition of the score file standard.
11025 * Headers:: How Gnus stores headers internally.
11026 * Ranges:: A handy format for storing mucho numbers.
11027 * Group Info:: The group info format.
11028 * Various File Formats:: Formats of files that Gnus use.
11032 @node Backend Interface
11033 @subsection Backend Interface
11035 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
11036 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
11037 server is a @dfn{backend} and some @dfn{backend variables}. As examples
11038 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
11039 examples of the latter we have @code{nntp-port-number} and
11040 @code{nnmbox-directory}.
11042 When Gnus asks for information from a backend---say @code{nntp}---on
11043 something, it will normally include a virtual server name in the
11044 function parameters. (If not, the backend should use the ``current''
11045 virtual server.) For instance, @code{nntp-request-list} takes a virtual
11046 server as its only (optional) parameter. If this virtual server hasn't
11047 been opened, the function should fail.
11049 Note that a virtual server name has no relation to some physical server
11050 name. Take this example:
11054 (nntp-address "ifi.uio.no")
11055 (nntp-port-number 4324))
11058 Here the virtual server name is @samp{"odd-one"} while the name of
11059 the physical server is @samp{"ifi.uio.no"}.
11061 The backends should be able to switch between several virtual servers.
11062 The standard backends implement this by keeping an alist of virtual
11063 server environments that it pulls down/pushes up when needed.
11065 There are two groups of interface functions: @dfn{required functions},
11066 which must be present, and @dfn{optional functions}, which Gnus will
11067 always check whether are present before attempting to call.
11069 All these functions are expected to return data in the buffer
11070 @code{nntp-server-buffer} (@samp{" *nntpd*"}), which is somewhat
11071 unfortunately named, but we'll have to live with it. When I talk about
11072 ``resulting data'', I always refer to the data in that buffer. When I
11073 talk about ``return value'', I talk about the function value returned by
11076 Some backends could be said to be @dfn{server-forming} backends, and
11077 some might be said to not be. The latter are backends that generally
11078 only operate on one group at a time, and have no concept of ``server'' --
11079 they have a group, and they deliver info on that group and nothing more.
11081 In the examples and definitions I will refer to the imaginary backend
11084 @cindex @code{nnchoke}
11087 * Required Backend Functions:: Functions that must be implemented.
11088 * Optional Backend Functions:: Functions that need not be implemented.
11092 @node Required Backend Functions
11093 @subsubsection Required Backend Functions
11097 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
11099 @var{articles} is either a range of article numbers or a list of
11100 @code{Message-ID}s. Current backends do not fully support either---only
11101 sequences (lists) of article numbers, and most backends do not support
11102 retrieval of @code{Message-ID}s. But they should try for both.
11104 The result data should either be HEADs or NOV lines, and the result
11105 value should either be @code{headers} or @code{nov} to reflect this.
11106 This might later be expanded to @code{various}, which will be a mixture
11107 of HEADs and NOV lines, but this is currently not supported by Gnus.
11109 If @var{fetch-old} is non-@code{nil} it says to try to fetch "extra
11110 headers, in some meaning of the word. This is generally done by
11111 fetching (at most) @var{fetch-old} extra headers less than the smallest
11112 article number in @code{articles}, and fill in the gaps as well. The
11113 presence of this parameter can be ignored if the backend finds it
11114 cumbersome to follow the request. If this is non-@code{nil} and not a
11115 number, do maximum fetches.
11117 Here's an example HEAD:
11120 221 1056 Article retrieved.
11121 Path: ifi.uio.no!sturles
11122 From: sturles@@ifi.uio.no (Sturle Sunde)
11123 Newsgroups: ifi.discussion
11124 Subject: Re: Something very droll
11125 Date: 27 Oct 1994 14:02:57 +0100
11126 Organization: Dept. of Informatics, University of Oslo, Norway
11128 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
11129 References: <38jdmq$4qu@@visbur.ifi.uio.no>
11130 NNTP-Posting-Host: holmenkollen.ifi.uio.no
11134 So a @code{headers} return value would imply that there's a number of
11135 these in the data buffer.
11137 Here's a BNF definition of such a buffer:
11141 head = error / valid-head
11142 error-message = [ "4" / "5" ] 2number " " <error message> eol
11143 valid-head = valid-message *header "." eol
11144 valid-message = "221 " <number> " Article retrieved." eol
11145 header = <text> eol
11148 If the return value is @code{nov}, the data buffer should contain
11149 @dfn{network overview database} lines. These are basically fields
11153 nov-buffer = *nov-line
11154 nov-line = 8*9 [ field <TAB> ] eol
11155 field = <text except TAB>
11158 For a closer explanation what should be in those fields,
11162 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
11164 @var{server} is here the virtual server name. @var{definitions} is a
11165 list of @code{(VARIABLE VALUE)} pairs that defines this virtual server.
11167 If the server can't be opened, no error should be signaled. The backend
11168 may then choose to refuse further attempts at connecting to this
11169 server. In fact, it should do so.
11171 If the server is opened already, this function should return a
11172 non-@code{nil} value. There should be no data returned.
11175 @item (nnchoke-close-server &optional SERVER)
11177 Close connection to @var{server} and free all resources connected
11180 There should be no data returned.
11183 @item (nnchoke-request-close)
11185 Close connection to all servers and free all resources that the backend
11186 have reserved. All buffers that have been created by that backend
11187 should be killed. (Not the @code{nntp-server-buffer}, though.)
11189 There should be no data returned.
11192 @item (nnchoke-server-opened &optional SERVER)
11194 This function should return whether @var{server} is opened, and that the
11195 connection to it is still alive. This function should under no
11196 circumstances attempt to reconnect to a server that is has lost
11199 There should be no data returned.
11202 @item (nnchoke-status-message &optional SERVER)
11204 This function should return the last error message from @var{server}.
11206 There should be no data returned.
11209 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
11211 The result data from this function should be the article specified by
11212 @var{article}. This might either be a @code{Message-ID} or a number.
11213 It is optional whether to implement retrieval by @code{Message-ID}, but
11214 it would be nice if that were possible.
11216 If @var{to-buffer} is non-@code{nil}, the result data should be returned
11217 in this buffer instead of the normal data buffer. This is to make it
11218 possible to avoid copying large amounts of data from one buffer to
11219 another, and Gnus mainly request articles to be inserted directly into
11220 its article buffer.
11223 @item (nnchoke-open-group GROUP &optional SERVER)
11225 Make @var{group} the current group.
11227 There should be no data returned by this function.
11230 @item (nnchoke-request-group GROUP &optional SERVER)
11232 Get data on @var{group}. This function also has the side effect of
11233 making @var{group} the current group.
11235 Here's an example of some result data and a definition of the same:
11238 211 56 1000 1059 ifi.discussion
11241 The first number is the status, which should be @samp{211}. Next is the
11242 total number of articles in the group, the lowest article number, the
11243 highest article number, and finally the group name. Note that the total
11244 number of articles may be less than one might think while just
11245 considering the highest and lowest article numbers, but some articles
11246 may have been cancelled. Gnus just discards the total-number, so
11247 whether one should take the bother to generate it properly (if that is a
11248 problem) is left as an excercise to the reader.
11251 group-status = [ error / info ] eol
11252 error = [ "4" / "5" ] 2<number> " " <Error message>
11253 info = "211 " 3* [ <number> " " ] <string>
11257 @item (nnchoke-close-group GROUP &optional SERVER)
11259 Close @var{group} and free any resources connected to it. This will be
11260 a no-op on most backends.
11262 There should be no data returned.
11265 @item (nnchoke-request-list &optional SERVER)
11267 Return a list of all groups available on @var{server}. And that means
11270 Here's an example from a server that only carries two groups:
11273 ifi.test 0000002200 0000002000 y
11274 ifi.discussion 3324 3300 n
11277 On each line we have a group name, then the highest article number in
11278 that group, the lowest article number, and finally a flag.
11281 active-file = *active-line
11282 active-line = name " " <number> " " <number> " " flags eol
11284 flags = "n" / "y" / "m" / "x" / "j" / "=" name
11287 The flag says whether the group is read-only (@samp{n}), is moderated
11288 (@samp{m}), is dead (@samp{x}), is aliased to some other group
11289 (@samp{=other-group} or none of the above (@samp{y}).
11292 @item (nnchoke-request-post &optional SERVER)
11294 This function should post the current buffer. It might return whether
11295 the posting was successful or not, but that's not required. If, for
11296 instance, the posting is done asynchronously, it has generally not been
11297 completed by the time this function concludes. In that case, this
11298 function should set up some kind of sentinel to beep the user loud and
11299 clear if the posting could not be completed.
11301 There should be no result data from this function.
11304 @item (nnchoke-request-post-buffer POST GROUP SUBJECT HEADER ARTICLE-BUFFER INFO FOLLOW-TO RESPECT-POSTER)
11306 This function should return a buffer suitable for composing an article
11307 to be posted by @code{nnchoke-request-post}. If @var{post} is
11308 non-@code{nil}, this is not a followup, but a totally new article.
11309 @var{group} is the name of the group to be posted to. @var{subject} is
11310 the subject of the message. @var{article-buffer} is the buffer being
11311 followed up, if that is the case. @var{info} is the group info.
11312 @var{follow-to} is the group that one is supposed to re-direct the
11313 article ot. If @var{respect-poster} is non-@code{nil}, the special
11314 @samp{"poster"} value of a @code{Followup-To} header is to be respected.
11316 There should be no result data returned.
11320 @node Optional Backend Functions
11321 @subsubsection Optional Backend Functions
11325 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
11327 @var{groups} is a list of groups, and this function should request data
11328 on all those groups. How it does it is of no concern to Gnus, but it
11329 should attempt to do this in a speedy fashion.
11331 The return value of this function can be either @code{active} or
11332 @code{group}, which says what the format of the result data is. The
11333 former is in the same format as the data from
11334 @code{nnchoke-request-list}, while the latter is a buffer full of lines
11335 in the same format as @code{nnchoke-request-group} gives.
11338 group-buffer = *active-line / *group-status
11342 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
11344 A Gnus group info (@pxref{Group Info}) is handed to the backend for
11345 alterations. This comes in handy if the backend really carries all the
11346 information (as is the case with virtual an imap groups). This function
11347 may alter the info in any manner it sees fit, and should return the
11348 (altered) group info. This function may alter the group info
11349 destructively, so no copying is needed before boogeying.
11351 There should be no result data from this function.
11354 @item (nnchoke-request-type GROUP &optional ARTICLE)
11356 When the user issues commands for ``sending news'' (@kbd{F} in the summary
11357 buffer, for instance), Gnus has to know whether the article the user is
11358 following up is news or mail. This function should return @code{news}
11359 if @var{article} in @var{group} is news, @code{mail} if it is mail and
11360 @code{unknown} if the type can't be decided. (The @var{article}
11361 parameter is necessary in @code{nnvirtual} groups which might very well
11362 combine mail groups and news groups.)
11364 There should be no result data from this function.
11367 @item (nnchoke-request-update-mark GROUP ARTICLE MARK)
11369 If the user tries to set a mark that the backend doesn't like, this
11370 function may change the mark. Gnus will use whatever this function
11371 returns as the mark for @var{article} instead of the original
11372 @var{mark}. If the backend doesn't care, it must return the original
11373 @var{mark}, and not @code{nil} or any other type of garbage.
11375 The only use for this that I can see is what @code{nnvirtual} does with
11376 it---if a component group is auto-expirable, marking an article as read
11377 in the virtual group should result in the article being marked as
11380 There should be no result data from this function.
11383 @item (nnchoke-request-scan &optional GROUP SERVER)
11385 This function may be called at any time (by Gnus or anything else) to
11386 request that the backend check for incoming articles, in one way or
11387 another. A mail backend will typically read the spool file or query the
11388 POP server when this function is invoked. The @var{group} doesn't have
11389 to be heeded---if the backend decides that it is too much work just
11390 scanning for a single group, it may do a total scan of all groups. It
11391 would be nice, however, to keep things local if that's practical.
11393 There should be no result data from this function.
11396 @item (nnchoke-request-asynchronous GROUP &optional SERVER ARTICLES)
11398 This is a request to fetch articles asynchronously later.
11399 @var{articles} is an alist of @var{(article-number line-number)}. One
11400 would generally expect that if one later fetches article number 4, for
11401 instance, some sort of asynchronous fetching of the articles after 4
11402 (which might be 5, 6, 7 or 11, 3, 909 depending on the order in that
11403 alist) would be fetched asynchronouly, but that is left up to the
11404 backend. Gnus doesn't care.
11406 There should be no result data from this function.
11409 @item (nnchoke-request-group-description GROUP &optional SERVER)
11411 The result data from this function should be a description of
11415 description-line = name <TAB> description eol
11417 description = <text>
11420 @item (nnchoke-request-list-newsgroups &optional SERVER)
11422 The result data from this function should be the description of all
11423 groups available on the server.
11426 description-buffer = *description-line
11430 @item (nnchoke-request-newgroups DATE &optional SERVER)
11432 The result data from this function should be all groups that were
11433 created after @samp{date}, which is in normal human-readable date
11434 format. The data should be in the active buffer format.
11437 @item (nnchoke-request-create-groups GROUP &optional SERVER)
11439 This function should create an empty group with name @var{group}.
11441 There should be no return data.
11444 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
11446 This function should run the expiry process on all articles in the
11447 @var{articles} range (which is currently a simple list of article
11448 numbers.) It is left up to the backend to decide how old articles
11449 should be before they are removed by this function. If @var{force} is
11450 non-@code{nil}, all @var{articles} should be deleted, no matter how new
11453 This function should return a list of articles that it did not/was not
11456 There should be no result data returned.
11459 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
11462 This function should move @var{article} (which is a number) from
11463 @var{group} by calling @var{accept-form}.
11465 This function should ready the article in question for moving by
11466 removing any header lines it has added to the article, and generally
11467 should ``tidy up'' the article. Then it should @code{eval}
11468 @var{accept-form} in the buffer where the ``tidy'' article is. This will
11469 do the actual copying. If this @code{eval} returns a non-@code{nil}
11470 value, the article should be removed.
11472 If @var{last} is @code{nil}, that means that there is a high likelihood
11473 that there will be more requests issued shortly, so that allows some
11476 There should be no data returned.
11479 @item (nnchoke-request-accept-article GROUP &optional LAST)
11481 This function takes the current buffer and inserts it into @var{group}.
11482 If @var{last} in @code{nil}, that means that there will be more calls to
11483 this function in short order.
11485 There should be no data returned.
11488 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
11490 This function should remove @var{article} (which is a number) from
11491 @var{group} and insert @var{buffer} there instead.
11493 There should be no data returned.
11496 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
11498 This function should delete @var{group}. If @var{force}, it should
11499 really delete all the articles in the group, and then delete the group
11500 itself. (If there is such a thing as ``the group itself''.)
11502 There should be no data returned.
11505 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
11507 This function should rename @var{group} into @var{new-name}. All
11508 articles that are in @var{group} should move to @var{new-name}.
11510 There should be no data returned.
11516 @node Score File Syntax
11517 @subsection Score File Syntax
11519 Score files are meant to be easily parsable, but yet extremely
11520 mallable. It was decided that something that had the same read syntax
11521 as an Emacs Lisp list would fit that spec.
11523 Here's a typical score file:
11527 ("win95" -10000 nil s)
11534 BNF definition of a score file:
11537 score-file = "" / "(" *element ")"
11538 element = rule / atom
11539 rule = string-rule / number-rule / date-rule
11540 string-rule = "(" quote string-header quote space *string-match ")"
11541 number-rule = "(" quote number-header quote space *number-match ")"
11542 date-rule = "(" quote date-header quote space *date-match ")"
11544 string-header = "subject" / "from" / "references" / "message-id" /
11545 "xref" / "body" / "head" / "all" / "followup"
11546 number-header = "lines" / "chars"
11547 date-header = "date"
11548 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
11549 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
11550 score = "nil" / <integer>
11551 date = "nil" / <natural number>
11552 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
11553 "r" / "regex" / "R" / "Regex" /
11554 "e" / "exact" / "E" / "Exact" /
11555 "f" / "fuzzy" / "F" / "Fuzzy"
11556 number-match = "(" <integer> [ "" / [ space score [ "" /
11557 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
11558 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
11559 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
11560 space date [ "" / [ space date-match-t ] ] ] ] ")"
11561 date-match-t = "nil" / "at" / "before" / "after"
11562 atom = "(" [ required-atom / optional-atom ] ")"
11563 required-atom = mark / expunge / mark-and-expunge / files /
11564 exclude-files / read-only / touched
11565 optional-atom = adapt / local / eval
11566 mark = "mark" space nil-or-number
11567 nil-or-number = "nil" / <integer>
11568 expunge = "expunge" space nil-or-number
11569 mark-and-expunge = "mark-and-expunge" space nil-or-number
11570 files = "files" *[ space <string> ]
11571 exclude-files = "exclude-files" *[ space <string> ]
11572 read-only = "read-only" [ space "nil" / space "t" ]
11573 adapt = "adapt" [ space "nil" / space "t" / space adapt-rule ]
11574 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
11575 local = "local" *[ space "(" <string> space <form> ")" ]
11576 eval = "eval" space <form>
11577 space = *[ " " / <TAB> / <NEWLINE> ]
11580 Any unrecognized elements in a score file should be ignored, but not
11583 As you can see, white space is needed, but the type and amount of white
11584 space is irrelevant. This means that formatting of the score file is
11585 left up to the programmer---if it's simpler to just spew it all out on
11586 one looong line, then that's ok.
11588 The meaning of the various atoms are explained elsewhere in this
11593 @subsection Headers
11595 Gnus uses internally a format for storing article headers that
11596 corresponds to the @sc{nov} format in a mysterious fashion. One could
11597 almost suspect that the author looked at the @sc{nov} specification and
11598 just shamelessly @emph{stole} the entire thing, and one would be right.
11600 @dfn{Header} is a severly overloaded term. ``Header'' is used in RFC1036
11601 to talk about lines in the head of an article (eg., @code{From}). It is
11602 used by many people as a synonym for ``head''---``the header and the
11603 body''. (That should be avoided, in my opinion.) And Gnus uses a format
11604 interanally that it calls ``header'', which is what I'm talking about
11605 here. This is a 9-element vector, basically, with each header (ouch)
11608 These slots are, in order: @code{number}, @code{subject}, @code{from},
11609 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
11610 @code{xref}. There are macros for accessing and setting these slots --
11611 they all have predicatable names beginning with @code{mail-header-} and
11612 @code{mail-header-set-}, respectively.
11614 The @code{xref} slot is really a @code{misc} slot. Any extra info will
11621 @sc{gnus} introduced a concept that I found so useful that I've started
11622 using it a lot and have elaborated on it greatly.
11624 The question is simple: If you have a large amount of objects that are
11625 identified by numbers (say, articles, to take a @emph{wild} example)
11626 that you want to callify as being ``included'', a normal sequence isn't
11627 very useful. (A 200,000 length sequence is a bit long-winded.)
11629 The solution is as simple as the question: You just collapse the
11633 (1 2 3 4 5 6 10 11 12)
11636 is transformed into
11639 ((1 . 6) (10 . 12))
11642 To avoid having those nasty @samp{(13 . 13)} elements to denote a
11643 lonesome object, a @samp{13} is a valid element:
11646 ((1 . 6) 7 (10 . 12))
11649 This means that comparing two ranges to find out whether they are equal
11650 is slightly tricky:
11653 ((1 . 5) 7 8 (10 . 12))
11659 ((1 . 5) (7 . 8) (10 . 12))
11662 are equal. In fact, any non-descending list is a range:
11668 is a perfectly valid range, although a pretty longwinded one. This is
11675 and is equal to the previous range.
11677 Here's a BNF definition of ranges. Of course, one must remember the
11678 semantic requirement that the numbers are non-descending. (Any number
11679 of repetition of the same number is allowed, but apt to disappear in
11683 range = simple-range / normal-range
11684 simple-range = "(" number " . " number ")"
11685 normal-range = "(" start-contents ")"
11686 contents = "" / simple-range *[ " " contents ] /
11687 number *[ " " contents ]
11690 Gnus currently uses ranges to keep track of read articles and article
11691 marks. I plan on implementing a number of range operators in C if The
11692 Powers That Be are willing to let me. (I haven't asked yet, because I
11693 need to do some more thinking on what operators I need to make life
11694 totally range-based without ever having to convert back to normal
11699 @subsection Group Info
11701 Gnus stores all permanent info on groups in a @dfn{group info} list.
11702 This list is from three to six elements (or more) long and exhaustively
11703 describes the group.
11705 Here are two example group infos; one is a very simple group while the
11706 second is a more complex one:
11709 ("no.group" 5 (1 . 54324))
11711 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
11712 ((tick (15 . 19)) (replied 3 6 (19 . 3)))
11714 (auto-expire (to-address "ding@@ifi.uio.no")))
11717 The first element is the group name as Gnus knows the group; the second
11718 is the group level; the third is the read articles in range format; the
11719 fourth is a list of article marks lists; the fifth is the select method;
11720 and the sixth contains the group parameters.
11722 Here's a BNF definition of the group info format:
11725 info = "(" group space level space read
11726 [ "" / [ space marks-list [ "" / [ space method [ "" /
11727 space parameters ] ] ] ] ] ")"
11728 group = quote <string> quote
11729 level = <integer in the range of 1 to inf>
11731 marks-lists = nil / "(" *marks ")"
11732 marks = "(" <string> range ")"
11733 method = "(" <string> *elisp-forms ")"
11734 parameters = "(" *elisp-forms ")"
11737 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
11738 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
11742 @node Various File Formats
11743 @subsection Various File Formats
11746 * Active File Format:: Information on articles and groups available.
11747 * Newsgroups File Format:: Group descriptions.
11751 @node Active File Format
11752 @subsubsection Active File Format
11754 The active file lists all groups that are available on the server in
11755 question. It also lists the highest and lowest current article numbers
11758 Here's an exceprt from a typical active file:
11761 soc.motss 296030 293865 y
11762 alt.binaries.pictures.fractals 3922 3913 n
11763 comp.sources.unix 1605 1593 m
11764 comp.binaries.ibm.pc 5097 5089 y
11765 no.general 1000 900 y
11768 Here's a pseudo-BNF definition of this file:
11771 active = *group-line
11772 group-line = group space high-number space low-number space flag <NEWLINE>
11773 group = <non-white-space string>
11775 high-number = <non-negative integer>
11776 low-number = <positive integer>
11777 flag = "y" / "n" / "m" / "j" / "x" / "=" group
11781 @node Newsgroups File Format
11782 @subsubsection Newsgroups File Format
11784 The newsgroups file lists groups along with their descriptions. Not all
11785 groups on the server have to be listed, and not all groups in the file
11786 have to exist on the server. The file is meant purely as information to
11789 The format is quite simple; a group name, a tab, and the description.
11790 Here's the definition:
11794 line = group tab description <NEWLINE>
11795 group = <non-white-space string>
11797 description = <string>
11801 @node Emacs for Heathens
11802 @section Emacs for Heathens
11804 Believe it or not, but some people who use Gnus haven't really used
11805 Emacs much before they embarked on their journey on the Gnus Love Boat.
11806 If you are one of those unfortunates whom ``@kbd{M-C-a}'', ``kill the
11807 region'', and ``set @code{gnus-flargblossen} to an alist where the key is
11808 a regexp that is used for matching on the group name'' are magical
11809 phrases with little or no meaning, then this appendix is for you. If
11810 you are already familiar with Emacs, just ignore this and go fondle your
11814 * Keystrokes:: Entering text and executing commands.
11815 * Emacs Lisp:: The built-in Emacs programming language.
11820 @subsection Keystrokes
11824 Q: What is an experienced Emacs user?
11827 A: A person who wishes that the terminal had pedals.
11830 Yes, when you use Emacs, you are apt to use the control key, the shift
11831 key and the meta key a lot. This is very annoying to some people
11832 (notably @code{vi}le users), and the rest of us just love the hell out
11833 of it. Just give up and submit. Emacs really does stand for
11834 ``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you may
11835 have heard from other disreputable sources (like the Emacs author).
11837 The shift key is normally located near your pinky fingers, and are
11838 normally used to get capital letters and stuff. You probably use it all
11839 the time. The control key is normally marked ``CTRL'' or something like
11840 that. The meta key is, funnily enough, never marked as such on any
11841 keyboards. The one I'm curretly at has a key that's marked ``Alt'', which
11842 is the meta key on this keyboard. It's usually located somewhere to the
11843 left hand side of the keyboard, usually on the bottom row.
11845 Now, us Emacs people doesn't say ``press the meta-control-m key'', because
11846 that's just too inconvenient. We say ``press the @kbd{M-C-m} key''.
11847 @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the prefix that
11848 means ``control''. So ``press @kbd{C-k}'' means ``press down the control
11849 key, and hold it down while you press @kbd{k}''. ``Press @kbd{M-C-k}''
11850 means ``press down and hold down the meta key and the control key and
11851 then press @kbd{k}''. Simple, ay?
11853 This is somewhat complicated by the fact that not all keyboards have a
11854 meta key. In that case you can use the ``escape'' key. Then @kbd{M-k}
11855 means ``press escape, release escape, press @kbd{k}''. That's much more
11856 work than if you have a meta key, so if that's the case, I respectfully
11857 suggest you get a real keyboard with a meta key. You can't live without
11863 @subsection Emacs Lisp
11865 Emacs is the King of Editors because it's really a Lisp interpreter.
11866 Each and every key you tap runs some Emacs Lisp code snippet, and since
11867 Emacs Lisp is an interpreted language, that means that you can configure
11868 any key to run any random code. You just, like, do it.
11870 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
11871 functions. (These are byte-compiled for speed, but it's still
11872 interpreted.) If you decide that you don't like the way Gnus does
11873 certain things, it's trivial to have it do something a different way.
11874 (Well, at least if you know how to write Lisp code.) However, that's
11875 beyond the scope of this manual, so we are simply going to talk about
11876 some common constructs that you normally use in your @file{.emacs} file
11879 If you want to set the variable @code{gnus-florgbnize} to four (4), you
11880 write the following:
11883 (setq gnus-florgbnize 4)
11886 This function (really ``special form'') @code{setq} is the one that can
11887 set a variable to some value. This is really all you need to know. Now
11888 you can go and fill your @code{.emacs} file with lots of these to change
11891 If you have put that thing in your @code{.emacs} file, it will be read
11892 and @code{eval}ed (which is lispese for ``run'') the next time you start
11893 Emacs. If you want to change the variable right away, simply say
11894 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
11895 previous ``form'', which here is a simple @code{setq} statement.
11897 Go ahead---just try it, if you're located at your Emacs. After you
11898 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
11899 is the return value of the form you @code{eval}ed.
11903 If the manual says ``set @code{gnus-read-active-file} to @code{some}'',
11907 (setq gnus-read-active-file 'some)
11910 On the other hand, if the manual says ``set @code{gnus-nntp-server} to
11911 @samp{"nntp.ifi.uio.no"}'', that means:
11914 (setq gnus-nntp-server "nntp.ifi.uio.no")
11917 So be careful not to mix up strings (the latter) with symbols (the
11918 former). The manual is unambiguous, but it can be confusing.
11921 @include gnus-faq.texi