1 \input texinfo @c -*-texinfo-*-
4 @settitle Gnus 5.6.3 Manual
9 @c * Gnus: (gnus). The news reader Gnus.
14 @setchapternewpage odd
18 \documentclass[twoside,a4paper,openright,11pt]{book}
19 \usepackage[latin1]{inputenc}
20 \usepackage{pagestyle}
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]{{\fontfamily{pfu}\fontsize{10pt}{10}\selectfont #1}}
40 \newcommand{\gnuscode}[1]{\gnustt{#1}}
41 \newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\fontfamily{pfu}\fontsize{10pt}{10}\selectfont #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]{{\fontsize{10pt}{10}\selectfont\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}{\symbol{"5E}}
60 \newcommand{\gnusunderline}{\symbol{"5F}}
61 \newcommand{\gnusnot}{$\neg$}
62 \newcommand{\gnustilde}{\symbol{"7E}}
63 \newcommand{\gnusless}{{$<$}}
64 \newcommand{\gnusgreater}{{$>$}}
66 \newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=ps/gnus-head.eps,height=1cm}}}
67 \newcommand{\gnusinteresting}{
68 \marginpar[\mbox{}\hfill\gnushead]{\gnushead}
71 \newcommand{\gnuscleardoublepage}{\ifodd\count0\mbox{}\clearpage\thispagestyle{empty}\mbox{}\clearpage\else\clearpage\fi}
73 \newcommand{\gnuspagechapter}[1]{
80 \newcommand{\gnuschapter}[2]{
82 \ifdim \gnusdimen = 0pt\setcounter{page}{1}\pagestyle{gnus}\pagenumbering{arabic} \gnusdimen 1pt\fi
84 \renewcommand{\gnussectionname}{}
85 \renewcommand{\gnuschaptername}{#2}
88 \begin{picture}(500,500)(0,0)
89 \put(480,350){\makebox(0,0)[tr]{#1}}
90 \put(40,300){\makebox(500,50)[bl]{{\Huge\bf{#2}}}}
95 \newcommand{\gnusfigure}[3]{
97 \mbox{}\ifodd\count0\hspace*{-0.8cm}\else\hspace*{-3cm}\fi\begin{picture}(440,#2)
104 \newcommand{\gnusicon}[1]{
105 \marginpar[\mbox{}\hfill\raisebox{-1.5cm}{\epsfig{figure=tmp/#1-up.ps,height=1.5cm}}]{\raisebox{-1cm}{\epsfig{figure=tmp/#1-up.ps,height=1cm}}}
108 \newcommand{\gnuspicon}[1]{
109 \margindex{\epsfig{figure=#1,width=2cm}}
112 \newcommand{\gnusxface}[2]{
113 \margindex{\epsfig{figure=#1,width=1cm}\epsfig{figure=#2,width=1cm}}
116 \newcommand{\gnussmiley}[2]{
117 \margindex{\makebox[2cm]{\hfill\epsfig{figure=#1,width=0.5cm}\hfill\epsfig{figure=#2,width=0.5cm}\hfill}}
120 \newcommand{\gnusitemx}[1]{\mbox{}\vspace*{-\itemsep}\vspace*{-\parsep}\item#1}
122 \newcommand{\gnussection}[1]{
123 \renewcommand{\gnussectionname}{#1}
127 \newenvironment{codelist}%
132 \newenvironment{kbdlist}%
138 \newenvironment{dfnlist}%
143 \newenvironment{stronglist}%
148 \newenvironment{samplist}%
153 \newenvironment{varlist}%
158 \newenvironment{emphlist}%
163 \newlength\gnusheadtextwidth
164 \setlength{\gnusheadtextwidth}{\headtextwidth}
165 \addtolength{\gnusheadtextwidth}{1cm}
167 \newpagestyle{gnuspreamble}%
172 \hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\mbox{}}\textbf{\hfill\roman{page}}}
176 \hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\roman{page}\hfill\mbox{}}}
185 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
187 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
192 \newpagestyle{gnusindex}%
197 \hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\gnuschaptername\hfill\arabic{page}}}}
201 \hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}
209 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
211 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
221 \makebox[12cm]{\hspace*{3.1cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{chapter}.\arabic{section}} \textbf{\gnussectionname\hfill\arabic{page}}}}}
225 \makebox[12cm]{\hspace*{-2.95cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}}
233 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
235 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
240 \pagenumbering{roman}
241 \pagestyle{gnuspreamble}
251 %\addtolength{\oddsidemargin}{-5cm}
252 %\addtolength{\evensidemargin}{-5cm}
254 \addtolength{\textheight}{2cm}
256 \gnustitle{\gnustitlename}\\
259 \hspace*{0cm}\epsfig{figure=ps/gnus-big-logo.eps,height=15cm}
262 \gnusauthor{by Lars Magne Ingebrigtsen}
269 \thispagestyle{empty}
271 Copyright \copyright{} 1995,96,97 Free Software Foundation, Inc.
273 Permission is granted to make and distribute verbatim copies of
274 this manual provided the copyright notice and this permission notice
275 are preserved on all copies.
277 Permission is granted to copy and distribute modified versions of this
278 manual under the conditions for verbatim copying, provided that the
279 entire resulting derived work is distributed under the terms of a
280 permission notice identical to this one.
282 Permission is granted to copy and distribute translations of this manual
283 into another language, under the above conditions for modified versions.
292 This file documents Gnus, the GNU Emacs newsreader.
294 Copyright (C) 1995,96 Free Software Foundation, Inc.
296 Permission is granted to make and distribute verbatim copies of
297 this manual provided the copyright notice and this permission notice
298 are preserved on all copies.
301 Permission is granted to process this file through Tex and print the
302 results, provided the printed document carries copying permission
303 notice identical to this one except for the removal of this paragraph
304 (this paragraph not being relevant to the printed manual).
307 Permission is granted to copy and distribute modified versions of this
308 manual under the conditions for verbatim copying, provided also that the
309 entire resulting derived work is distributed under the terms of a
310 permission notice identical to this one.
312 Permission is granted to copy and distribute translations of this manual
313 into another language, under the above conditions for modified versions.
319 @title Gnus 5.6.3 Manual
321 @author by Lars Magne Ingebrigtsen
324 @vskip 0pt plus 1filll
325 Copyright @copyright{} 1995,96,97 Free Software Foundation, Inc.
327 Permission is granted to make and distribute verbatim copies of
328 this manual provided the copyright notice and this permission notice
329 are preserved on all copies.
331 Permission is granted to copy and distribute modified versions of this
332 manual under the conditions for verbatim copying, provided that the
333 entire resulting derived work is distributed under the terms of a
334 permission notice identical to this one.
336 Permission is granted to copy and distribute translations of this manual
337 into another language, under the above conditions for modified versions.
346 @top The Gnus Newsreader
350 You can read news (and mail) from within Emacs by using Gnus. The news
351 can be gotten by any nefarious means you can think of---@sc{nntp}, local
352 spool or your mbox file. All at the same time, if you want to push your
355 This manual corresponds to Gnus 5.6.3.
366 Gnus is the advanced, self-documenting, customizable, extensible
367 unreal-time newsreader for GNU Emacs.
369 Oops. That sounds oddly familiar, so let's start over again to avoid
370 being accused of plagiarism:
372 Gnus is a message-reading laboratory. It will let you look at just
373 about anything as if it were a newsgroup. You can read mail with it,
374 you can browse directories with it, you can @code{ftp} with it---you can
375 even read news with it!
377 Gnus tries to empower people who read news the same way Emacs empowers
378 people who edit text. Gnus sets no limits to what the user should be
379 allowed to do. Users are encouraged to extend Gnus to make it behave
380 like they want it to behave. A program should not control people;
381 people should be empowered to do what they want by using (or abusing)
388 * Starting Up:: Finding news can be a pain.
389 * The Group Buffer:: Selecting, subscribing and killing groups.
390 * The Summary Buffer:: Reading, saving and posting articles.
391 * The Article Buffer:: Displaying and handling articles.
392 * Composing Messages:: Information on sending mail and news.
393 * Select Methods:: Gnus reads all messages from various select methods.
394 * Scoring:: Assigning values to articles.
395 * Various:: General purpose settings.
396 * The End:: Farewell and goodbye.
397 * Appendices:: Terminology, Emacs intro, FAQ, History, Internals.
398 * Index:: Variable, function and concept index.
399 * Key Index:: Key Index.
403 @chapter Starting Gnus
408 If your system administrator has set things up properly, starting Gnus
409 and reading news is extremely easy---you just type @kbd{M-x gnus} in
412 @findex gnus-other-frame
413 @kindex M-x gnus-other-frame
414 If you want to start Gnus in a different frame, you can use the command
415 @kbd{M-x gnus-other-frame} instead.
417 If things do not go smoothly at startup, you have to twiddle some
418 variables in your @file{~/.gnus} file. This file is similar to
419 @file{~/.emacs}, but is read when gnus starts.
421 If you puzzle at any terms used in this manual, please refer to the
422 terminology section (@pxref{Terminology}).
425 * Finding the News:: Choosing a method for getting news.
426 * The First Time:: What does Gnus do the first time you start it?
427 * The Server is Down:: How can I read my mail then?
428 * Slave Gnusae:: You can have more than one Gnus active at a time.
429 * Fetching a Group:: Starting Gnus just to read a group.
430 * New Groups:: What is Gnus supposed to do with new groups?
431 * Startup Files:: Those pesky startup files---@file{.newsrc}.
432 * Auto Save:: Recovering from a crash.
433 * The Active File:: Reading the active file over a slow line Takes Time.
434 * Changing Servers:: You may want to move from one server to another.
435 * Startup Variables:: Other variables you might change.
439 @node Finding the News
440 @section Finding the News
443 @vindex gnus-select-method
445 The @code{gnus-select-method} variable says where Gnus should look for
446 news. This variable should be a list where the first element says
447 @dfn{how} and the second element says @dfn{where}. This method is your
448 native method. All groups not fetched with this method are
451 For instance, if the @samp{news.somewhere.edu} @sc{nntp} server is where
452 you want to get your daily dosage of news from, you'd say:
455 (setq gnus-select-method '(nntp "news.somewhere.edu"))
458 If you want to read directly from the local spool, say:
461 (setq gnus-select-method '(nnspool ""))
464 If you can use a local spool, you probably should, as it will almost
465 certainly be much faster.
467 @vindex gnus-nntpserver-file
469 @cindex @sc{nntp} server
470 If this variable is not set, Gnus will take a look at the
471 @code{NNTPSERVER} environment variable. If that variable isn't set,
472 Gnus will see whether @code{gnus-nntpserver-file}
473 (@file{/etc/nntpserver} by default) has any opinions on the matter. If
474 that fails as well, Gnus will try to use the machine running Emacs as an @sc{nntp} server. That's a long shot, though.
476 @vindex gnus-nntp-server
477 If @code{gnus-nntp-server} is set, this variable will override
478 @code{gnus-select-method}. You should therefore set
479 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
481 @vindex gnus-secondary-servers
482 You can also make Gnus prompt you interactively for the name of an
483 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
484 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
485 in the @code{gnus-secondary-servers} list (if any). You can also just
486 type in the name of any server you feel like visiting.
488 @findex gnus-group-browse-foreign-server
490 However, if you use one @sc{nntp} server regularly and are just
491 interested in a couple of groups from a different server, you would be
492 better served by using the @kbd{B} command in the group buffer. It will
493 let you have a look at what groups are available, and you can subscribe
494 to any of the groups you want to. This also makes @file{.newsrc}
495 maintenance much tidier. @xref{Foreign Groups}.
497 @vindex gnus-secondary-select-methods
499 A slightly different approach to foreign groups is to set the
500 @code{gnus-secondary-select-methods} variable. The select methods
501 listed in this variable are in many ways just as native as the
502 @code{gnus-select-method} server. They will also be queried for active
503 files during startup (if that's required), and new newsgroups that
504 appear on these servers will be subscribed (or not) just as native
507 For instance, if you use the @code{nnmbox} backend to read your mail, you
508 would typically set this variable to
511 (setq gnus-secondary-select-methods '((nnmbox "")))
516 @section The First Time
517 @cindex first time usage
519 If no startup files exist, Gnus will try to determine what groups should
520 be subscribed by default.
522 @vindex gnus-default-subscribed-newsgroups
523 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
524 will subscribe you to just those groups in that list, leaving the rest
525 killed. Your system administrator should have set this variable to
528 Since she hasn't, Gnus will just subscribe you to a few arbitrarily
529 picked groups (i.e., @samp{*.newusers}). (@dfn{Arbitrary} is defined
530 here as @dfn{whatever Lars thinks you should read}.)
532 You'll also be subscribed to the Gnus documentation group, which should
533 help you with most common problems.
535 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
536 use the normal functions for handling new groups, and not do anything
540 @node The Server is Down
541 @section The Server is Down
542 @cindex server errors
544 If the default server is down, Gnus will understandably have some
545 problems starting. However, if you have some mail groups in addition to
546 the news groups, you may want to start Gnus anyway.
548 Gnus, being the trusting sort of program, will ask whether to proceed
549 without a native select method if that server can't be contacted. This
550 will happen whether the server doesn't actually exist (i.e., you have
551 given the wrong address) or the server has just momentarily taken ill
552 for some reason or other. If you decide to continue and have no foreign
553 groups, you'll find it difficult to actually do anything in the group
554 buffer. But, hey, that's your problem. Blllrph!
556 @findex gnus-no-server
557 @kindex M-x gnus-no-server
559 If you know that the server is definitely down, or you just want to read
560 your mail without bothering with the server at all, you can use the
561 @code{gnus-no-server} command to start Gnus. That might come in handy
562 if you're in a hurry as well. This command will not attempt to contact
563 your primary server---instead, it will just activate all groups on level
564 1 and 2. (You should preferably keep no native groups on those two
569 @section Slave Gnusae
572 You might want to run more than one Emacs with more than one Gnus at the
573 same time. If you are using different @file{.newsrc} files (e.g., if you
574 are using the two different Gnusae to read from two different servers),
575 that is no problem whatsoever. You just do it.
577 The problem appears when you want to run two Gnusae that use the same
580 To work around that problem some, we here at the Think-Tank at the Gnus
581 Towers have come up with a new concept: @dfn{Masters} and
582 @dfn{slaves}. (We have applied for a patent on this concept, and have
583 taken out a copyright on those words. If you wish to use those words in
584 conjunction with each other, you have to send $1 per usage instance to
585 me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
586 Applications}) will be much more expensive, of course.)
588 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
589 however you do it). Each subsequent slave Gnusae should be started with
590 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
591 files, but instead save @dfn{slave files} that contain information only
592 on what groups have been read in the slave session. When a master Gnus
593 starts, it will read (and delete) these slave files, incorporating all
594 information from them. (The slave files will be read in the sequence
595 they were created, so the latest changes will have precedence.)
597 Information from the slave files has, of course, precedence over the
598 information in the normal (i.e., master) @code{.newsrc} file.
601 @node Fetching a Group
602 @section Fetching a Group
603 @cindex fetching a group
605 @findex gnus-fetch-group
606 It is sometimes convenient to be able to just say ``I want to read this
607 group and I don't care whether Gnus has been started or not''. This is
608 perhaps more useful for people who write code than for users, but the
609 command @code{gnus-fetch-group} provides this functionality in any case.
610 It takes the group name as a parameter.
618 @vindex gnus-check-new-newsgroups
619 If you are satisfied that you really never want to see any new groups,
620 you can set @code{gnus-check-new-newsgroups} to @code{nil}. This will
621 also save you some time at startup. Even if this variable is
622 @code{nil}, you can always subscribe to the new groups just by pressing
623 @kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
624 is @code{ask-server} by default. If you set this variable to
625 @code{always}, then Gnus will query the backends for new groups even
626 when you do the @kbd{g} command (@pxref{Scanning New Messages}).
629 * Checking New Groups:: Determining what groups are new.
630 * Subscription Methods:: What Gnus should do with new groups.
631 * Filtering New Groups:: Making Gnus ignore certain new groups.
635 @node Checking New Groups
636 @subsection Checking New Groups
638 Gnus normally determines whether a group is new or not by comparing the
639 list of groups from the active file(s) with the lists of subscribed and
640 dead groups. This isn't a particularly fast method. If
641 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
642 server for new groups since the last time. This is both faster and
643 cheaper. This also means that you can get rid of the list of killed
644 groups altogether, so you may set @code{gnus-save-killed-list} to
645 @code{nil}, which will save time both at startup, at exit, and all over.
646 Saves disk space, too. Why isn't this the default, then?
647 Unfortunately, not all servers support this command.
649 I bet I know what you're thinking now: How do I find out whether my
650 server supports @code{ask-server}? No? Good, because I don't have a
651 fail-safe answer. I would suggest just setting this variable to
652 @code{ask-server} and see whether any new groups appear within the next
653 few days. If any do, then it works. If none do, then it doesn't
654 work. I could write a function to make Gnus guess whether the server
655 supports @code{ask-server}, but it would just be a guess. So I won't.
656 You could @code{telnet} to the server and say @code{HELP} and see
657 whether it lists @samp{NEWGROUPS} among the commands it understands. If
658 it does, then it might work. (But there are servers that lists
659 @samp{NEWGROUPS} without supporting the function properly.)
661 This variable can also be a list of select methods. If so, Gnus will
662 issue an @code{ask-server} command to each of the select methods, and
663 subscribe them (or not) using the normal methods. This might be handy
664 if you are monitoring a few servers for new groups. A side effect is
665 that startup will take much longer, so you can meditate while waiting.
666 Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss.
669 @node Subscription Methods
670 @subsection Subscription Methods
672 @vindex gnus-subscribe-newsgroup-method
673 What Gnus does when it encounters a new group is determined by the
674 @code{gnus-subscribe-newsgroup-method} variable.
676 This variable should contain a function. This function will be called
677 with the name of the new group as the only parameter.
679 Some handy pre-fab functions are:
683 @item gnus-subscribe-zombies
684 @vindex gnus-subscribe-zombies
685 Make all new groups zombies. This is the default. You can browse the
686 zombies later (with @kbd{A z}) and either kill them all off properly
687 (with @kbd{S z}), or subscribe to them (with @kbd{u}).
689 @item gnus-subscribe-randomly
690 @vindex gnus-subscribe-randomly
691 Subscribe all new groups in arbitrary order. This really means that all
692 new groups will be added at ``the top'' of the group buffer.
694 @item gnus-subscribe-alphabetically
695 @vindex gnus-subscribe-alphabetically
696 Subscribe all new groups in alphabetical order.
698 @item gnus-subscribe-hierarchically
699 @vindex gnus-subscribe-hierarchically
700 Subscribe all new groups hierarchically. The difference between this
701 function and @code{gnus-subscribe-alphabetically} is slight.
702 @code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly
703 alphabetical fashion, while this function will enter groups into it's
704 hierarchy. So if you want to have the @samp{rec} hierarchy before the
705 @samp{comp} hierarchy, this function will not mess that configuration
706 up. Or something like that.
708 @item gnus-subscribe-interactively
709 @vindex gnus-subscribe-interactively
710 Subscribe new groups interactively. This means that Gnus will ask
711 you about @strong{all} new groups. The groups you choose to subscribe
712 to will be subscribed hierarchically.
714 @item gnus-subscribe-killed
715 @vindex gnus-subscribe-killed
720 @vindex gnus-subscribe-hierarchical-interactive
721 A closely related variable is
722 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
723 mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
724 hierarchical fashion whether to subscribe to new groups or not. Gnus
725 will ask you for each sub-hierarchy whether you want to descend the
728 One common mistake is to set the variable a few paragraphs above
729 (@code{gnus-subscribe-newsgroup-method}) to
730 @code{gnus-subscribe-hierarchical-interactive}. This is an error. This
731 will not work. This is ga-ga. So don't do it.
734 @node Filtering New Groups
735 @subsection Filtering New Groups
737 A nice and portable way to control which new newsgroups should be
738 subscribed (or ignored) is to put an @dfn{options} line at the start of
739 the @file{.newsrc} file. Here's an example:
742 options -n !alt.all !rec.all sci.all
745 @vindex gnus-subscribe-options-newsgroup-method
746 This line obviously belongs to a serious-minded intellectual scientific
747 person (or she may just be plain old boring), because it says that all
748 groups that have names beginning with @samp{alt} and @samp{rec} should
749 be ignored, and all groups with names beginning with @samp{sci} should
750 be subscribed. Gnus will not use the normal subscription method for
751 subscribing these groups.
752 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
753 variable defaults to @code{gnus-subscribe-alphabetically}.
755 @vindex gnus-options-not-subscribe
756 @vindex gnus-options-subscribe
757 If you don't want to mess with your @file{.newsrc} file, you can just
758 set the two variables @code{gnus-options-subscribe} and
759 @code{gnus-options-not-subscribe}. These two variables do exactly the
760 same as the @file{.newsrc} @samp{options -n} trick. Both are regexps,
761 and if the new group matches the former, it will be unconditionally
762 subscribed, and if it matches the latter, it will be ignored.
764 @vindex gnus-auto-subscribed-groups
765 Yet another variable that meddles here is
766 @code{gnus-auto-subscribed-groups}. It works exactly like
767 @code{gnus-options-subscribe}, and is therefore really superfluous, but I
768 thought it would be nice to have two of these. This variable is more
769 meant for setting some ground rules, while the other variable is used
770 more for user fiddling. By default this variable makes all new groups
771 that come from mail backends (@code{nnml}, @code{nnbabyl},
772 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
773 don't like that, just set this variable to @code{nil}.
775 New groups that match this regexp are subscribed using
776 @code{gnus-subscribe-options-newsgroup-method}.
779 @node Changing Servers
780 @section Changing Servers
781 @cindex changing servers
783 Sometimes it is necessary to move from one @sc{nntp} server to another.
784 This happens very rarely, but perhaps you change jobs, or one server is
785 very flaky and you want to use another.
787 Changing the server is pretty easy, right? You just change
788 @code{gnus-select-method} to point to the new server?
792 Article numbers are not (in any way) kept synchronized between different
793 @sc{nntp} servers, and the only way Gnus keeps track of what articles
794 you have read is by keeping track of article numbers. So when you
795 change @code{gnus-select-method}, your @file{.newsrc} file becomes
798 Gnus provides a few functions to attempt to translate a @file{.newsrc}
799 file from one server to another. They all have one thing in
800 common---they take a looong time to run. You don't want to use these
801 functions more than absolutely necessary.
803 @kindex M-x gnus-change-server
804 @findex gnus-change-server
805 If you have access to both servers, Gnus can request the headers for all
806 the articles you have read and compare @code{Message-ID}s and map the
807 article numbers of the read articles and article marks. The @kbd{M-x
808 gnus-change-server} command will do this for all your native groups. It
809 will prompt for the method you want to move to.
811 @kindex M-x gnus-group-move-group-to-server
812 @findex gnus-group-move-group-to-server
813 You can also move individual groups with the @kbd{M-x
814 gnus-group-move-group-to-server} command. This is useful if you want to
815 move a (foreign) group from one server to another.
817 @kindex M-x gnus-group-clear-data-on-native-groups
818 @findex gnus-group-clear-data-on-native-groups
819 If you don't have access to both the old and new server, all your marks
820 and read ranges have become worthless. You can use the @kbd{M-x
821 gnus-group-clear-data-on-native-groups} command to clear out all data
822 that you have on your native groups. Use with caution.
826 @section Startup Files
827 @cindex startup files
832 Now, you all know about the @file{.newsrc} file. All subscription
833 information is traditionally stored in this file.
835 Things got a bit more complicated with @sc{gnus}. In addition to
836 keeping the @file{.newsrc} file updated, it also used a file called
837 @file{.newsrc.el} for storing all the information that didn't fit into
838 the @file{.newsrc} file. (Actually, it also duplicated everything in
839 the @file{.newsrc} file.) @sc{gnus} would read whichever one of these
840 files was the most recently saved, which enabled people to swap between
841 @sc{gnus} and other newsreaders.
843 That was kinda silly, so Gnus went one better: In addition to the
844 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
845 @file{.newsrc.eld}. It will read whichever of these files that are most
846 recent, but it will never write a @file{.newsrc.el} file. You should
847 never delete the @file{.newsrc.eld} file---it contains much information
848 not stored in the @file{.newsrc} file.
850 @vindex gnus-save-newsrc-file
851 You can turn off writing the @file{.newsrc} file by setting
852 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
853 the file and save some space, as well as making exit from Gnus faster.
854 However, this will make it impossible to use other newsreaders than
855 Gnus. But hey, who would want to, right?
857 @vindex gnus-save-killed-list
858 If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus
859 will not save the list of killed groups to the startup file. This will
860 save both time (when starting and quitting) and space (on disk). It
861 will also mean that Gnus has no record of what groups are new or old,
862 so the automatic new groups subscription methods become meaningless.
863 You should always set @code{gnus-check-new-newsgroups} to @code{nil} or
864 @code{ask-server} if you set this variable to @code{nil} (@pxref{New
865 Groups}). This variable can also be a regular expression. If that's
866 the case, remove all groups that do not match this regexp before
867 saving. This can be useful in certain obscure situations that involve
868 several servers where not all servers support @code{ask-server}.
870 @vindex gnus-startup-file
871 The @code{gnus-startup-file} variable says where the startup files are.
872 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
873 file being whatever that one is, with a @samp{.eld} appended.
875 @vindex gnus-save-newsrc-hook
876 @vindex gnus-save-quick-newsrc-hook
877 @vindex gnus-save-standard-newsrc-hook
878 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
879 files, while @code{gnus-save-quick-newsrc-hook} is called just before
880 saving the @file{.newsrc.eld} file, and
881 @code{gnus-save-standard-newsrc-hook} is called just before saving the
882 @file{.newsrc} file. The latter two are commonly used to turn version
883 control on or off. Version control is on by default when saving the
884 startup files. If you want to turn backup creation off, say something like:
887 (defun turn-off-backup ()
888 (set (make-local-variable 'backup-inhibited) t))
890 (add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup)
891 (add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup)
894 @vindex gnus-init-file
895 When Gnus starts, it will read the @code{gnus-site-init-file}
896 (@file{.../site-lisp/gnus} by default) and @code{gnus-init-file}
897 (@file{~/.gnus} by default) files. These are normal Emacs Lisp files
898 and can be used to avoid cluttering your @file{~/.emacs} and
899 @file{site-init} files with Gnus stuff. Gnus will also check for files
900 with the same names as these, but with @file{.elc} and @file{.el}
901 suffixes. In other words, if you have set @code{gnus-init-file} to
902 @file{~/.gnus}, it will look for @file{~/.gnus.elc}, @file{~/.gnus.el},
903 and finally @file{~/.gnus} (in this order).
912 Whenever you do something that changes the Gnus data (reading articles,
913 catching up, killing/subscribing groups), the change is added to a
914 special @dfn{dribble buffer}. This buffer is auto-saved the normal
915 Emacs way. If your Emacs should crash before you have saved the
916 @file{.newsrc} files, all changes you have made can be recovered from
919 If Gnus detects this file at startup, it will ask the user whether to
920 read it. The auto save file is deleted whenever the real startup file is
923 @vindex gnus-use-dribble-file
924 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
925 maintain a dribble buffer. The default is @code{t}.
927 @vindex gnus-dribble-directory
928 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
929 this variable is @code{nil}, which it is by default, Gnus will dribble
930 into the directory where the @file{.newsrc} file is located. (This is
931 normally the user's home directory.) The dribble file will get the same
932 file permissions as the @code{.newsrc} file.
935 @node The Active File
936 @section The Active File
938 @cindex ignored groups
940 When Gnus starts, or indeed whenever it tries to determine whether new
941 articles have arrived, it reads the active file. This is a very large
942 file that lists all the active groups and articles on the server.
944 @vindex gnus-ignored-newsgroups
945 Before examining the active file, Gnus deletes all lines that match the
946 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
947 any groups with bogus names, but you can use this variable to make Gnus
948 ignore hierarchies you aren't ever interested in. However, this is not
949 recommended. In fact, it's highly discouraged. Instead, @pxref{New
950 Groups} for an overview of other variables that can be used instead.
953 @c @code{nil} by default, and will slow down active file handling somewhat
954 @c if you set it to anything else.
956 @vindex gnus-read-active-file
958 The active file can be rather Huge, so if you have a slow network, you
959 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
960 reading the active file. This variable is @code{some} by default.
962 Gnus will try to make do by getting information just on the groups that
963 you actually subscribe to.
965 Note that if you subscribe to lots and lots of groups, setting this
966 variable to @code{nil} will probably make Gnus slower, not faster. At
967 present, having this variable @code{nil} will slow Gnus down
968 considerably, unless you read news over a 2400 baud modem.
970 This variable can also have the value @code{some}. Gnus will then
971 attempt to read active info only on the subscribed groups. On some
972 servers this is quite fast (on sparkling, brand new INN servers that
973 support the @code{LIST ACTIVE group} command), on others this isn't fast
974 at all. In any case, @code{some} should be faster than @code{nil}, and
975 is certainly faster than @code{t} over slow lines.
977 If this variable is @code{nil}, Gnus will ask for group info in total
978 lock-step, which isn't very fast. If it is @code{some} and you use an
979 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
980 read all the replies in one swoop. This will normally result in better
981 performance, but if the server does not support the aforementioned
982 @code{LIST ACTIVE group} command, this isn't very nice to the server.
984 In any case, if you use @code{some} or @code{nil}, you should definitely
985 kill all groups that you aren't interested in to speed things up.
987 Note that this variable also affects active file retrieval from
988 secondary select methods.
991 @node Startup Variables
992 @section Startup Variables
997 @vindex gnus-load-hook
998 A hook run while Gnus is being loaded. Note that this hook will
999 normally be run just once in each Emacs session, no matter how many
1000 times you start Gnus.
1002 @item gnus-before-startup-hook
1003 @vindex gnus-before-startup-hook
1004 A hook run after starting up Gnus successfully.
1006 @item gnus-startup-hook
1007 @vindex gnus-startup-hook
1008 A hook run as the very last thing after starting up Gnus
1010 @item gnus-started-hook
1011 @vindex gnus-started-hook
1012 A hook that is run as the very last thing after starting up Gnus
1015 @item gnus-started-hook
1016 @vindex gnus-started-hook
1017 A hook that is run after reading the @file{.newsrc} file(s), but before
1018 generating the group buffer.
1020 @item gnus-check-bogus-newsgroups
1021 @vindex gnus-check-bogus-newsgroups
1022 If non-@code{nil}, Gnus will check for and delete all bogus groups at
1023 startup. A @dfn{bogus group} is a group that you have in your
1024 @file{.newsrc} file, but doesn't exist on the news server. Checking for
1025 bogus groups can take quite a while, so to save time and resources it's
1026 best to leave this option off, and do the checking for bogus groups once
1027 in a while from the group buffer instead (@pxref{Group Maintenance}).
1029 @item gnus-inhibit-startup-message
1030 @vindex gnus-inhibit-startup-message
1031 If non-@code{nil}, the startup message won't be displayed. That way,
1032 your boss might not notice as easily that you are reading news instead
1033 of doing your job. Note that this variable is used before
1034 @file{.gnus.el} is loaded, so it should be set in @code{.emacs} instead.
1036 @item gnus-no-groups-message
1037 @vindex gnus-no-groups-message
1038 Message displayed by Gnus when no groups are available.
1040 @item gnus-play-startup-jingle
1041 @vindex gnus-play-startup-jingle
1042 If non-@code{nil}, play the Gnus jingle at startup.
1044 @item gnus-startup-jingle
1045 @vindex gnus-startup-jingle
1046 Jingle to be played if the above variable is non-@code{nil}. The
1047 default is @samp{Tuxedomoon.Jingle4.au}.
1052 @node The Group Buffer
1053 @chapter The Group Buffer
1054 @cindex group buffer
1056 The @dfn{group buffer} lists all (or parts) of the available groups. It
1057 is the first buffer shown when Gnus starts, and will never be killed as
1058 long as Gnus is active.
1062 \gnusfigure{The Group Buffer}{320}{
1063 \put(75,50){\epsfig{figure=tmp/group.ps,height=9cm}}
1064 \put(120,37){\makebox(0,0)[t]{Buffer name}}
1065 \put(120,38){\vector(1,2){10}}
1066 \put(40,60){\makebox(0,0)[r]{Mode line}}
1067 \put(40,58){\vector(1,0){30}}
1068 \put(200,28){\makebox(0,0)[t]{Native select method}}
1069 \put(200,26){\vector(-1,2){15}}
1075 * Group Buffer Format:: Information listed and how you can change it.
1076 * Group Maneuvering:: Commands for moving in the group buffer.
1077 * Selecting a Group:: Actually reading news.
1078 * Group Data:: Changing the info for a group.
1079 * Subscription Commands:: Unsubscribing, killing, subscribing.
1080 * Group Levels:: Levels? What are those, then?
1081 * Group Score:: A mechanism for finding out what groups you like.
1082 * Marking Groups:: You can mark groups for later processing.
1083 * Foreign Groups:: Creating and editing groups.
1084 * Group Parameters:: Each group may have different parameters set.
1085 * Listing Groups:: Gnus can list various subsets of the groups.
1086 * Sorting Groups:: Re-arrange the group order.
1087 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
1088 * Browse Foreign Server:: You can browse a server. See what it has to offer.
1089 * Exiting Gnus:: Stop reading news and get some work done.
1090 * Group Topics:: A folding group mode divided into topics.
1091 * Misc Group Stuff:: Other stuff that you can to do.
1095 @node Group Buffer Format
1096 @section Group Buffer Format
1099 * Group Line Specification:: Deciding how the group buffer is to look.
1100 * Group Modeline Specification:: The group buffer modeline.
1101 * Group Highlighting:: Having nice colors in the group buffer.
1105 @node Group Line Specification
1106 @subsection Group Line Specification
1107 @cindex group buffer format
1109 The default format of the group buffer is nice and dull, but you can
1110 make it as exciting and ugly as you feel like.
1112 Here's a couple of example group lines:
1115 25: news.announce.newusers
1116 * 0: alt.fan.andrea-dworkin
1121 You can see that there are 25 unread articles in
1122 @samp{news.announce.newusers}. There are no unread articles, but some
1123 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1124 asterisk at the beginning of the line?).
1126 @vindex gnus-group-line-format
1127 You can change that format to whatever you want by fiddling with the
1128 @code{gnus-group-line-format} variable. This variable works along the
1129 lines of a @code{format} specification, which is pretty much the same as
1130 a @code{printf} specifications, for those of you who use (feh!) C.
1131 @xref{Formatting Variables}.
1133 @samp{%M%S%5y: %(%g%)\n} is the value that produced those lines above.
1135 There should always be a colon on the line; the cursor always moves to
1136 the colon after performing an operation. Nothing else is required---not
1137 even the group name. All displayed text is just window dressing, and is
1138 never examined by Gnus. Gnus stores all real information it needs using
1141 (Note that if you make a really strange, wonderful, spreadsheet-like
1142 layout, everybody will believe you are hard at work with the accounting
1143 instead of wasting time reading news.)
1145 Here's a list of all available format characters:
1150 An asterisk if the group only has marked articles.
1153 Whether the group is subscribed.
1156 Level of subscribedness.
1159 Number of unread articles.
1162 Number of dormant articles.
1165 Number of ticked articles.
1168 Number of read articles.
1171 Estimated total number of articles. (This is really @var{max-number}
1172 minus @var{min-number} plus 1.)
1175 Number of unread, unticked, non-dormant articles.
1178 Number of ticked and dormant articles.
1187 Newsgroup description.
1190 @samp{m} if moderated.
1193 @samp{(m)} if moderated.
1202 A string that looks like @samp{<%s:%n>} if a foreign select method is
1206 Indentation based on the level of the topic (@pxref{Group Topics}).
1209 @vindex gnus-group-uncollapsed-levels
1210 Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels}
1211 variable says how many levels to leave at the end of the group name.
1212 The default is 1---this will mean that group names like
1213 @samp{gnu.emacs.gnus} will be shortened to @samp{g.emacs.gnus}.
1216 @vindex gnus-new-mail-mark
1218 @samp{%} (@code{gnus-new-mail-mark}) if there has arrived new mail to
1222 A string that says when you last read the group (@pxref{Group
1226 User defined specifier. The next character in the format string should
1227 be a letter. Gnus will call the function
1228 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1229 following @samp{%u}. The function will be passed a single dummy
1230 parameter as argument. The function should return a string, which will
1231 be inserted into the buffer just like information from any other
1236 All the ``number-of'' specs will be filled with an asterisk (@samp{*})
1237 if no info is available---for instance, if it is a non-activated foreign
1238 group, or a bogus native group.
1241 @node Group Modeline Specification
1242 @subsection Group Modeline Specification
1243 @cindex group modeline
1245 @vindex gnus-group-mode-line-format
1246 The mode line can be changed by setting
1247 @code{gnus-group-mode-line-format} (@pxref{Formatting Variables}). It
1248 doesn't understand that many format specifiers:
1252 The native news server.
1254 The native select method.
1258 @node Group Highlighting
1259 @subsection Group Highlighting
1260 @cindex highlighting
1261 @cindex group highlighting
1263 @vindex gnus-group-highlight
1264 Highlighting in the group buffer is controlled by the
1265 @code{gnus-group-highlight} variable. This is an alist with elements
1266 that look like @var{(form . face)}. If @var{form} evaluates to
1267 something non-@code{nil}, the @var{face} will be used on the line.
1269 Here's an example value for this variable that might look nice if the
1273 (face-spec-set 'my-group-face-1 '((t (:foreground "Red" :bold t))))
1274 (face-spec-set 'my-group-face-2 '((t (:foreground "SeaGreen" :bold t))))
1275 (face-spec-set 'my-group-face-3 '((t (:foreground "SpringGreen" :bold t))))
1276 (face-spec-set 'my-group-face-4 '((t (:foreground "SteelBlue" :bold t))))
1277 (face-spec-set 'my-group-face-5 '((t (:foreground "SkyBlue" :bold t))))
1279 (setq gnus-group-highlight
1280 '(((> unread 200) . my-group-face-1)
1281 ((and (< level 3) (zerop unread)) . my-group-face-2)
1282 ((< level 3) . my-group-face-3)
1283 ((zerop unread) . my-group-face-4)
1284 (t . my-group-face-5)))
1287 Also @pxref{Faces and Fonts}.
1289 Variables that are dynamically bound when the forms are evaluated
1296 The number of unread articles in the group.
1300 Whether the group is a mail group.
1302 The level of the group.
1304 The score of the group.
1306 The number of ticked articles in the group.
1308 The total number of articles in the group. Or rather, MAX-NUMBER minus
1309 MIN-NUMBER plus one.
1311 When using the topic minor mode, this variable is bound to the current
1312 topic being inserted.
1315 When the forms are @code{eval}ed, point is at the beginning of the line
1316 of the group in question, so you can use many of the normal Gnus
1317 functions for snarfing info on the group.
1319 @vindex gnus-group-update-hook
1320 @findex gnus-group-highlight-line
1321 @code{gnus-group-update-hook} is called when a group line is changed.
1322 It will not be called when @code{gnus-visual} is @code{nil}. This hook
1323 calls @code{gnus-group-highlight-line} by default.
1326 @node Group Maneuvering
1327 @section Group Maneuvering
1328 @cindex group movement
1330 All movement commands understand the numeric prefix and will behave as
1331 expected, hopefully.
1337 @findex gnus-group-next-unread-group
1338 Go to the next group that has unread articles
1339 (@code{gnus-group-next-unread-group}).
1345 @findex gnus-group-prev-unread-group
1346 Go to the previous group that has unread articles
1347 (@code{gnus-group-prev-unread-group}).
1351 @findex gnus-group-next-group
1352 Go to the next group (@code{gnus-group-next-group}).
1356 @findex gnus-group-prev-group
1357 Go to the previous group (@code{gnus-group-prev-group}).
1361 @findex gnus-group-next-unread-group-same-level
1362 Go to the next unread group on the same (or lower) level
1363 (@code{gnus-group-next-unread-group-same-level}).
1367 @findex gnus-group-prev-unread-group-same-level
1368 Go to the previous unread group on the same (or lower) level
1369 (@code{gnus-group-prev-unread-group-same-level}).
1372 Three commands for jumping to groups:
1378 @findex gnus-group-jump-to-group
1379 Jump to a group (and make it visible if it isn't already)
1380 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1385 @findex gnus-group-best-unread-group
1386 Jump to the unread group with the lowest level
1387 (@code{gnus-group-best-unread-group}).
1391 @findex gnus-group-first-unread-group
1392 Jump to the first group with unread articles
1393 (@code{gnus-group-first-unread-group}).
1396 @vindex gnus-group-goto-unread
1397 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1398 commands will move to the next group, not the next unread group. Even
1399 the commands that say they move to the next unread group. The default
1403 @node Selecting a Group
1404 @section Selecting a Group
1405 @cindex group selection
1410 @kindex SPACE (Group)
1411 @findex gnus-group-read-group
1412 Select the current group, switch to the summary buffer and display the
1413 first unread article (@code{gnus-group-read-group}). If there are no
1414 unread articles in the group, or if you give a non-numerical prefix to
1415 this command, Gnus will offer to fetch all the old articles in this
1416 group from the server. If you give a numerical prefix @var{N}, @var{N}
1417 determines the number of articles Gnus will fetch. If @var{N} is
1418 positive, Gnus fetches the @var{N} newest articles, if @var{N} is
1419 negative, Gnus fetches the @var{abs(N)} oldest articles.
1423 @findex gnus-group-select-group
1424 Select the current group and switch to the summary buffer
1425 (@code{gnus-group-select-group}). Takes the same arguments as
1426 @code{gnus-group-read-group}---the only difference is that this command
1427 does not display the first unread article automatically upon group
1431 @kindex M-RET (Group)
1432 @findex gnus-group-quick-select-group
1433 This does the same as the command above, but tries to do it with the
1434 minimum amount of fuzz (@code{gnus-group-quick-select-group}). No
1435 scoring/killing will be performed, there will be no highlights and no
1436 expunging. This might be useful if you're in a real hurry and have to
1437 enter some humongous group. If you give a 0 prefix to this command
1438 (i.e., @kbd{0 M-RET}), Gnus won't even generate the summary buffer,
1439 which is useful if you want to toggle threading before generating the
1440 summary buffer (@pxref{Summary Generation Commands}).
1443 @kindex M-SPACE (Group)
1444 @findex gnus-group-visible-select-group
1445 This is yet one more command that does the same as the @kbd{RET}
1446 command, but this one does it without expunging and hiding dormants
1447 (@code{gnus-group-visible-select-group}).
1450 @kindex M-C-RET (Group)
1451 @findex gnus-group-select-group-ephemerally
1452 Finally, this command selects the current group ephemerally without
1453 doing any processing of its contents
1454 (@code{gnus-group-select-group-ephemerally}). Even threading has been
1455 turned off. Everything you do in the group after selecting it in this
1456 manner will have no permanent effects.
1460 @vindex gnus-large-newsgroup
1461 The @code{gnus-large-newsgroup} variable says what Gnus should consider
1462 to be a big group. This is 200 by default. If the group has more
1463 (unread and/or ticked) articles than this, Gnus will query the user
1464 before entering the group. The user can then specify how many articles
1465 should be fetched from the server. If the user specifies a negative
1466 number (@code{-n}), the @code{n} oldest articles will be fetched. If it
1467 is positive, the @code{n} articles that have arrived most recently will
1470 @vindex gnus-select-group-hook
1471 @vindex gnus-auto-select-first
1472 @code{gnus-auto-select-first} control whether any articles are selected
1473 automatically when entering a group with the @kbd{SPACE} command.
1478 Don't select any articles when entering the group. Just display the
1479 full summary buffer.
1482 Select the first unread article when entering the group.
1485 Select the most high-scored article in the group when entering the
1489 If you want to prevent automatic selection in some group (say, in a
1490 binary group with Huge articles) you can set this variable to @code{nil}
1491 in @code{gnus-select-group-hook}, which is called when a group is
1495 @node Subscription Commands
1496 @section Subscription Commands
1497 @cindex subscription
1505 @findex gnus-group-unsubscribe-current-group
1506 @c @icon{gnus-group-unsubscribe}
1507 Toggle subscription to the current group
1508 (@code{gnus-group-unsubscribe-current-group}).
1514 @findex gnus-group-unsubscribe-group
1515 Prompt for a group to subscribe, and then subscribe it. If it was
1516 subscribed already, unsubscribe it instead
1517 (@code{gnus-group-unsubscribe-group}).
1523 @findex gnus-group-kill-group
1524 @c @icon{gnus-group-kill-group}
1525 Kill the current group (@code{gnus-group-kill-group}).
1531 @findex gnus-group-yank-group
1532 Yank the last killed group (@code{gnus-group-yank-group}).
1535 @kindex C-x C-t (Group)
1536 @findex gnus-group-transpose-groups
1537 Transpose two groups (@code{gnus-group-transpose-groups}). This isn't
1538 really a subscription command, but you can use it instead of a
1539 kill-and-yank sequence sometimes.
1545 @findex gnus-group-kill-region
1546 Kill all groups in the region (@code{gnus-group-kill-region}).
1550 @findex gnus-group-kill-all-zombies
1551 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
1554 @kindex S C-k (Group)
1555 @findex gnus-group-kill-level
1556 Kill all groups on a certain level (@code{gnus-group-kill-level}).
1557 These groups can't be yanked back after killing, so this command should
1558 be used with some caution. The only time where this command comes in
1559 really handy is when you have a @file{.newsrc} with lots of unsubscribed
1560 groups that you want to get rid off. @kbd{S C-k} on level 7 will
1561 kill off all unsubscribed groups that do not have message numbers in the
1562 @file{.newsrc} file.
1566 Also @pxref{Group Levels}.
1576 @findex gnus-group-catchup-current
1577 @vindex gnus-group-catchup-group-hook
1578 @c @icon{gnus-group-catchup-current}
1579 Mark all unticked articles in this group as read
1580 (@code{gnus-group-catchup-current}).
1581 @code{gnus-group-catchup-group-hook} is called when catching up a group from
1586 @findex gnus-group-catchup-current-all
1587 Mark all articles in this group, even the ticked ones, as read
1588 (@code{gnus-group-catchup-current-all}).
1592 @findex gnus-group-clear-data
1593 Clear the data from the current group---nix out marks and the list of
1594 read articles (@code{gnus-group-clear-data}).
1596 @item M-x gnus-group-clear-data-on-native-groups
1597 @kindex M-x gnus-group-clear-data-on-native-groups
1598 @findex gnus-group-clear-data-on-native-groups
1599 If you have switched from one @sc{nntp} server to another, all your marks
1600 and read ranges have become worthless. You can use this command to
1601 clear out all data that you have on your native groups. Use with
1608 @section Group Levels
1612 All groups have a level of @dfn{subscribedness}. For instance, if a
1613 group is on level 2, it is more subscribed than a group on level 5. You
1614 can ask Gnus to just list groups on a given level or lower
1615 (@pxref{Listing Groups}), or to just check for new articles in groups on
1616 a given level or lower (@pxref{Scanning New Messages}).
1618 Remember: The higher the level of the group, the less important it is.
1624 @findex gnus-group-set-current-level
1625 Set the level of the current group. If a numeric prefix is given, the
1626 next @var{n} groups will have their levels set. The user will be
1627 prompted for a level.
1630 @vindex gnus-level-killed
1631 @vindex gnus-level-zombie
1632 @vindex gnus-level-unsubscribed
1633 @vindex gnus-level-subscribed
1634 Gnus considers groups from levels 1 to
1635 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
1636 @code{gnus-level-subscribed} (exclusive) and
1637 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
1638 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
1639 (default 8) and @code{gnus-level-killed} to be killed (completely dead)
1640 (default 9). Gnus treats subscribed and unsubscribed groups exactly the
1641 same, but zombie and killed groups have no information on what articles
1642 you have read, etc, stored. This distinction between dead and living
1643 groups isn't done because it is nice or clever, it is done purely for
1644 reasons of efficiency.
1646 It is recommended that you keep all your mail groups (if any) on quite
1647 low levels (e.g. 1 or 2).
1649 If you want to play with the level variables, you should show some care.
1650 Set them once, and don't touch them ever again. Better yet, don't touch
1651 them at all unless you know exactly what you're doing.
1653 @vindex gnus-level-default-unsubscribed
1654 @vindex gnus-level-default-subscribed
1655 Two closely related variables are @code{gnus-level-default-subscribed}
1656 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
1657 which are the levels that new groups will be put on if they are
1658 (un)subscribed. These two variables should, of course, be inside the
1659 relevant valid ranges.
1661 @vindex gnus-keep-same-level
1662 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
1663 will only move to groups of the same level (or lower). In
1664 particular, going from the last article in one group to the next group
1665 will go to the next group of the same level (or lower). This might be
1666 handy if you want to read the most important groups before you read the
1669 @vindex gnus-group-default-list-level
1670 All groups with a level less than or equal to
1671 @code{gnus-group-default-list-level} will be listed in the group buffer
1674 @vindex gnus-group-list-inactive-groups
1675 If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
1676 groups will be listed along with the unread groups. This variable is
1677 @code{t} by default. If it is @code{nil}, inactive groups won't be
1680 @vindex gnus-group-use-permanent-levels
1681 If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you
1682 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
1683 use this level as the ``work'' level.
1685 @vindex gnus-activate-level
1686 Gnus will normally just activate (i. e., query the server about) groups
1687 on level @code{gnus-activate-level} or less. If you don't want to
1688 activate unsubscribed groups, for instance, you might set this variable
1689 to 5. The default is 6.
1693 @section Group Score
1698 You would normally keep important groups on high levels, but that scheme
1699 is somewhat restrictive. Don't you wish you could have Gnus sort the
1700 group buffer according to how often you read groups, perhaps? Within
1703 This is what @dfn{group score} is for. You can assign a score to each
1704 group. You can then sort the group buffer based on this score.
1705 Alternatively, you can sort on score and then level. (Taken together,
1706 the level and the score is called the @dfn{rank} of the group. A group
1707 that is on level 4 and has a score of 1 has a higher rank than a group
1708 on level 5 that has a score of 300. (The level is the most significant
1709 part and the score is the least significant part.))
1711 @findex gnus-summary-bubble-group
1712 If you want groups you read often to get higher scores than groups you
1713 read seldom you can add the @code{gnus-summary-bubble-group} function to
1714 the @code{gnus-summary-exit-hook} hook. This will result (after
1715 sorting) in a bubbling sort of action. If you want to see that in
1716 action after each summary exit, you can add
1717 @code{gnus-group-sort-groups-by-rank} or
1718 @code{gnus-group-sort-groups-by-score} to the same hook, but that will
1719 slow things down somewhat.
1722 @node Marking Groups
1723 @section Marking Groups
1724 @cindex marking groups
1726 If you want to perform some command on several groups, and they appear
1727 subsequently in the group buffer, you would normally just give a
1728 numerical prefix to the command. Most group commands will then do your
1729 bidding on those groups.
1731 However, if the groups are not in sequential order, you can still
1732 perform a command on several groups. You simply mark the groups first
1733 with the process mark and then execute the command.
1741 @findex gnus-group-mark-group
1742 Set the mark on the current group (@code{gnus-group-mark-group}).
1748 @findex gnus-group-unmark-group
1749 Remove the mark from the current group
1750 (@code{gnus-group-unmark-group}).
1754 @findex gnus-group-unmark-all-groups
1755 Remove the mark from all groups (@code{gnus-group-unmark-all-groups}).
1759 @findex gnus-group-mark-region
1760 Mark all groups between point and mark (@code{gnus-group-mark-region}).
1764 @findex gnus-group-mark-buffer
1765 Mark all groups in the buffer (@code{gnus-group-mark-buffer}).
1769 @findex gnus-group-mark-regexp
1770 Mark all groups that match some regular expression
1771 (@code{gnus-group-mark-regexp}).
1774 Also @pxref{Process/Prefix}.
1776 @findex gnus-group-universal-argument
1777 If you want to execute some command on all groups that have been marked
1778 with the process mark, you can use the @kbd{M-&}
1779 (@code{gnus-group-universal-argument}) command. It will prompt you for
1780 the command to be executed.
1783 @node Foreign Groups
1784 @section Foreign Groups
1785 @cindex foreign groups
1787 Below are some group mode commands for making and editing general foreign
1788 groups, as well as commands to ease the creation of a few
1789 special-purpose groups. All these commands insert the newly created
1790 groups under point---@code{gnus-subscribe-newsgroup-method} is not
1797 @findex gnus-group-make-group
1798 @cindex making groups
1799 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
1800 for a name, a method and possibly an @dfn{address}. For an easier way
1801 to subscribe to @sc{nntp} groups, @pxref{Browse Foreign Server}.
1805 @findex gnus-group-rename-group
1806 @cindex renaming groups
1807 Rename the current group to something else
1808 (@code{gnus-group-rename-group}). This is valid only on some
1809 groups---mail groups mostly. This command might very well be quite slow
1815 @findex gnus-group-customize
1816 Customize the group parameters (@code{gnus-group-customize}).
1820 @findex gnus-group-edit-group-method
1821 @cindex renaming groups
1822 Enter a buffer where you can edit the select method of the current
1823 group (@code{gnus-group-edit-group-method}).
1827 @findex gnus-group-edit-group-parameters
1828 Enter a buffer where you can edit the group parameters
1829 (@code{gnus-group-edit-group-parameters}).
1833 @findex gnus-group-edit-group
1834 Enter a buffer where you can edit the group info
1835 (@code{gnus-group-edit-group}).
1839 @findex gnus-group-make-directory-group
1841 Make a directory group (@pxref{Directory Groups}). You will be prompted
1842 for a directory name (@code{gnus-group-make-directory-group}).
1847 @findex gnus-group-make-help-group
1848 Make the Gnus help group (@code{gnus-group-make-help-group}).
1852 @cindex (ding) archive
1853 @cindex archive group
1854 @findex gnus-group-make-archive-group
1855 @vindex gnus-group-archive-directory
1856 @vindex gnus-group-recent-archive-directory
1857 Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
1858 default a group pointing to the most recent articles will be created
1859 (@code{gnus-group-recent-archive-directory}), but given a prefix, a full
1860 group will be created from @code{gnus-group-archive-directory}.
1864 @findex gnus-group-make-kiboze-group
1866 Make a kiboze group. You will be prompted for a name, for a regexp to
1867 match groups to be ``included'' in the kiboze group, and a series of
1868 strings to match on headers (@code{gnus-group-make-kiboze-group}).
1869 @xref{Kibozed Groups}.
1873 @findex gnus-group-enter-directory
1875 Read an arbitrary directory as if it were a newsgroup with the
1876 @code{nneething} backend (@code{gnus-group-enter-directory}).
1877 @xref{Anything Groups}.
1881 @findex gnus-group-make-doc-group
1882 @cindex ClariNet Briefs
1884 Make a group based on some file or other
1885 (@code{gnus-group-make-doc-group}). If you give a prefix to this
1886 command, you will be prompted for a file name and a file type.
1887 Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
1888 @code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs},
1889 @code{rfc934}, @code{rfc822-forward}, and @code{forward}. If you run
1890 this command without a prefix, Gnus will guess at the file type.
1891 @xref{Document Groups}.
1895 @findex gnus-group-make-web-group
1900 Make an ephemeral group based on a web search
1901 (@code{gnus-group-make-web-group}). If you give a prefix to this
1902 command, make a solid group instead. You will be prompted for the
1903 search engine type and the search string. Valid search engine types
1904 include @code{dejanews}, @code{altavista} and @code{reference}.
1905 @xref{Web Searches}.
1908 @kindex G DEL (Group)
1909 @findex gnus-group-delete-group
1910 This function will delete the current group
1911 (@code{gnus-group-delete-group}). If given a prefix, this function will
1912 actually delete all the articles in the group, and forcibly remove the
1913 group itself from the face of the Earth. Use a prefix only if you are
1914 absolutely sure of what you are doing. This command can't be used on
1915 read-only groups (like @code{nntp} group), though.
1919 @findex gnus-group-make-empty-virtual
1920 Make a new, fresh, empty @code{nnvirtual} group
1921 (@code{gnus-group-make-empty-virtual}). @xref{Virtual Groups}.
1925 @findex gnus-group-add-to-virtual
1926 Add the current group to an @code{nnvirtual} group
1927 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
1930 @xref{Select Methods} for more information on the various select
1933 @vindex gnus-activate-foreign-newsgroups
1934 If @code{gnus-activate-foreign-newsgroups} is a positive number,
1935 Gnus will check all foreign groups with this level or lower at startup.
1936 This might take quite a while, especially if you subscribe to lots of
1937 groups from different @sc{nntp} servers.
1940 @node Group Parameters
1941 @section Group Parameters
1942 @cindex group parameters
1944 The group parameters store information local to a particular group.
1945 Here's an example group parameter list:
1948 ((to-address . "ding@@gnus.org")
1952 We see that each element consists of a "dotted pair"---the thing before
1953 the dot is the key, while the thing after the dot is the value. All the
1954 parameters have this form @emph{except} local variable specs, which are
1955 not dotted pairs, but proper lists.
1957 The following group parameters can be used:
1962 Address used by when doing followups and new posts.
1965 (to-address . "some@@where.com")
1968 This is primarily useful in mail groups that represent closed mailing
1969 lists---mailing lists where it's expected that everybody that writes to
1970 the mailing list is subscribed to it. Since using this parameter
1971 ensures that the mail only goes to the mailing list itself, it means
1972 that members won't receive two copies of your followups.
1974 Using @code{to-address} will actually work whether the group is foreign
1975 or not. Let's say there's a group on the server that is called
1976 @samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten
1977 the articles from a mail-to-news gateway. Posting directly to this
1978 group is therefore impossible---you have to send mail to the mailing
1979 list address instead.
1983 Address used when doing a @kbd{a} in that group.
1986 (to-list . "some@@where.com")
1989 It is totally ignored
1990 when doing a followup---except that if it is present in a news group,
1991 you'll get mail group semantics when doing @kbd{f}.
1993 If you do an @kbd{a} command in a mail group and you have neither a
1994 @code{to-list} group parameter nor a @code{to-address} group paramater,
1995 then a @code{to-list} group parameter will be added automatically upon
1996 sending the message if @code{gnus-add-to-list} is set to @code{t}.
1997 @vindex gnus-add-to-list
1999 If you do an @kbd{a} command in a mail group and you don't have a
2000 @code{to-list} group parameter, one will be added automatically upon
2001 sending the message.
2005 If the group parameter list has the element @code{(visible . t)},
2006 that group will always be visible in the Group buffer, regardless
2007 of whether it has any unread articles.
2009 @item broken-reply-to
2010 @cindex broken-reply-to
2011 Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To}
2012 headers in this group are to be ignored. This can be useful if you're
2013 reading a mailing list group where the listserv has inserted
2014 @code{Reply-To} headers that point back to the listserv itself. This is
2015 broken behavior. So there!
2019 Elements like @code{(to-group . "some.group.name")} means that all
2020 posts in that group will be sent to @code{some.group.name}.
2024 If you have @code{(newsgroup . t)} in the group parameter list, Gnus
2025 will treat all responses as if they were responses to news articles.
2026 This can be useful if you have a mail group that's really a mirror of a
2031 If @code{(gcc-self . t)} is present in the group parameter list, newly
2032 composed messages will be @code{Gcc}'d to the current group. If
2033 @code{(gcc-self . none)} is present, no @code{Gcc:} header will be
2034 generated, if @code{(gcc-self . "string")} is present, this string will
2035 be inserted literally as a @code{gcc} header. This parameter takes
2036 precedence over any default @code{Gcc} rules as described later
2037 (@pxref{Archived Messages}).
2041 If the group parameter has an element that looks like @code{(auto-expire
2042 . t)}, all articles read will be marked as expirable. For an
2043 alternative approach, @pxref{Expiring Mail}.
2046 @cindex total-expire
2047 If the group parameter has an element that looks like
2048 @code{(total-expire . t)}, all read articles will be put through the
2049 expiry process, even if they are not marked as expirable. Use with
2050 caution. Unread, ticked and dormant articles are not eligible for
2055 @vindex nnmail-expiry-wait-function
2056 If the group parameter has an element that looks like @code{(expiry-wait
2057 . 10)}, this value will override any @code{nnmail-expiry-wait} and
2058 @code{nnmail-expiry-wait-function} when expiring expirable messages.
2059 The value can either be a number of days (not necessarily an integer) or
2060 the symbols @code{never} or @code{immediate}.
2063 @cindex score file group parameter
2064 Elements that look like @code{(score-file . "file")} will make
2065 @file{file} into the current adaptive score file for the group in
2066 question. All adaptive score entries will be put into this file.
2069 @cindex adapt file group parameter
2070 Elements that look like @code{(adapt-file . "file")} will make
2071 @file{file} into the current adaptive file for the group in question.
2072 All adaptive score entries will be put into this file.
2075 When unsubscribing from a mailing list you should never send the
2076 unsubscription notice to the mailing list itself. Instead, you'd send
2077 messages to the administrative address. This parameter allows you to
2078 put the admin address somewhere convenient.
2081 Elements that look like @code{(display . MODE)} say which articles to
2082 display on entering the group. Valid values are:
2086 Display all articles, both read and unread.
2089 Display the default visible articles, which normally includes unread and
2094 Elements that look like @code{(comment . "This is a comment")}
2095 are arbitrary comments on the group. They are currently ignored by
2096 Gnus, but provide a place for you to store information on particular
2099 @item @var{(variable form)}
2100 You can use the group parameters to set variables local to the group you
2101 are entering. If you want to turn threading off in @samp{news.answers},
2102 you could put @code{(gnus-show-threads nil)} in the group parameters of
2103 that group. @code{gnus-show-threads} will be made into a local variable
2104 in the summary buffer you enter, and the form @code{nil} will be
2105 @code{eval}ed there.
2107 This can also be used as a group-specific hook function, if you'd like.
2108 If you want to hear a beep when you enter a group, you could put
2109 something like @code{(dummy-variable (ding))} in the parameters of that
2110 group. @code{dummy-variable} will be set to the result of the
2111 @code{(ding)} form, but who cares?
2115 Use the @kbd{G p} command to edit group parameters of a group. You
2116 might also be interested in reading about topic parameters (@pxref{Topic
2120 @node Listing Groups
2121 @section Listing Groups
2122 @cindex group listing
2124 These commands all list various slices of the groups available.
2132 @findex gnus-group-list-groups
2133 List all groups that have unread articles
2134 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
2135 command will list only groups of level ARG and lower. By default, it
2136 only lists groups of level five (i. e.,
2137 @code{gnus-group-default-list-level}) or lower (i.e., just subscribed
2144 @findex gnus-group-list-all-groups
2145 List all groups, whether they have unread articles or not
2146 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
2147 this command will list only groups of level ARG and lower. By default,
2148 it lists groups of level seven or lower (i.e., just subscribed and
2149 unsubscribed groups).
2153 @findex gnus-group-list-level
2154 List all unread groups on a specific level
2155 (@code{gnus-group-list-level}). If given a prefix, also list the groups
2156 with no unread articles.
2160 @findex gnus-group-list-killed
2161 List all killed groups (@code{gnus-group-list-killed}). If given a
2162 prefix argument, really list all groups that are available, but aren't
2163 currently (un)subscribed. This could entail reading the active file
2168 @findex gnus-group-list-zombies
2169 List all zombie groups (@code{gnus-group-list-zombies}).
2173 @findex gnus-group-list-matching
2174 List all unread, subscribed groups with names that match a regexp
2175 (@code{gnus-group-list-matching}).
2179 @findex gnus-group-list-all-matching
2180 List groups that match a regexp (@code{gnus-group-list-all-matching}).
2184 @findex gnus-group-list-active
2185 List absolutely all groups in the active file(s) of the
2186 server(s) you are connected to (@code{gnus-group-list-active}). This
2187 might very well take quite a while. It might actually be a better idea
2188 to do a @kbd{A M} to list all matching, and just give @samp{.} as the
2189 thing to match on. Also note that this command may list groups that
2190 don't exist (yet)---these will be listed as if they were killed groups.
2191 Take the output with some grains of salt.
2195 @findex gnus-group-apropos
2196 List all groups that have names that match a regexp
2197 (@code{gnus-group-apropos}).
2201 @findex gnus-group-description-apropos
2202 List all groups that have names or descriptions that match a regexp
2203 (@code{gnus-group-description-apropos}).
2207 @vindex gnus-permanently-visible-groups
2208 @cindex visible group parameter
2209 Groups that match the @code{gnus-permanently-visible-groups} regexp will
2210 always be shown, whether they have unread articles or not. You can also
2211 add the @code{visible} element to the group parameters in question to
2212 get the same effect.
2214 @vindex gnus-list-groups-with-ticked-articles
2215 Groups that have just ticked articles in it are normally listed in the
2216 group buffer. If @code{gnus-list-groups-with-ticked-articles} is
2217 @code{nil}, these groups will be treated just like totally empty
2218 groups. It is @code{t} by default.
2221 @node Sorting Groups
2222 @section Sorting Groups
2223 @cindex sorting groups
2225 @kindex C-c C-s (Group)
2226 @findex gnus-group-sort-groups
2227 @vindex gnus-group-sort-function
2228 The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the
2229 group buffer according to the function(s) given by the
2230 @code{gnus-group-sort-function} variable. Available sorting functions
2235 @item gnus-group-sort-by-alphabet
2236 @findex gnus-group-sort-by-alphabet
2237 Sort the group names alphabetically. This is the default.
2239 @item gnus-group-sort-by-real-name
2240 @findex gnus-group-sort-by-real-name
2241 Sort the group alphabetically on the real (unprefixed) group names.
2243 @item gnus-group-sort-by-level
2244 @findex gnus-group-sort-by-level
2245 Sort by group level.
2247 @item gnus-group-sort-by-score
2248 @findex gnus-group-sort-by-score
2249 Sort by group score. @xref{Group Score}.
2251 @item gnus-group-sort-by-rank
2252 @findex gnus-group-sort-by-rank
2253 Sort by group score and then the group level. The level and the score
2254 are, when taken together, the group's @dfn{rank}. @xref{Group Score}.
2256 @item gnus-group-sort-by-unread
2257 @findex gnus-group-sort-by-unread
2258 Sort by number of unread articles.
2260 @item gnus-group-sort-by-method
2261 @findex gnus-group-sort-by-method
2262 Sort alphabetically on the select method.
2267 @code{gnus-group-sort-function} can also be a list of sorting
2268 functions. In that case, the most significant sort key function must be
2272 There are also a number of commands for sorting directly according to
2273 some sorting criteria:
2277 @kindex G S a (Group)
2278 @findex gnus-group-sort-groups-by-alphabet
2279 Sort the group buffer alphabetically by group name
2280 (@code{gnus-group-sort-groups-by-alphabet}).
2283 @kindex G S u (Group)
2284 @findex gnus-group-sort-groups-by-unread
2285 Sort the group buffer by the number of unread articles
2286 (@code{gnus-group-sort-groups-by-unread}).
2289 @kindex G S l (Group)
2290 @findex gnus-group-sort-groups-by-level
2291 Sort the group buffer by group level
2292 (@code{gnus-group-sort-groups-by-level}).
2295 @kindex G S v (Group)
2296 @findex gnus-group-sort-groups-by-score
2297 Sort the group buffer by group score
2298 (@code{gnus-group-sort-groups-by-score}). @xref{Group Score}.
2301 @kindex G S r (Group)
2302 @findex gnus-group-sort-groups-by-rank
2303 Sort the group buffer by group rank
2304 (@code{gnus-group-sort-groups-by-rank}). @xref{Group Score}.
2307 @kindex G S m (Group)
2308 @findex gnus-group-sort-groups-by-method
2309 Sort the group buffer alphabetically by backend name
2310 (@code{gnus-group-sort-groups-by-method}).
2314 When given a prefix, all these commands will sort in reverse order.
2316 You can also sort a subset of the groups:
2320 @kindex G P a (Group)
2321 @findex gnus-group-sort-selected-groups-by-alphabet
2322 Sort the process/prefixed groups in the group buffer alphabetically by
2323 group name (@code{gnus-group-sort-selected-groups-by-alphabet}).
2326 @kindex G P u (Group)
2327 @findex gnus-group-sort-selected-groups-by-unread
2328 Sort the process/prefixed groups in the group buffer by the number of
2329 unread articles (@code{gnus-group-sort-selected-groups-by-unread}).
2332 @kindex G P l (Group)
2333 @findex gnus-group-sort-selected-groups-by-level
2334 Sort the process/prefixed groups in the group buffer by group level
2335 (@code{gnus-group-sort-selected-groups-by-level}).
2338 @kindex G P v (Group)
2339 @findex gnus-group-sort-selected-groups-by-score
2340 Sort the process/prefixed groups in the group buffer by group score
2341 (@code{gnus-group-sort-selected-groups-by-score}). @xref{Group Score}.
2344 @kindex G P r (Group)
2345 @findex gnus-group-sort-selected-groups-by-rank
2346 Sort the process/prefixed groups in the group buffer by group rank
2347 (@code{gnus-group-sort-selected-groups-by-rank}). @xref{Group Score}.
2350 @kindex G P m (Group)
2351 @findex gnus-group-sort-selected-groups-by-method
2352 Sort the process/prefixed groups in the group buffer alphabetically by
2353 backend name (@code{gnus-group-sort-selected-groups-by-method}).
2359 @node Group Maintenance
2360 @section Group Maintenance
2361 @cindex bogus groups
2366 @findex gnus-group-check-bogus-groups
2367 Find bogus groups and delete them
2368 (@code{gnus-group-check-bogus-groups}).
2372 @findex gnus-group-find-new-groups
2373 Find new groups and process them (@code{gnus-group-find-new-groups}).
2374 If given a prefix, use the @code{ask-server} method to query the server
2378 @kindex C-c C-x (Group)
2379 @findex gnus-group-expire-articles
2380 Run all expirable articles in the current group through the expiry
2381 process (if any) (@code{gnus-group-expire-articles}).
2384 @kindex C-c M-C-x (Group)
2385 @findex gnus-group-expire-all-groups
2386 Run all articles in all groups through the expiry process
2387 (@code{gnus-group-expire-all-groups}).
2392 @node Browse Foreign Server
2393 @section Browse Foreign Server
2394 @cindex foreign servers
2395 @cindex browsing servers
2400 @findex gnus-group-browse-foreign-server
2401 You will be queried for a select method and a server name. Gnus will
2402 then attempt to contact this server and let you browse the groups there
2403 (@code{gnus-group-browse-foreign-server}).
2406 @findex gnus-browse-mode
2407 A new buffer with a list of available groups will appear. This buffer
2408 will use the @code{gnus-browse-mode}. This buffer looks a bit (well,
2409 a lot) like a normal group buffer.
2411 Here's a list of keystrokes available in the browse mode:
2416 @findex gnus-group-next-group
2417 Go to the next group (@code{gnus-group-next-group}).
2421 @findex gnus-group-prev-group
2422 Go to the previous group (@code{gnus-group-prev-group}).
2425 @kindex SPACE (Browse)
2426 @findex gnus-browse-read-group
2427 Enter the current group and display the first article
2428 (@code{gnus-browse-read-group}).
2431 @kindex RET (Browse)
2432 @findex gnus-browse-select-group
2433 Enter the current group (@code{gnus-browse-select-group}).
2437 @findex gnus-browse-unsubscribe-current-group
2438 Unsubscribe to the current group, or, as will be the case here,
2439 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
2445 @findex gnus-browse-exit
2446 Exit browse mode (@code{gnus-browse-exit}).
2450 @findex gnus-browse-describe-briefly
2451 Describe browse mode briefly (well, there's not much to describe, is
2452 there) (@code{gnus-browse-describe-briefly}).
2457 @section Exiting Gnus
2458 @cindex exiting Gnus
2460 Yes, Gnus is ex(c)iting.
2465 @findex gnus-group-suspend
2466 Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
2467 but it kills all buffers except the Group buffer. I'm not sure why this
2468 is a gain, but then who am I to judge?
2472 @findex gnus-group-exit
2473 @c @icon{gnus-group-exit}
2474 Quit Gnus (@code{gnus-group-exit}).
2478 @findex gnus-group-quit
2479 Quit Gnus without saving the @file{.newsrc} files (@code{gnus-group-quit}).
2480 The dribble file will be saved, though (@pxref{Auto Save}).
2483 @vindex gnus-exit-gnus-hook
2484 @vindex gnus-suspend-gnus-hook
2485 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
2486 @code{gnus-exit-gnus-hook} is called when you quit Gnus, while
2487 @code{gnus-after-exiting-gnus-hook} is called as the final item when
2492 If you wish to completely unload Gnus and all its adherents, you can use
2493 the @code{gnus-unload} command. This command is also very handy when
2494 trying to customize meta-variables.
2499 Miss Lisa Cannifax, while sitting in English class, felt her feet go
2500 numbly heavy and herself fall into a hazy trance as the boy sitting
2501 behind her drew repeated lines with his pencil across the back of her
2507 @section Group Topics
2510 If you read lots and lots of groups, it might be convenient to group
2511 them hierarchically according to topics. You put your Emacs groups over
2512 here, your sex groups over there, and the rest (what, two groups or so?)
2513 you put in some misc section that you never bother with anyway. You can
2514 even group the Emacs sex groups as a sub-topic to either the Emacs
2515 groups or the sex groups---or both! Go wild!
2519 \gnusfigure{Group Topics}{400}{
2520 \put(75,50){\epsfig{figure=tmp/group-topic.ps,height=9cm}}
2531 2: alt.religion.emacs
2534 0: comp.talk.emacs.recovery
2536 8: comp.binaries.fractals
2537 13: comp.sources.unix
2540 @findex gnus-topic-mode
2542 To get this @emph{fab} functionality you simply turn on (ooh!) the
2543 @code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
2544 is a toggling command.)
2546 Go ahead, just try it. I'll still be here when you get back. La de
2547 dum... Nice tune, that... la la la... What, you're back? Yes, and now
2548 press @kbd{l}. There. All your groups are now listed under
2549 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
2552 If you want this permanently enabled, you should add that minor mode to
2553 the hook for the group mode:
2556 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
2560 * Topic Variables:: How to customize the topics the Lisp Way.
2561 * Topic Commands:: Interactive E-Z commands.
2562 * Topic Sorting:: Sorting each topic individually.
2563 * Topic Topology:: A map of the world.
2564 * Topic Parameters:: Parameters that apply to all groups in a topic.
2568 @node Topic Variables
2569 @subsection Topic Variables
2570 @cindex topic variables
2572 Now, if you select a topic, it will fold/unfold that topic, which is
2573 really neat, I think.
2575 @vindex gnus-topic-line-format
2576 The topic lines themselves are created according to the
2577 @code{gnus-topic-line-format} variable (@pxref{Formatting Variables}).
2590 Number of groups in the topic.
2592 Number of unread articles in the topic.
2594 Number of unread articles in the topic and all its subtopics.
2597 @vindex gnus-topic-indent-level
2598 Each sub-topic (and the groups in the sub-topics) will be indented with
2599 @code{gnus-topic-indent-level} times the topic level number of spaces.
2602 @vindex gnus-topic-mode-hook
2603 @code{gnus-topic-mode-hook} is called in topic minor mode buffers.
2605 @vindex gnus-topic-display-empty-topics
2606 The @code{gnus-topic-display-empty-topics} says whether to display even
2607 topics that have no unread articles in them. The default is @code{t}.
2610 @node Topic Commands
2611 @subsection Topic Commands
2612 @cindex topic commands
2614 When the topic minor mode is turned on, a new @kbd{T} submap will be
2615 available. In addition, a few of the standard keys change their
2616 definitions slightly.
2622 @findex gnus-topic-create-topic
2623 Prompt for a new topic name and create it
2624 (@code{gnus-topic-create-topic}).
2628 @findex gnus-topic-move-group
2629 Move the current group to some other topic
2630 (@code{gnus-topic-move-group}). This command uses the process/prefix
2631 convention (@pxref{Process/Prefix}).
2635 @findex gnus-topic-copy-group
2636 Copy the current group to some other topic
2637 (@code{gnus-topic-copy-group}). This command uses the process/prefix
2638 convention (@pxref{Process/Prefix}).
2642 @findex gnus-topic-remove-group
2643 Remove a group from the current topic (@code{gnus-topic-remove-group}).
2644 This command uses the process/prefix convention
2645 (@pxref{Process/Prefix}).
2649 @findex gnus-topic-move-matching
2650 Move all groups that match some regular expression to a topic
2651 (@code{gnus-topic-move-matching}).
2655 @findex gnus-topic-copy-matching
2656 Copy all groups that match some regular expression to a topic
2657 (@code{gnus-topic-copy-matching}).
2661 @findex gnus-topic-toggle-display-empty-topics
2662 Toggle hiding empty topics
2663 (@code{gnus-topic-toggle-display-empty-topics}).
2667 @findex gnus-topic-mark-topic
2668 Mark all groups in the current topic with the process mark
2669 (@code{gnus-topic-mark-topic}).
2672 @kindex T M-# (Topic)
2673 @findex gnus-topic-unmark-topic
2674 Remove the process mark from all groups in the current topic
2675 (@code{gnus-topic-unmark-topic}).
2679 @findex gnus-topic-select-group
2681 Either select a group or fold a topic (@code{gnus-topic-select-group}).
2682 When you perform this command on a group, you'll enter the group, as
2683 usual. When done on a topic line, the topic will be folded (if it was
2684 visible) or unfolded (if it was folded already). So it's basically a
2685 toggling command on topics. In addition, if you give a numerical
2686 prefix, group on that level (and lower) will be displayed.
2689 @kindex T TAB (Topic)
2690 @findex gnus-topic-indent
2691 ``Indent'' the current topic so that it becomes a sub-topic of the
2692 previous topic (@code{gnus-topic-indent}). If given a prefix,
2693 ``un-indent'' the topic instead.
2697 @findex gnus-topic-kill-group
2698 Kill a group or topic (@code{gnus-topic-kill-group}). All groups in the
2699 topic will be removed along with the topic.
2703 @findex gnus-topic-yank-group
2704 Yank the previously killed group or topic
2705 (@code{gnus-topic-yank-group}). Note that all topics will be yanked
2710 @findex gnus-topic-rename
2711 Rename a topic (@code{gnus-topic-rename}).
2714 @kindex T DEL (Topic)
2715 @findex gnus-topic-delete
2716 Delete an empty topic (@code{gnus-topic-delete}).
2720 @findex gnus-topic-list-active
2721 List all groups that Gnus knows about in a topics-ified way
2722 (@code{gnus-topic-list-active}).
2726 @findex gnus-topic-edit-parameters
2727 @cindex group parameters
2728 @cindex topic parameters
2730 Edit the topic parameters (@code{gnus-topic-edit-parameters}).
2731 @xref{Topic Parameters}.
2737 @subsection Topic Sorting
2738 @cindex topic sorting
2740 You can sort the groups in each topic individually with the following
2746 @kindex T S a (Topic)
2747 @findex gnus-topic-sort-groups-by-alphabet
2748 Sort the current topic alphabetically by group name
2749 (@code{gnus-topic-sort-groups-by-alphabet}).
2752 @kindex T S u (Topic)
2753 @findex gnus-topic-sort-groups-by-unread
2754 Sort the current topic by the number of unread articles
2755 (@code{gnus-topic-sort-groups-by-unread}).
2758 @kindex T S l (Topic)
2759 @findex gnus-topic-sort-groups-by-level
2760 Sort the current topic by group level
2761 (@code{gnus-topic-sort-groups-by-level}).
2764 @kindex T S v (Topic)
2765 @findex gnus-topic-sort-groups-by-score
2766 Sort the current topic by group score
2767 (@code{gnus-topic-sort-groups-by-score}). @xref{Group Score}.
2770 @kindex T S r (Topic)
2771 @findex gnus-topic-sort-groups-by-rank
2772 Sort the current topic by group rank
2773 (@code{gnus-topic-sort-groups-by-rank}). @xref{Group Score}.
2776 @kindex T S m (Topic)
2777 @findex gnus-topic-sort-groups-by-method
2778 Sort the current topic alphabetically by backend name
2779 (@code{gnus-topic-sort-groups-by-method}).
2783 @xref{Sorting Groups} for more information about group sorting.
2786 @node Topic Topology
2787 @subsection Topic Topology
2788 @cindex topic topology
2791 So, let's have a look at an example group buffer:
2797 2: alt.religion.emacs
2800 0: comp.talk.emacs.recovery
2802 8: comp.binaries.fractals
2803 13: comp.sources.unix
2806 So, here we have one top-level topic (@samp{Gnus}), two topics under
2807 that, and one sub-topic under one of the sub-topics. (There is always
2808 just one (1) top-level topic). This topology can be expressed as
2813 (("Emacs -- I wuw it!" visible)
2814 (("Naughty Emacs" visible)))
2818 @vindex gnus-topic-topology
2819 This is in fact how the variable @code{gnus-topic-topology} would look
2820 for the display above. That variable is saved in the @file{.newsrc.eld}
2821 file, and shouldn't be messed with manually---unless you really want
2822 to. Since this variable is read from the @file{.newsrc.eld} file,
2823 setting it in any other startup files will have no effect.
2825 This topology shows what topics are sub-topics of what topics (right),
2826 and which topics are visible. Two settings are currently
2827 allowed---@code{visible} and @code{invisible}.
2830 @node Topic Parameters
2831 @subsection Topic Parameters
2832 @cindex topic parameters
2834 All groups in a topic will inherit group parameters from the parent (and
2835 ancestor) topic parameters. All valid group parameters are valid topic
2836 parameters (@pxref{Group Parameters}).
2838 Group parameters (of course) override topic parameters, and topic
2839 parameters in sub-topics override topic parameters in super-topics. You
2840 know. Normal inheritance rules. (@dfn{Rules} is here a noun, not a
2841 verb, although you may feel free to disagree with me here.)
2847 2: alt.religion.emacs
2851 0: comp.talk.emacs.recovery
2853 8: comp.binaries.fractals
2854 13: comp.sources.unix
2858 The @samp{Emacs} topic has the topic parameter @code{(score-file
2859 . "emacs.SCORE")}; the @samp{Relief} topic has the topic parameter
2860 @code{(score-file . "relief.SCORE")}; and the @samp{Misc} topic has the
2861 topic parameter @code{(score-file . "emacs.SCORE")}. In addition,
2862 @samp{alt.religion.emacs} has the group parameter @code{(score-file
2863 . "religion.SCORE")}.
2865 Now, when you enter @samp{alt.sex.emacs} in the @samp{Relief} topic, you
2866 will get the @file{relief.SCORE} home score file. If you enter the same
2867 group in the @samp{Emacs} topic, you'll get the @file{emacs.SCORE} home
2868 score file. If you enter the group @samp{alt.religion.emacs}, you'll
2869 get the @file{religion.SCORE} home score file.
2871 This seems rather simple and self-evident, doesn't it? Well, yes. But
2872 there are some problems, especially with the @code{total-expiry}
2873 parameter. Say you have a mail group in two topics; one with
2874 @code{total-expiry} and one without. What happens when you do @kbd{M-x
2875 gnus-expire-all-expirable-groups}? Gnus has no way of telling which one
2876 of these topics you mean to expire articles from, so anything may
2877 happen. In fact, I hereby declare that it is @dfn{undefined} what
2878 happens. You just have to be careful if you do stuff like that.
2881 @node Misc Group Stuff
2882 @section Misc Group Stuff
2885 * Scanning New Messages:: Asking Gnus to see whether new messages have arrived.
2886 * Group Information:: Information and help on groups and Gnus.
2887 * Group Timestamp:: Making Gnus keep track of when you last read a group.
2888 * File Commands:: Reading and writing the Gnus files.
2895 @findex gnus-group-enter-server-mode
2896 Enter the server buffer (@code{gnus-group-enter-server-mode}).
2897 @xref{The Server Buffer}.
2901 @findex gnus-group-post-news
2902 Post an article to a group (@code{gnus-group-post-news}). If given a
2903 prefix, the current group name will be used as the default.
2907 @findex gnus-group-mail
2908 Mail a message somewhere (@code{gnus-group-mail}).
2912 Variables for the group buffer:
2916 @item gnus-group-mode-hook
2917 @vindex gnus-group-mode-hook
2918 is called after the group buffer has been
2921 @item gnus-group-prepare-hook
2922 @vindex gnus-group-prepare-hook
2923 is called after the group buffer is
2924 generated. It may be used to modify the buffer in some strange,
2927 @item gnus-group-prepared-hook
2928 @vindex gnus-group-prepare-hook
2929 is called as the very last thing after the group buffer has been
2930 generated. It may be used to move point around, for instance.
2932 @item gnus-permanently-visible-groups
2933 @vindex gnus-permanently-visible-groups
2934 Groups matching this regexp will always be listed in the group buffer,
2935 whether they are empty or not.
2940 @node Scanning New Messages
2941 @subsection Scanning New Messages
2942 @cindex new messages
2943 @cindex scanning new news
2949 @findex gnus-group-get-new-news
2950 @c @icon{gnus-group-get-new-news}
2951 Check the server(s) for new articles. If the numerical prefix is used,
2952 this command will check only groups of level @var{arg} and lower
2953 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
2954 command will force a total re-reading of the active file(s) from the
2959 @findex gnus-group-get-new-news-this-group
2960 @vindex gnus-goto-next-group-when-activating
2961 @c @icon{gnus-group-get-new-news-this-group}
2962 Check whether new articles have arrived in the current group
2963 (@code{gnus-group-get-new-news-this-group}).
2964 @code{gnus-goto-next-group-when-activating} says whether this command is
2965 to move point to the next group or not. It is @code{t} by default.
2967 @findex gnus-activate-all-groups
2968 @cindex activating groups
2970 @kindex C-c M-g (Group)
2971 Activate absolutely all groups (@code{gnus-activate-all-groups}).
2976 @findex gnus-group-restart
2977 Restart Gnus (@code{gnus-group-restart}). This saves the @file{.newsrc}
2978 file(s), closes the connection to all servers, clears up all run-time
2979 Gnus variables, and then starts Gnus all over again.
2983 @vindex gnus-get-new-news-hook
2984 @code{gnus-get-new-news-hook} is run just before checking for new news.
2986 @vindex gnus-after-getting-new-news-hook
2987 @code{gnus-after-getting-new-news-hook} is run after checking for new
2991 @node Group Information
2992 @subsection Group Information
2993 @cindex group information
2994 @cindex information on groups
3001 @findex gnus-group-fetch-faq
3002 @vindex gnus-group-faq-directory
3005 Try to fetch the FAQ for the current group
3006 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
3007 @code{gnus-group-faq-directory}, which is usually a directory on a
3008 remote machine. This variable can also be a list of directories. In
3009 that case, giving a prefix to this command will allow you to choose
3010 between the various sites. @code{ange-ftp} (or @code{efs}) will be used
3011 for fetching the file.
3013 If fetching from the first site is unsuccessful, Gnus will attempt to go
3014 through @code{gnus-group-faq-directory} and try to open them one by one.
3018 @c @icon{gnus-group-describe-group}
3020 @kindex C-c C-d (Group)
3021 @cindex describing groups
3022 @cindex group description
3023 @findex gnus-group-describe-group
3024 Describe the current group (@code{gnus-group-describe-group}). If given
3025 a prefix, force Gnus to re-read the description from the server.
3029 @findex gnus-group-describe-all-groups
3030 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
3031 prefix, force Gnus to re-read the description file from the server.
3038 @findex gnus-version
3039 Display current Gnus version numbers (@code{gnus-version}).
3043 @findex gnus-group-describe-briefly
3044 Give a very short help message (@code{gnus-group-describe-briefly}).
3047 @kindex C-c C-i (Group)
3050 @findex gnus-info-find-node
3051 Go to the Gnus info node (@code{gnus-info-find-node}).
3055 @node Group Timestamp
3056 @subsection Group Timestamp
3058 @cindex group timestamps
3060 It can be convenient to let Gnus keep track of when you last read a
3061 group. To set the ball rolling, you should add
3062 @code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}:
3065 (add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp)
3068 After doing this, each time you enter a group, it'll be recorded.
3070 This information can be displayed in various ways---the easiest is to
3071 use the @samp{%d} spec in the group line format:
3074 (setq gnus-group-line-format
3075 "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n")
3078 This will result in lines looking like:
3081 * 0: mail.ding 19961002T012943
3082 0: custom 19961002T012713
3085 As you can see, the date is displayed in compact ISO 8601 format. This
3086 may be a bit too much, so to just display the date, you could say
3090 (setq gnus-group-line-format
3091 "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n")
3096 @subsection File Commands
3097 @cindex file commands
3103 @findex gnus-group-read-init-file
3104 @vindex gnus-init-file
3105 @cindex reading init file
3106 Re-read the init file (@code{gnus-init-file}, which defaults to
3107 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
3111 @findex gnus-group-save-newsrc
3112 @cindex saving .newsrc
3113 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
3114 (@code{gnus-group-save-newsrc}). If given a prefix, force saving the
3115 file(s) whether Gnus thinks it is necessary or not.
3118 @c @kindex Z (Group)
3119 @c @findex gnus-group-clear-dribble
3120 @c Clear the dribble buffer (@code{gnus-group-clear-dribble}).
3125 @node The Summary Buffer
3126 @chapter The Summary Buffer
3127 @cindex summary buffer
3129 A line for each article is displayed in the summary buffer. You can
3130 move around, read articles, post articles and reply to articles.
3132 The most common way to a summary buffer is to select a group from the
3133 group buffer (@pxref{Selecting a Group}).
3135 You can have as many summary buffers open as you wish.
3138 * Summary Buffer Format:: Deciding how the summary buffer is to look.
3139 * Summary Maneuvering:: Moving around the summary buffer.
3140 * Choosing Articles:: Reading articles.
3141 * Paging the Article:: Scrolling the current article.
3142 * Reply Followup and Post:: Posting articles.
3143 * Canceling and Superseding:: ``Whoops, I shouldn't have called him that.''
3144 * Marking Articles:: Marking articles as read, expirable, etc.
3145 * Limiting:: You can limit the summary buffer.
3146 * Threading:: How threads are made.
3147 * Sorting:: How articles and threads are sorted.
3148 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
3149 * Article Caching:: You may store articles in a cache.
3150 * Persistent Articles:: Making articles expiry-resistant.
3151 * Article Backlog:: Having already read articles hang around.
3152 * Saving Articles:: Ways of customizing article saving.
3153 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
3154 * Article Treatment:: The article buffer can be mangled at will.
3155 * Article Commands:: Doing various things with the article buffer.
3156 * Summary Sorting:: Sorting the summary buffer in various ways.
3157 * Finding the Parent:: No child support? Get the parent.
3158 * Alternative Approaches:: Reading using non-default summaries.
3159 * Tree Display:: A more visual display of threads.
3160 * Mail Group Commands:: Some commands can only be used in mail groups.
3161 * Various Summary Stuff:: What didn't fit anywhere else.
3162 * Exiting the Summary Buffer:: Returning to the Group buffer.
3163 * Crosspost Handling:: How crossposted articles are dealt with.
3164 * Duplicate Suppression:: An alternative when crosspost handling fails.
3168 @node Summary Buffer Format
3169 @section Summary Buffer Format
3170 @cindex summary buffer format
3174 \gnusfigure{The Summary Buffer}{180}{
3175 \put(0,0){\epsfig{figure=tmp/summary.ps,width=7.5cm}}
3176 \put(445,0){\makebox(0,0)[br]{\epsfig{figure=tmp/summary-article.ps,width=7.5cm}}}
3182 * Summary Buffer Lines:: You can specify how summary lines should look.
3183 * Summary Buffer Mode Line:: You can say how the mode line should look.
3184 * Summary Highlighting:: Making the summary buffer all pretty and nice.
3187 @findex mail-extract-address-components
3188 @findex gnus-extract-address-components
3189 @vindex gnus-extract-address-components
3190 Gnus will use the value of the @code{gnus-extract-address-components}
3191 variable as a function for getting the name and address parts of a
3192 @code{From} header. Two pre-defined functions exist:
3193 @code{gnus-extract-address-components}, which is the default, quite
3194 fast, and too simplistic solution; and
3195 @code{mail-extract-address-components}, which works very nicely, but is
3196 slower. The default function will return the wrong answer in 5% of the
3197 cases. If this is unacceptable to you, use the other function instead.
3199 @vindex gnus-summary-same-subject
3200 @code{gnus-summary-same-subject} is a string indicating that the current
3201 article has the same subject as the previous. This string will be used
3202 with those specs that require it. The default is @code{""}.
3205 @node Summary Buffer Lines
3206 @subsection Summary Buffer Lines
3208 @vindex gnus-summary-line-format
3209 You can change the format of the lines in the summary buffer by changing
3210 the @code{gnus-summary-line-format} variable. It works along the same
3211 lines as a normal @code{format} string, with some extensions
3212 (@pxref{Formatting Variables}).
3214 The default string is @samp{%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n}.
3216 The following format specification characters are understood:
3224 Subject if the article is the root of the thread or the previous article
3225 had a different subject, @code{gnus-summary-same-subject} otherwise.
3226 (@code{gnus-summary-same-subject} defaults to @code{""}.)
3228 Full @code{From} header.
3230 The name (from the @code{From} header).
3232 The name (from the @code{From} header). This differs from the @code{n}
3233 spec in that it uses the function designated by the
3234 @code{gnus-extract-address-components} variable, which is slower, but
3235 may be more thorough.
3237 The address (from the @code{From} header). This works the same way as
3240 Number of lines in the article.
3242 Number of characters in the article.
3244 Indentation based on thread level (@pxref{Customizing Threading}).
3246 Nothing if the article is a root and lots of spaces if it isn't (it
3247 pushes everything after it off the screen).
3249 Opening bracket, which is normally @samp{[}, but can also be @samp{<}
3250 for adopted articles (@pxref{Customizing Threading}).
3252 Closing bracket, which is normally @samp{]}, but can also be @samp{>}
3253 for adopted articles.
3255 One space for each thread level.
3257 Twenty minus thread level spaces.
3263 Score as a number (@pxref{Scoring}).
3265 @vindex gnus-summary-zcore-fuzz
3266 Zcore, @samp{+} if above the default level and @samp{-} if below the
3267 default level. If the difference between
3268 @code{gnus-summary-default-level} and the score is less than
3269 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
3277 The @code{Date} in @code{DD-MMM} format.
3279 The @code{Date} in @var{YYYYMMDD}@code{T}@var{HHMMSS} format.
3285 Number of articles in the current sub-thread. Using this spec will slow
3286 down summary buffer generation somewhat.
3288 An @samp{=} (@code{gnus-not-empty-thread-mark}) will be displayed if the
3289 article has any children.
3295 User defined specifier. The next character in the format string should
3296 be a letter. Gnus will call the function
3297 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
3298 following @samp{%u}. The function will be passed the current header as
3299 argument. The function should return a string, which will be inserted
3300 into the summary just like information from any other summary specifier.
3303 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
3304 have to be handled with care. For reasons of efficiency, Gnus will
3305 compute what column these characters will end up in, and ``hard-code''
3306 that. This means that it is invalid to have these specs after a
3307 variable-length spec. Well, you might not be arrested, but your summary
3308 buffer will look strange, which is bad enough.
3310 The smart choice is to have these specs as far to the left as possible.
3311 (Isn't that the case with everything, though? But I digress.)
3313 This restriction may disappear in later versions of Gnus.
3316 @node Summary Buffer Mode Line
3317 @subsection Summary Buffer Mode Line
3319 @vindex gnus-summary-mode-line-format
3320 You can also change the format of the summary mode bar. Set
3321 @code{gnus-summary-mode-line-format} to whatever you like. The default
3322 is @samp{Gnus: %%b [%A] %Z}.
3324 Here are the elements you can play with:
3330 Unprefixed group name.
3332 Current article number.
3336 Number of unread articles in this group.
3338 Number of unread articles in this group that aren't displayed in the
3341 A string with the number of unread and unselected articles represented
3342 either as @samp{<%U(+%e) more>} if there are both unread and unselected
3343 articles, and just as @samp{<%U more>} if there are just unread articles
3344 and no unselected ones.
3346 Shortish group name. For instance, @samp{rec.arts.anime} will be
3347 shortened to @samp{r.a.anime}.
3349 Subject of the current article.
3351 User-defined spec (@pxref{User-Defined Specs}).
3353 Name of the current score file (@pxref{Scoring}).
3355 Number of dormant articles (@pxref{Unread Articles}).
3357 Number of ticked articles (@pxref{Unread Articles}).
3359 Number of articles that have been marked as read in this session.
3361 Number of articles expunged by the score files.
3365 @node Summary Highlighting
3366 @subsection Summary Highlighting
3370 @item gnus-visual-mark-article-hook
3371 @vindex gnus-visual-mark-article-hook
3372 This hook is run after selecting an article. It is meant to be used for
3373 highlighting the article in some way. It is not run if
3374 @code{gnus-visual} is @code{nil}.
3376 @item gnus-summary-update-hook
3377 @vindex gnus-summary-update-hook
3378 This hook is called when a summary line is changed. It is not run if
3379 @code{gnus-visual} is @code{nil}.
3381 @item gnus-summary-selected-face
3382 @vindex gnus-summary-selected-face
3383 This is the face (or @dfn{font} as some people call it) used to
3384 highlight the current article in the summary buffer.
3386 @item gnus-summary-highlight
3387 @vindex gnus-summary-highlight
3388 Summary lines are highlighted according to this variable, which is a
3389 list where the elements are of the format @var{(FORM . FACE)}. If you
3390 would, for instance, like ticked articles to be italic and high-scored
3391 articles to be bold, you could set this variable to something like
3393 (((eq mark gnus-ticked-mark) . italic)
3394 ((> score default) . bold))
3396 As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
3397 @var{FACE} will be applied to the line.
3401 @node Summary Maneuvering
3402 @section Summary Maneuvering
3403 @cindex summary movement
3405 All the straight movement commands understand the numeric prefix and
3406 behave pretty much as you'd expect.
3408 None of these commands select articles.
3413 @kindex M-n (Summary)
3414 @kindex G M-n (Summary)
3415 @findex gnus-summary-next-unread-subject
3416 Go to the next summary line of an unread article
3417 (@code{gnus-summary-next-unread-subject}).
3421 @kindex M-p (Summary)
3422 @kindex G M-p (Summary)
3423 @findex gnus-summary-prev-unread-subject
3424 Go to the previous summary line of an unread article
3425 (@code{gnus-summary-prev-unread-subject}).
3430 @kindex G j (Summary)
3431 @findex gnus-summary-goto-article
3432 Ask for an article number or @code{Message-ID}, and then go to that
3433 article (@code{gnus-summary-goto-article}).
3436 @kindex G g (Summary)
3437 @findex gnus-summary-goto-subject
3438 Ask for an article number and then go to the summary line of that article
3439 without displaying the article (@code{gnus-summary-goto-subject}).
3442 If Gnus asks you to press a key to confirm going to the next group, you
3443 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
3444 buffer, searching for the next group to read without actually returning
3445 to the group buffer.
3447 Variables related to summary movement:
3451 @vindex gnus-auto-select-next
3452 @item gnus-auto-select-next
3453 If you issue one of the movement commands (like @kbd{n}) and there are
3454 no more unread articles after the current one, Gnus will offer to go to
3455 the next group. If this variable is @code{t} and the next group is
3456 empty, Gnus will exit summary mode and return to the group buffer. If
3457 this variable is neither @code{t} nor @code{nil}, Gnus will select the
3458 next group, no matter whether it has any unread articles or not. As a
3459 special case, if this variable is @code{quietly}, Gnus will select the
3460 next group without asking for confirmation. If this variable is
3461 @code{almost-quietly}, the same will happen only if you are located on
3462 the last article in the group. Finally, if this variable is
3463 @code{slightly-quietly}, the @kbd{Z n} command will go to the next group
3464 without confirmation. Also @pxref{Group Levels}.
3466 @item gnus-auto-select-same
3467 @vindex gnus-auto-select-same
3468 If non-@code{nil}, all the movement commands will try to go to the next
3469 article with the same subject as the current. (@dfn{Same} here might
3470 mean @dfn{roughly equal}. See @code{gnus-summary-gather-subject-limit}
3471 for details (@pxref{Customizing Threading}).) This variable is not
3472 particularly useful if you use a threaded display.
3474 @item gnus-summary-check-current
3475 @vindex gnus-summary-check-current
3476 If non-@code{nil}, all the ``unread'' movement commands will not proceed
3477 to the next (or previous) article if the current article is unread.
3478 Instead, they will choose the current article.
3480 @item gnus-auto-center-summary
3481 @vindex gnus-auto-center-summary
3482 If non-@code{nil}, Gnus will keep the point in the summary buffer
3483 centered at all times. This makes things quite tidy, but if you have a
3484 slow network connection, or simply do not like this un-Emacsism, you can
3485 set this variable to @code{nil} to get the normal Emacs scrolling
3486 action. This will also inhibit horizontal re-centering of the summary
3487 buffer, which might make it more inconvenient to read extremely long
3493 @node Choosing Articles
3494 @section Choosing Articles
3495 @cindex selecting articles
3498 * Choosing Commands:: Commands for choosing articles.
3499 * Choosing Variables:: Variables that influence these commands.
3503 @node Choosing Commands
3504 @subsection Choosing Commands
3506 None of the following movement commands understand the numeric prefix,
3507 and they all select and display an article.
3511 @kindex SPACE (Summary)
3512 @findex gnus-summary-next-page
3513 Select the current article, or, if that one's read already, the next
3514 unread article (@code{gnus-summary-next-page}).
3519 @kindex G n (Summary)
3520 @findex gnus-summary-next-unread-article
3521 @c @icon{gnus-summary-next-unread}
3522 Go to next unread article (@code{gnus-summary-next-unread-article}).
3527 @findex gnus-summary-prev-unread-article
3528 @c @icon{gnus-summary-prev-unread}
3529 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
3534 @kindex G N (Summary)
3535 @findex gnus-summary-next-article
3536 Go to the next article (@code{gnus-summary-next-article}).
3541 @kindex G P (Summary)
3542 @findex gnus-summary-prev-article
3543 Go to the previous article (@code{gnus-summary-prev-article}).
3546 @kindex G C-n (Summary)
3547 @findex gnus-summary-next-same-subject
3548 Go to the next article with the same subject
3549 (@code{gnus-summary-next-same-subject}).
3552 @kindex G C-p (Summary)
3553 @findex gnus-summary-prev-same-subject
3554 Go to the previous article with the same subject
3555 (@code{gnus-summary-prev-same-subject}).
3559 @kindex G f (Summary)
3561 @findex gnus-summary-first-unread-article
3562 Go to the first unread article
3563 (@code{gnus-summary-first-unread-article}).
3567 @kindex G b (Summary)
3569 @findex gnus-summary-best-unread-article
3570 Go to the article with the highest score
3571 (@code{gnus-summary-best-unread-article}).
3576 @kindex G l (Summary)
3577 @findex gnus-summary-goto-last-article
3578 Go to the previous article read (@code{gnus-summary-goto-last-article}).
3581 @kindex G o (Summary)
3582 @findex gnus-summary-pop-article
3584 @cindex article history
3585 Pop an article off the summary history and go to this article
3586 (@code{gnus-summary-pop-article}). This command differs from the
3587 command above in that you can pop as many previous articles off the
3588 history as you like, while @kbd{l} toggles the two last read articles.
3589 For a somewhat related issue (if you use these commands a lot),
3590 @pxref{Article Backlog}.
3594 @node Choosing Variables
3595 @subsection Choosing Variables
3597 Some variables relevant for moving and selecting articles:
3600 @item gnus-auto-extend-newsgroup
3601 @vindex gnus-auto-extend-newsgroup
3602 All the movement commands will try to go to the previous (or next)
3603 article, even if that article isn't displayed in the Summary buffer if
3604 this variable is non-@code{nil}. Gnus will then fetch the article from
3605 the server and display it in the article buffer.
3607 @item gnus-select-article-hook
3608 @vindex gnus-select-article-hook
3609 This hook is called whenever an article is selected. By default it
3610 exposes any threads hidden under the selected article.
3612 @item gnus-mark-article-hook
3613 @vindex gnus-mark-article-hook
3614 @findex gnus-summary-mark-unread-as-read
3615 @findex gnus-summary-mark-read-and-unread-as-read
3616 @findex gnus-unread-mark
3617 This hook is called whenever an article is selected. It is intended to
3618 be used for marking articles as read. The default value is
3619 @code{gnus-summary-mark-read-and-unread-as-read}, and will change the
3620 mark of almost any article you read to @code{gnus-unread-mark}. The
3621 only articles not affected by this function are ticked, dormant, and
3622 expirable articles. If you'd instead like to just have unread articles
3623 marked as read, you can use @code{gnus-summary-mark-unread-as-read}
3624 instead. It will leave marks like @code{gnus-low-score-mark},
3625 @code{gnus-del-mark} (and so on) alone.
3630 @node Paging the Article
3631 @section Scrolling the Article
3632 @cindex article scrolling
3637 @kindex SPACE (Summary)
3638 @findex gnus-summary-next-page
3639 Pressing @kbd{SPACE} will scroll the current article forward one page,
3640 or, if you have come to the end of the current article, will choose the
3641 next article (@code{gnus-summary-next-page}).
3644 @kindex DEL (Summary)
3645 @findex gnus-summary-prev-page
3646 Scroll the current article back one page (@code{gnus-summary-prev-page}).
3649 @kindex RET (Summary)
3650 @findex gnus-summary-scroll-up
3651 Scroll the current article one line forward
3652 (@code{gnus-summary-scroll-up}).
3656 @kindex A g (Summary)
3658 @findex gnus-summary-show-article
3659 (Re)fetch the current article (@code{gnus-summary-show-article}). If
3660 given a prefix, fetch the current article, but don't run any of the
3661 article treatment functions. This will give you a ``raw'' article, just
3662 the way it came from the server.
3667 @kindex A < (Summary)
3668 @findex gnus-summary-beginning-of-article
3669 Scroll to the beginning of the article
3670 (@code{gnus-summary-beginning-of-article}).
3675 @kindex A > (Summary)
3676 @findex gnus-summary-end-of-article
3677 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
3681 @kindex A s (Summary)
3683 @findex gnus-summary-isearch-article
3684 Perform an isearch in the article buffer
3685 (@code{gnus-summary-isearch-article}).
3689 @findex gnus-summary-select-article-buffer
3690 Select the article buffer (@code{gnus-summary-select-article-buffer}).
3695 @node Reply Followup and Post
3696 @section Reply, Followup and Post
3699 * Summary Mail Commands:: Sending mail.
3700 * Summary Post Commands:: Sending news.
3704 @node Summary Mail Commands
3705 @subsection Summary Mail Commands
3707 @cindex composing mail
3709 Commands for composing a mail message:
3715 @kindex S r (Summary)
3717 @findex gnus-summary-reply
3718 @c @icon{gnus-summary-mail-reply}
3719 @c @icon{gnus-summary-reply}
3720 Mail a reply to the author of the current article
3721 (@code{gnus-summary-reply}).
3726 @kindex S R (Summary)
3727 @findex gnus-summary-reply-with-original
3728 @c @icon{gnus-summary-reply-with-original}
3729 Mail a reply to the author of the current article and include the
3730 original message (@code{gnus-summary-reply-with-original}). This
3731 command uses the process/prefix convention.
3734 @kindex S w (Summary)
3735 @findex gnus-summary-wide-reply
3736 Mail a wide reply to the author of the current article
3737 (@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that
3738 goes out to all people listed in the @code{To}, @code{From} (or
3739 @code{Reply-to}) and @code{Cc} headers.
3742 @kindex S W (Summary)
3743 @findex gnus-summary-wide-reply-with-original
3744 Mail a wide reply to the current article and include the original
3745 message (@code{gnus-summary-reply-with-original}). This command uses
3746 the process/prefix convention.
3749 @kindex S o m (Summary)
3750 @findex gnus-summary-mail-forward
3751 @c @icon{gnus-summary-mail-forward}
3752 Forward the current article to some other person
3753 (@code{gnus-summary-mail-forward}). If given a prefix, include the full
3754 headers of the forwarded article.
3759 @kindex S m (Summary)
3760 @findex gnus-summary-mail-other-window
3761 @c @icon{gnus-summary-mail-originate}
3762 Send a mail to some other person
3763 (@code{gnus-summary-mail-other-window}).
3766 @kindex S D b (Summary)
3767 @findex gnus-summary-resend-bounced-mail
3768 @cindex bouncing mail
3769 If you have sent a mail, but the mail was bounced back to you for some
3770 reason (wrong address, transient failure), you can use this command to
3771 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
3772 will be popped into a mail buffer where you can edit the headers before
3773 sending the mail off again. If you give a prefix to this command, and
3774 the bounced mail is a reply to some other mail, Gnus will try to fetch
3775 that mail and display it for easy perusal of its headers. This might
3776 very well fail, though.
3779 @kindex S D r (Summary)
3780 @findex gnus-summary-resend-message
3781 Not to be confused with the previous command,
3782 @code{gnus-summary-resend-message} will prompt you for an address to
3783 send the current message off to, and then send it to that place. The
3784 headers of the message won't be altered---but lots of headers that say
3785 @code{Resent-To}, @code{Resent-From} and so on will be added. This
3786 means that you actually send a mail to someone that has a @code{To}
3787 header that (probably) points to yourself. This will confuse people.
3788 So, natcherly you'll only do that if you're really eVIl.
3790 This command is mainly used if you have several accounts and want to
3791 ship a mail to a different account of yours. (If you're both
3792 @code{root} and @code{postmaster} and get a mail for @code{postmaster}
3793 to the @code{root} account, you may want to resend it to
3794 @code{postmaster}. Ordnung muß sein!
3796 This command understands the process/prefix convention
3797 (@pxref{Process/Prefix}).
3800 @kindex S O m (Summary)
3801 @findex gnus-uu-digest-mail-forward
3802 Digest the current series (@pxref{Decoding Articles}) and forward the
3803 result using mail (@code{gnus-uu-digest-mail-forward}). This command
3804 uses the process/prefix convention (@pxref{Process/Prefix}).
3807 @kindex S M-c (Summary)
3808 @findex gnus-summary-mail-crosspost-complaint
3809 @cindex crossposting
3810 @cindex excessive crossposting
3811 Send a complaint about excessive crossposting to the author of the
3812 current article (@code{gnus-summary-mail-crosspost-complaint}).
3814 @findex gnus-crosspost-complaint
3815 This command is provided as a way to fight back agains the current
3816 crossposting pandemic that's sweeping Usenet. It will compose a reply
3817 using the @code{gnus-crosspost-complaint} variable as a preamble. This
3818 command understands the process/prefix convention
3819 (@pxref{Process/Prefix}) and will prompt you before sending each mail.
3824 @node Summary Post Commands
3825 @subsection Summary Post Commands
3827 @cindex composing news
3829 Commands for posting a news article:
3835 @kindex S p (Summary)
3836 @findex gnus-summary-post-news
3837 @c @icon{gnus-summary-post-news}
3838 Post an article to the current group
3839 (@code{gnus-summary-post-news}).
3844 @kindex S f (Summary)
3845 @findex gnus-summary-followup
3846 @c @icon{gnus-summary-followup}
3847 Post a followup to the current article (@code{gnus-summary-followup}).
3851 @kindex S F (Summary)
3853 @c @icon{gnus-summary-followup-with-original}
3854 @findex gnus-summary-followup-with-original
3855 Post a followup to the current article and include the original message
3856 (@code{gnus-summary-followup-with-original}). This command uses the
3857 process/prefix convention.
3860 @kindex S n (Summary)
3861 @findex gnus-summary-followup-to-mail
3862 Post a followup to the current article via news, even if you got the
3863 message through mail (@code{gnus-summary-followup-to-mail}).
3866 @kindex S n (Summary)
3867 @findex gnus-summary-followup-to-mail
3868 Post a followup to the current article via news, even if you got the
3869 message through mail and include the original message
3870 (@code{gnus-summary-followup-to-mail-with-original}). This command uses
3871 the process/prefix convention.
3874 @kindex S o p (Summary)
3875 @findex gnus-summary-post-forward
3876 Forward the current article to a newsgroup
3877 (@code{gnus-summary-post-forward}). If given a prefix, include the full
3878 headers of the forwarded article.
3881 @kindex S O p (Summary)
3882 @findex gnus-uu-digest-post-forward
3884 @cindex making digests
3885 Digest the current series and forward the result to a newsgroup
3886 (@code{gnus-uu-digest-mail-forward}). This command uses the
3887 process/prefix convention.
3890 @kindex S u (Summary)
3891 @findex gnus-uu-post-news
3892 @c @icon{gnus-uu-post-news}
3893 Uuencode a file, split it into parts, and post it as a series
3894 (@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}).
3898 @node Canceling and Superseding
3899 @section Canceling Articles
3900 @cindex canceling articles
3901 @cindex superseding articles
3903 Have you ever written something, and then decided that you really,
3904 really, really wish you hadn't posted that?
3906 Well, you can't cancel mail, but you can cancel posts.
3908 @findex gnus-summary-cancel-article
3910 @c @icon{gnus-summary-cancel-article}
3911 Find the article you wish to cancel (you can only cancel your own
3912 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
3913 c} (@code{gnus-summary-cancel-article}). Your article will be
3914 canceled---machines all over the world will be deleting your article.
3915 This command uses the process/prefix convention (@pxref{Process/Prefix}).
3917 Be aware, however, that not all sites honor cancels, so your article may
3918 live on here and there, while most sites will delete the article in
3921 Gnus will use the ``current'' select method when cancelling. If you
3922 want to use the standard posting method, use the @samp{a} symbolic
3923 prefix (@pxref{Symbolic Prefixes}).
3925 If you discover that you have made some mistakes and want to do some
3926 corrections, you can post a @dfn{superseding} article that will replace
3927 your original article.
3929 @findex gnus-summary-supersede-article
3931 Go to the original article and press @kbd{S s}
3932 (@code{gnus-summary-supersede-article}). You will be put in a buffer
3933 where you can edit the article all you want before sending it off the
3936 The same goes for superseding as for canceling, only more so: Some
3937 sites do not honor superseding. On those sites, it will appear that you
3938 have posted almost the same article twice.
3940 If you have just posted the article, and change your mind right away,
3941 there is a trick you can use to cancel/supersede the article without
3942 waiting for the article to appear on your site first. You simply return
3943 to the post buffer (which is called @code{*sent ...*}). There you will
3944 find the article you just posted, with all the headers intact. Change
3945 the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes}
3946 header by substituting one of those words for the word
3947 @code{Message-ID}. Then just press @kbd{C-c C-c} to send the article as
3948 you would do normally. The previous article will be
3949 canceled/superseded.
3951 Just remember, kids: There is no 'c' in 'supersede'.
3954 @node Marking Articles
3955 @section Marking Articles
3956 @cindex article marking
3957 @cindex article ticking
3960 There are several marks you can set on an article.
3962 You have marks that decide the @dfn{readedness} (whoo, neato-keano
3963 neologism ohoy!) of the article. Alphabetic marks generally mean
3964 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
3966 In addition, you also have marks that do not affect readedness.
3969 * Unread Articles:: Marks for unread articles.
3970 * Read Articles:: Marks for read articles.
3971 * Other Marks:: Marks that do not affect readedness.
3975 There's a plethora of commands for manipulating these marks:
3979 * Setting Marks:: How to set and remove marks.
3980 * Setting Process Marks:: How to mark articles for later processing.
3984 @node Unread Articles
3985 @subsection Unread Articles
3987 The following marks mark articles as (kinda) unread, in one form or
3992 @vindex gnus-ticked-mark
3993 Marked as ticked (@code{gnus-ticked-mark}).
3995 @dfn{Ticked articles} are articles that will remain visible always. If
3996 you see an article that you find interesting, or you want to put off
3997 reading it, or replying to it, until sometime later, you'd typically
3998 tick it. However, articles can be expired, so if you want to keep an
3999 article forever, you'll have to make it persistent (@pxref{Persistent
4003 @vindex gnus-dormant-mark
4004 Marked as dormant (@code{gnus-dormant-mark}).
4006 @dfn{Dormant articles} will only appear in the summary buffer if there
4007 are followups to it. If you want to see them even if they don't have
4008 followups, you can use the @kbd{/ D} command (@pxref{Limiting}).
4011 @vindex gnus-unread-mark
4012 Markes as unread (@code{gnus-unread-mark}).
4014 @dfn{Unread articles} are articles that haven't been read at all yet.
4019 @subsection Read Articles
4020 @cindex expirable mark
4022 All the following marks mark articles as read.
4027 @vindex gnus-del-mark
4028 These are articles that the user has marked as read with the @kbd{d}
4029 command manually, more or less (@code{gnus-del-mark}).
4032 @vindex gnus-read-mark
4033 Articles that have actually been read (@code{gnus-read-mark}).
4036 @vindex gnus-ancient-mark
4037 Articles that were marked as read in previous sessions and are now
4038 @dfn{old} (@code{gnus-ancient-mark}).
4041 @vindex gnus-killed-mark
4042 Marked as killed (@code{gnus-killed-mark}).
4045 @vindex gnus-kill-file-mark
4046 Marked as killed by kill files (@code{gnus-kill-file-mark}).
4049 @vindex gnus-low-score-mark
4050 Marked as read by having too low a score (@code{gnus-low-score-mark}).
4053 @vindex gnus-catchup-mark
4054 Marked as read by a catchup (@code{gnus-catchup-mark}).
4057 @vindex gnus-canceled-mark
4058 Canceled article (@code{gnus-canceled-mark})
4061 @vindex gnus-souped-mark
4062 @sc{SOUP}ed article (@code{gnus-souped-mark}). @xref{SOUP}.
4065 @vindex gnus-sparse-mark
4066 Sparsely reffed article (@code{gnus-sparse-mark}). @xref{Customizing
4070 @vindex gnus-duplicate-mark
4071 Article marked as read by duplicate suppression
4072 (@code{gnus-duplicated-mark}). @xref{Duplicate Suppression}.
4076 All these marks just mean that the article is marked as read, really.
4077 They are interpreted differently when doing adaptive scoring, though.
4079 One more special mark, though:
4083 @vindex gnus-expirable-mark
4084 Marked as expirable (@code{gnus-expirable-mark}).
4086 Marking articles as @dfn{expirable} (or have them marked as such
4087 automatically) doesn't make much sense in normal groups---a user doesn't
4088 control expiring of news articles, but in mail groups, for instance,
4089 articles marked as @dfn{expirable} can be deleted by Gnus at
4095 @subsection Other Marks
4096 @cindex process mark
4099 There are some marks that have nothing to do with whether the article is
4105 You can set a bookmark in the current article. Say you are reading a
4106 long thesis on cats' urinary tracts, and have to go home for dinner
4107 before you've finished reading the thesis. You can then set a bookmark
4108 in the article, and Gnus will jump to this bookmark the next time it
4109 encounters the article. @xref{Setting Marks}
4112 @vindex gnus-replied-mark
4113 All articles that you have replied to or made a followup to (i.e., have
4114 answered) will be marked with an @samp{A} in the second column
4115 (@code{gnus-replied-mark}).
4118 @vindex gnus-cached-mark
4119 Articles stored in the article cache will be marked with an @samp{*} in
4120 the second column (@code{gnus-cached-mark}). @xref{Article Caching}
4123 @vindex gnus-saved-mark
4124 Articles ``saved'' (in some manner or other; not necessarily
4125 religiously) are marked with an @samp{S} in the second column
4126 (@code{gnus-saved-mark}).
4129 @vindex gnus-not-empty-thread-mark
4130 @vindex gnus-empty-thread-mark
4131 If the @samp{%e} spec is used, the presence of threads or not will be
4132 marked with @code{gnus-not-empty-thread-mark} and
4133 @code{gnus-empty-thread-mark} in the third column, respectively.
4136 @vindex gnus-process-mark
4137 Finally we have the @dfn{process mark} (@code{gnus-process-mark}). A
4138 variety of commands react to the presence of the process mark. For
4139 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
4140 all articles that have been marked with the process mark. Articles
4141 marked with the process mark have a @samp{#} in the second column.
4145 You might have noticed that most of these ``non-readedness'' marks
4146 appear in the second column by default. So if you have a cached, saved,
4147 replied article that you have process-marked, what will that look like?
4149 Nothing much. The precedence rules go as follows: process -> cache ->
4150 replied -> saved. So if the article is in the cache and is replied,
4151 you'll only see the cache mark and not the replied mark.
4155 @subsection Setting Marks
4156 @cindex setting marks
4158 All the marking commands understand the numeric prefix.
4163 @kindex M c (Summary)
4164 @kindex M-u (Summary)
4165 @findex gnus-summary-clear-mark-forward
4166 @cindex mark as unread
4167 Clear all readedness-marks from the current article
4168 (@code{gnus-summary-clear-mark-forward}). In other words, mark the
4174 @kindex M t (Summary)
4175 @findex gnus-summary-tick-article-forward
4176 Tick the current article (@code{gnus-summary-tick-article-forward}).
4177 @xref{Article Caching}
4182 @kindex M ? (Summary)
4183 @findex gnus-summary-mark-as-dormant
4184 Mark the current article as dormant
4185 (@code{gnus-summary-mark-as-dormant}). @xref{Article Caching}
4189 @kindex M d (Summary)
4191 @findex gnus-summary-mark-as-read-forward
4192 Mark the current article as read
4193 (@code{gnus-summary-mark-as-read-forward}).
4197 @findex gnus-summary-mark-as-read-backward
4198 Mark the current article as read and move point to the previous line
4199 (@code{gnus-summary-mark-as-read-backward}).
4204 @kindex M k (Summary)
4205 @findex gnus-summary-kill-same-subject-and-select
4206 Mark all articles that have the same subject as the current one as read,
4207 and then select the next unread article
4208 (@code{gnus-summary-kill-same-subject-and-select}).
4212 @kindex M K (Summary)
4213 @kindex C-k (Summary)
4214 @findex gnus-summary-kill-same-subject
4215 Mark all articles that have the same subject as the current one as read
4216 (@code{gnus-summary-kill-same-subject}).
4219 @kindex M C (Summary)
4220 @findex gnus-summary-catchup
4221 @c @icon{gnus-summary-catchup}
4222 Mark all unread articles as read (@code{gnus-summary-catchup}).
4225 @kindex M C-c (Summary)
4226 @findex gnus-summary-catchup-all
4227 Mark all articles in the group as read---even the ticked and dormant
4228 articles (@code{gnus-summary-catchup-all}).
4231 @kindex M H (Summary)
4232 @findex gnus-summary-catchup-to-here
4233 Catchup the current group to point
4234 (@code{gnus-summary-catchup-to-here}).
4237 @kindex C-w (Summary)
4238 @findex gnus-summary-mark-region-as-read
4239 Mark all articles between point and mark as read
4240 (@code{gnus-summary-mark-region-as-read}).
4243 @kindex M V k (Summary)
4244 @findex gnus-summary-kill-below
4245 Kill all articles with scores below the default score (or below the
4246 numeric prefix) (@code{gnus-summary-kill-below}).
4250 @kindex M e (Summary)
4252 @findex gnus-summary-mark-as-expirable
4253 Mark the current article as expirable
4254 (@code{gnus-summary-mark-as-expirable}).
4257 @kindex M b (Summary)
4258 @findex gnus-summary-set-bookmark
4259 Set a bookmark in the current article
4260 (@code{gnus-summary-set-bookmark}).
4263 @kindex M B (Summary)
4264 @findex gnus-summary-remove-bookmark
4265 Remove the bookmark from the current article
4266 (@code{gnus-summary-remove-bookmark}).
4269 @kindex M V c (Summary)
4270 @findex gnus-summary-clear-above
4271 Clear all marks from articles with scores over the default score (or
4272 over the numeric prefix) (@code{gnus-summary-clear-above}).
4275 @kindex M V u (Summary)
4276 @findex gnus-summary-tick-above
4277 Tick all articles with scores over the default score (or over the
4278 numeric prefix) (@code{gnus-summary-tick-above}).
4281 @kindex M V m (Summary)
4282 @findex gnus-summary-mark-above
4283 Prompt for a mark, and mark all articles with scores over the default
4284 score (or over the numeric prefix) with this mark
4285 (@code{gnus-summary-clear-above}).
4288 @vindex gnus-summary-goto-unread
4289 The @code{gnus-summary-goto-unread} variable controls what action should
4290 be taken after setting a mark. If non-@code{nil}, point will move to
4291 the next/previous unread article. If @code{nil}, point will just move
4292 one line up or down. As a special case, if this variable is
4293 @code{never}, all the marking commands as well as other commands (like
4294 @kbd{SPACE}) will move to the next article, whether it is unread or not.
4295 The default is @code{t}.
4298 @node Setting Process Marks
4299 @subsection Setting Process Marks
4300 @cindex setting process marks
4307 @kindex M P p (Summary)
4308 @findex gnus-summary-mark-as-processable
4309 Mark the current article with the process mark
4310 (@code{gnus-summary-mark-as-processable}).
4311 @findex gnus-summary-unmark-as-processable
4315 @kindex M P u (Summary)
4316 @kindex M-# (Summary)
4317 Remove the process mark, if any, from the current article
4318 (@code{gnus-summary-unmark-as-processable}).
4321 @kindex M P U (Summary)
4322 @findex gnus-summary-unmark-all-processable
4323 Remove the process mark from all articles
4324 (@code{gnus-summary-unmark-all-processable}).
4327 @kindex M P i (Summary)
4328 @findex gnus-uu-invert-processable
4329 Invert the list of process marked articles
4330 (@code{gnus-uu-invert-processable}).
4333 @kindex M P R (Summary)
4334 @findex gnus-uu-mark-by-regexp
4335 Mark articles by a regular expression (@code{gnus-uu-mark-by-regexp}).
4338 @kindex M P r (Summary)
4339 @findex gnus-uu-mark-region
4340 Mark articles in region (@code{gnus-uu-mark-region}).
4343 @kindex M P t (Summary)
4344 @findex gnus-uu-mark-thread
4345 Mark all articles in the current (sub)thread
4346 (@code{gnus-uu-mark-thread}).
4349 @kindex M P T (Summary)
4350 @findex gnus-uu-unmark-thread
4351 Unmark all articles in the current (sub)thread
4352 (@code{gnus-uu-unmark-thread}).
4355 @kindex M P v (Summary)
4356 @findex gnus-uu-mark-over
4357 Mark all articles that have a score above the prefix argument
4358 (@code{gnus-uu-mark-over}).
4361 @kindex M P s (Summary)
4362 @findex gnus-uu-mark-series
4363 Mark all articles in the current series (@code{gnus-uu-mark-series}).
4366 @kindex M P S (Summary)
4367 @findex gnus-uu-mark-sparse
4368 Mark all series that have already had some articles marked
4369 (@code{gnus-uu-mark-sparse}).
4372 @kindex M P a (Summary)
4373 @findex gnus-uu-mark-all
4374 Mark all articles in series order (@code{gnus-uu-mark-series}).
4377 @kindex M P b (Summary)
4378 @findex gnus-uu-mark-buffer
4379 Mark all articles in the buffer in the order they appear
4380 (@code{gnus-uu-mark-buffer}).
4383 @kindex M P k (Summary)
4384 @findex gnus-summary-kill-process-mark
4385 Push the current process mark set onto the stack and unmark all articles
4386 (@code{gnus-summary-kill-process-mark}).
4389 @kindex M P y (Summary)
4390 @findex gnus-summary-yank-process-mark
4391 Pop the previous process mark set from the stack and restore it
4392 (@code{gnus-summary-yank-process-mark}).
4395 @kindex M P w (Summary)
4396 @findex gnus-summary-save-process-mark
4397 Push the current process mark set onto the stack
4398 (@code{gnus-summary-save-process-mark}).
4407 It can be convenient to limit the summary buffer to just show some
4408 subset of the articles currently in the group. The effect most limit
4409 commands have is to remove a few (or many) articles from the summary
4412 All limiting commands work on subsets of the articles already fetched
4413 from the servers. None of these commands query the server for
4414 additional articles.
4420 @kindex / / (Summary)
4421 @findex gnus-summary-limit-to-subject
4422 Limit the summary buffer to articles that match some subject
4423 (@code{gnus-summary-limit-to-subject}).
4426 @kindex / a (Summary)
4427 @findex gnus-summary-limit-to-author
4428 Limit the summary buffer to articles that match some author
4429 (@code{gnus-summary-limit-to-author}).
4433 @kindex / u (Summary)
4435 @findex gnus-summary-limit-to-unread
4436 Limit the summary buffer to articles not marked as read
4437 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
4438 buffer to articles strictly unread. This means that ticked and
4439 dormant articles will also be excluded.
4442 @kindex / m (Summary)
4443 @findex gnus-summary-limit-to-marks
4444 Ask for a mark and then limit to all articles that have not been marked
4445 with that mark (@code{gnus-summary-limit-to-marks}).
4448 @kindex / t (Summary)
4449 @findex gnus-summary-limit-to-age
4450 Ask for a number and then limit the summary buffer to articles older than (or equal to) that number of days
4451 (@code{gnus-summary-limit-to-marks}). If given a prefix, limit to
4452 articles younger than that number of days.
4455 @kindex / n (Summary)
4456 @findex gnus-summary-limit-to-articles
4457 Limit the summary buffer to the current article
4458 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
4459 convention (@pxref{Process/Prefix}).
4462 @kindex / w (Summary)
4463 @findex gnus-summary-pop-limit
4464 Pop the previous limit off the stack and restore it
4465 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
4469 @kindex / v (Summary)
4470 @findex gnus-summary-limit-to-score
4471 Limit the summary buffer to articles that have a score at or above some
4472 score (@code{gnus-summary-limit-to-score}).
4476 @kindex M S (Summary)
4477 @kindex / E (Summary)
4478 @findex gnus-summary-limit-include-expunged
4479 Display all expunged articles
4480 (@code{gnus-summary-limit-include-expunged}).
4483 @kindex / D (Summary)
4484 @findex gnus-summary-limit-include-dormant
4485 Display all dormant articles (@code{gnus-summary-limit-include-dormant}).
4488 @kindex / d (Summary)
4489 @findex gnus-summary-limit-exclude-dormant
4490 Hide all dormant articles (@code{gnus-summary-limit-exclude-dormant}).
4493 @kindex / T (Summary)
4494 @findex gnus-summary-limit-include-thread
4495 Include all the articles in the current thread.
4498 @kindex / c (Summary)
4499 @findex gnus-summary-limit-exclude-childless-dormant
4500 Hide all dormant articles that have no children
4501 (@code{gnus-summary-limit-exclude-childless-dormant}).
4504 @kindex / C (Summary)
4505 @findex gnus-summary-limit-mark-excluded-as-read
4506 Mark all excluded unread articles as read
4507 (@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix,
4508 also mark excluded ticked and dormant articles as read.
4516 @cindex article threading
4518 Gnus threads articles by default. @dfn{To thread} is to put responses
4519 to articles directly after the articles they respond to---in a
4520 hierarchical fashion.
4522 Threading is done by looking at the @code{References} headers of the
4523 articles. In a perfect world, this would be enough to build pretty
4524 trees, but unfortunately, the @code{References} header is often broken
4525 or simply missing. Weird news propagration excarcerbates the problem,
4526 so one has to employ other heuristics to get pleasing results. A
4527 plethora of approaches exists, as detailed in horrible detail in
4528 @pxref{Customizing Threading}.
4530 First, a quick overview of the concepts:
4534 The top-most article in a thread; the first article in the thread.
4537 A tree-like article structure.
4540 A small(er) section of this tree-like structure.
4543 Threads often lose their roots due to article expiry, or due to the root
4544 already having been read in a previous session, and not displayed in the
4545 summary buffer. We then typicall have many sub-threads that really
4546 belong to one thread, but are without connecting roots. These are
4547 called loose threads.
4549 @item thread gathering
4550 An attempt to gather loose threads into bigger threads.
4552 @item sparse threads
4553 A thread where the missing articles have been ``guessed'' at, and are
4554 displayed as empty lines in the summary buffer.
4560 * Customizing Threading:: Variables you can change to affect the threading.
4561 * Thread Commands:: Thread based commands in the summary buffer.
4565 @node Customizing Threading
4566 @subsection Customizing Threading
4567 @cindex customizing threading
4570 * Loose Threads:: How Gnus gathers loose threads into bigger threads.
4571 * Filling In Threads:: Making the threads displayed look fuller.
4572 * More Threading:: Even more variables for fiddling with threads.
4573 * Low-Level Threading:: You thought it was over... but you were wrong!
4578 @subsubsection Loose Threads
4581 @cindex loose threads
4584 @item gnus-summary-make-false-root
4585 @vindex gnus-summary-make-false-root
4586 If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
4587 and create a dummy root at the top. (Wait a minute. Root at the top?
4588 Yup.) Loose subtrees occur when the real root has expired, or you've
4589 read or killed the root in a previous session.
4591 When there is no real root of a thread, Gnus will have to fudge
4592 something. This variable says what fudging method Gnus should use.
4593 There are four possible values:
4597 \gnusfigure{The Summary Buffer}{390}{
4598 \put(0,0){\epsfig{figure=tmp/summary-adopt.ps,width=7.5cm}}
4599 \put(445,0){\makebox(0,0)[br]{\epsfig{figure=tmp/summary-empty.ps,width=7.5cm}}}
4600 \put(0,400){\makebox(0,0)[tl]{\epsfig{figure=tmp/summary-none.ps,width=7.5cm}}}
4601 \put(445,400){\makebox(0,0)[tr]{\epsfig{figure=tmp/summary-dummy.ps,width=7.5cm}}}
4606 @cindex adopting articles
4611 Gnus will make the first of the orphaned articles the parent. This
4612 parent will adopt all the other articles. The adopted articles will be
4613 marked as such by pointy brackets (@samp{<>}) instead of the standard
4614 square brackets (@samp{[]}). This is the default method.
4617 @vindex gnus-summary-dummy-line-format
4618 Gnus will create a dummy summary line that will pretend to be the
4619 parent. This dummy line does not correspond to any real article, so
4620 selecting it will just select the first real article after the dummy
4621 article. @code{gnus-summary-dummy-line-format} is used to specify the
4622 format of the dummy roots. It accepts only one format spec: @samp{S},
4623 which is the subject of the article. @xref{Formatting Variables}.
4626 Gnus won't actually make any article the parent, but simply leave the
4627 subject field of all orphans except the first empty. (Actually, it will
4628 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
4632 Don't make any article parent at all. Just gather the threads and
4633 display them after one another.
4636 Don't gather loose threads.
4639 @item gnus-summary-gather-subject-limit
4640 @vindex gnus-summary-gather-subject-limit
4641 Loose threads are gathered by comparing subjects of articles. If this
4642 variable is @code{nil}, Gnus requires an exact match between the
4643 subjects of the loose threads before gathering them into one big
4644 super-thread. This might be too strict a requirement, what with the
4645 presence of stupid newsreaders that chop off long subject lines. If
4646 you think so, set this variable to, say, 20 to require that only the
4647 first 20 characters of the subjects have to match. If you set this
4648 variable to a really low number, you'll find that Gnus will gather
4649 everything in sight into one thread, which isn't very helpful.
4651 @cindex fuzzy article gathering
4652 If you set this variable to the special value @code{fuzzy}, Gnus will
4653 use a fuzzy string comparison algorithm on the subjects (@pxref{Fuzzy
4656 @item gnus-simplify-subject-fuzzy-regexp
4657 @vindex gnus-simplify-subject-fuzzy-regexp
4658 This can either be a regular expression or list of regular expressions
4659 that match strings that will be removed from subjects if fuzzy subject
4660 simplification is used.
4662 @item gnus-simplify-ignored-prefixes
4663 @vindex gnus-simplify-ignored-prefixes
4664 If you set @code{gnus-summary-gather-subject-limit} to something as low
4665 as 10, you might consider setting this variable to something sensible:
4667 @c Written by Michael Ernst <mernst@cs.rice.edu>
4669 (setq gnus-simplify-ignored-prefixes
4675 "wanted" "followup" "summary\\( of\\)?"
4676 "help" "query" "problem" "question"
4677 "answer" "reference" "announce"
4678 "How can I" "How to" "Comparison of"
4683 (mapconcat 'identity
4684 '("for" "for reference" "with" "about")
4686 "\\)?\\]?:?[ \t]*"))
4689 All words that match this regexp will be removed before comparing two
4692 @item gnus-simplify-subject-functions
4693 @vindex gnus-simplify-subject-functions
4694 If non-@code{nil}, this variable overrides
4695 @code{gnus-summary-gather-subject-limit}. This variable should be a
4696 list of functions to apply to the @code{Subject} string iteratively to
4697 arrive at the simplified version of the string.
4699 Useful functions to put in this list include:
4702 @item gnus-simplify-subject-re
4703 @findex gnus-simplify-subject-re
4704 Strip the leading @samp{Re:}.
4706 @item gnus-simplify-subject-fuzzy
4707 @findex gnus-simplify-subject-fuzzy
4710 @item gnus-simplify-whitespace
4711 @findex gnus-simplify-whitespace
4712 Remove excessive whitespace.
4715 You may also write your own functions, of course.
4718 @item gnus-summary-gather-exclude-subject
4719 @vindex gnus-summary-gather-exclude-subject
4720 Since loose thread gathering is done on subjects only, that might lead
4721 to many false hits, especially with certain common subjects like
4722 @samp{} and @samp{(none)}. To make the situation slightly better,
4723 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
4724 what subjects should be excluded from the gathering process.@*
4725 The default is @samp{^ *$\\|^(none)$}.
4727 @item gnus-summary-thread-gathering-function
4728 @vindex gnus-summary-thread-gathering-function
4729 Gnus gathers threads by looking at @code{Subject} headers. This means
4730 that totally unrelated articles may end up in the same ``thread'', which
4731 is confusing. An alternate approach is to look at all the
4732 @code{Message-ID}s in all the @code{References} headers to find matches.
4733 This will ensure that no gathered threads ever include unrelated
4734 articles, but it also means that people who have posted with broken
4735 newsreaders won't be gathered properly. The choice is yours---plague or
4739 @item gnus-gather-threads-by-subject
4740 @findex gnus-gather-threads-by-subject
4741 This function is the default gathering function and looks at
4742 @code{Subject}s exclusively.
4744 @item gnus-gather-threads-by-references
4745 @findex gnus-gather-threads-by-references
4746 This function looks at @code{References} headers exclusively.
4749 If you want to test gathering by @code{References}, you could say
4753 (setq gnus-summary-thread-gathering-function
4754 'gnus-gather-threads-by-references)
4760 @node Filling In Threads
4761 @subsubsection Filling In Threads
4764 @item gnus-fetch-old-headers
4765 @vindex gnus-fetch-old-headers
4766 If non-@code{nil}, Gnus will attempt to build old threads by fetching
4767 more old headers---headers to articles marked as read. If you
4768 would like to display as few summary lines as possible, but still
4769 connect as many loose threads as possible, you should set this variable
4770 to @code{some} or a number. If you set it to a number, no more than
4771 that number of extra old headers will be fetched. In either case,
4772 fetching old headers only works if the backend you are using carries
4773 overview files---this would normally be @code{nntp}, @code{nnspool} and
4774 @code{nnml}. Also remember that if the root of the thread has been
4775 expired by the server, there's not much Gnus can do about that.
4777 This variable can also be set to @code{invisible}. This won't have any
4778 visible effects, but is useful if you use the @kbd{A T} command a lot
4779 (@pxref{Finding the Parent}).
4781 @item gnus-build-sparse-threads
4782 @vindex gnus-build-sparse-threads
4783 Fetching old headers can be slow. A low-rent similar effect can be
4784 gotten by setting this variable to @code{some}. Gnus will then look at
4785 the complete @code{References} headers of all articles and try to string
4786 together articles that belong in the same thread. This will leave
4787 @dfn{gaps} in the threading display where Gnus guesses that an article
4788 is missing from the thread. (These gaps appear like normal summary
4789 lines. If you select a gap, Gnus will try to fetch the article in
4790 question.) If this variable is @code{t}, Gnus will display all these
4791 ``gaps'' without regard for whether they are useful for completing the
4792 thread or not. Finally, if this variable is @code{more}, Gnus won't cut
4793 off sparse leaf nodes that don't lead anywhere. This variable is
4794 @code{nil} by default.
4799 @node More Threading
4800 @subsubsection More Threading
4803 @item gnus-show-threads
4804 @vindex gnus-show-threads
4805 If this variable is @code{nil}, no threading will be done, and all of
4806 the rest of the variables here will have no effect. Turning threading
4807 off will speed group selection up a bit, but it is sure to make reading
4808 slower and more awkward.
4810 @item gnus-thread-hide-subtree
4811 @vindex gnus-thread-hide-subtree
4812 If non-@code{nil}, all threads will be hidden when the summary buffer is
4815 @item gnus-thread-expunge-below
4816 @vindex gnus-thread-expunge-below
4817 All threads that have a total score (as defined by
4818 @code{gnus-thread-score-function}) less than this number will be
4819 expunged. This variable is @code{nil} by default, which means that no
4820 threads are expunged.
4822 @item gnus-thread-hide-killed
4823 @vindex gnus-thread-hide-killed
4824 if you kill a thread and this variable is non-@code{nil}, the subtree
4827 @item gnus-thread-ignore-subject
4828 @vindex gnus-thread-ignore-subject
4829 Sometimes somebody changes the subject in the middle of a thread. If
4830 this variable is non-@code{nil}, the subject change is ignored. If it
4831 is @code{nil}, which is the default, a change in the subject will result
4834 @item gnus-thread-indent-level
4835 @vindex gnus-thread-indent-level
4836 This is a number that says how much each sub-thread should be indented.
4842 @node Low-Level Threading
4843 @subsubsection Low-Level Threading
4847 @item gnus-parse-headers-hook
4848 @vindex gnus-parse-headers-hook
4849 Hook run before parsing any headers. The default value is
4850 @code{(gnus-decode-rfc1522)}, which means that QPized headers will be
4851 slightly decoded in a hackish way. This is likely to change in the
4852 future when Gnus becomes @sc{MIME}ified.
4854 @item gnus-alter-header-function
4855 @vindex gnus-alter-header-function
4856 If non-@code{nil}, this function will be called to allow alteration of
4857 article header structures. The function is called with one parameter,
4858 the article header vector, which it may alter in any way. For instance,
4859 if you have a mail-to-news gateway which alters the @code{Message-ID}s
4860 in systematic ways (by adding prefixes and such), you can use this
4861 variable to un-scramble the @code{Message-ID}s so that they are more
4862 meaningful. Here's one example:
4865 (setq gnus-alter-header-function 'my-alter-message-id)
4867 (defun my-alter-message-id (header)
4868 (let ((id (mail-header-id header)))
4870 "\\(<[^<>@@]*\\)\\.?cygnus\\..*@@\\([^<>@@]*>\\)" id)
4872 (concat (match-string 1 id) "@@" (match-string 2 id))
4879 @node Thread Commands
4880 @subsection Thread Commands
4881 @cindex thread commands
4887 @kindex T k (Summary)
4888 @kindex M-C-k (Summary)
4889 @findex gnus-summary-kill-thread
4890 Mark all articles in the current (sub-)thread as read
4891 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
4892 remove all marks instead. If the prefix argument is negative, tick
4897 @kindex T l (Summary)
4898 @kindex M-C-l (Summary)
4899 @findex gnus-summary-lower-thread
4900 Lower the score of the current (sub-)thread
4901 (@code{gnus-summary-lower-thread}).
4904 @kindex T i (Summary)
4905 @findex gnus-summary-raise-thread
4906 Increase the score of the current (sub-)thread
4907 (@code{gnus-summary-raise-thread}).
4910 @kindex T # (Summary)
4911 @findex gnus-uu-mark-thread
4912 Set the process mark on the current (sub-)thread
4913 (@code{gnus-uu-mark-thread}).
4916 @kindex T M-# (Summary)
4917 @findex gnus-uu-unmark-thread
4918 Remove the process mark from the current (sub-)thread
4919 (@code{gnus-uu-unmark-thread}).
4922 @kindex T T (Summary)
4923 @findex gnus-summary-toggle-threads
4924 Toggle threading (@code{gnus-summary-toggle-threads}).
4927 @kindex T s (Summary)
4928 @findex gnus-summary-show-thread
4929 Expose the (sub-)thread hidden under the current article, if any
4930 (@code{gnus-summary-show-thread}).
4933 @kindex T h (Summary)
4934 @findex gnus-summary-hide-thread
4935 Hide the current (sub-)thread (@code{gnus-summary-hide-thread}).
4938 @kindex T S (Summary)
4939 @findex gnus-summary-show-all-threads
4940 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
4943 @kindex T H (Summary)
4944 @findex gnus-summary-hide-all-threads
4945 Hide all threads (@code{gnus-summary-hide-all-threads}).
4948 @kindex T t (Summary)
4949 @findex gnus-summary-rethread-current
4950 Re-thread the current article's thread
4951 (@code{gnus-summary-rethread-current}). This works even when the
4952 summary buffer is otherwise unthreaded.
4955 @kindex T ^ (Summary)
4956 @findex gnus-summary-reparent-thread
4957 Make the current article the child of the marked (or previous) article
4958 (@code{gnus-summary-reparent-thread}).
4962 The following commands are thread movement commands. They all
4963 understand the numeric prefix.
4968 @kindex T n (Summary)
4969 @findex gnus-summary-next-thread
4970 Go to the next thread (@code{gnus-summary-next-thread}).
4973 @kindex T p (Summary)
4974 @findex gnus-summary-prev-thread
4975 Go to the previous thread (@code{gnus-summary-prev-thread}).
4978 @kindex T d (Summary)
4979 @findex gnus-summary-down-thread
4980 Descend the thread (@code{gnus-summary-down-thread}).
4983 @kindex T u (Summary)
4984 @findex gnus-summary-up-thread
4985 Ascend the thread (@code{gnus-summary-up-thread}).
4988 @kindex T o (Summary)
4989 @findex gnus-summary-top-thread
4990 Go to the top of the thread (@code{gnus-summary-top-thread}).
4993 @vindex gnus-thread-operation-ignore-subject
4994 If you ignore subject while threading, you'll naturally end up with
4995 threads that have several different subjects in them. If you then issue
4996 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
4997 wish to kill the entire thread, but just those parts of the thread that
4998 have the same subject as the current article. If you like this idea,
4999 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If it
5000 is non-@code{nil} (which it is by default), subjects will be ignored
5001 when doing thread commands. If this variable is @code{nil}, articles in
5002 the same thread with different subjects will not be included in the
5003 operation in question. If this variable is @code{fuzzy}, only articles
5004 that have subjects fuzzily equal will be included (@pxref{Fuzzy
5011 @findex gnus-thread-sort-by-total-score
5012 @findex gnus-thread-sort-by-date
5013 @findex gnus-thread-sort-by-score
5014 @findex gnus-thread-sort-by-subject
5015 @findex gnus-thread-sort-by-author
5016 @findex gnus-thread-sort-by-number
5017 @vindex gnus-thread-sort-functions
5018 If you are using a threaded summary display, you can sort the threads by
5019 setting @code{gnus-thread-sort-functions}, which is a list of functions.
5020 By default, sorting is done on article numbers. Ready-made sorting
5021 predicate functions include @code{gnus-thread-sort-by-number},
5022 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
5023 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
5024 @code{gnus-thread-sort-by-total-score}.
5026 Each function takes two threads and returns non-@code{nil} if the first
5027 thread should be sorted before the other. Note that sorting really is
5028 normally done by looking only at the roots of each thread. If you use
5029 more than one function, the primary sort key should be the last function
5030 in the list. You should probably always include
5031 @code{gnus-thread-sort-by-number} in the list of sorting
5032 functions---preferably first. This will ensure that threads that are
5033 equal with respect to the other sort criteria will be displayed in
5034 ascending article order.
5036 If you would like to sort by score, then by subject, and finally by
5037 number, you could do something like:
5040 (setq gnus-thread-sort-functions
5041 '(gnus-thread-sort-by-number
5042 gnus-thread-sort-by-subject
5043 gnus-thread-sort-by-total-score))
5046 The threads that have highest score will be displayed first in the
5047 summary buffer. When threads have the same score, they will be sorted
5048 alphabetically. The threads that have the same score and the same
5049 subject will be sorted by number, which is (normally) the sequence in
5050 which the articles arrived.
5052 If you want to sort by score and then reverse arrival order, you could
5056 (setq gnus-thread-sort-functions
5058 (not (gnus-thread-sort-by-number t1 t2)))
5059 gnus-thread-sort-by-score))
5062 @vindex gnus-thread-score-function
5063 The function in the @code{gnus-thread-score-function} variable (default
5064 @code{+}) is used for calculating the total score of a thread. Useful
5065 functions might be @code{max}, @code{min}, or squared means, or whatever
5068 @findex gnus-article-sort-functions
5069 @findex gnus-article-sort-by-date
5070 @findex gnus-article-sort-by-score
5071 @findex gnus-article-sort-by-subject
5072 @findex gnus-article-sort-by-author
5073 @findex gnus-article-sort-by-number
5074 If you are using an unthreaded display for some strange reason or other,
5075 you have to fiddle with the @code{gnus-article-sort-functions} variable.
5076 It is very similar to the @code{gnus-thread-sort-functions}, except that
5077 it uses slightly different functions for article comparison. Available
5078 sorting predicate functions are @code{gnus-article-sort-by-number},
5079 @code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
5080 @code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
5082 If you want to sort an unthreaded summary display by subject, you could
5086 (setq gnus-article-sort-functions
5087 '(gnus-article-sort-by-number
5088 gnus-article-sort-by-subject))
5093 @node Asynchronous Fetching
5094 @section Asynchronous Article Fetching
5095 @cindex asynchronous article fetching
5096 @cindex article pre-fetch
5099 If you read your news from an @sc{nntp} server that's far away, the
5100 network latencies may make reading articles a chore. You have to wait
5101 for a while after pressing @kbd{n} to go to the next article before the
5102 article appears. Why can't Gnus just go ahead and fetch the article
5103 while you are reading the previous one? Why not, indeed.
5105 First, some caveats. There are some pitfalls to using asynchronous
5106 article fetching, especially the way Gnus does it.
5108 Let's say you are reading article 1, which is short, and article 2 is
5109 quite long, and you are not interested in reading that. Gnus does not
5110 know this, so it goes ahead and fetches article 2. You decide to read
5111 article 3, but since Gnus is in the process of fetching article 2, the
5112 connection is blocked.
5114 To avoid these situations, Gnus will open two (count 'em two)
5115 connections to the server. Some people may think this isn't a very nice
5116 thing to do, but I don't see any real alternatives. Setting up that
5117 extra connection takes some time, so Gnus startup will be slower.
5119 Gnus will fetch more articles than you will read. This will mean that
5120 the link between your machine and the @sc{nntp} server will become more
5121 loaded than if you didn't use article pre-fetch. The server itself will
5122 also become more loaded---both with the extra article requests, and the
5125 Ok, so now you know that you shouldn't really use this thing... unless
5128 @vindex gnus-asynchronous
5129 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
5130 happen automatically.
5132 @vindex gnus-use-article-prefetch
5133 You can control how many articles are to be pre-fetched by setting
5134 @code{gnus-use-article-prefetch}. This is 30 by default, which means
5135 that when you read an article in the group, the backend will pre-fetch
5136 the next 30 articles. If this variable is @code{t}, the backend will
5137 pre-fetch all the articles it can without bound. If it is
5138 @code{nil}, no pre-fetching will be done.
5140 @vindex gnus-async-prefetch-article-p
5141 @findex gnus-async-read-p
5142 There are probably some articles that you don't want to pre-fetch---read
5143 articles, for instance. The @code{gnus-async-prefetch-article-p} variable controls whether an article is to be pre-fetched. This function should
5144 return non-@code{nil} when the article in question is to be
5145 pre-fetched. The default is @code{gnus-async-read-p}, which returns
5146 @code{nil} on read articles. The function is called with an article
5147 data structure as the only parameter.
5149 If, for instance, you wish to pre-fetch only unread articles shorter than 100 lines, you could say something like:
5152 (defun my-async-short-unread-p (data)
5153 "Return non-nil for short, unread articles."
5154 (and (gnus-data-unread-p data)
5155 (< (mail-header-lines (gnus-data-header data))
5158 (setq gnus-async-prefetch-article-p 'my-async-short-unread-p)
5161 These functions will be called many, many times, so they should
5162 preferably be short and sweet to avoid slowing down Gnus too much.
5163 It's probably a good idea to byte-compile things like this.
5165 @vindex gnus-prefetched-article-deletion-strategy
5166 Articles have to be removed from the asynch buffer sooner or later. The
5167 @code{gnus-prefetched-article-deletion-strategy} says when to remove
5168 articles. This is a list that may contain the following elements:
5172 Remove articles when they are read.
5175 Remove articles when exiting the group.
5178 The default value is @code{(read exit)}.
5180 @vindex gnus-use-header-prefetch
5181 If @code{gnus-use-header-prefetch} is non-@code{nil}, prefetch articles
5182 from the next group.
5185 @node Article Caching
5186 @section Article Caching
5187 @cindex article caching
5190 If you have an @emph{extremely} slow @sc{nntp} connection, you may
5191 consider turning article caching on. Each article will then be stored
5192 locally under your home directory. As you may surmise, this could
5193 potentially use @emph{huge} amounts of disk space, as well as eat up all
5194 your inodes so fast it will make your head swim. In vodka.
5196 Used carefully, though, it could be just an easier way to save articles.
5198 @vindex gnus-use-long-file-name
5199 @vindex gnus-cache-directory
5200 @vindex gnus-use-cache
5201 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
5202 all articles ticked or marked as dormant will then be copied
5203 over to your local cache (@code{gnus-cache-directory}). Whether this
5204 cache is flat or hierarchal is controlled by the
5205 @code{gnus-use-long-file-name} variable, as usual.
5207 When re-selecting a ticked or dormant article, it will be fetched from the
5208 cache instead of from the server. As articles in your cache will never
5209 expire, this might serve as a method of saving articles while still
5210 keeping them where they belong. Just mark all articles you want to save
5211 as dormant, and don't worry.
5213 When an article is marked as read, is it removed from the cache.
5215 @vindex gnus-cache-remove-articles
5216 @vindex gnus-cache-enter-articles
5217 The entering/removal of articles from the cache is controlled by the
5218 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
5219 variables. Both are lists of symbols. The first is @code{(ticked
5220 dormant)} by default, meaning that ticked and dormant articles will be
5221 put in the cache. The latter is @code{(read)} by default, meaning that
5222 articles marked as read are removed from the cache. Possibly
5223 symbols in these two lists are @code{ticked}, @code{dormant},
5224 @code{unread} and @code{read}.
5226 @findex gnus-jog-cache
5227 So where does the massive article-fetching and storing come into the
5228 picture? The @code{gnus-jog-cache} command will go through all
5229 subscribed newsgroups, request all unread articles, score them, and
5230 store them in the cache. You should only ever, ever ever ever, use this
5231 command if 1) your connection to the @sc{nntp} server is really, really,
5232 really slow and 2) you have a really, really, really huge disk.
5233 Seriously. One way to cut down on the number of articles downloaded is
5234 to score unwanted articles down and have them marked as read. They will
5235 not then be downloaded by this command.
5237 @vindex gnus-uncacheable-groups
5238 It is likely that you do not want caching on some groups. For instance,
5239 if your @code{nnml} mail is located under your home directory, it makes no
5240 sense to cache it somewhere else under your home directory. Unless you
5241 feel that it's neat to use twice as much space. To limit the caching,
5242 you could set the @code{gnus-uncacheable-groups} regexp to
5243 @samp{^nnml}, for instance. This variable is @code{nil} by
5246 @findex gnus-cache-generate-nov-databases
5247 @findex gnus-cache-generate-active
5248 @vindex gnus-cache-active-file
5249 The cache stores information on what articles it contains in its active
5250 file (@code{gnus-cache-active-file}). If this file (or any other parts
5251 of the cache) becomes all messed up for some reason or other, Gnus
5252 offers two functions that will try to set things right. @kbd{M-x
5253 gnus-cache-generate-nov-databases} will (re)build all the @sc{nov}
5254 files, and @kbd{gnus-cache-generate-active} will (re)generate the active
5258 @node Persistent Articles
5259 @section Persistent Articles
5260 @cindex persistent articles
5262 Closely related to article caching, we have @dfn{persistent articles}.
5263 In fact, it's just a different way of looking at caching, and much more
5264 useful in my opinion.
5266 Say you're reading a newsgroup, and you happen on to some valuable gem
5267 that you want to keep and treasure forever. You'd normally just save it
5268 (using one of the many saving commands) in some file. The problem with
5269 that is that it's just, well, yucky. Ideally you'd prefer just having
5270 the article remain in the group where you found it forever; untouched by
5271 the expiry going on at the news server.
5273 This is what a @dfn{persistent article} is---an article that just won't
5274 be deleted. It's implemented using the normal cache functions, but
5275 you use two explicit commands for managing persistent articles:
5281 @findex gnus-cache-enter-article
5282 Make the current article persistent (@code{gnus-cache-enter-article}).
5285 @kindex M-* (Summary)
5286 @findex gnus-cache-remove-article
5287 Remove the current article from the persistent articles
5288 (@code{gnus-cache-remove-article}). This will normally delete the
5292 Both these commands understand the process/prefix convention.
5294 To avoid having all ticked articles (and stuff) entered into the cache,
5295 you should set @code{gnus-use-cache} to @code{passive} if you're just
5296 interested in persistent articles:
5299 (setq gnus-use-cache 'passive)
5303 @node Article Backlog
5304 @section Article Backlog
5306 @cindex article backlog
5308 If you have a slow connection, but the idea of using caching seems
5309 unappealing to you (and it is, really), you can help the situation some
5310 by switching on the @dfn{backlog}. This is where Gnus will buffer
5311 already read articles so that it doesn't have to re-fetch articles
5312 you've already read. This only helps if you are in the habit of
5313 re-selecting articles you've recently read, of course. If you never do
5314 that, turning the backlog on will slow Gnus down a little bit, and
5315 increase memory usage some.
5317 @vindex gnus-keep-backlog
5318 If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
5319 at most @var{n} old articles in a buffer for later re-fetching. If this
5320 variable is non-@code{nil} and is not a number, Gnus will store
5321 @emph{all} read articles, which means that your Emacs will grow without
5322 bound before exploding and taking your machine down with you. I put
5323 that in there just to keep y'all on your toes.
5325 This variable is @code{nil} by default.
5328 @node Saving Articles
5329 @section Saving Articles
5330 @cindex saving articles
5332 Gnus can save articles in a number of ways. Below is the documentation
5333 for saving articles in a fairly straight-forward fashion (i.e., little
5334 processing of the article is done before it is saved). For a different
5335 approach (uudecoding, unsharing) you should use @code{gnus-uu}
5336 (@pxref{Decoding Articles}).
5338 @vindex gnus-save-all-headers
5339 If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
5340 unwanted headers before saving the article.
5342 @vindex gnus-saved-headers
5343 If the preceding variable is @code{nil}, all headers that match the
5344 @code{gnus-saved-headers} regexp will be kept, while the rest will be
5345 deleted before saving.
5351 @kindex O o (Summary)
5353 @findex gnus-summary-save-article
5354 @c @icon{gnus-summary-save-article}
5355 Save the current article using the default article saver
5356 (@code{gnus-summary-save-article}).
5359 @kindex O m (Summary)
5360 @findex gnus-summary-save-article-mail
5361 Save the current article in mail format
5362 (@code{gnus-summary-save-article-mail}).
5365 @kindex O r (Summary)
5366 @findex gnus-summary-save-article-rmail
5367 Save the current article in rmail format
5368 (@code{gnus-summary-save-article-rmail}).
5371 @kindex O f (Summary)
5372 @findex gnus-summary-save-article-file
5373 @c @icon{gnus-summary-save-article-file}
5374 Save the current article in plain file format
5375 (@code{gnus-summary-save-article-file}).
5378 @kindex O F (Summary)
5379 @findex gnus-summary-write-article-file
5380 Write the current article in plain file format, overwriting any previous
5381 file contents (@code{gnus-summary-write-article-file}).
5384 @kindex O b (Summary)
5385 @findex gnus-summary-save-article-body-file
5386 Save the current article body in plain file format
5387 (@code{gnus-summary-save-article-body-file}).
5390 @kindex O h (Summary)
5391 @findex gnus-summary-save-article-folder
5392 Save the current article in mh folder format
5393 (@code{gnus-summary-save-article-folder}).
5396 @kindex O v (Summary)
5397 @findex gnus-summary-save-article-vm
5398 Save the current article in a VM folder
5399 (@code{gnus-summary-save-article-vm}).
5402 @kindex O p (Summary)
5403 @findex gnus-summary-pipe-output
5404 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
5405 the current article to a process (@code{gnus-summary-pipe-output}).
5408 @vindex gnus-prompt-before-saving
5409 All these commands use the process/prefix convention
5410 (@pxref{Process/Prefix}). If you save bunches of articles using these
5411 functions, you might get tired of being prompted for files to save each
5412 and every article in. The prompting action is controlled by
5413 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
5414 default, giving you that excessive prompting action you know and
5415 loathe. If you set this variable to @code{t} instead, you'll be prompted
5416 just once for each series of articles you save. If you like to really
5417 have Gnus do all your thinking for you, you can even set this variable
5418 to @code{nil}, which means that you will never be prompted for files to
5419 save articles in. Gnus will simply save all the articles in the default
5423 @vindex gnus-default-article-saver
5424 You can customize the @code{gnus-default-article-saver} variable to make
5425 Gnus do what you want it to. You can use any of the four ready-made
5426 functions below, or you can create your own.
5430 @item gnus-summary-save-in-rmail
5431 @findex gnus-summary-save-in-rmail
5432 @vindex gnus-rmail-save-name
5433 @findex gnus-plain-save-name
5434 This is the default format, @dfn{babyl}. Uses the function in the
5435 @code{gnus-rmail-save-name} variable to get a file name to save the
5436 article in. The default is @code{gnus-plain-save-name}.
5438 @item gnus-summary-save-in-mail
5439 @findex gnus-summary-save-in-mail
5440 @vindex gnus-mail-save-name
5441 Save in a Unix mail (mbox) file. Uses the function in the
5442 @code{gnus-mail-save-name} variable to get a file name to save the
5443 article in. The default is @code{gnus-plain-save-name}.
5445 @item gnus-summary-save-in-file
5446 @findex gnus-summary-save-in-file
5447 @vindex gnus-file-save-name
5448 @findex gnus-numeric-save-name
5449 Append the article straight to an ordinary file. Uses the function in
5450 the @code{gnus-file-save-name} variable to get a file name to save the
5451 article in. The default is @code{gnus-numeric-save-name}.
5453 @item gnus-summary-save-body-in-file
5454 @findex gnus-summary-save-body-in-file
5455 Append the article body to an ordinary file. Uses the function in the
5456 @code{gnus-file-save-name} variable to get a file name to save the
5457 article in. The default is @code{gnus-numeric-save-name}.
5459 @item gnus-summary-save-in-folder
5460 @findex gnus-summary-save-in-folder
5461 @findex gnus-folder-save-name
5462 @findex gnus-Folder-save-name
5463 @vindex gnus-folder-save-name
5466 Save the article to an MH folder using @code{rcvstore} from the MH
5467 library. Uses the function in the @code{gnus-folder-save-name} variable
5468 to get a file name to save the article in. The default is
5469 @code{gnus-folder-save-name}, but you can also use
5470 @code{gnus-Folder-save-name}, which creates capitalized names.
5472 @item gnus-summary-save-in-vm
5473 @findex gnus-summary-save-in-vm
5474 Save the article in a VM folder. You have to have the VM mail
5475 reader to use this setting.
5478 @vindex gnus-article-save-directory
5479 All of these functions, except for the last one, will save the article
5480 in the @code{gnus-article-save-directory}, which is initialized from the
5481 @code{SAVEDIR} environment variable. This is @file{~/News/} by
5484 As you can see above, the functions use different functions to find a
5485 suitable name of a file to save the article in. Below is a list of
5486 available functions that generate names:
5490 @item gnus-Numeric-save-name
5491 @findex gnus-Numeric-save-name
5492 File names like @file{~/News/Alt.andrea-dworkin/45}.
5494 @item gnus-numeric-save-name
5495 @findex gnus-numeric-save-name
5496 File names like @file{~/News/alt.andrea-dworkin/45}.
5498 @item gnus-Plain-save-name
5499 @findex gnus-Plain-save-name
5500 File names like @file{~/News/Alt.andrea-dworkin}.
5502 @item gnus-plain-save-name
5503 @findex gnus-plain-save-name
5504 File names like @file{~/News/alt.andrea-dworkin}.
5507 @vindex gnus-split-methods
5508 You can have Gnus suggest where to save articles by plonking a regexp into
5509 the @code{gnus-split-methods} alist. For instance, if you would like to
5510 save articles related to Gnus in the file @file{gnus-stuff}, and articles
5511 related to VM in @code{vm-stuff}, you could set this variable to something
5515 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
5516 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
5517 (my-choosing-function "../other-dir/my-stuff")
5518 ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
5521 We see that this is a list where each element is a list that has two
5522 elements---the @dfn{match} and the @dfn{file}. The match can either be
5523 a string (in which case it is used as a regexp to match on the article
5524 head); it can be a symbol (which will be called as a function with the
5525 group name as a parameter); or it can be a list (which will be
5526 @code{eval}ed). If any of these actions have a non-@code{nil} result,
5527 the @dfn{file} will be used as a default prompt. In addition, the
5528 result of the operation itself will be used if the function or form
5529 called returns a string or a list of strings.
5531 You basically end up with a list of file names that might be used when
5532 saving the current article. (All ``matches'' will be used.) You will
5533 then be prompted for what you really want to use as a name, with file
5534 name completion over the results from applying this variable.
5536 This variable is @code{((gnus-article-archive-name))} by default, which
5537 means that Gnus will look at the articles it saves for an
5538 @code{Archive-name} line and use that as a suggestion for the file
5541 Here's an example function to clean up file names somewhat. If you have
5542 lots of mail groups called things like
5543 @samp{nnml:mail.whatever}, you may want to chop off the beginning of
5544 these group names before creating the file name to save to. The
5545 following will do just that:
5548 (defun my-save-name (group)
5549 (when (string-match "^nnml:mail." group)
5550 (substring group (match-end 0))))
5552 (setq gnus-split-methods
5553 '((gnus-article-archive-name)
5558 @vindex gnus-use-long-file-name
5559 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
5560 @code{nil}, all the preceding functions will replace all periods
5561 (@samp{.}) in the group names with slashes (@samp{/})---which means that
5562 the functions will generate hierarchies of directories instead of having
5563 all the files in the toplevel directory
5564 (@file{~/News/alt/andrea-dworkin} instead of
5565 @file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
5566 on most systems. However, for historical reasons, this is @code{nil} on
5567 Xenix and usg-unix-v machines by default.
5569 This function also affects kill and score file names. If this variable
5570 is a list, and the list contains the element @code{not-score}, long file
5571 names will not be used for score files, if it contains the element
5572 @code{not-save}, long file names will not be used for saving, and if it
5573 contains the element @code{not-kill}, long file names will not be used
5576 If you'd like to save articles in a hierarchy that looks something like
5580 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
5581 (setq gnus-default-article-saver 'gnus-summary-save-in-file) ; no encoding
5584 Then just save with @kbd{o}. You'd then read this hierarchy with
5585 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
5586 the toplevel directory as the argument (@file{~/News/}). Then just walk
5587 around to the groups/directories with @code{nneething}.
5590 @node Decoding Articles
5591 @section Decoding Articles
5592 @cindex decoding articles
5594 Sometime users post articles (or series of articles) that have been
5595 encoded in some way or other. Gnus can decode them for you.
5598 * Uuencoded Articles:: Uudecode articles.
5599 * Shell Archives:: Unshar articles.
5600 * PostScript Files:: Split PostScript.
5601 * Other Files:: Plain save and binhex.
5602 * Decoding Variables:: Variables for a happy decoding.
5603 * Viewing Files:: You want to look at the result of the decoding?
5607 @cindex article series
5608 All these functions use the process/prefix convention
5609 (@pxref{Process/Prefix}) for finding out what articles to work on, with
5610 the extension that a ``single article'' means ``a single series''. Gnus
5611 can find out by itself what articles belong to a series, decode all the
5612 articles and unpack/view/save the resulting file(s).
5614 Gnus guesses what articles are in the series according to the following
5615 simplish rule: The subjects must be (nearly) identical, except for the
5616 last two numbers of the line. (Spaces are largely ignored, however.)
5618 For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
5619 will find all the articles that match the regexp @samp{^cat.gif
5620 ([0-9]+/[0-9]+).*$}.
5622 Subjects that are non-standard, like @samp{cat.gif (2/3) Part 6 of a
5623 series}, will not be properly recognized by any of the automatic viewing
5624 commands, and you have to mark the articles manually with @kbd{#}.
5627 @node Uuencoded Articles
5628 @subsection Uuencoded Articles
5630 @cindex uuencoded articles
5635 @kindex X u (Summary)
5636 @findex gnus-uu-decode-uu
5637 @c @icon{gnus-uu-decode-uu}
5638 Uudecodes the current series (@code{gnus-uu-decode-uu}).
5641 @kindex X U (Summary)
5642 @findex gnus-uu-decode-uu-and-save
5643 Uudecodes and saves the current series
5644 (@code{gnus-uu-decode-uu-and-save}).
5647 @kindex X v u (Summary)
5648 @findex gnus-uu-decode-uu-view
5649 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
5652 @kindex X v U (Summary)
5653 @findex gnus-uu-decode-uu-and-save-view
5654 Uudecodes, views and saves the current series
5655 (@code{gnus-uu-decode-uu-and-save-view}).
5659 Remember that these all react to the presence of articles marked with
5660 the process mark. If, for instance, you'd like to decode and save an
5661 entire newsgroup, you'd typically do @kbd{M P a}
5662 (@code{gnus-uu-mark-all}) and then @kbd{X U}
5663 (@code{gnus-uu-decode-uu-and-save}).
5665 All this is very much different from how @code{gnus-uu} worked with
5666 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
5667 the sun. This version of @code{gnus-uu} generally assumes that you mark
5668 articles in some way (@pxref{Setting Process Marks}) and then press
5671 @vindex gnus-uu-notify-files
5672 Note: When trying to decode articles that have names matching
5673 @code{gnus-uu-notify-files}, which is hard-coded to
5674 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
5675 automatically post an article on @samp{comp.unix.wizards} saying that
5676 you have just viewed the file in question. This feature can't be turned
5680 @node Shell Archives
5681 @subsection Shell Archives
5683 @cindex shell archives
5684 @cindex shared articles
5686 Shell archives (``shar files'') used to be a popular way to distribute
5687 sources, but it isn't used all that much today. In any case, we have
5688 some commands to deal with these:
5693 @kindex X s (Summary)
5694 @findex gnus-uu-decode-unshar
5695 Unshars the current series (@code{gnus-uu-decode-unshar}).
5698 @kindex X S (Summary)
5699 @findex gnus-uu-decode-unshar-and-save
5700 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
5703 @kindex X v s (Summary)
5704 @findex gnus-uu-decode-unshar-view
5705 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
5708 @kindex X v S (Summary)
5709 @findex gnus-uu-decode-unshar-and-save-view
5710 Unshars, views and saves the current series
5711 (@code{gnus-uu-decode-unshar-and-save-view}).
5715 @node PostScript Files
5716 @subsection PostScript Files
5722 @kindex X p (Summary)
5723 @findex gnus-uu-decode-postscript
5724 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
5727 @kindex X P (Summary)
5728 @findex gnus-uu-decode-postscript-and-save
5729 Unpack and save the current PostScript series
5730 (@code{gnus-uu-decode-postscript-and-save}).
5733 @kindex X v p (Summary)
5734 @findex gnus-uu-decode-postscript-view
5735 View the current PostScript series
5736 (@code{gnus-uu-decode-postscript-view}).
5739 @kindex X v P (Summary)
5740 @findex gnus-uu-decode-postscript-and-save-view
5741 View and save the current PostScript series
5742 (@code{gnus-uu-decode-postscript-and-save-view}).
5747 @subsection Other Files
5751 @kindex X o (Summary)
5752 @findex gnus-uu-decode-save
5753 Save the current series
5754 (@code{gnus-uu-decode-save}).
5757 @kindex X b (Summary)
5758 @findex gnus-uu-decode-binhex
5759 Unbinhex the current series (@code{gnus-uu-decode-binhex}). This
5760 doesn't really work yet.
5764 @node Decoding Variables
5765 @subsection Decoding Variables
5767 Adjective, not verb.
5770 * Rule Variables:: Variables that say how a file is to be viewed.
5771 * Other Decode Variables:: Other decode variables.
5772 * Uuencoding and Posting:: Variables for customizing uuencoding.
5776 @node Rule Variables
5777 @subsubsection Rule Variables
5778 @cindex rule variables
5780 Gnus uses @dfn{rule variables} to decide how to view a file. All these
5781 variables are of the form
5784 (list '(regexp1 command2)
5791 @item gnus-uu-user-view-rules
5792 @vindex gnus-uu-user-view-rules
5794 This variable is consulted first when viewing files. If you wish to use,
5795 for instance, @code{sox} to convert an @samp{.au} sound file, you could
5798 (setq gnus-uu-user-view-rules
5799 (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
5802 @item gnus-uu-user-view-rules-end
5803 @vindex gnus-uu-user-view-rules-end
5804 This variable is consulted if Gnus couldn't make any matches from the
5805 user and default view rules.
5807 @item gnus-uu-user-archive-rules
5808 @vindex gnus-uu-user-archive-rules
5809 This variable can be used to say what commands should be used to unpack
5814 @node Other Decode Variables
5815 @subsubsection Other Decode Variables
5818 @vindex gnus-uu-grabbed-file-functions
5820 @item gnus-uu-grabbed-file-functions
5821 All functions in this list will be called right after each file has been
5822 successfully decoded---so that you can move or view files right away,
5823 and don't have to wait for all files to be decoded before you can do
5824 anything. Ready-made functions you can put in this list are:
5828 @item gnus-uu-grab-view
5829 @findex gnus-uu-grab-view
5832 @item gnus-uu-grab-move
5833 @findex gnus-uu-grab-move
5834 Move the file (if you're using a saving function.)
5837 @item gnus-uu-be-dangerous
5838 @vindex gnus-uu-be-dangerous
5839 Specifies what to do if unusual situations arise during decoding. If
5840 @code{nil}, be as conservative as possible. If @code{t}, ignore things
5841 that didn't work, and overwrite existing files. Otherwise, ask each
5844 @item gnus-uu-ignore-files-by-name
5845 @vindex gnus-uu-ignore-files-by-name
5846 Files with name matching this regular expression won't be viewed.
5848 @item gnus-uu-ignore-files-by-type
5849 @vindex gnus-uu-ignore-files-by-type
5850 Files with a @sc{mime} type matching this variable won't be viewed.
5851 Note that Gnus tries to guess what type the file is based on the name.
5852 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
5855 @item gnus-uu-tmp-dir
5856 @vindex gnus-uu-tmp-dir
5857 Where @code{gnus-uu} does its work.
5859 @item gnus-uu-do-not-unpack-archives
5860 @vindex gnus-uu-do-not-unpack-archives
5861 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
5862 looking for files to display.
5864 @item gnus-uu-view-and-save
5865 @vindex gnus-uu-view-and-save
5866 Non-@code{nil} means that the user will always be asked to save a file
5869 @item gnus-uu-ignore-default-view-rules
5870 @vindex gnus-uu-ignore-default-view-rules
5871 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
5874 @item gnus-uu-ignore-default-archive-rules
5875 @vindex gnus-uu-ignore-default-archive-rules
5876 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
5879 @item gnus-uu-kill-carriage-return
5880 @vindex gnus-uu-kill-carriage-return
5881 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
5884 @item gnus-uu-unmark-articles-not-decoded
5885 @vindex gnus-uu-unmark-articles-not-decoded
5886 Non-@code{nil} means that @code{gnus-uu} will mark unsuccessfully
5887 decoded articles as unread.
5889 @item gnus-uu-correct-stripped-uucode
5890 @vindex gnus-uu-correct-stripped-uucode
5891 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
5892 uuencoded files that have had trailing spaces deleted.
5894 @item gnus-uu-pre-uudecode-hook
5895 @vindex gnus-uu-pre-uudecode-hook
5896 Hook run before sending a message to @code{uudecode}.
5898 @item gnus-uu-view-with-metamail
5899 @vindex gnus-uu-view-with-metamail
5901 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
5902 commands defined by the rule variables and just fudge a @sc{mime}
5903 content type based on the file name. The result will be fed to
5904 @code{metamail} for viewing.
5906 @item gnus-uu-save-in-digest
5907 @vindex gnus-uu-save-in-digest
5908 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
5909 decoding, will save in digests. If this variable is @code{nil},
5910 @code{gnus-uu} will just save everything in a file without any
5911 embellishments. The digesting almost conforms to RFC1153---no easy way
5912 to specify any meaningful volume and issue numbers were found, so I
5913 simply dropped them.
5918 @node Uuencoding and Posting
5919 @subsubsection Uuencoding and Posting
5923 @item gnus-uu-post-include-before-composing
5924 @vindex gnus-uu-post-include-before-composing
5925 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
5926 before you compose the article. If this variable is @code{t}, you can
5927 either include an encoded file with @kbd{C-c C-i} or have one included
5928 for you when you post the article.
5930 @item gnus-uu-post-length
5931 @vindex gnus-uu-post-length
5932 Maximum length of an article. The encoded file will be split into how
5933 many articles it takes to post the entire file.
5935 @item gnus-uu-post-threaded
5936 @vindex gnus-uu-post-threaded
5937 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
5938 thread. This may not be smart, as no other decoder I have seen is able
5939 to follow threads when collecting uuencoded articles. (Well, I have
5940 seen one package that does that---@code{gnus-uu}, but somehow, I don't
5941 think that counts...) Default is @code{nil}.
5943 @item gnus-uu-post-separate-description
5944 @vindex gnus-uu-post-separate-description
5945 Non-@code{nil} means that the description will be posted in a separate
5946 article. The first article will typically be numbered (0/x). If this
5947 variable is @code{nil}, the description the user enters will be included
5948 at the beginning of the first article, which will be numbered (1/x).
5949 Default is @code{t}.
5955 @subsection Viewing Files
5956 @cindex viewing files
5957 @cindex pseudo-articles
5959 After decoding, if the file is some sort of archive, Gnus will attempt
5960 to unpack the archive and see if any of the files in the archive can be
5961 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
5962 containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
5963 uncompress and de-tar the main file, and then view the two pictures.
5964 This unpacking process is recursive, so if the archive contains archives
5965 of archives, it'll all be unpacked.
5967 Finally, Gnus will normally insert a @dfn{pseudo-article} for each
5968 extracted file into the summary buffer. If you go to these
5969 ``articles'', you will be prompted for a command to run (usually Gnus
5970 will make a suggestion), and then the command will be run.
5972 @vindex gnus-view-pseudo-asynchronously
5973 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
5974 until the viewing is done before proceeding.
5976 @vindex gnus-view-pseudos
5977 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
5978 the pseudo-articles into the summary buffer, but view them
5979 immediately. If this variable is @code{not-confirm}, the user won't even
5980 be asked for a confirmation before viewing is done.
5982 @vindex gnus-view-pseudos-separately
5983 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
5984 pseudo-article will be created for each file to be viewed. If
5985 @code{nil}, all files that use the same viewing command will be given as
5986 a list of parameters to that command.
5988 @vindex gnus-insert-pseudo-articles
5989 If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert
5990 pseudo-articles when decoding. It is @code{t} by default.
5992 So; there you are, reading your @emph{pseudo-articles} in your
5993 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
5994 Why isn't anything real anymore? How did we get here?
5997 @node Article Treatment
5998 @section Article Treatment
6000 Reading through this huge manual, you may have quite forgotten that the
6001 object of newsreaders is to actually, like, read what people have
6002 written. Reading articles. Unfortunately, people are quite bad at
6003 writing, so there are tons of functions and variables to make reading
6004 these articles easier.
6007 * Article Highlighting:: You want to make the article look like fruit salad.
6008 * Article Fontisizing:: Making emphasized text look niced.
6009 * Article Hiding:: You also want to make certain info go away.
6010 * Article Washing:: Lots of way-neat functions to make life better.
6011 * Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
6012 * Article Date:: Grumble, UT!
6013 * Article Signature:: What is a signature?
6017 @node Article Highlighting
6018 @subsection Article Highlighting
6021 Not only do you want your article buffer to look like fruit salad, but
6022 you want it to look like technicolor fruit salad.
6027 @kindex W H a (Summary)
6028 @findex gnus-article-highlight
6029 Highlight the current article (@code{gnus-article-highlight}).
6032 @kindex W H h (Summary)
6033 @findex gnus-article-highlight-headers
6034 @vindex gnus-header-face-alist
6035 Highlight the headers (@code{gnus-article-highlight-headers}). The
6036 highlighting will be done according to the @code{gnus-header-face-alist}
6037 variable, which is a list where each element has the form @var{(regexp
6038 name content)}. @var{regexp} is a regular expression for matching the
6039 header, @var{name} is the face used for highlighting the header name
6040 (@pxref{Faces and Fonts}) and @var{content} is the face for highlighting
6041 the header value. The first match made will be used. Note that
6042 @var{regexp} shouldn't have @samp{^} prepended---Gnus will add one.
6045 @kindex W H c (Summary)
6046 @findex gnus-article-highlight-citation
6047 Highlight cited text (@code{gnus-article-highlight-citation}).
6049 Some variables to customize the citation highlights:
6052 @vindex gnus-cite-parse-max-size
6054 @item gnus-cite-parse-max-size
6055 If the article size if bigger than this variable (which is 25000 by
6056 default), no citation highlighting will be performed.
6058 @item gnus-cite-prefix-regexp
6059 @vindex gnus-cite-prefix-regexp
6060 Regexp matching the longest possible citation prefix on a line.
6062 @item gnus-cite-max-prefix
6063 @vindex gnus-cite-max-prefix
6064 Maximum possible length for a citation prefix (default 20).
6066 @item gnus-cite-face-list
6067 @vindex gnus-cite-face-list
6068 List of faces used for highlighting citations (@pxref{Faces and Fonts}).
6069 When there are citations from multiple articles in the same message,
6070 Gnus will try to give each citation from each article its own face.
6071 This should make it easier to see who wrote what.
6073 @item gnus-supercite-regexp
6074 @vindex gnus-supercite-regexp
6075 Regexp matching normal Supercite attribution lines.
6077 @item gnus-supercite-secondary-regexp
6078 @vindex gnus-supercite-secondary-regexp
6079 Regexp matching mangled Supercite attribution lines.
6081 @item gnus-cite-minimum-match-count
6082 @vindex gnus-cite-minimum-match-count
6083 Minimum number of identical prefixes we have to see before we believe
6084 that it's a citation.
6086 @item gnus-cite-attribution-prefix
6087 @vindex gnus-cite-attribution-prefix
6088 Regexp matching the beginning of an attribution line.
6090 @item gnus-cite-attribution-suffix
6091 @vindex gnus-cite-attribution-suffix
6092 Regexp matching the end of an attribution line.
6094 @item gnus-cite-attribution-face
6095 @vindex gnus-cite-attribution-face
6096 Face used for attribution lines. It is merged with the face for the
6097 cited text belonging to the attribution.
6103 @kindex W H s (Summary)
6104 @vindex gnus-signature-separator
6105 @vindex gnus-signature-face
6106 @findex gnus-article-highlight-signature
6107 Highlight the signature (@code{gnus-article-highlight-signature}).
6108 Everything after @code{gnus-signature-separator} (@pxref{Article
6109 Signature}) in an article will be considered a signature and will be
6110 highlighted with @code{gnus-signature-face}, which is @code{italic} by
6116 @node Article Fontisizing
6117 @subsection Article Fontisizing
6119 @cindex article emphasis
6121 @findex gnus-article-emphasize
6122 @kindex W e (Summary)
6123 People commonly add emphasis to words in news articles by writing things
6124 like @samp{_this_} or @samp{*this*}. Gnus can make this look nicer by
6125 running the article through the @kbd{W e}
6126 (@code{gnus-article-emphasize}) command.
6128 @vindex gnus-article-emphasis
6129 How the emphasis is computed is controlled by the
6130 @code{gnus-article-emphasis} variable. This is an alist where the first
6131 element is a regular expression to be matched. The second is a number
6132 that says what regular expression grouping is used to find the entire
6133 emphasized word. The third is a number that says what regexp grouping
6134 should be displayed and highlighted. (The text between these two
6135 groupings will be hidden.) The fourth is the face used for
6139 (setq gnus-article-emphasis
6140 '(("_\\(\\w+\\)_" 0 1 gnus-emphasis-underline)
6141 ("\\*\\(\\w+\\)\\*" 0 1 gnus-emphasis-bold)))
6144 @vindex gnus-emphasis-underline
6145 @vindex gnus-emphasis-bold
6146 @vindex gnus-emphasis-italic
6147 @vindex gnus-emphasis-underline-bold
6148 @vindex gnus-emphasis-underline-italic
6149 @vindex gnus-emphasis-bold-italic
6150 @vindex gnus-emphasis-underline-bold-italic
6151 By default, there are seven rules, and they use the following faces:
6152 @code{gnus-emphasis-bold}, @code{gnus-emphasis-italic},
6153 @code{gnus-emphasis-underline}, @code{gnus-emphasis-bold-italic},
6154 @code{gnus-emphasis-underline-italic},
6155 @code{gnus-emphasis-underline-bold}, and
6156 @code{gnus-emphasis-underline-bold-italic}.
6158 If you want to change these faces, you can either use @kbd{M-x
6159 customize}, or you can use @code{copy-face}. For instance, if you want
6160 to make @code{gnus-emphasis-italic} use a red face instead, you could
6164 (copy-face 'red 'gnus-emphasis-italic)
6168 @node Article Hiding
6169 @subsection Article Hiding
6170 @cindex article hiding
6172 Or rather, hiding certain things in each article. There usually is much
6173 too much cruft in most articles.
6178 @kindex W W a (Summary)
6179 @findex gnus-article-hide
6180 Do maximum hiding on the summary buffer (@kbd{gnus-article-hide}).
6183 @kindex W W h (Summary)
6184 @findex gnus-article-hide-headers
6185 Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
6189 @kindex W W b (Summary)
6190 @findex gnus-article-hide-boring-headers
6191 Hide headers that aren't particularly interesting
6192 (@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}.
6195 @kindex W W s (Summary)
6196 @findex gnus-article-hide-signature
6197 Hide signature (@code{gnus-article-hide-signature}). @xref{Article
6201 @kindex W W p (Summary)
6202 @findex gnus-article-hide-pgp
6203 @vindex gnus-article-hide-pgp-hook
6204 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}). The
6205 @code{gnus-article-hide-pgp-hook} hook will be run after a @sc{pgp}
6206 signature has been hidden.
6209 @kindex W W P (Summary)
6210 @findex gnus-article-hide-pem
6211 Hide @sc{pem} (privacy enhanced messages) cruft
6212 (@code{gnus-article-hide-pem}).
6215 @kindex W W c (Summary)
6216 @findex gnus-article-hide-citation
6217 Hide citation (@code{gnus-article-hide-citation}). Some variables for
6218 customizing the hiding:
6222 @item gnus-cite-hide-percentage
6223 @vindex gnus-cite-hide-percentage
6224 If the cited text is of a bigger percentage than this variable (default
6225 50), hide the cited text.
6227 @item gnus-cite-hide-absolute
6228 @vindex gnus-cite-hide-absolute
6229 The cited text must have at least this length (default 10) before it
6232 @item gnus-cited-text-button-line-format
6233 @vindex gnus-cited-text-button-line-format
6234 Gnus adds buttons to show where the cited text has been hidden, and to
6235 allow toggle hiding the text. The format of the variable is specified
6236 by this format-like variable (@pxref{Formatting Variables}). These
6241 Start point of the hidden text.
6243 End point of the hidden text.
6245 Length of the hidden text.
6248 @item gnus-cited-lines-visible
6249 @vindex gnus-cited-lines-visible
6250 The number of lines at the beginning of the cited text to leave shown.
6255 @kindex W W C (Summary)
6256 @findex gnus-article-hide-citation-in-followups
6257 Hide cited text in articles that aren't roots
6258 (@code{gnus-article-hide-citation-in-followups}). This isn't very
6259 useful as an interactive command, but might be a handy function to stick
6260 in @code{gnus-article-display-hook} (@pxref{Customizing Articles}).
6264 All these ``hiding'' commands are toggles, but if you give a negative
6265 prefix to these commands, they will show what they have previously
6266 hidden. If you give a positive prefix, they will always hide.
6268 Also @pxref{Article Highlighting} for further variables for
6269 citation customization.
6272 @node Article Washing
6273 @subsection Article Washing
6275 @cindex article washing
6277 We call this ``article washing'' for a really good reason. Namely, the
6278 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
6280 @dfn{Washing} is defined by us as ``changing something from something to
6281 something else'', but normally results in something looking better.
6287 @kindex W l (Summary)
6288 @findex gnus-summary-stop-page-breaking
6289 Remove page breaks from the current article
6290 (@code{gnus-summary-stop-page-breaking}).
6293 @kindex W r (Summary)
6294 @findex gnus-summary-caesar-message
6295 @c @icon{gnus-summary-caesar-message}
6296 Do a Caesar rotate (rot13) on the article buffer
6297 (@code{gnus-summary-caesar-message}).
6298 Unreadable articles that tell you to read them with Caesar rotate or rot13.
6299 (Typically offensive jokes and such.)
6301 It's commonly called ``rot13'' because each letter is rotated 13
6302 positions in the alphabet, e. g. @samp{B} (letter #2) -> @samp{O} (letter
6303 #15). It is sometimes referred to as ``Caesar rotate'' because Caesar
6304 is rumoured to have employed this form of, uh, somewhat weak encryption.
6307 @kindex W t (Summary)
6308 @findex gnus-summary-toggle-header
6309 Toggle whether to display all headers in the article buffer
6310 (@code{gnus-summary-toggle-header}).
6313 @kindex W v (Summary)
6314 @findex gnus-summary-verbose-header
6315 Toggle whether to display all headers in the article buffer permanently
6316 (@code{gnus-summary-verbose-header}).
6319 @kindex W m (Summary)
6320 @findex gnus-summary-toggle-mime
6321 Toggle whether to run the article through @sc{mime} before displaying
6322 (@code{gnus-summary-toggle-mime}).
6325 @kindex W o (Summary)
6326 @findex gnus-article-treat-overstrike
6327 Treat overstrike (@code{gnus-article-treat-overstrike}).
6330 @kindex W d (Summary)
6331 @findex gnus-article-treat-dumbquotes
6332 Treat M******** sm*rtq**t*s (@code{gnus-article-treat-dumbquotes}).
6335 @kindex W w (Summary)
6336 @findex gnus-article-fill-cited-article
6337 Do word wrap (@code{gnus-article-fill-cited-article}). If you use this
6338 function in @code{gnus-article-display-hook}, it should be run fairly
6339 late and certainly after any highlighting.
6341 You can give the command a numerical prefix to specify the width to use
6345 @kindex W c (Summary)
6346 @findex gnus-article-remove-cr
6347 Remove CR (i. e., @samp{^M}s on the end of the lines)
6348 (@code{gnus-article-remove-cr}).
6351 @kindex W q (Summary)
6352 @findex gnus-article-de-quoted-unreadable
6353 Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
6354 Quoted-Printable is one common @sc{mime} encoding employed when sending
6355 non-ASCII (i. e., 8-bit) articles. It typically makes strings like
6356 @samp{déjà vu} look like @samp{d=E9j=E0 vu}, which doesn't look very
6360 @kindex W f (Summary)
6362 @findex gnus-article-display-x-face
6363 @findex gnus-article-x-face-command
6364 @vindex gnus-article-x-face-command
6365 @vindex gnus-article-x-face-too-ugly
6371 Look for and display any X-Face headers
6372 (@code{gnus-article-display-x-face}). The command executed by this
6373 function is given by the @code{gnus-article-x-face-command} variable.
6374 If this variable is a string, this string will be executed in a
6375 sub-shell. If it is a function, this function will be called with the
6376 face as the argument. If the @code{gnus-article-x-face-too-ugly} (which
6377 is a regexp) matches the @code{From} header, the face will not be shown.
6378 The default action under Emacs is to fork off an @code{xv} to view the
6379 face; under XEmacs the default action is to display the face before the
6380 @code{From} header. (It's nicer if XEmacs has been compiled with X-Face
6381 support---that will make display somewhat faster. If there's no native
6382 X-Face support, Gnus will try to convert the @code{X-Face} header using
6383 external programs from the @code{pbmplus} package and friends.) If you
6384 want to have this function in the display hook, it should probably come
6388 @kindex W b (Summary)
6389 @findex gnus-article-add-buttons
6390 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
6391 @xref{Article Buttons}
6394 @kindex W B (Summary)
6395 @findex gnus-article-add-buttons-to-head
6396 Add clickable buttons to the article headers
6397 (@code{gnus-article-add-buttons-to-head}).
6400 @kindex W E l (Summary)
6401 @findex gnus-article-strip-leading-blank-lines
6402 Remove all blank lines from the beginning of the article
6403 (@code{gnus-article-strip-leading-blank-lines}).
6406 @kindex W E m (Summary)
6407 @findex gnus-article-strip-multiple-blank-lines
6408 Replace all blank lines with empty lines and then all multiple empty
6409 lines with a single empty line.
6410 (@code{gnus-article-strip-multiple-blank-lines}).
6413 @kindex W E t (Summary)
6414 @findex gnus-article-remove-trailing-blank-lines
6415 Remove all blank lines at the end of the article
6416 (@code{gnus-article-remove-trailing-blank-lines}).
6419 @kindex W E a (Summary)
6420 @findex gnus-article-strip-blank-lines
6421 Do all the three commands above
6422 (@code{gnus-article-strip-blank-lines}).
6425 @kindex W E A (Summary)
6426 @findex gnus-article-strip-all-blank-lines
6427 Remove all blank lines
6428 (@code{gnus-article-strip-all-blank-lines}).
6431 @kindex W E s (Summary)
6432 @findex gnus-article-strip-leading-space
6433 Remove all white space from the beginning of all lines of the article
6434 body (@code{gnus-article-strip-leading-space}).
6439 @node Article Buttons
6440 @subsection Article Buttons
6443 People often include references to other stuff in articles, and it would
6444 be nice if Gnus could just fetch whatever it is that people talk about
6445 with the minimum of fuzz when you hit @kbd{RET} or use the middle mouse
6446 button on these references.
6448 Gnus adds @dfn{buttons} to certain standard references by default:
6449 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
6450 two variables, one that handles article bodies and one that handles
6455 @item gnus-button-alist
6456 @vindex gnus-button-alist
6457 This is an alist where each entry has this form:
6460 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
6466 All text that match this regular expression will be considered an
6467 external reference. Here's a typical regexp that matches embedded URLs:
6468 @samp{<URL:\\([^\n\r>]*\\)>}.
6471 Gnus has to know which parts of the matches is to be highlighted. This
6472 is a number that says what sub-expression of the regexp is to be
6473 highlighted. If you want it all highlighted, you use 0 here.
6476 This form will be @code{eval}ed, and if the result is non-@code{nil},
6477 this is considered a match. This is useful if you want extra sifting to
6478 avoid false matches.
6481 This function will be called when you click on this button.
6484 As with @var{button-par}, this is a sub-expression number, but this one
6485 says which part of the match is to be sent as data to @var{function}.
6489 So the full entry for buttonizing URLs is then
6492 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
6495 @item gnus-header-button-alist
6496 @vindex gnus-header-button-alist
6497 This is just like the other alist, except that it is applied to the
6498 article head only, and that each entry has an additional element that is
6499 used to say what headers to apply the buttonize coding to:
6502 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
6505 @var{HEADER} is a regular expression.
6507 @item gnus-button-url-regexp
6508 @vindex gnus-button-url-regexp
6509 A regular expression that matches embedded URLs. It is used in the
6510 default values of the variables above.
6512 @item gnus-article-button-face
6513 @vindex gnus-article-button-face
6514 Face used on buttons.
6516 @item gnus-article-mouse-face
6517 @vindex gnus-article-mouse-face
6518 Face used when the mouse cursor is over a button.
6524 @subsection Article Date
6526 The date is most likely generated in some obscure timezone you've never
6527 heard of, so it's quite nice to be able to find out what the time was
6528 when the article was sent.
6533 @kindex W T u (Summary)
6534 @findex gnus-article-date-ut
6535 Display the date in UT (aka. GMT, aka ZULU)
6536 (@code{gnus-article-date-ut}).
6539 @kindex W T i (Summary)
6540 @findex gnus-article-date-iso8601
6542 Display the date in international format, aka. ISO 8601
6543 (@code{gnus-article-date-iso8601}).
6546 @kindex W T l (Summary)
6547 @findex gnus-article-date-local
6548 Display the date in the local timezone (@code{gnus-article-date-local}).
6551 @kindex W T s (Summary)
6552 @vindex gnus-article-time-format
6553 @findex gnus-article-date-user
6554 @findex format-time-string
6555 Display the date using a user-defined format
6556 (@code{gnus-article-date-user}). The format is specified by the
6557 @code{gnus-article-time-format} variable, and is a string that's passed
6558 to @code{format-time-string}. See the documentation of that variable
6559 for a list of possible format specs.
6562 @kindex W T e (Summary)
6563 @findex gnus-article-date-lapsed
6564 @findex gnus-start-date-timer
6565 @findex gnus-stop-date-timer
6566 Say how much time has elapsed between the article was posted and now
6567 (@code{gnus-article-date-lapsed}). If you want to have this line
6568 updated continually, you can put
6571 (gnus-start-date-timer)
6574 in your @file{.gnus.el} file, or you can run it off of some hook. If
6575 you want to stop the timer, you can use the @code{gnus-stop-date-timer}
6579 @kindex W T o (Summary)
6580 @findex gnus-article-date-original
6581 Display the original date (@code{gnus-article-date-original}). This can
6582 be useful if you normally use some other conversion function and are
6583 worried that it might be doing something totally wrong. Say, claiming
6584 that the article was posted in 1854. Although something like that is
6585 @emph{totally} impossible. Don't you trust me? *titter*
6590 @node Article Signature
6591 @subsection Article Signature
6593 @cindex article signature
6595 @vindex gnus-signature-separator
6596 Each article is divided into two parts---the head and the body. The
6597 body can be divided into a signature part and a text part. The variable
6598 that says what is to be considered a signature is
6599 @code{gnus-signature-separator}. This is normally the standard
6600 @samp{^-- $} as mandated by son-of-RFC 1036. However, many people use
6601 non-standard signature separators, so this variable can also be a list
6602 of regular expressions to be tested, one by one. (Searches are done
6603 from the end of the body towards the beginning.) One likely value is:
6606 (setq gnus-signature-separator
6607 '("^-- $" ; The standard
6608 "^-- *$" ; A common mangling
6609 "^-------*$" ; Many people just use a looong
6610 ; line of dashes. Shame!
6611 "^ *--------*$" ; Double-shame!
6612 "^________*$" ; Underscores are also popular
6613 "^========*$")) ; Pervert!
6616 The more permissive you are, the more likely it is that you'll get false
6619 @vindex gnus-signature-limit
6620 @code{gnus-signature-limit} provides a limit to what is considered a
6625 If it is an integer, no signature may be longer (in characters) than
6628 If it is a floating point number, no signature may be longer (in lines)
6631 If it is a function, the function will be called without any parameters,
6632 and if it returns @code{nil}, there is no signature in the buffer.
6634 If it is a string, it will be used as a regexp. If it matches, the text
6635 in question is not a signature.
6638 This variable can also be a list where the elements may be of the types
6639 listed above. Here's an example:
6642 (setq gnus-signature-limit
6643 '(200.0 "^---*Forwarded article"))
6646 This means that if there are more than 200 lines after the signature
6647 separator, or the text after the signature separator is matched by
6648 the regular expression @samp{^---*Forwarded article}, then it isn't a
6649 signature after all.
6652 @node Article Commands
6653 @section Article Commands
6660 @kindex A P (Summary)
6661 @vindex gnus-ps-print-hook
6662 @findex gnus-summary-print-article
6663 Generate and print a PostScript image of the article buffer
6664 (@code{gnus-summary-print-article}). @code{gnus-ps-print-hook} will be
6665 run just before printing the buffer.
6670 @node Summary Sorting
6671 @section Summary Sorting
6672 @cindex summary sorting
6674 You can have the summary buffer sorted in various ways, even though I
6675 can't really see why you'd want that.
6680 @kindex C-c C-s C-n (Summary)
6681 @findex gnus-summary-sort-by-number
6682 Sort by article number (@code{gnus-summary-sort-by-number}).
6685 @kindex C-c C-s C-a (Summary)
6686 @findex gnus-summary-sort-by-author
6687 Sort by author (@code{gnus-summary-sort-by-author}).
6690 @kindex C-c C-s C-s (Summary)
6691 @findex gnus-summary-sort-by-subject
6692 Sort by subject (@code{gnus-summary-sort-by-subject}).
6695 @kindex C-c C-s C-d (Summary)
6696 @findex gnus-summary-sort-by-date
6697 Sort by date (@code{gnus-summary-sort-by-date}).
6700 @kindex C-c C-s C-l (Summary)
6701 @findex gnus-summary-sort-by-lines
6702 Sort by lines (@code{gnus-summary-sort-by-lines}).
6705 @kindex C-c C-s C-i (Summary)
6706 @findex gnus-summary-sort-by-score
6707 Sort by score (@code{gnus-summary-sort-by-score}).
6710 These functions will work both when you use threading and when you don't
6711 use threading. In the latter case, all summary lines will be sorted,
6712 line by line. In the former case, sorting will be done on a
6713 root-by-root basis, which might not be what you were looking for. To
6714 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
6718 @node Finding the Parent
6719 @section Finding the Parent
6720 @cindex parent articles
6721 @cindex referring articles
6726 @findex gnus-summary-refer-parent-article
6727 If you'd like to read the parent of the current article, and it is not
6728 displayed in the summary buffer, you might still be able to. That is,
6729 if the current group is fetched by @sc{nntp}, the parent hasn't expired
6730 and the @code{References} in the current article are not mangled, you
6731 can just press @kbd{^} or @kbd{A r}
6732 (@code{gnus-summary-refer-parent-article}). If everything goes well,
6733 you'll get the parent. If the parent is already displayed in the
6734 summary buffer, point will just move to this article.
6736 If given a positive numerical prefix, fetch that many articles back into
6737 the ancestry. If given a negative numerical prefix, fetch just that
6738 ancestor. So if you say @kbd{3 ^}, Gnus will fetch the parent, the
6739 grandparent and the grandgrandparent of the current article. If you say
6740 @kbd{-3 ^}, Gnus will only fetch the grandgrandparent of the current
6744 @findex gnus-summary-refer-references
6745 @kindex A R (Summary)
6746 Fetch all articles mentioned in the @code{References} header of the
6747 article (@code{gnus-summary-refer-references}).
6750 @findex gnus-summary-refer-thread
6751 @kindex A T (Summary)
6752 Display the full thread where the current article appears
6753 (@code{gnus-summary-refer-thread}). This command has to fetch all the
6754 headers in the current group to work, so it usually takes a while. If
6755 you do it often, you may consider setting @code{gnus-fetch-old-headers}
6756 to @code{invisible} (@pxref{Filling In Threads}). This won't have any
6757 visible effects normally, but it'll make this command work a whole lot
6758 faster. Of course, it'll make group entry somewhat slow.
6760 @vindex gnus-refer-thread-limit
6761 The @code{gnus-refer-thread-limit} variable says how many old (i. e.,
6762 articles before the first displayed in the current group) headers to
6763 fetch when doing this command. The default is 200. If @code{t}, all
6764 the available headers will be fetched. This variable can be overridden
6765 by giving the @kbd{A T} command a numerical prefix.
6768 @findex gnus-summary-refer-article
6769 @kindex M-^ (Summary)
6771 @cindex fetching by Message-ID
6772 You can also ask the @sc{nntp} server for an arbitrary article, no
6773 matter what group it belongs to. @kbd{M-^}
6774 (@code{gnus-summary-refer-article}) will ask you for a
6775 @code{Message-ID}, which is one of those long, hard-to-read thingies
6776 that look something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You
6777 have to get it all exactly right. No fuzzy searches, I'm afraid.
6780 The current select method will be used when fetching by
6781 @code{Message-ID} from non-news select method, but you can override this
6782 by giving this command a prefix.
6784 @vindex gnus-refer-article-method
6785 If the group you are reading is located on a backend that does not
6786 support fetching by @code{Message-ID} very well (like @code{nnspool}),
6787 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
6788 would, perhaps, be best if the @sc{nntp} server you consult is the one
6789 updating the spool you are reading from, but that's not really
6792 Most of the mail backends support fetching by @code{Message-ID}, but do
6793 not do a particularly excellent job at it. That is, @code{nnmbox} and
6794 @code{nnbabyl} are able to locate articles from any groups, while
6795 @code{nnml} and @code{nnfolder} are only able to locate articles that
6796 have been posted to the current group. (Anything else would be too time
6797 consuming.) @code{nnmh} does not support this at all.
6800 @node Alternative Approaches
6801 @section Alternative Approaches
6803 Different people like to read news using different methods. This being
6804 Gnus, we offer a small selection of minor modes for the summary buffers.
6807 * Pick and Read:: First mark articles and then read them.
6808 * Binary Groups:: Auto-decode all articles.
6813 @subsection Pick and Read
6814 @cindex pick and read
6816 Some newsreaders (like @code{nn} and, uhm, @code{Netnews} on VM/CMS) use
6817 a two-phased reading interface. The user first marks in a summary
6818 buffer the articles she wants to read. Then she starts reading the
6819 articles with just an article buffer displayed.
6821 @findex gnus-pick-mode
6822 @kindex M-x gnus-pick-mode
6823 Gnus provides a summary buffer minor mode that allows
6824 this---@code{gnus-pick-mode}. This basically means that a few process
6825 mark commands become one-keystroke commands to allow easy marking, and
6826 it provides one additional command for switching to the summary buffer.
6828 Here are the available keystrokes when using pick mode:
6833 @findex gnus-summary-mark-as-processable
6834 Pick the article on the current line
6835 (@code{gnus-summary-mark-as-processable}). If given a numerical prefix,
6836 go to that article and pick it. (The line number is normally displayed
6837 at the beginning of the summary pick lines.)
6840 @kindex SPACE (Pick)
6841 @findex gnus-pick-next-page
6842 Scroll the summary buffer up one page (@code{gnus-pick-next-page}). If
6843 at the end of the buffer, start reading the picked articles.
6847 @findex gnus-summary-unmark-as-processable
6848 Unpick the article (@code{gnus-summary-unmark-as-processable}).
6852 @findex gnus-summary-unmark-all-processable
6853 Unpick all articles (@code{gnus-summary-unmark-all-processable}).
6857 @findex gnus-uu-mark-thread
6858 Pick the thread (@code{gnus-uu-mark-thread}).
6862 @findex gnus-uu-unmark-thread
6863 Unpick the thread (@code{gnus-uu-unmark-thread}).
6867 @findex gnus-uu-mark-region
6868 Pick the region (@code{gnus-uu-mark-region}).
6872 @findex gnus-uu-unmark-region
6873 Unpick the region (@code{gnus-uu-unmark-region}).
6877 @findex gnus-uu-mark-by-regexp
6878 Pick articles that match a regexp (@code{gnus-uu-mark-by-regexp}).
6882 @findex gnus-uu-unmark-by-regexp
6883 Unpick articles that match a regexp (@code{gnus-uu-unmark-by-regexp}).
6887 @findex gnus-uu-mark-buffer
6888 Pick the buffer (@code{gnus-uu-mark-buffer}).
6892 @findex gnus-uu-unmark-buffer
6893 Unpick the buffer (@code{gnus-uu-unmark-buffer}).
6897 @findex gnus-pick-start-reading
6898 @vindex gnus-pick-display-summary
6899 Start reading the picked articles (@code{gnus-pick-start-reading}). If
6900 given a prefix, mark all unpicked articles as read first. If
6901 @code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer
6902 will still be visible when you are reading.
6906 If this sounds like a good idea to you, you could say:
6909 (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
6912 @vindex gnus-pick-mode-hook
6913 @code{gnus-pick-mode-hook} is run in pick minor mode buffers.
6915 @vindex gnus-mark-unpicked-articles-as-read
6916 If @code{gnus-mark-unpicked-articles-as-read} is non-@code{nil}, mark
6917 all unpicked articles as read. The default is @code{nil}.
6919 @vindex gnus-summary-pick-line-format
6920 The summary line format in pick mode is slightly different from the
6921 standard format. At the beginning of each line the line number is
6922 displayed. The pick mode line format is controlled by the
6923 @code{gnus-summary-pick-line-format} variable (@pxref{Formatting
6924 Variables}). It accepts the same format specs that
6925 @code{gnus-summary-line-format} does (@pxref{Summary Buffer Lines}).
6929 @subsection Binary Groups
6930 @cindex binary groups
6932 @findex gnus-binary-mode
6933 @kindex M-x gnus-binary-mode
6934 If you spend much time in binary groups, you may grow tired of hitting
6935 @kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode}
6936 is a minor mode for summary buffers that makes all ordinary Gnus article
6937 selection functions uudecode series of articles and display the result
6938 instead of just displaying the articles the normal way.
6941 @findex gnus-binary-show-article
6942 The only way, in fact, to see the actual articles is the @kbd{g}
6943 command, when you have turned on this mode
6944 (@code{gnus-binary-show-article}).
6946 @vindex gnus-binary-mode-hook
6947 @code{gnus-binary-mode-hook} is called in binary minor mode buffers.
6951 @section Tree Display
6954 @vindex gnus-use-trees
6955 If you don't like the normal Gnus summary display, you might try setting
6956 @code{gnus-use-trees} to @code{t}. This will create (by default) an
6957 additional @dfn{tree buffer}. You can execute all summary mode commands
6960 There are a few variables to customize the tree display, of course:
6963 @item gnus-tree-mode-hook
6964 @vindex gnus-tree-mode-hook
6965 A hook called in all tree mode buffers.
6967 @item gnus-tree-mode-line-format
6968 @vindex gnus-tree-mode-line-format
6969 A format string for the mode bar in the tree mode buffers. The default
6970 is @samp{Gnus: %%b %S %Z}. For a list of valid specs, @pxref{Summary
6973 @item gnus-selected-tree-face
6974 @vindex gnus-selected-tree-face
6975 Face used for highlighting the selected article in the tree buffer. The
6976 default is @code{modeline}.
6978 @item gnus-tree-line-format
6979 @vindex gnus-tree-line-format
6980 A format string for the tree nodes. The name is a bit of a misnomer,
6981 though---it doesn't define a line, but just the node. The default value
6982 is @samp{%(%[%3,3n%]%)}, which displays the first three characters of
6983 the name of the poster. It is vital that all nodes are of the same
6984 length, so you @emph{must} use @samp{%4,4n}-like specifiers.
6990 The name of the poster.
6992 The @code{From} header.
6994 The number of the article.
6996 The opening bracket.
6998 The closing bracket.
7003 @xref{Formatting Variables}.
7005 Variables related to the display are:
7008 @item gnus-tree-brackets
7009 @vindex gnus-tree-brackets
7010 This is used for differentiating between ``real'' articles and
7011 ``sparse'' articles. The format is @var{((real-open . real-close)
7012 (sparse-open . sparse-close) (dummy-open . dummy-close))}, and the
7013 default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}) (?< . ?>))}.
7015 @item gnus-tree-parent-child-edges
7016 @vindex gnus-tree-parent-child-edges
7017 This is a list that contains the characters used for connecting parent
7018 nodes to their children. The default is @code{(?- ?\\ ?|)}.
7022 @item gnus-tree-minimize-window
7023 @vindex gnus-tree-minimize-window
7024 If this variable is non-@code{nil}, Gnus will try to keep the tree
7025 buffer as small as possible to allow more room for the other Gnus
7026 windows. If this variable is a number, the tree buffer will never be
7027 higher than that number. The default is @code{t}. Note that if you
7028 have several windows displayed side-by-side in a frame and the tree
7029 buffer is one of these, minimizing the tree window will also resize all
7030 other windows displayed next to it.
7032 @item gnus-generate-tree-function
7033 @vindex gnus-generate-tree-function
7034 @findex gnus-generate-horizontal-tree
7035 @findex gnus-generate-vertical-tree
7036 The function that actually generates the thread tree. Two predefined
7037 functions are available: @code{gnus-generate-horizontal-tree} and
7038 @code{gnus-generate-vertical-tree} (which is the default).
7042 Here's an example from a horizontal tree buffer:
7045 @{***@}-(***)-[odd]-[Gun]
7055 Here's the same thread displayed in a vertical tree buffer:
7059 |--------------------------\-----\-----\
7060 (***) [Bjo] [Gun] [Gun]
7062 [odd] [Jan] [odd] (***) [Jor]
7064 [Gun] [Eri] [Eri] [odd]
7069 If you're using horizontal trees, it might be nice to display the trees
7070 side-by-side with the summary buffer. You could add something like the
7071 following to your @file{.gnus.el} file:
7074 (setq gnus-use-trees t
7075 gnus-generate-tree-function 'gnus-generate-horizontal-tree
7076 gnus-tree-minimize-window nil)
7077 (gnus-add-configuration
7081 (summary 0.75 point)
7086 @xref{Windows Configuration}.
7089 @node Mail Group Commands
7090 @section Mail Group Commands
7091 @cindex mail group commands
7093 Some commands only make sense in mail groups. If these commands are
7094 invalid in the current group, they will raise a hell and let you know.
7096 All these commands (except the expiry and edit commands) use the
7097 process/prefix convention (@pxref{Process/Prefix}).
7102 @kindex B e (Summary)
7103 @findex gnus-summary-expire-articles
7104 Expire all expirable articles in the group
7105 (@code{gnus-summary-expire-articles}).
7108 @kindex B M-C-e (Summary)
7109 @findex gnus-summary-expire-articles-now
7110 Delete all the expirable articles in the group
7111 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
7112 articles eligible for expiry in the current group will
7113 disappear forever into that big @file{/dev/null} in the sky.
7116 @kindex B DEL (Summary)
7117 @findex gnus-summary-delete-article
7118 @c @icon{gnus-summary-mail-delete}
7119 Delete the mail article. This is ``delete'' as in ``delete it from your
7120 disk forever and ever, never to return again.'' Use with caution.
7121 (@code{gnus-summary-delete-article}).
7124 @kindex B m (Summary)
7126 @findex gnus-summary-move-article
7127 Move the article from one mail group to another
7128 (@code{gnus-summary-move-article}).
7131 @kindex B c (Summary)
7133 @findex gnus-summary-copy-article
7134 @c @icon{gnus-summary-mail-copy}
7135 Copy the article from one group (mail group or not) to a mail group
7136 (@code{gnus-summary-copy-article}).
7139 @kindex B B (Summary)
7140 @cindex crosspost mail
7141 @findex gnus-summary-crosspost-article
7142 Crosspost the current article to some other group
7143 (@code{gnus-summary-crosspost-article}). This will create a new copy of
7144 the article in the other group, and the Xref headers of the article will
7145 be properly updated.
7148 @kindex B i (Summary)
7149 @findex gnus-summary-import-article
7150 Import an arbitrary file into the current mail newsgroup
7151 (@code{gnus-summary-import-article}). You will be prompted for a file
7152 name, a @code{From} header and a @code{Subject} header.
7155 @kindex B r (Summary)
7156 @findex gnus-summary-respool-article
7157 Respool the mail article (@code{gnus-summary-move-article}).
7158 @code{gnus-summary-respool-default-method} will be used as the default
7159 select method when respooling. This variable is @code{nil} by default,
7160 which means that the current group select method will be used instead.
7164 @kindex B w (Summary)
7166 @findex gnus-summary-edit-article
7167 @kindex C-c C-c (Article)
7168 Edit the current article (@code{gnus-summary-edit-article}). To finish
7169 editing and make the changes permanent, type @kbd{C-c C-c}
7170 (@kbd{gnus-summary-edit-article-done}). If you give a prefix to the
7171 @kbd{C-c C-c} command, Gnus won't re-highlight the article.
7174 @kindex B q (Summary)
7175 @findex gnus-summary-respool-query
7176 If you want to re-spool an article, you might be curious as to what group
7177 the article will end up in before you do the re-spooling. This command
7178 will tell you (@code{gnus-summary-respool-query}).
7181 @kindex B p (Summary)
7182 @findex gnus-summary-article-posted-p
7183 Some people have a tendency to send you "courtesy" copies when they
7184 follow up to articles you have posted. These usually have a
7185 @code{Newsgroups} header in them, but not always. This command
7186 (@code{gnus-summary-article-posted-p}) will try to fetch the current
7187 article from your news server (or rather, from
7188 @code{gnus-refer-article-method} or @code{gnus-select-method}) and will
7189 report back whether it found the article or not. Even if it says that
7190 it didn't find the article, it may have been posted anyway---mail
7191 propagation is much faster than news propagation, and the news copy may
7192 just not have arrived yet.
7196 @vindex gnus-move-split-methods
7197 @cindex moving articles
7198 If you move (or copy) articles regularly, you might wish to have Gnus
7199 suggest where to put the articles. @code{gnus-move-split-methods} is a
7200 variable that uses the same syntax as @code{gnus-split-methods}
7201 (@pxref{Saving Articles}). You may customize that variable to create
7202 suggestions you find reasonable.
7205 (setq gnus-move-split-methods
7206 '(("^From:.*Lars Magne" "nnml:junk")
7207 ("^Subject:.*gnus" "nnfolder:important")
7208 (".*" "nnml:misc")))
7212 @node Various Summary Stuff
7213 @section Various Summary Stuff
7216 * Summary Group Information:: Information oriented commands.
7217 * Searching for Articles:: Multiple article commands.
7218 * Summary Generation Commands:: (Re)generating the summary buffer.
7219 * Really Various Summary Commands:: Those pesky non-conformant commands.
7223 @vindex gnus-summary-mode-hook
7224 @item gnus-summary-mode-hook
7225 This hook is called when creating a summary mode buffer.
7227 @vindex gnus-summary-generate-hook
7228 @item gnus-summary-generate-hook
7229 This is called as the last thing before doing the threading and the
7230 generation of the summary buffer. It's quite convenient for customizing
7231 the threading variables based on what data the newsgroup has. This hook
7232 is called from the summary buffer after most summary buffer variables
7235 @vindex gnus-summary-prepare-hook
7236 @item gnus-summary-prepare-hook
7237 It is called after the summary buffer has been generated. You might use
7238 it to, for instance, highlight lines or modify the look of the buffer in
7239 some other ungodly manner. I don't care.
7241 @vindex gnus-summary-ignore-duplicates
7242 @item gnus-summary-ignore-duplicates
7243 When Gnus discovers two articles that have the same @code{Message-ID},
7244 it has to do something drastic. No articles are allowed to have the
7245 same @code{Message-ID}, but this may happen when reading mail from some
7246 sources. Gnus allows you to customize what happens with this variable.
7247 If it is @code{nil} (which is the default), Gnus will rename the
7248 @code{Message-ID} (for display purposes only) and display the article as
7249 any other article. If this variable is @code{t}, it won't display the
7250 article---it'll be as if it never existed.
7255 @node Summary Group Information
7256 @subsection Summary Group Information
7261 @kindex H f (Summary)
7262 @findex gnus-summary-fetch-faq
7263 @vindex gnus-group-faq-directory
7264 Try to fetch the FAQ (list of frequently asked questions) for the
7265 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
7266 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
7267 on a remote machine. This variable can also be a list of directories.
7268 In that case, giving a prefix to this command will allow you to choose
7269 between the various sites. @code{ange-ftp} or @code{efs} will probably
7270 be used for fetching the file.
7273 @kindex H d (Summary)
7274 @findex gnus-summary-describe-group
7275 Give a brief description of the current group
7276 (@code{gnus-summary-describe-group}). If given a prefix, force
7277 rereading the description from the server.
7280 @kindex H h (Summary)
7281 @findex gnus-summary-describe-briefly
7282 Give an extremely brief description of the most important summary
7283 keystrokes (@code{gnus-summary-describe-briefly}).
7286 @kindex H i (Summary)
7287 @findex gnus-info-find-node
7288 Go to the Gnus info node (@code{gnus-info-find-node}).
7292 @node Searching for Articles
7293 @subsection Searching for Articles
7298 @kindex M-s (Summary)
7299 @findex gnus-summary-search-article-forward
7300 Search through all subsequent articles for a regexp
7301 (@code{gnus-summary-search-article-forward}).
7304 @kindex M-r (Summary)
7305 @findex gnus-summary-search-article-backward
7306 Search through all previous articles for a regexp
7307 (@code{gnus-summary-search-article-backward}).
7311 @findex gnus-summary-execute-command
7312 This command will prompt you for a header field, a regular expression to
7313 match on this field, and a command to be executed if the match is made
7314 (@code{gnus-summary-execute-command}). If given a prefix, search
7318 @kindex M-& (Summary)
7319 @findex gnus-summary-universal-argument
7320 Perform any operation on all articles that have been marked with
7321 the process mark (@code{gnus-summary-universal-argument}).
7324 @node Summary Generation Commands
7325 @subsection Summary Generation Commands
7330 @kindex Y g (Summary)
7331 @findex gnus-summary-prepare
7332 Regenerate the current summary buffer (@code{gnus-summary-prepare}).
7335 @kindex Y c (Summary)
7336 @findex gnus-summary-insert-cached-articles
7337 Pull all cached articles (for the current group) into the summary buffer
7338 (@code{gnus-summary-insert-cached-articles}).
7343 @node Really Various Summary Commands
7344 @subsection Really Various Summary Commands
7349 @kindex C-d (Summary)
7350 @findex gnus-summary-enter-digest-group
7351 If the current article is a collection of other articles (for instance,
7352 a digest), you might use this command to enter a group based on the that
7353 article (@code{gnus-summary-enter-digest-group}). Gnus will try to
7354 guess what article type is currently displayed unless you give a prefix
7355 to this command, which forces a ``digest'' interpretation. Basically,
7356 whenever you see a message that is a collection of other messages of
7357 some format, you @kbd{C-d} and read these messages in a more convenient
7361 @kindex M-C-d (Summary)
7362 @findex gnus-summary-read-document
7363 This command is very similar to the one above, but lets you gather
7364 several documents into one biiig group
7365 (@code{gnus-summary-read-document}). It does this by opening several
7366 @code{nndoc} groups for each document, and then opening an
7367 @code{nnvirtual} group on top of these @code{nndoc} groups. This
7368 command understands the process/prefix convention
7369 (@pxref{Process/Prefix}).
7372 @kindex C-t (Summary)
7373 @findex gnus-summary-toggle-truncation
7374 Toggle truncation of summary lines
7375 (@code{gnus-summary-toggle-truncation}). This will probably confuse the
7376 line centering function in the summary buffer, so it's not a good idea
7377 to have truncation switched off while reading articles.
7381 @findex gnus-summary-expand-window
7382 Expand the summary buffer window (@code{gnus-summary-expand-window}).
7383 If given a prefix, force an @code{article} window configuration.
7386 @kindex M-C-e (Summary)
7387 @findex gnus-summary-edit-parameters
7388 Edit the group parameters (@pxref{Group Parameters}) of the current
7389 group (@code{gnus-summary-edit-parameters}).
7394 @node Exiting the Summary Buffer
7395 @section Exiting the Summary Buffer
7396 @cindex summary exit
7397 @cindex exiting groups
7399 Exiting from the summary buffer will normally update all info on the
7400 group and return you to the group buffer.
7406 @kindex Z Z (Summary)
7408 @findex gnus-summary-exit
7409 @vindex gnus-summary-exit-hook
7410 @vindex gnus-summary-prepare-exit-hook
7411 @c @icon{gnus-summary-exit}
7412 Exit the current group and update all information on the group
7413 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
7414 called before doing much of the exiting, which calls
7415 @code{gnus-summary-expire-articles} by default.
7416 @code{gnus-summary-exit-hook} is called after finishing the exit
7417 process. @code{gnus-group-no-more-groups-hook} is run when returning to
7418 group mode having no more (unread) groups.
7422 @kindex Z E (Summary)
7424 @findex gnus-summary-exit-no-update
7425 Exit the current group without updating any information on the group
7426 (@code{gnus-summary-exit-no-update}).
7430 @kindex Z c (Summary)
7432 @findex gnus-summary-catchup-and-exit
7433 @c @icon{gnus-summary-catchup-and-exit}
7434 Mark all unticked articles in the group as read and then exit
7435 (@code{gnus-summary-catchup-and-exit}).
7438 @kindex Z C (Summary)
7439 @findex gnus-summary-catchup-all-and-exit
7440 Mark all articles, even the ticked ones, as read and then exit
7441 (@code{gnus-summary-catchup-all-and-exit}).
7444 @kindex Z n (Summary)
7445 @findex gnus-summary-catchup-and-goto-next-group
7446 Mark all articles as read and go to the next group
7447 (@code{gnus-summary-catchup-and-goto-next-group}).
7450 @kindex Z R (Summary)
7451 @findex gnus-summary-reselect-current-group
7452 Exit this group, and then enter it again
7453 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
7454 all articles, both read and unread.
7458 @kindex Z G (Summary)
7459 @kindex M-g (Summary)
7460 @findex gnus-summary-rescan-group
7461 @c @icon{gnus-summary-mail-get}
7462 Exit the group, check for new articles in the group, and select the
7463 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
7464 articles, both read and unread.
7467 @kindex Z N (Summary)
7468 @findex gnus-summary-next-group
7469 Exit the group and go to the next group
7470 (@code{gnus-summary-next-group}).
7473 @kindex Z P (Summary)
7474 @findex gnus-summary-prev-group
7475 Exit the group and go to the previous group
7476 (@code{gnus-summary-prev-group}).
7479 @kindex Z s (Summary)
7480 @findex gnus-summary-save-newsrc
7481 Save the current number of read/marked articles in the dribble buffer
7482 and then save the dribble buffer (@code{gnus-summary-save-newsrc}). If
7483 given a prefix, also save the @file{.newsrc} file(s). Using this
7484 command will make exit without updating (the @kbd{Q} command) worthless.
7487 @vindex gnus-exit-group-hook
7488 @code{gnus-exit-group-hook} is called when you exit the current
7491 @findex gnus-summary-wake-up-the-dead
7492 @findex gnus-dead-summary-mode
7493 @vindex gnus-kill-summary-on-exit
7494 If you're in the habit of exiting groups, and then changing your mind
7495 about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}.
7496 If you do that, Gnus won't kill the summary buffer when you exit it.
7497 (Quelle surprise!) Instead it will change the name of the buffer to
7498 something like @samp{*Dead Summary ... *} and install a minor mode
7499 called @code{gnus-dead-summary-mode}. Now, if you switch back to this
7500 buffer, you'll find that all keys are mapped to a function called
7501 @code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead
7502 summary buffer will result in a live, normal summary buffer.
7504 There will never be more than one dead summary buffer at any one time.
7506 @vindex gnus-use-cross-reference
7507 The data on the current group will be updated (which articles you have
7508 read, which articles you have replied to, etc.) when you exit the
7509 summary buffer. If the @code{gnus-use-cross-reference} variable is
7510 @code{t} (which is the default), articles that are cross-referenced to
7511 this group and are marked as read, will also be marked as read in the
7512 other subscribed groups they were cross-posted to. If this variable is
7513 neither @code{nil} nor @code{t}, the article will be marked as read in
7514 both subscribed and unsubscribed groups (@pxref{Crosspost Handling}).
7517 @node Crosspost Handling
7518 @section Crosspost Handling
7522 Marking cross-posted articles as read ensures that you'll never have to
7523 read the same article more than once. Unless, of course, somebody has
7524 posted it to several groups separately. Posting the same article to
7525 several groups (not cross-posting) is called @dfn{spamming}, and you are
7526 by law required to send nasty-grams to anyone who perpetrates such a
7527 heinous crime. You may want to try NoCeM handling to filter out spam
7530 Remember: Cross-posting is kinda ok, but posting the same article
7531 separately to several groups is not. Massive cross-posting (aka.
7532 @dfn{velveeta}) is to be avoided at all costs, and you can even use the
7533 @code{gnus-summary-mail-crosspost-complaint} command to complain about
7534 excessive crossposting (@pxref{Summary Mail Commands}).
7536 @cindex cross-posting
7539 One thing that may cause Gnus to not do the cross-posting thing
7540 correctly is if you use an @sc{nntp} server that supports @sc{xover}
7541 (which is very nice, because it speeds things up considerably) which
7542 does not include the @code{Xref} header in its @sc{nov} lines. This is
7543 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
7544 even with @sc{xover} by registering the @code{Xref} lines of all
7545 articles you actually read, but if you kill the articles, or just mark
7546 them as read without reading them, Gnus will not get a chance to snoop
7547 the @code{Xref} lines out of these articles, and will be unable to use
7548 the cross reference mechanism.
7550 @cindex LIST overview.fmt
7551 @cindex overview.fmt
7552 To check whether your @sc{nntp} server includes the @code{Xref} header
7553 in its overview files, try @samp{telnet your.nntp.server nntp},
7554 @samp{MODE READER} on @code{inn} servers, and then say @samp{LIST
7555 overview.fmt}. This may not work, but if it does, and the last line you
7556 get does not read @samp{Xref:full}, then you should shout and whine at
7557 your news admin until she includes the @code{Xref} header in the
7560 @vindex gnus-nov-is-evil
7561 If you want Gnus to get the @code{Xref}s right all the time, you have to
7562 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
7567 For an alternative approach, @pxref{Duplicate Suppression}.
7570 @node Duplicate Suppression
7571 @section Duplicate Suppression
7573 By default, Gnus tries to make sure that you don't have to read the same
7574 article more than once by utilizing the crossposting mechanism
7575 (@pxref{Crosspost Handling}). However, that simple and efficient
7576 approach may not work satisfactory for some users for various
7581 The @sc{nntp} server may fail to generate the @code{Xref} header. This
7582 is evil and not very common.
7585 The @sc{nntp} server may fail to include the @code{Xref} header in the
7586 @file{.overview} data bases. This is evil and all too common, alas.
7589 You may be reading the same group (or several related groups) from
7590 different @sc{nntp} servers.
7593 You may be getting mail that duplicates articles posted to groups.
7596 I'm sure there are other situations where @code{Xref} handling fails as
7597 well, but these four are the most common situations.
7599 If, and only if, @code{Xref} handling fails for you, then you may
7600 consider switching on @dfn{duplicate suppression}. If you do so, Gnus
7601 will remember the @code{Message-ID}s of all articles you have read or
7602 otherwise marked as read, and then, as if by magic, mark them as read
7603 all subsequent times you see them---in @emph{all} groups. Using this
7604 mechanism is quite likely to be somewhat inefficient, but not overly
7605 so. It's certainly preferable to reading the same articles more than
7608 Duplicate suppression is not a very subtle instrument. It's more like a
7609 sledge hammer than anything else. It works in a very simple
7610 fashion---if you have marked an article as read, it adds this Message-ID
7611 to a cache. The next time it sees this Message-ID, it will mark the
7612 article as read with the @samp{M} mark. It doesn't care what group it
7616 @item gnus-suppress-duplicates
7617 @vindex gnus-suppress-duplicates
7618 If non-@code{nil}, suppress duplicates.
7620 @item gnus-save-duplicate-list
7621 @vindex gnus-save-duplicate-list
7622 If non-@code{nil}, save the list of duplicates to a file. This will
7623 make startup and shutdown take longer, so the default is @code{nil}.
7624 However, this means that only duplicate articles read in a single Gnus
7625 session are suppressed.
7627 @item gnus-duplicate-list-length
7628 @vindex gnus-duplicate-list-length
7629 This variable says how many @code{Message-ID}s to keep in the duplicate
7630 suppression list. The default is 10000.
7632 @item gnus-duplicate-file
7633 @vindex gnus-duplicate-file
7634 The name of the file to store the duplicate suppression list in. The
7635 default is @file{~/News/suppression}.
7638 If you have a tendency to stop and start Gnus often, setting
7639 @code{gnus-save-duplicate-list} to @code{t} is probably a good idea. If
7640 you leave Gnus running for weeks on end, you may have it @code{nil}. On
7641 the other hand, saving the list makes startup and shutdown much slower,
7642 so that means that if you stop and start Gnus often, you should set
7643 @code{gnus-save-duplicate-list} to @code{nil}. Uhm. I'll leave this up
7644 to you to figure out, I think.
7647 @node The Article Buffer
7648 @chapter The Article Buffer
7649 @cindex article buffer
7651 The articles are displayed in the article buffer, of which there is only
7652 one. All the summary buffers share the same article buffer unless you
7653 tell Gnus otherwise.
7656 * Hiding Headers:: Deciding what headers should be displayed.
7657 * Using MIME:: Pushing articles through @sc{mime} before reading them.
7658 * Customizing Articles:: Tailoring the look of the articles.
7659 * Article Keymap:: Keystrokes available in the article buffer.
7660 * Misc Article:: Other stuff.
7664 @node Hiding Headers
7665 @section Hiding Headers
7666 @cindex hiding headers
7667 @cindex deleting headers
7669 The top section of each article is the @dfn{head}. (The rest is the
7670 @dfn{body}, but you may have guessed that already.)
7672 @vindex gnus-show-all-headers
7673 There is a lot of useful information in the head: the name of the person
7674 who wrote the article, the date it was written and the subject of the
7675 article. That's well and nice, but there's also lots of information
7676 most people do not want to see---what systems the article has passed
7677 through before reaching you, the @code{Message-ID}, the
7678 @code{References}, etc. ad nauseum---and you'll probably want to get rid
7679 of some of those lines. If you want to keep all those lines in the
7680 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
7682 Gnus provides you with two variables for sifting headers:
7686 @item gnus-visible-headers
7687 @vindex gnus-visible-headers
7688 If this variable is non-@code{nil}, it should be a regular expression
7689 that says what headers you wish to keep in the article buffer. All
7690 headers that do not match this variable will be hidden.
7692 For instance, if you only want to see the name of the person who wrote
7693 the article and the subject, you'd say:
7696 (setq gnus-visible-headers "^From:\\|^Subject:")
7699 This variable can also be a list of regexps to match headers to
7702 @item gnus-ignored-headers
7703 @vindex gnus-ignored-headers
7704 This variable is the reverse of @code{gnus-visible-headers}. If this
7705 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
7706 should be a regular expression that matches all lines that you want to
7707 hide. All lines that do not match this variable will remain visible.
7709 For instance, if you just want to get rid of the @code{References} line
7710 and the @code{Xref} line, you might say:
7713 (setq gnus-ignored-headers "^References:\\|^Xref:")
7716 This variable can also be a list of regexps to match headers to
7719 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
7720 variable will have no effect.
7724 @vindex gnus-sorted-header-list
7725 Gnus can also sort the headers for you. (It does this by default.) You
7726 can control the sorting by setting the @code{gnus-sorted-header-list}
7727 variable. It is a list of regular expressions that says in what order
7728 the headers are to be displayed.
7730 For instance, if you want the name of the author of the article first,
7731 and then the subject, you might say something like:
7734 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
7737 Any headers that are to remain visible, but are not listed in this
7738 variable, will be displayed in random order after all the headers listed in this variable.
7740 @findex gnus-article-hide-boring-headers
7741 @vindex gnus-article-display-hook
7742 @vindex gnus-boring-article-headers
7743 You can hide further boring headers by entering
7744 @code{gnus-article-hide-boring-headers} into
7745 @code{gnus-article-display-hook}. What this function does depends on
7746 the @code{gnus-boring-article-headers} variable. It's a list, but this
7747 list doesn't actually contain header names. Instead is lists various
7748 @dfn{boring conditions} that Gnus can check and remove from sight.
7750 These conditions are:
7753 Remove all empty headers.
7755 Remove the @code{Newsgroups} header if it only contains the current group
7758 Remove the @code{Followup-To} header if it is identical to the
7759 @code{Newsgroups} header.
7761 Remove the @code{Reply-To} header if it lists the same address as the
7764 Remove the @code{Date} header if the article is less than three days
7767 Remove the @code{To} header if it is very long.
7769 Remove all @code{To} headers if there are more than one.
7772 To include the four first elements, you could say something like;
7775 (setq gnus-boring-article-headers
7776 '(empty newsgroups followup-to reply-to))
7779 This is also the default value for this variable.
7783 @section Using @sc{mime}
7786 Mime is a standard for waving your hands through the air, aimlessly,
7787 while people stand around yawning.
7789 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
7790 while all newsreaders die of fear.
7792 @sc{mime} may specify what character set the article uses, the encoding
7793 of the characters, and it also makes it possible to embed pictures and
7794 other naughty stuff in innocent-looking articles.
7796 @vindex gnus-show-mime
7797 @vindex gnus-show-mime-method
7798 @vindex gnus-strict-mime
7799 @findex metamail-buffer
7800 Gnus handles @sc{mime} by pushing the articles through
7801 @code{gnus-show-mime-method}, which is @code{metamail-buffer} by
7802 default. This function calls the external @code{metamail} program to
7803 actually do the work. One common problem with this program is that is
7804 thinks that it can't display 8-bit things in the Emacs buffer. To tell
7805 it the truth, put something like the following in your
7806 @file{.bash_profile} file. (You do use @code{bash}, don't you?)
7809 export MM_CHARSET="iso-8859-1"
7812 For more information on @code{metamail}, see its manual page.
7814 Set @code{gnus-show-mime} to @code{t} if you want to use
7815 @sc{mime} all the time. However, if @code{gnus-strict-mime} is
7816 non-@code{nil}, the @sc{mime} method will only be used if there are
7817 @sc{mime} headers in the article. If you have @code{gnus-show-mime}
7818 set, then you'll see some unfortunate display glitches in the article
7819 buffer. These can't be avoided.
7821 It might be best to just use the toggling functions from the summary
7822 buffer to avoid getting nasty surprises. (For instance, you enter the
7823 group @samp{alt.sing-a-long} and, before you know it, @sc{mime} has
7824 decoded the sound file in the article and some horrible sing-a-long song
7825 comes screaming out your speakers, and you can't find the volume
7826 button, because there isn't one, and people are starting to look at you,
7827 and you try to stop the program, but you can't, and you can't find the
7828 program to control the volume, and everybody else in the room suddenly
7829 decides to look at you disdainfully, and you'll feel rather stupid.)
7831 Any similarity to real events and people is purely coincidental. Ahem.
7834 @node Customizing Articles
7835 @section Customizing Articles
7836 @cindex article customization
7838 @vindex gnus-article-display-hook
7839 The @code{gnus-article-display-hook} is called after the article has
7840 been inserted into the article buffer. It is meant to handle all
7841 treatment of the article before it is displayed.
7843 @findex gnus-article-maybe-highlight
7844 By default this hook just contains @code{gnus-article-hide-headers},
7845 @code{gnus-article-treat-overstrike}, and
7846 @code{gnus-article-maybe-highlight}, but there are thousands, nay
7847 millions, of functions you can put in this hook. For an overview of
7848 functions @pxref{Article Highlighting}, @pxref{Article Hiding},
7849 @pxref{Article Washing}, @pxref{Article Buttons} and @pxref{Article
7850 Date}. Note that the order of functions in this hook might affect
7851 things, so you may have to fiddle a bit to get the desired results.
7853 You can, of course, write your own functions. The functions are called
7854 from the article buffer, and you can do anything you like, pretty much.
7855 There is no information that you have to keep in the buffer---you can
7856 change everything. However, you shouldn't delete any headers. Instead
7857 make them invisible if you want to make them go away.
7860 @node Article Keymap
7861 @section Article Keymap
7863 Most of the keystrokes in the summary buffer can also be used in the
7864 article buffer. They should behave as if you typed them in the summary
7865 buffer, which means that you don't actually have to have a summary
7866 buffer displayed while reading. You can do it all from the article
7869 A few additional keystrokes are available:
7874 @kindex SPACE (Article)
7875 @findex gnus-article-next-page
7876 Scroll forwards one page (@code{gnus-article-next-page}).
7879 @kindex DEL (Article)
7880 @findex gnus-article-prev-page
7881 Scroll backwards one page (@code{gnus-article-prev-page}).
7884 @kindex C-c ^ (Article)
7885 @findex gnus-article-refer-article
7886 If point is in the neighborhood of a @code{Message-ID} and you press
7887 @kbd{r}, Gnus will try to get that article from the server
7888 (@code{gnus-article-refer-article}).
7891 @kindex C-c C-m (Article)
7892 @findex gnus-article-mail
7893 Send a reply to the address near point (@code{gnus-article-mail}). If
7894 given a prefix, include the mail.
7898 @findex gnus-article-show-summary
7899 Reconfigure the buffers so that the summary buffer becomes visible
7900 (@code{gnus-article-show-summary}).
7904 @findex gnus-article-describe-briefly
7905 Give a very brief description of the available keystrokes
7906 (@code{gnus-article-describe-briefly}).
7909 @kindex TAB (Article)
7910 @findex gnus-article-next-button
7911 Go to the next button, if any (@code{gnus-article-next-button}). This
7912 only makes sense if you have buttonizing turned on.
7915 @kindex M-TAB (Article)
7916 @findex gnus-article-prev-button
7917 Go to the previous button, if any (@code{gnus-article-prev-button}).
7923 @section Misc Article
7927 @item gnus-single-article-buffer
7928 @vindex gnus-single-article-buffer
7929 If non-@code{nil}, use the same article buffer for all the groups.
7930 (This is the default.) If @code{nil}, each group will have its own
7933 @vindex gnus-article-prepare-hook
7934 @item gnus-article-prepare-hook
7935 This hook is called right after the article has been inserted into the
7936 article buffer. It is mainly intended for functions that do something
7937 depending on the contents; it should probably not be used for changing
7938 the contents of the article buffer.
7940 @vindex gnus-article-display-hook
7941 @item gnus-article-display-hook
7942 This hook is called as the last thing when displaying an article, and is
7943 intended for modifying the contents of the buffer, doing highlights,
7944 hiding headers, and the like.
7946 @item gnus-article-mode-hook
7947 @vindex gnus-article-mode-hook
7948 Hook called in article mode buffers.
7950 @item gnus-article-mode-syntax-table
7951 @vindex gnus-article-mode-syntax-table
7952 Syntax table used in article buffers. It is initialized from
7953 @code{text-mode-syntax-table}.
7955 @vindex gnus-article-mode-line-format
7956 @item gnus-article-mode-line-format
7957 This variable is a format string along the same lines as
7958 @code{gnus-summary-mode-line-format}. It accepts the same
7959 format specifications as that variable, with one extension:
7963 The @dfn{wash status} of the article. This is a short string with one
7964 character for each possible article wash operation that may have been
7968 @vindex gnus-break-pages
7970 @item gnus-break-pages
7971 Controls whether @dfn{page breaking} is to take place. If this variable
7972 is non-@code{nil}, the articles will be divided into pages whenever a
7973 page delimiter appears in the article. If this variable is @code{nil},
7974 paging will not be done.
7976 @item gnus-page-delimiter
7977 @vindex gnus-page-delimiter
7978 This is the delimiter mentioned above. By default, it is @samp{^L}
7983 @node Composing Messages
7984 @chapter Composing Messages
7985 @cindex composing messages
7988 @cindex sending mail
7993 @kindex C-c C-c (Post)
7994 All commands for posting and mailing will put you in a message buffer
7995 where you can edit the article all you like, before you send the article
7996 by pressing @kbd{C-c C-c}. @xref{Top, , Top, message, The Message
7997 Manual}. If you are in a foreign news group, and you wish to post the
7998 article using the foreign server, you can give a prefix to @kbd{C-c C-c}
7999 to make Gnus try to post using the foreign server.
8002 * Mail:: Mailing and replying.
8003 * Post:: Posting and following up.
8004 * Posting Server:: What server should you post via?
8005 * Mail and Post:: Mailing and posting at the same time.
8006 * Archived Messages:: Where Gnus stores the messages you've sent.
8007 * Drafts:: Postponing messages and rejected messages.
8008 * Rejected Articles:: What happens if the server doesn't like your article?
8011 Also see @pxref{Canceling and Superseding} for information on how to
8012 remove articles you shouldn't have posted.
8018 Variables for customizing outgoing mail:
8021 @item gnus-uu-digest-headers
8022 @vindex gnus-uu-digest-headers
8023 List of regexps to match headers included in digested messages. The
8024 headers will be included in the sequence they are matched.
8026 @item gnus-add-to-list
8027 @vindex gnus-add-to-list
8028 If non-@code{nil}, add a @code{to-list} group parameter to mail groups
8029 that have none when you do a @kbd{a}.
8037 Variables for composing news articles:
8040 @item gnus-sent-message-ids-file
8041 @vindex gnus-sent-message-ids-file
8042 Gnus will keep a @code{Message-ID} history file of all the mails it has
8043 sent. If it discovers that it has already sent a mail, it will ask the
8044 user whether to re-send the mail. (This is primarily useful when
8045 dealing with @sc{soup} packets and the like where one is apt to send the
8046 same packet multiple times.) This variable says what the name of this
8047 history file is. It is @file{~/News/Sent-Message-IDs} by default. Set
8048 this variable to @code{nil} if you don't want Gnus to keep a history
8051 @item gnus-sent-message-ids-length
8052 @vindex gnus-sent-message-ids-length
8053 This variable says how many @code{Message-ID}s to keep in the history
8054 file. It is 1000 by default.
8059 @node Posting Server
8060 @section Posting Server
8062 When you press those magical @kbd{C-c C-c} keys to ship off your latest
8063 (extremely intelligent, of course) article, where does it go?
8065 Thank you for asking. I hate you.
8067 @vindex gnus-post-method
8069 It can be quite complicated. Normally, Gnus will use the same native
8070 server. However. If your native server doesn't allow posting, just
8071 reading, you probably want to use some other server to post your
8072 (extremely intelligent and fabulously interesting) articles. You can
8073 then set the @code{gnus-post-method} to some other method:
8076 (setq gnus-post-method '(nnspool ""))
8079 Now, if you've done this, and then this server rejects your article, or
8080 this server is down, what do you do then? To override this variable you
8081 can use a non-zero prefix to the @kbd{C-c C-c} command to force using
8082 the ``current'' server for posting.
8084 If you give a zero prefix (i.e., @kbd{C-u 0 C-c C-c}) to that command,
8085 Gnus will prompt you for what method to use for posting.
8087 You can also set @code{gnus-post-method} to a list of select methods.
8088 If that's the case, Gnus will always prompt you for what method to use
8093 @section Mail and Post
8095 Here's a list of variables relevant to both mailing and
8099 @item gnus-mailing-list-groups
8100 @findex gnus-mailing-list-groups
8101 @cindex mailing lists
8103 If your news server offers groups that are really mailing lists
8104 gatewayed to the @sc{nntp} server, you can read those groups without
8105 problems, but you can't post/followup to them without some difficulty.
8106 One solution is to add a @code{to-address} to the group parameters
8107 (@pxref{Group Parameters}). An easier thing to do is set the
8108 @code{gnus-mailing-list-groups} to a regexp that matches the groups that
8109 really are mailing lists. Then, at least, followups to the mailing
8110 lists will work most of the time. Posting to these groups (@kbd{a}) is
8111 still a pain, though.
8115 You may want to do spell-checking on messages that you send out. Or, if
8116 you don't want to spell-check by hand, you could add automatic
8117 spell-checking via the @code{ispell} package:
8120 @findex ispell-message
8122 (add-hook 'message-send-hook 'ispell-message)
8126 @node Archived Messages
8127 @section Archived Messages
8128 @cindex archived messages
8129 @cindex sent messages
8131 Gnus provides a few different methods for storing the mail and news you
8132 send. The default method is to use the @dfn{archive virtual server} to
8133 store the messages. If you want to disable this completely, the
8134 @code{gnus-message-archive-group} variable should be @code{nil}, which
8137 @vindex gnus-message-archive-method
8138 @code{gnus-message-archive-method} says what virtual server Gnus is to
8139 use to store sent messages. The default is:
8143 (nnfolder-directory "~/Mail/archive")
8144 (nnfolder-active-file "~/Mail/archive/active")
8145 (nnfolder-get-new-mail nil)
8146 (nnfolder-inhibit-expiry t))
8149 You can, however, use any mail select method (@code{nnml},
8150 @code{nnmbox}, etc.). @code{nnfolder} is a quite likeable select method
8151 for doing this sort of thing, though. If you don't like the default
8152 directory chosen, you could say something like:
8155 (setq gnus-message-archive-method
8156 '(nnfolder "archive"
8157 (nnfolder-inhibit-expiry t)
8158 (nnfolder-active-file "~/News/sent-mail/active")
8159 (nnfolder-directory "~/News/sent-mail/")))
8162 @vindex gnus-message-archive-group
8164 Gnus will insert @code{Gcc} headers in all outgoing messages that point
8165 to one or more group(s) on that server. Which group to use is
8166 determined by the @code{gnus-message-archive-group} variable.
8168 This variable can be used to do the following:
8172 Messages will be saved in that group.
8173 @item a list of strings
8174 Messages will be saved in all those groups.
8175 @item an alist of regexps, functions and forms
8176 When a key ``matches'', the result is used.
8178 No message archiving will take place. This is the default.
8183 Just saving to a single group called @samp{MisK}:
8185 (setq gnus-message-archive-group "MisK")
8188 Saving to two groups, @samp{MisK} and @samp{safe}:
8190 (setq gnus-message-archive-group '("MisK" "safe"))
8193 Save to different groups based on what group you are in:
8195 (setq gnus-message-archive-group
8196 '(("^alt" "sent-to-alt")
8197 ("mail" "sent-to-mail")
8198 (".*" "sent-to-misc")))
8203 (setq gnus-message-archive-group
8204 '((if (message-news-p)
8209 How about storing all news messages in one file, but storing all mail
8210 messages in one file per month:
8213 (setq gnus-message-archive-group
8214 '((if (message-news-p)
8216 (concat "mail." (format-time-string
8217 "%Y-%m" (current-time))))))
8220 (XEmacs 19.13 doesn't have @code{format-time-string}, so you'll have to
8221 use a different value for @code{gnus-message-archive-group} there.)
8223 Now, when you send a message off, it will be stored in the appropriate
8224 group. (If you want to disable storing for just one particular message,
8225 you can just remove the @code{Gcc} header that has been inserted.) The
8226 archive group will appear in the group buffer the next time you start
8227 Gnus, or the next time you press @kbd{F} in the group buffer. You can
8228 enter it and read the articles in it just like you'd read any other
8229 group. If the group gets really big and annoying, you can simply rename
8230 if (using @kbd{G r} in the group buffer) to something
8231 nice---@samp{misc-mail-september-1995}, or whatever. New messages will
8232 continue to be stored in the old (now empty) group.
8234 That's the default method of archiving sent messages. Gnus offers a
8235 different way for the people who don't like the default method. In that
8236 case you should set @code{gnus-message-archive-group} to @code{nil};
8237 this will disable archiving.
8240 @item gnus-outgoing-message-group
8241 @vindex gnus-outgoing-message-group
8242 All outgoing messages will be put in this group. If you want to store
8243 all your outgoing mail and articles in the group @samp{nnml:archive},
8244 you set this variable to that value. This variable can also be a list of
8247 If you want to have greater control over what group to put each
8248 message in, you can set this variable to a function that checks the
8249 current newsgroup name and then returns a suitable group name (or list
8252 This variable can be used instead of @code{gnus-message-archive-group},
8253 but the latter is the preferred method.
8257 @c @node Posting Styles
8258 @c @section Posting Styles
8259 @c @cindex posting styles
8262 @c All them variables, they make my head swim.
8264 @c So what if you want a different @code{Organization} and signature based
8265 @c on what groups you post to? And you post both from your home machine
8266 @c and your work machine, and you want different @code{From} lines, and so
8269 @c @vindex gnus-posting-styles
8270 @c One way to do stuff like that is to write clever hooks that change the
8271 @c variables you need to have changed. That's a bit boring, so somebody
8272 @c came up with the bright idea of letting the user specify these things in
8273 @c a handy alist. Here's an example of a @code{gnus-posting-styles}
8278 @c (signature . "Peace and happiness")
8279 @c (organization . "What me?"))
8281 @c (signature . "Death to everybody"))
8282 @c ("comp.emacs.i-love-it"
8283 @c (organization . "Emacs is it")))
8286 @c As you might surmise from this example, this alist consists of several
8287 @c @dfn{styles}. Each style will be applicable if the first element
8288 @c ``matches'', in some form or other. The entire alist will be iterated
8289 @c over, from the beginning towards the end, and each match will be
8290 @c applied, which means that attributes in later styles that match override
8291 @c the same attributes in earlier matching styles. So
8292 @c @samp{comp.programming.literate} will have the @samp{Death to everybody}
8293 @c signature and the @samp{What me?} @code{Organization} header.
8295 @c The first element in each style is called the @code{match}. If it's a
8296 @c string, then Gnus will try to regexp match it against the group name.
8297 @c If it's a function symbol, that function will be called with no
8298 @c arguments. If it's a variable symbol, then the variable will be
8299 @c referenced. If it's a list, then that list will be @code{eval}ed. In
8300 @c any case, if this returns a non-@code{nil} value, then the style is said
8303 @c Each style may contain a arbitrary amount of @dfn{attributes}. Each
8304 @c attribute consists of a @var{(name . value)} pair. The attribute name
8305 @c can be one of @code{signature}, @code{organization} or @code{from}. The
8306 @c attribute name can also be a string. In that case, this will be used as
8307 @c a header name, and the value will be inserted in the headers of the
8310 @c The attribute value can be a string (used verbatim), a function (the
8311 @c return value will be used), a variable (its value will be used) or a
8312 @c list (it will be @code{eval}ed and the return value will be used).
8314 @c So here's a new example:
8317 @c (setq gnus-posting-styles
8319 @c (signature . "~/.signature")
8320 @c (from . "user@@foo (user)")
8321 @c ("X-Home-Page" . (getenv "WWW_HOME"))
8322 @c (organization . "People's Front Against MWM"))
8324 @c (signature . my-funny-signature-randomizer))
8325 @c ((equal (system-name) "gnarly")
8326 @c (signature . my-quote-randomizer))
8327 @c (posting-from-work-p
8328 @c (signature . "~/.work-signature")
8329 @c (from . "user@@bar.foo (user)")
8330 @c (organization . "Important Work, Inc"))
8332 @c (signature . "~/.mail-signature"))))
8339 If you are writing a message (mail or news) and suddenly remember that
8340 you have a steak in the oven (or some pesto in the food processor, you
8341 craaazy vegetarians), you'll probably wish there was a method to save
8342 the message you are writing so that you can continue editing it some
8343 other day, and send it when you feel its finished.
8345 Well, don't worry about it. Whenever you start composing a message of
8346 some sort using the Gnus mail and post commands, the buffer you get will
8347 automatically associate to an article in a special @dfn{draft} group.
8348 If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
8349 article will be saved there. (Auto-save files also go to the draft
8353 @vindex nndraft-directory
8354 The draft group is a special group (which is implemented as an
8355 @code{nndraft} group, if you absolutely have to know) called
8356 @samp{nndraft:drafts}. The variable @code{nndraft-directory} says where
8357 @code{nndraft} is to store its files. What makes this group special is
8358 that you can't tick any articles in it or mark any articles as
8359 read---all articles in the group are permanently unread.
8361 If the group doesn't exist, it will be created and you'll be subscribed
8362 to it. The only way to make it disappear from the Group buffer is to
8365 @c @findex gnus-dissociate-buffer-from-draft
8366 @c @kindex C-c M-d (Mail)
8367 @c @kindex C-c M-d (Post)
8368 @c @findex gnus-associate-buffer-with-draft
8369 @c @kindex C-c C-d (Mail)
8370 @c @kindex C-c C-d (Post)
8371 @c If you're writing some super-secret message that you later want to
8372 @c encode with PGP before sending, you may wish to turn the auto-saving
8373 @c (and association with the draft group) off. You never know who might be
8374 @c interested in reading all your extremely valuable and terribly horrible
8375 @c and interesting secrets. The @kbd{C-c M-d}
8376 @c (@code{gnus-dissociate-buffer-from-draft}) command does that for you.
8377 @c If you change your mind and want to turn the auto-saving back on again,
8378 @c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that.
8380 @c @vindex gnus-use-draft
8381 @c To leave association with the draft group off by default, set
8382 @c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default.
8384 @findex gnus-draft-edit-message
8386 When you want to continue editing the article, you simply enter the
8387 draft group and push @kbd{D e} (@code{gnus-draft-edit-message}) to do
8388 that. You will be placed in a buffer where you left off.
8390 Rejected articles will also be put in this draft group (@pxref{Rejected
8393 @findex gnus-draft-send-all-messages
8394 @findex gnus-draft-send-message
8395 If you have lots of rejected messages you want to post (or mail) without
8396 doing further editing, you can use the @kbd{D s} command
8397 (@code{gnus-draft-send-message}). This command understands the
8398 process/prefix convention (@pxref{Process/Prefix}). The @kbd{D S}
8399 command (@code{gnus-draft-send-all-messages}) will ship off all messages
8402 If you have some messages that you wish not to send, you can use the
8403 @kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message
8404 as unsendable. This is a toggling command.
8407 @node Rejected Articles
8408 @section Rejected Articles
8409 @cindex rejected articles
8411 Sometimes a news server will reject an article. Perhaps the server
8412 doesn't like your face. Perhaps it just feels miserable. Perhaps
8413 @emph{there be demons}. Perhaps you have included too much cited text.
8414 Perhaps the disk is full. Perhaps the server is down.
8416 These situations are, of course, totally beyond the control of Gnus.
8417 (Gnus, of course, loves the way you look, always feels great, has angels
8418 fluttering around inside of it, doesn't care about how much cited text
8419 you include, never runs full and never goes down.) So Gnus saves these
8420 articles until some later time when the server feels better.
8422 The rejected articles will automatically be put in a special draft group
8423 (@pxref{Drafts}). When the server comes back up again, you'd then
8424 typically enter that group and send all the articles off.
8427 @node Select Methods
8428 @chapter Select Methods
8429 @cindex foreign groups
8430 @cindex select methods
8432 A @dfn{foreign group} is a group not read by the usual (or
8433 default) means. It could be, for instance, a group from a different
8434 @sc{nntp} server, it could be a virtual group, or it could be your own
8435 personal mail group.
8437 A foreign group (or any group, really) is specified by a @dfn{name} and
8438 a @dfn{select method}. To take the latter first, a select method is a
8439 list where the first element says what backend to use (e.g. @code{nntp},
8440 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
8441 name}. There may be additional elements in the select method, where the
8442 value may have special meaning for the backend in question.
8444 One could say that a select method defines a @dfn{virtual server}---so
8445 we do just that (@pxref{The Server Buffer}).
8447 The @dfn{name} of the group is the name the backend will recognize the
8450 For instance, the group @samp{soc.motss} on the @sc{nntp} server
8451 @samp{some.where.edu} will have the name @samp{soc.motss} and select
8452 method @code{(nntp "some.where.edu")}. Gnus will call this group
8453 @samp{nntp+some.where.edu:soc.motss}, even though the @code{nntp}
8454 backend just knows this group as @samp{soc.motss}.
8456 The different methods all have their peculiarities, of course.
8459 * The Server Buffer:: Making and editing virtual servers.
8460 * Getting News:: Reading USENET news with Gnus.
8461 * Getting Mail:: Reading your personal mail with Gnus.
8462 * Other Sources:: Reading directories, files, SOUP packets.
8463 * Combined Groups:: Combining groups into one group.
8464 * Gnus Unplugged:: Reading news and mail offline.
8468 @node The Server Buffer
8469 @section The Server Buffer
8471 Traditionally, a @dfn{server} is a machine or a piece of software that
8472 one connects to, and then requests information from. Gnus does not
8473 connect directly to any real servers, but does all transactions through
8474 one backend or other. But that's just putting one layer more between
8475 the actual media and Gnus, so we might just as well say that each
8476 backend represents a virtual server.
8478 For instance, the @code{nntp} backend may be used to connect to several
8479 different actual @sc{nntp} servers, or, perhaps, to many different ports
8480 on the same actual @sc{nntp} server. You tell Gnus which backend to
8481 use, and what parameters to set by specifying a @dfn{select method}.
8483 These select method specifications can sometimes become quite
8484 complicated---say, for instance, that you want to read from the
8485 @sc{nntp} server @samp{news.funet.fi} on port number 13, which
8486 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
8487 Anyways, if you had to specify that for each group that used this
8488 server, that would be too much work, so Gnus offers a way of naming
8489 select methods, which is what you do in the server buffer.
8491 To enter the server buffer, use the @kbd{^}
8492 (@code{gnus-group-enter-server-mode}) command in the group buffer.
8495 * Server Buffer Format:: You can customize the look of this buffer.
8496 * Server Commands:: Commands to manipulate servers.
8497 * Example Methods:: Examples server specifications.
8498 * Creating a Virtual Server:: An example session.
8499 * Server Variables:: Which variables to set.
8500 * Servers and Methods:: You can use server names as select methods.
8501 * Unavailable Servers:: Some servers you try to contact may be down.
8504 @vindex gnus-server-mode-hook
8505 @code{gnus-server-mode-hook} is run when creating the server buffer.
8508 @node Server Buffer Format
8509 @subsection Server Buffer Format
8510 @cindex server buffer format
8512 @vindex gnus-server-line-format
8513 You can change the look of the server buffer lines by changing the
8514 @code{gnus-server-line-format} variable. This is a @code{format}-like
8515 variable, with some simple extensions:
8520 How the news is fetched---the backend name.
8523 The name of this server.
8526 Where the news is to be fetched from---the address.
8529 The opened/closed/denied status of the server.
8532 @vindex gnus-server-mode-line-format
8533 The mode line can also be customized by using the
8534 @code{gnus-server-mode-line-format} variable. The following specs are
8545 Also @pxref{Formatting Variables}.
8548 @node Server Commands
8549 @subsection Server Commands
8550 @cindex server commands
8556 @findex gnus-server-add-server
8557 Add a new server (@code{gnus-server-add-server}).
8561 @findex gnus-server-edit-server
8562 Edit a server (@code{gnus-server-edit-server}).
8565 @kindex SPACE (Server)
8566 @findex gnus-server-read-server
8567 Browse the current server (@code{gnus-server-read-server}).
8571 @findex gnus-server-exit
8572 Return to the group buffer (@code{gnus-server-exit}).
8576 @findex gnus-server-kill-server
8577 Kill the current server (@code{gnus-server-kill-server}).
8581 @findex gnus-server-yank-server
8582 Yank the previously killed server (@code{gnus-server-yank-server}).
8586 @findex gnus-server-copy-server
8587 Copy the current server (@code{gnus-server-copy-server}).
8591 @findex gnus-server-list-servers
8592 List all servers (@code{gnus-server-list-servers}).
8596 @findex gnus-server-scan-server
8597 Request that the server scan its sources for new articles
8598 (@code{gnus-server-scan-server}). This is mainly sensible with mail
8603 @findex gnus-server-regenerate-server
8604 Request that the server regenerate all its data structures
8605 (@code{gnus-server-regenerate-server}). This can be useful if you have
8606 a mail backend that has gotten out of synch.
8611 @node Example Methods
8612 @subsection Example Methods
8614 Most select methods are pretty simple and self-explanatory:
8617 (nntp "news.funet.fi")
8620 Reading directly from the spool is even simpler:
8626 As you can see, the first element in a select method is the name of the
8627 backend, and the second is the @dfn{address}, or @dfn{name}, if you
8630 After these two elements, there may be an arbitrary number of
8631 @var{(variable form)} pairs.
8633 To go back to the first example---imagine that you want to read from
8634 port 15 on that machine. This is what the select method should
8638 (nntp "news.funet.fi" (nntp-port-number 15))
8641 You should read the documentation to each backend to find out what
8642 variables are relevant, but here's an @code{nnmh} example:
8644 @code{nnmh} is a mail backend that reads a spool-like structure. Say
8645 you have two structures that you wish to access: One is your private
8646 mail spool, and the other is a public one. Here's the possible spec for
8650 (nnmh "private" (nnmh-directory "~/private/mail/"))
8653 (This server is then called @samp{private}, but you may have guessed
8656 Here's the method for a public spool:
8660 (nnmh-directory "/usr/information/spool/")
8661 (nnmh-get-new-mail nil))
8664 If you are behind a firewall and only have access to the @sc{nntp}
8665 server from the firewall machine, you can instruct Gnus to @code{rlogin}
8666 on the firewall machine and telnet from there to the @sc{nntp} server.
8667 Doing this can be rather fiddly, but your virtual server definition
8668 should probably look something like this:
8672 (nntp-address "the.firewall.machine")
8673 (nntp-open-connection-function nntp-open-rlogin)
8674 (nntp-end-of-line "\n")
8675 (nntp-rlogin-parameters
8676 ("telnet" "the.real.nntp.host" "nntp")))
8681 @node Creating a Virtual Server
8682 @subsection Creating a Virtual Server
8684 If you're saving lots of articles in the cache by using persistent
8685 articles, you may want to create a virtual server to read the cache.
8687 First you need to add a new server. The @kbd{a} command does that. It
8688 would probably be best to use @code{nnspool} to read the cache. You
8689 could also use @code{nnml} or @code{nnmh}, though.
8691 Type @kbd{a nnspool RET cache RET}.
8693 You should now have a brand new @code{nnspool} virtual server called
8694 @samp{cache}. You now need to edit it to have the right definitions.
8695 Type @kbd{e} to edit the server. You'll be entered into a buffer that
8696 will contain the following:
8706 (nnspool-spool-directory "~/News/cache/")
8707 (nnspool-nov-directory "~/News/cache/")
8708 (nnspool-active-file "~/News/cache/active"))
8711 Type @kbd{C-c C-c} to return to the server buffer. If you now press
8712 @kbd{RET} over this virtual server, you should be entered into a browse
8713 buffer, and you should be able to enter any of the groups displayed.
8716 @node Server Variables
8717 @subsection Server Variables
8719 One sticky point when defining variables (both on backends and in Emacs
8720 in general) is that some variables are typically initialized from other
8721 variables when the definition of the variables is being loaded. If you
8722 change the "base" variable after the variables have been loaded, you
8723 won't change the "derived" variables.
8725 This typically affects directory and file variables. For instance,
8726 @code{nnml-directory} is @file{~/Mail/} by default, and all @code{nnml}
8727 directory variables are initialized from that variable, so
8728 @code{nnml-active-file} will be @file{~/Mail/active}. If you define a
8729 new virtual @code{nnml} server, it will @emph{not} suffice to set just
8730 @code{nnml-directory}---you have to explicitly set all the file
8731 variables to be what you want them to be. For a complete list of
8732 variables for each backend, see each backend's section later in this
8733 manual, but here's an example @code{nnml} definition:
8737 (nnml-directory "~/my-mail/")
8738 (nnml-active-file "~/my-mail/active")
8739 (nnml-newsgroups-file "~/my-mail/newsgroups"))
8743 @node Servers and Methods
8744 @subsection Servers and Methods
8746 Wherever you would normally use a select method
8747 (e.g. @code{gnus-secondary-select-method}, in the group select method,
8748 when browsing a foreign server) you can use a virtual server name
8749 instead. This could potentially save lots of typing. And it's nice all
8753 @node Unavailable Servers
8754 @subsection Unavailable Servers
8756 If a server seems to be unreachable, Gnus will mark that server as
8757 @code{denied}. That means that any subsequent attempt to make contact
8758 with that server will just be ignored. ``It can't be opened,'' Gnus
8759 will tell you, without making the least effort to see whether that is
8760 actually the case or not.
8762 That might seem quite naughty, but it does make sense most of the time.
8763 Let's say you have 10 groups subscribed to on server
8764 @samp{nephelococcygia.com}. This server is located somewhere quite far
8765 away from you and the machine is quite slow, so it takes 1 minute just
8766 to find out that it refuses connection to you today. If Gnus were to
8767 attempt to do that 10 times, you'd be quite annoyed, so Gnus won't
8768 attempt to do that. Once it has gotten a single ``connection refused'',
8769 it will regard that server as ``down''.
8771 So, what happens if the machine was only feeling unwell temporarily?
8772 How do you test to see whether the machine has come up again?
8774 You jump to the server buffer (@pxref{The Server Buffer}) and poke it
8775 with the following commands:
8781 @findex gnus-server-open-server
8782 Try to establish connection to the server on the current line
8783 (@code{gnus-server-open-server}).
8787 @findex gnus-server-close-server
8788 Close the connection (if any) to the server
8789 (@code{gnus-server-close-server}).
8793 @findex gnus-server-deny-server
8794 Mark the current server as unreachable
8795 (@code{gnus-server-deny-server}).
8798 @kindex M-o (Server)
8799 @findex gnus-server-open-all-servers
8800 Open the connections to all servers in the buffer
8801 (@code{gnus-server-open-all-servers}).
8804 @kindex M-c (Server)
8805 @findex gnus-server-close-all-servers
8806 Close the connections to all servers in the buffer
8807 (@code{gnus-server-close-all-servers}).
8811 @findex gnus-server-remove-denials
8812 Remove all marks to whether Gnus was denied connection from any servers
8813 (@code{gnus-server-remove-denials}).
8819 @section Getting News
8820 @cindex reading news
8821 @cindex news backends
8823 A newsreader is normally used for reading news. Gnus currently provides
8824 only two methods of getting news---it can read from an @sc{nntp} server,
8825 or it can read from a local spool.
8828 * NNTP:: Reading news from an @sc{nntp} server.
8829 * News Spool:: Reading news from the local spool.
8834 @subsection @sc{nntp}
8837 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
8838 You just specify @code{nntp} as method and the address of the @sc{nntp}
8839 server as the, uhm, address.
8841 If the @sc{nntp} server is located at a non-standard port, setting the
8842 third element of the select method to this port number should allow you
8843 to connect to the right port. You'll have to edit the group info for
8844 that (@pxref{Foreign Groups}).
8846 The name of the foreign group can be the same as a native group. In
8847 fact, you can subscribe to the same group from as many different servers
8848 you feel like. There will be no name collisions.
8850 The following variables can be used to create a virtual @code{nntp}
8855 @item nntp-server-opened-hook
8856 @vindex nntp-server-opened-hook
8857 @cindex @sc{mode reader}
8859 @cindex authentification
8860 @cindex nntp authentification
8861 @findex nntp-send-authinfo
8862 @findex nntp-send-mode-reader
8863 is run after a connection has been made. It can be used to send
8864 commands to the @sc{nntp} server after it has been contacted. By
8865 default it sends the command @code{MODE READER} to the server with the
8866 @code{nntp-send-mode-reader} function. This function should always be
8867 present in this hook.
8869 @item nntp-authinfo-function
8870 @vindex nntp-authinfo-function
8871 @findex nntp-send-authinfo
8872 @vindex nntp-authinfo-file
8873 This function will be used to send @samp{AUTHINFO} to the @sc{nntp}
8874 server. The default function is @code{nntp-send-authinfo}, which looks
8875 through your @file{~/.authinfo} (or whatever you've set the
8876 @code{nntp-authinfo-file} variable to) for applicable entries. If none
8877 are found, it will prompt you for a login name and a password. The
8878 format of the @file{~/.authinfo} file is (almost) the same as the
8879 @code{ftp} @file{~/.netrc} file, which is defined in the @code{ftp}
8880 manual page, but here are the salient facts:
8884 The file contains one or more line, each of which define one server.
8887 Each line may contain an arbitrary number of token/value pairs. The
8888 valid tokens include @samp{machine}, @samp{login}, @samp{password}, and
8889 @samp{force}. (The latter is not a valid @file{.netrc}/@code{ftp}
8890 token, which is the only way the @file{.authinfo} file format deviates
8891 from the @file{.netrc} file format.)
8895 Here's an example file:
8898 machine news.uio.no login larsi password geheimnis
8899 machine nntp.ifi.uio.no login larsi force yes
8902 The token/value pairs may appear in any order; @samp{machine} doesn't
8903 have to be first, for instance.
8905 In this example, both login name and password have been supplied for the
8906 former server, while the latter has only the login name listed, and the
8907 user will be prompted for the password. The latter also has the
8908 @samp{force} tag, which means that the authinfo will be sent to the
8909 @var{nntp} server upon connection; the default (i.e., when there is not
8910 @samp{force} tag) is to not send authinfo to the @var{nntp} server
8911 until the @var{nntp} server asks for it.
8913 Remember to not leave the @file{~/.authinfo} file world-readable.
8915 @item nntp-server-action-alist
8916 @vindex nntp-server-action-alist
8917 This is a list of regexps to match on server types and actions to be
8918 taken when matches are made. For instance, if you want Gnus to beep
8919 every time you connect to innd, you could say something like:
8922 (setq nntp-server-action-alist
8926 You probably don't want to do that, though.
8928 The default value is
8931 '(("nntpd 1\\.5\\.11t"
8932 (remove-hook 'nntp-server-opened-hook 'nntp-send-mode-reader)))
8935 This ensures that Gnus doesn't send the @code{MODE READER} command to
8936 nntpd 1.5.11t, since that command chokes that server, I've been told.
8938 @item nntp-maximum-request
8939 @vindex nntp-maximum-request
8940 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
8941 will collect headers by sending a series of @code{head} commands. To
8942 speed things up, the backend sends lots of these commands without
8943 waiting for reply, and then reads all the replies. This is controlled
8944 by the @code{nntp-maximum-request} variable, and is 400 by default. If
8945 your network is buggy, you should set this to 1.
8947 @item nntp-connection-timeout
8948 @vindex nntp-connection-timeout
8949 If you have lots of foreign @code{nntp} groups that you connect to
8950 regularly, you're sure to have problems with @sc{nntp} servers not
8951 responding properly, or being too loaded to reply within reasonable
8952 time. This is can lead to awkward problems, which can be helped
8953 somewhat by setting @code{nntp-connection-timeout}. This is an integer
8954 that says how many seconds the @code{nntp} backend should wait for a
8955 connection before giving up. If it is @code{nil}, which is the default,
8956 no timeouts are done.
8958 @c @item nntp-command-timeout
8959 @c @vindex nntp-command-timeout
8960 @c @cindex PPP connections
8961 @c @cindex dynamic IP addresses
8962 @c If you're running Gnus on a machine that has a dynamically assigned
8963 @c address, Gnus may become confused. If the address of your machine
8964 @c changes after connecting to the @sc{nntp} server, Gnus will simply sit
8965 @c waiting forever for replies from the server. To help with this
8966 @c unfortunate problem, you can set this command to a number. Gnus will
8967 @c then, if it sits waiting for a reply from the server longer than that
8968 @c number of seconds, shut down the connection, start a new one, and resend
8969 @c the command. This should hopefully be transparent to the user. A
8970 @c likely number is 30 seconds.
8972 @c @item nntp-retry-on-break
8973 @c @vindex nntp-retry-on-break
8974 @c If this variable is non-@code{nil}, you can also @kbd{C-g} if Gnus
8975 @c hangs. This will have much the same effect as the command timeout
8978 @item nntp-server-hook
8979 @vindex nntp-server-hook
8980 This hook is run as the last step when connecting to an @sc{nntp}
8983 @findex nntp-open-rlogin
8984 @findex nntp-open-telnet
8985 @findex nntp-open-network-stream
8986 @item nntp-open-connection-function
8987 @vindex nntp-open-connection-function
8988 This function is used to connect to the remote system. Three pre-made
8989 functions are @code{nntp-open-network-stream}, which is the default, and
8990 simply connects to some port or other on the remote system. The other
8991 two are @code{nntp-open-rlogin}, which does an @samp{rlogin} on the
8992 remote system, and then does a @samp{telnet} to the @sc{nntp} server
8993 available there, and @code{nntp-open-telnet}, which does a @samp{telnet}
8994 to the remote system and then another @samp{telnet} to get to the
8997 @code{nntp-open-rlogin}-related variables:
9001 @item nntp-rlogin-program
9002 @vindex nntp-rlogin-program
9003 Program used to log in on remote machines. The default is @samp{rsh},
9004 but @samp{ssh} is a popular alternative.
9006 @item nntp-rlogin-parameters
9007 @vindex nntp-rlogin-parameters
9008 This list will be used as the parameter list given to @code{rsh}.
9010 @item nntp-rlogin-user-name
9011 @vindex nntp-rlogin-user-name
9012 User name on the remote system.
9016 @code{nntp-open-telnet}-related variables:
9019 @item nntp-telnet-command
9020 @vindex nntp-telnet-command
9021 Command used to start @code{telnet}.
9023 @item nntp-telnet-switches
9024 @vindex nntp-telnet-switches
9025 List of strings to be used as the switches to the @code{telnet} command.
9027 @item nntp-telnet-user-name
9028 @vindex nntp-telnet-user-name
9029 User name for log in on the remote system.
9031 @item nntp-telnet-passwd
9032 @vindex nntp-telnet-passwd
9033 Password to use when logging in.
9035 @item nntp-telnet-parameters
9036 @vindex nntp-telnet-parameters
9037 A list of strings executed as a command after logging in
9040 @item nntp-telnet-shell-prompt
9041 @vindex nntp-telnet-shell-prompt
9042 Regexp matching the shell prompt on the remote machine. The default is
9043 @samp{bash\\|\$ *\r?$\\|> *\r?}.
9045 @item nntp-open-telnet-envuser
9046 @vindex nntp-open-telnet-envuser
9047 If non-@code{nil}, the @code{telnet} session (client and server both)
9048 will support the @code{ENVIRON} option and not prompt for login name.
9049 This works for Solaris @code{telnet}, for instance.
9053 @item nntp-end-of-line
9054 @vindex nntp-end-of-line
9055 String to use as end-of-line marker when talking to the @sc{nntp}
9056 server. This is @samp{\r\n} by default, but should be @samp{\n} when
9057 using @code{rlogin} to talk to the server.
9059 @item nntp-rlogin-user-name
9060 @vindex nntp-rlogin-user-name
9061 User name on the remote system when using the @code{rlogin} connect
9065 @vindex nntp-address
9066 The address of the remote system running the @sc{nntp} server.
9068 @item nntp-port-number
9069 @vindex nntp-port-number
9070 Port number to connect to when using the @code{nntp-open-network-stream}
9073 @item nntp-buggy-select
9074 @vindex nntp-buggy-select
9075 Set this to non-@code{nil} if your select routine is buggy.
9077 @item nntp-nov-is-evil
9078 @vindex nntp-nov-is-evil
9079 If the @sc{nntp} server does not support @sc{nov}, you could set this
9080 variable to @code{t}, but @code{nntp} usually checks automatically whether @sc{nov}
9083 @item nntp-xover-commands
9084 @vindex nntp-xover-commands
9087 List of strings used as commands to fetch @sc{nov} lines from a
9088 server. The default value of this variable is @code{("XOVER"
9092 @vindex nntp-nov-gap
9093 @code{nntp} normally sends just one big request for @sc{nov} lines to
9094 the server. The server responds with one huge list of lines. However,
9095 if you have read articles 2-5000 in the group, and only want to read
9096 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
9097 lines that you will not need. This variable says how
9098 big a gap between two consecutive articles is allowed to be before the
9099 @code{XOVER} request is split into several request. Note that if your
9100 network is fast, setting this variable to a really small number means
9101 that fetching will probably be slower. If this variable is @code{nil},
9102 @code{nntp} will never split requests. The default is 5.
9104 @item nntp-prepare-server-hook
9105 @vindex nntp-prepare-server-hook
9106 A hook run before attempting to connect to an @sc{nntp} server.
9108 @item nntp-warn-about-losing-connection
9109 @vindex nntp-warn-about-losing-connection
9110 If this variable is non-@code{nil}, some noise will be made when a
9111 server closes connection.
9113 @item nntp-record-commands
9114 @vindex nntp-record-commands
9115 If non-@code{nil}, @code{nntp} will log all commands it sends to the
9116 @sc{nntp} server (along with a timestep) in the @samp{*nntp-log*}
9117 buffer. This is useful if you are debugging a Gnus/@sc{nntp} connection
9118 that doesn't seem to work.
9124 @subsection News Spool
9128 Subscribing to a foreign group from the local spool is extremely easy,
9129 and might be useful, for instance, to speed up reading groups that
9130 contain very big articles---@samp{alt.binaries.pictures.furniture}, for
9133 Anyways, you just specify @code{nnspool} as the method and @code{""} (or
9134 anything else) as the address.
9136 If you have access to a local spool, you should probably use that as the
9137 native select method (@pxref{Finding the News}). It is normally faster
9138 than using an @code{nntp} select method, but might not be. It depends.
9139 You just have to try to find out what's best at your site.
9143 @item nnspool-inews-program
9144 @vindex nnspool-inews-program
9145 Program used to post an article.
9147 @item nnspool-inews-switches
9148 @vindex nnspool-inews-switches
9149 Parameters given to the inews program when posting an article.
9151 @item nnspool-spool-directory
9152 @vindex nnspool-spool-directory
9153 Where @code{nnspool} looks for the articles. This is normally
9154 @file{/usr/spool/news/}.
9156 @item nnspool-nov-directory
9157 @vindex nnspool-nov-directory
9158 Where @code{nnspool} will look for @sc{nov} files. This is normally
9159 @file{/usr/spool/news/over.view/}.
9161 @item nnspool-lib-dir
9162 @vindex nnspool-lib-dir
9163 Where the news lib dir is (@file{/usr/lib/news/} by default).
9165 @item nnspool-active-file
9166 @vindex nnspool-active-file
9167 The path to the active file.
9169 @item nnspool-newsgroups-file
9170 @vindex nnspool-newsgroups-file
9171 The path to the group descriptions file.
9173 @item nnspool-history-file
9174 @vindex nnspool-history-file
9175 The path to the news history file.
9177 @item nnspool-active-times-file
9178 @vindex nnspool-active-times-file
9179 The path to the active date file.
9181 @item nnspool-nov-is-evil
9182 @vindex nnspool-nov-is-evil
9183 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
9186 @item nnspool-sift-nov-with-sed
9187 @vindex nnspool-sift-nov-with-sed
9189 If non-@code{nil}, which is the default, use @code{sed} to get the
9190 relevant portion from the overview file. If nil, @code{nnspool} will
9191 load the entire file into a buffer and process it there.
9197 @section Getting Mail
9198 @cindex reading mail
9201 Reading mail with a newsreader---isn't that just plain WeIrD? But of
9205 * Getting Started Reading Mail:: A simple cookbook example.
9206 * Splitting Mail:: How to create mail groups.
9207 * Mail Backend Variables:: Variables for customizing mail handling.
9208 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
9209 * Mail and Procmail:: Reading mail groups that procmail create.
9210 * Incorporating Old Mail:: What about the old mail you have?
9211 * Expiring Mail:: Getting rid of unwanted mail.
9212 * Washing Mail:: Removing gruft from the mail you get.
9213 * Duplicates:: Dealing with duplicated mail.
9214 * Not Reading Mail:: Using mail backends for reading other files.
9215 * Choosing a Mail Backend:: Gnus can read a variety of mail formats.
9219 @node Getting Started Reading Mail
9220 @subsection Getting Started Reading Mail
9222 It's quite easy to use Gnus to read your new mail. You just plonk the
9223 mail backend of your choice into @code{gnus-secondary-select-methods},
9224 and things will happen automatically.
9226 For instance, if you want to use @code{nnml} (which is a "one file per
9227 mail" backend), you could put the following in your @file{.gnus} file:
9230 (setq gnus-secondary-select-methods
9231 '((nnml "private")))
9234 Now, the next time you start Gnus, this backend will be queried for new
9235 articles, and it will move all the messages in your spool file to its
9236 directory, which is @code{~/Mail/} by default. The new group that will
9237 be created (@samp{mail.misc}) will be subscribed, and you can read it
9238 like any other group.
9240 You will probably want to split the mail into several groups, though:
9243 (setq nnmail-split-methods
9244 '(("junk" "^From:.*Lars Ingebrigtsen")
9245 ("crazy" "^Subject:.*die\\|^Organization:.*flabby")
9249 This will result in three new @code{nnml} mail groups being created:
9250 @samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the
9251 mail that doesn't fit into the first two groups will be placed in the
9254 This should be sufficient for reading mail with Gnus. You might want to
9255 give the other sections in this part of the manual a perusal, though.
9256 Especially @pxref{Choosing a Mail Backend} and @pxref{Expiring Mail}.
9259 @node Splitting Mail
9260 @subsection Splitting Mail
9261 @cindex splitting mail
9262 @cindex mail splitting
9264 @vindex nnmail-split-methods
9265 The @code{nnmail-split-methods} variable says how the incoming mail is
9266 to be split into groups.
9269 (setq nnmail-split-methods
9270 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
9271 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
9275 This variable is a list of lists, where the first element of each of
9276 these lists is the name of the mail group (they do not have to be called
9277 something beginning with @samp{mail}, by the way), and the second
9278 element is a regular expression used on the header of each mail to
9279 determine if it belongs in this mail group. The first string may
9280 contain @samp{\\1} forms, like the ones used by @code{replace-match} to
9281 insert sub-expressions from the matched text. For instance:
9284 ("list.\\1" "From:.*\\(.*\\)-list@@majordomo.com")
9287 If the first element is the special symbol @code{junk}, then messages
9288 that match the regexp will disappear into the aether. Use with
9291 The second element can also be a function. In that case, it will be
9292 called narrowed to the headers with the first element of the rule as the
9293 argument. It should return a non-@code{nil} value if it thinks that the
9294 mail belongs in that group.
9296 The last of these groups should always be a general one, and the regular
9297 expression should @emph{always} be @samp{} so that it matches any mails
9298 that haven't been matched by any of the other regexps. (These rules are
9299 processed from the beginning of the alist toward the end. The first
9300 rule to make a match will "win", unless you have crossposting enabled.
9301 In that case, all matching rules will "win".)
9303 If you like to tinker with this yourself, you can set this variable to a
9304 function of your choice. This function will be called without any
9305 arguments in a buffer narrowed to the headers of an incoming mail
9306 message. The function should return a list of group names that it
9307 thinks should carry this mail message.
9309 Note that the mail backends are free to maul the poor, innocent,
9310 incoming headers all they want to. They all add @code{Lines} headers;
9311 some add @code{X-Gnus-Group} headers; most rename the Unix mbox
9312 @code{From<SPACE>} line to something else.
9314 @vindex nnmail-crosspost
9315 The mail backends all support cross-posting. If several regexps match,
9316 the mail will be ``cross-posted'' to all those groups.
9317 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
9318 that no articles are crossposted to the general (@samp{}) group.
9320 @vindex nnmail-crosspost-link-function
9323 @code{nnmh} and @code{nnml} makes crossposts by creating hard links to
9324 the crossposted articles. However, not all file systems support hard
9325 links. If that's the case for you, set
9326 @code{nnmail-crosspost-link-function} to @code{copy-file}. (This
9327 variable is @code{add-name-to-file} by default.)
9329 @kindex M-x nnmail-split-history
9330 @kindex nnmail-split-history
9331 If you wish to see where the previous mail split put the messages, you
9332 can use the @kbd{M-x nnmail-split-history} command.
9334 Gnus gives you all the opportunity you could possibly want for shooting
9335 yourself in the foot. Let's say you create a group that will contain
9336 all the mail you get from your boss. And then you accidentally
9337 unsubscribe from the group. Gnus will still put all the mail from your
9338 boss in the unsubscribed group, and so, when your boss mails you ``Have
9339 that report ready by Monday or you're fired!'', you'll never see it and,
9340 come Tuesday, you'll still believe that you're gainfully employed while
9341 you really should be out collecting empty bottles to save up for next
9345 @node Mail Backend Variables
9346 @subsection Mail Backend Variables
9348 These variables are (for the most part) pertinent to all the various
9352 @vindex nnmail-read-incoming-hook
9353 @item nnmail-read-incoming-hook
9354 The mail backends all call this hook after reading new mail. You can
9355 use this hook to notify any mail watch programs, if you want to.
9357 @vindex nnmail-spool-file
9358 @item nnmail-spool-file
9362 @vindex nnmail-pop-password
9363 @vindex nnmail-pop-password-required
9364 The backends will look for new mail in this file. If this variable is
9365 @code{nil}, the mail backends will never attempt to fetch mail by
9366 themselves. If you are using a POP mail server and your name is
9367 @samp{larsi}, you should set this variable to @samp{po:larsi}. If
9368 your name is not @samp{larsi}, you should probably modify that
9369 slightly, but you may have guessed that already, you smart & handsome
9370 devil! You can also set this variable to @code{pop}, and Gnus will try
9371 to figure out the POP mail string by itself. In any case, Gnus will
9372 call @code{movemail} which will contact the POP server named in the
9373 @code{MAILHOST} environment variable. If the POP server needs a
9374 password, you can either set @code{nnmail-pop-password-required} to
9375 @code{t} and be prompted for the password, or set
9376 @code{nnmail-pop-password} to the password itself.
9378 @code{nnmail-spool-file} can also be a list of mailboxes.
9380 Your Emacs has to have been configured with @samp{--with-pop} before
9381 compilation. This is the default, but some installations have it
9384 When you use a mail backend, Gnus will slurp all your mail from your
9385 inbox and plonk it down in your home directory. Gnus doesn't move any
9386 mail if you're not using a mail backend---you have to do a lot of magic
9387 invocations first. At the time when you have finished drawing the
9388 pentagram, lightened the candles, and sacrificed the goat, you really
9389 shouldn't be too surprised when Gnus moves your mail.
9391 @vindex nnmail-use-procmail
9392 @vindex nnmail-procmail-suffix
9393 @item nnmail-use-procmail
9394 If non-@code{nil}, the mail backends will look in
9395 @code{nnmail-procmail-directory} for incoming mail. All the files in
9396 that directory that have names ending in @code{nnmail-procmail-suffix}
9397 will be considered incoming mailboxes, and will be searched for new
9400 @vindex nnmail-crash-box
9401 @item nnmail-crash-box
9402 When a mail backend reads a spool file, mail is first moved to this
9403 file, which is @file{~/.gnus-crash-box} by default. If this file
9404 already exists, it will always be read (and incorporated) before any
9407 @vindex nnmail-prepare-incoming-hook
9408 @item nnmail-prepare-incoming-hook
9409 This is run in a buffer that holds all the new incoming mail, and can be
9410 used for, well, anything, really.
9412 @vindex nnmail-split-hook
9413 @item nnmail-split-hook
9414 @findex article-decode-rfc1522
9415 @findex RFC1522 decoding
9416 Hook run in the buffer where the mail headers of each message is kept
9417 just before the splitting based on these headers is done. The hook is
9418 free to modify the buffer contents in any way it sees fit---the buffer
9419 is discarded after the splitting has been done, and no changes performed
9420 in the buffer will show up in any files. @code{gnus-article-decode-rfc1522}
9421 is one likely function to add to this hook.
9423 @vindex nnmail-pre-get-new-mail-hook
9424 @vindex nnmail-post-get-new-mail-hook
9425 @item nnmail-pre-get-new-mail-hook
9426 @itemx nnmail-post-get-new-mail-hook
9427 These are two useful hooks executed when treating new incoming
9428 mail---@code{nnmail-pre-get-new-mail-hook} (is called just before
9429 starting to handle the new mail) and
9430 @code{nnmail-post-get-new-mail-hook} (is called when the mail handling
9431 is done). Here's and example of using these two hooks to change the
9432 default file modes the new mail files get:
9435 (add-hook 'gnus-pre-get-new-mail-hook
9436 (lambda () (set-default-file-modes 511)))
9438 (add-hook 'gnus-post-get-new-mail-hook
9439 (lambda () (set-default-file-modes 551)))
9442 @item nnmail-tmp-directory
9443 @vindex nnmail-tmp-directory
9444 This variable says where to move incoming mail to -- while processing
9445 it. This is usually done in the same directory that the mail backend
9446 inhabits (e.g., @file{~/Mail/}), but if this variable is non-@code{nil},
9447 it will be used instead.
9449 @item nnmail-movemail-program
9450 @vindex nnmail-movemail-program
9451 This program is executed to move mail from the user's inbox to her home
9452 directory. The default is @samp{movemail}.
9454 This can also be a function. In that case, the function will be called
9455 with two parameters -- the name of the inbox, and the file to be moved
9458 @item nnmail-delete-incoming
9459 @vindex nnmail-delete-incoming
9460 @cindex incoming mail files
9461 @cindex deleting incoming files
9462 If non-@code{nil}, the mail backends will delete the temporary incoming
9463 file after splitting mail into the proper groups. This is @code{t} by
9466 @c This is @code{nil} by
9467 @c default for reasons of security.
9469 @c Since Red Gnus is an alpha release, it is to be expected to lose mail.
9470 (No Gnus release since (ding) Gnus 0.10 (or something like that) have
9471 lost mail, I think, but that's not the point. (Except certain versions
9472 of Red Gnus.)) By not deleting the Incoming* files, one can be sure not
9473 to lose mail -- if Gnus totally whacks out, one can always recover what
9476 You may delete the @file{Incoming*} files at will.
9478 @item nnmail-use-long-file-names
9479 @vindex nnmail-use-long-file-names
9480 If non-@code{nil}, the mail backends will use long file and directory
9481 names. Groups like @samp{mail.misc} will end up in directories
9482 (assuming use of @code{nnml} backend) or files (assuming use of
9483 @code{nnfolder} backend) like @file{mail.misc}. If it is @code{nil},
9484 the same group will end up in @file{mail/misc}.
9486 @item nnmail-delete-file-function
9487 @vindex nnmail-delete-file-function
9489 Function called to delete files. It is @code{delete-file} by default.
9491 @item nnmail-cache-accepted-message-ids
9492 @vindex nnmail-cache-accepted-message-ids
9493 If non-@code{nil}, put the @code{Message-ID}s of articles imported into
9494 the backend (via @code{Gcc}, for instance) into the mail duplication
9495 discovery cache. The default is @code{nil}.
9500 @node Fancy Mail Splitting
9501 @subsection Fancy Mail Splitting
9502 @cindex mail splitting
9503 @cindex fancy mail splitting
9505 @vindex nnmail-split-fancy
9506 @findex nnmail-split-fancy
9507 If the rather simple, standard method for specifying how to split mail
9508 doesn't allow you to do what you want, you can set
9509 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
9510 play with the @code{nnmail-split-fancy} variable.
9512 Let's look at an example value of this variable first:
9515 ;; Messages from the mailer daemon are not crossposted to any of
9516 ;; the ordinary groups. Warnings are put in a separate group
9517 ;; from real errors.
9518 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
9520 ;; Non-error messages are crossposted to all relevant
9521 ;; groups, but we don't crosspost between the group for the
9522 ;; (ding) list and the group for other (ding) related mail.
9523 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
9524 ("subject" "ding" "ding.misc"))
9525 ;; Other mailing lists...
9526 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
9527 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
9529 (any "larsi@@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen"))
9530 ;; Unmatched mail goes to the catch all group.
9534 This variable has the format of a @dfn{split}. A split is a (possibly)
9535 recursive structure where each split may contain other splits. Here are
9536 the five possible split syntaxes:
9541 @samp{group}: If the split is a string, that will be taken as a group name.
9544 @var{(FIELD VALUE SPLIT)}: If the split is a list, the first element of
9545 which is a string, then store the message as specified by SPLIT, if
9546 header FIELD (a regexp) contains VALUE (also a regexp).
9549 @var{(| SPLIT...)}: If the split is a list, and the first element is
9550 @code{|} (vertical bar), then process each SPLIT until one of them
9551 matches. A SPLIT is said to match if it will cause the mail message to
9552 be stored in one or more groups.
9555 @var{(& SPLIT...)}: If the split is a list, and the first element is
9556 @code{&}, then process all SPLITs in the list.
9559 @code{junk}: If the split is the symbol @code{junk}, then don't save
9563 @var{(: function arg1 arg2 ...)}: If the split is a list, and the first
9564 element is @code{:}, then the second element will be called as a
9565 function with @var{args} given as arguments. The function should return
9570 In these splits, @var{FIELD} must match a complete field name.
9571 @var{VALUE} must match a complete word according to the fundamental mode
9572 syntax table. You can use @code{.*} in the regexps to match partial
9573 field names or words. In other words, all @var{VALUE}'s are wrapped in
9574 @samp{\<} and @samp{\>} pairs.
9576 @vindex nnmail-split-abbrev-alist
9577 @var{FIELD} and @var{VALUE} can also be lisp symbols, in that case they
9578 are expanded as specified by the variable
9579 @code{nnmail-split-abbrev-alist}. This is an alist of cons cells, where
9580 the @code{car} of a cell contains the key, and the @code{cdr} contains the associated
9583 @vindex nnmail-split-fancy-syntax-table
9584 @code{nnmail-split-fancy-syntax-table} is the syntax table in effect
9585 when all this splitting is performed.
9587 If you want to have Gnus create groups dynamically based on some
9588 information in the headers (i.e., do @code{replace-match}-like
9589 substitions in the group names), you can say things like:
9592 (any "debian-\\(\\w*\\)@@lists.debian.org" "mail.debian.\\1")
9595 @node Mail and Procmail
9596 @subsection Mail and Procmail
9601 Many people use @code{procmail} (or some other mail filter program or
9602 external delivery agent---@code{slocal}, @code{elm}, etc) to split
9603 incoming mail into groups. If you do that, you should set
9604 @code{nnmail-spool-file} to @code{procmail} to ensure that the mail
9605 backends never ever try to fetch mail by themselves.
9607 If you have a combined @code{procmail}/POP/mailbox setup, you can do
9608 something like the following:
9610 @vindex nnmail-use-procmail
9612 (setq nnmail-use-procmail t)
9613 (setq nnmail-spool-file
9614 '("/usr/spool/mail/my-name" "po:my-name"))
9617 This also means that you probably don't want to set
9618 @code{nnmail-split-methods} either, which has some, perhaps, unexpected
9621 When a mail backend is queried for what groups it carries, it replies
9622 with the contents of that variable, along with any groups it has figured
9623 out that it carries by other means. None of the backends, except
9624 @code{nnmh}, actually go out to the disk and check what groups actually
9625 exist. (It's not trivial to distinguish between what the user thinks is
9626 a basis for a newsgroup and what is just a plain old file or directory.)
9628 This means that you have to tell Gnus (and the backends) by hand what
9631 Let's take the @code{nnmh} backend as an example:
9633 The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
9634 There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
9636 Go to the group buffer and type @kbd{G m}. When prompted, answer
9637 @samp{foo} for the name and @samp{nnmh} for the method. Repeat
9638 twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
9639 to include all your mail groups.
9641 That's it. You are now set to read your mail. An active file for this
9642 method will be created automatically.
9644 @vindex nnmail-procmail-suffix
9645 @vindex nnmail-procmail-directory
9646 If you use @code{nnfolder} or any other backend that store more than a
9647 single article in each file, you should never have procmail add mails to
9648 the file that Gnus sees. Instead, procmail should put all incoming mail
9649 in @code{nnmail-procmail-directory}. To arrive at the file name to put
9650 the incoming mail in, append @code{nnmail-procmail-suffix} to the group
9651 name. The mail backends will read the mail from these files.
9653 @vindex nnmail-resplit-incoming
9654 When Gnus reads a file called @file{mail.misc.spool}, this mail will be
9655 put in the @code{mail.misc}, as one would expect. However, if you want
9656 Gnus to split the mail the normal way, you could set
9657 @code{nnmail-resplit-incoming} to @code{t}.
9659 @vindex nnmail-keep-last-article
9660 If you use @code{procmail} to split things directly into an @code{nnmh}
9661 directory (which you shouldn't do), you should set
9662 @code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
9663 ever expiring the final article (i.e., the article with the highest
9664 article number) in a mail newsgroup. This is quite, quite important.
9666 Here's an example setup: The incoming spools are located in
9667 @file{~/incoming/} and have @samp{""} as suffixes (i.e., the incoming
9668 spool files have the same names as the equivalent groups). The
9669 @code{nnfolder} backend is to be used as the mail interface, and the
9670 @code{nnfolder} directory is @file{~/fMail/}.
9673 (setq nnfolder-directory "~/fMail/")
9674 (setq nnmail-spool-file 'procmail)
9675 (setq nnmail-procmail-directory "~/incoming/")
9676 (setq gnus-secondary-select-methods '((nnfolder "")))
9677 (setq nnmail-procmail-suffix "")
9681 @node Incorporating Old Mail
9682 @subsection Incorporating Old Mail
9684 Most people have lots of old mail stored in various file formats. If
9685 you have set up Gnus to read mail using one of the spiffy Gnus mail
9686 backends, you'll probably wish to have that old mail incorporated into
9689 Doing so can be quite easy.
9691 To take an example: You're reading mail using @code{nnml}
9692 (@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a
9693 satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox
9694 file filled with important, but old, mail. You want to move it into
9695 your @code{nnml} groups.
9701 Go to the group buffer.
9704 Type `G f' and give the path to the mbox file when prompted to create an
9705 @code{nndoc} group from the mbox file (@pxref{Foreign Groups}).
9708 Type `SPACE' to enter the newly created group.
9711 Type `M P b' to process-mark all articles in this group's buffer
9712 (@pxref{Setting Process Marks}).
9715 Type `B r' to respool all the process-marked articles, and answer
9716 @samp{nnml} when prompted (@pxref{Mail Group Commands}).
9719 All the mail messages in the mbox file will now also be spread out over
9720 all your @code{nnml} groups. Try entering them and check whether things
9721 have gone without a glitch. If things look ok, you may consider
9722 deleting the mbox file, but I wouldn't do that unless I was absolutely
9723 sure that all the mail has ended up where it should be.
9725 Respooling is also a handy thing to do if you're switching from one mail
9726 backend to another. Just respool all the mail in the old mail groups
9727 using the new mail backend.
9731 @subsection Expiring Mail
9732 @cindex article expiry
9734 Traditional mail readers have a tendency to remove mail articles when
9735 you mark them as read, in some way. Gnus takes a fundamentally
9736 different approach to mail reading.
9738 Gnus basically considers mail just to be news that has been received in
9739 a rather peculiar manner. It does not think that it has the power to
9740 actually change the mail, or delete any mail messages. If you enter a
9741 mail group, and mark articles as ``read'', or kill them in some other
9742 fashion, the mail articles will still exist on the system. I repeat:
9743 Gnus will not delete your old, read mail. Unless you ask it to, of
9746 To make Gnus get rid of your unwanted mail, you have to mark the
9747 articles as @dfn{expirable}. This does not mean that the articles will
9748 disappear right away, however. In general, a mail article will be
9749 deleted from your system if, 1) it is marked as expirable, AND 2) it is
9750 more than one week old. If you do not mark an article as expirable, it
9751 will remain on your system until hell freezes over. This bears
9752 repeating one more time, with some spurious capitalizations: IF you do
9753 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
9755 @vindex gnus-auto-expirable-newsgroups
9756 You do not have to mark articles as expirable by hand. Groups that
9757 match the regular expression @code{gnus-auto-expirable-newsgroups} will
9758 have all articles that you read marked as expirable automatically. All
9759 articles marked as expirable have an @samp{E} in the first
9760 column in the summary buffer.
9762 By default, if you have auto expiry switched on, Gnus will mark all the
9763 articles you read as expirable, no matter if they were read or unread
9764 before. To avoid having articles marked as read marked as expirable
9765 automatically, you can put something like the following in your
9768 @vindex gnus-mark-article-hook
9770 (remove-hook 'gnus-mark-article-hook
9771 'gnus-summary-mark-read-and-unread-as-read)
9772 (add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read)
9775 Note that making a group auto-expirable doesn't mean that all read
9776 articles are expired---only the articles marked as expirable
9777 will be expired. Also note that using the @kbd{d} command won't make
9778 groups expirable---only semi-automatic marking of articles as read will
9779 mark the articles as expirable in auto-expirable groups.
9781 Let's say you subscribe to a couple of mailing lists, and you want the
9782 articles you have read to disappear after a while:
9785 (setq gnus-auto-expirable-newsgroups
9786 "mail.nonsense-list\\|mail.nice-list")
9789 Another way to have auto-expiry happen is to have the element
9790 @code{auto-expire} in the group parameters of the group.
9792 If you use adaptive scoring (@pxref{Adaptive Scoring}) and
9793 auto-expiring, you'll have problems. Auto-expiring and adaptive scoring
9794 don't really mix very well.
9796 @vindex nnmail-expiry-wait
9797 The @code{nnmail-expiry-wait} variable supplies the default time an
9798 expirable article has to live. Gnus starts counting days from when the
9799 message @emph{arrived}, not from when it was sent. The default is seven
9802 Gnus also supplies a function that lets you fine-tune how long articles
9803 are to live, based on what group they are in. Let's say you want to
9804 have one month expiry period in the @samp{mail.private} group, a one day
9805 expiry period in the @samp{mail.junk} group, and a six day expiry period
9808 @vindex nnmail-expiry-wait-function
9810 (setq nnmail-expiry-wait-function
9812 (cond ((string= group "mail.private")
9814 ((string= group "mail.junk")
9816 ((string= group "important")
9822 The group names this function is fed are ``unadorned'' group
9823 names---no @samp{nnml:} prefixes and the like.
9825 The @code{nnmail-expiry-wait} variable and
9826 @code{nnmail-expiry-wait-function} function can either be a number (not
9827 necessarily an integer) or one of the symbols @code{immediate} or
9830 You can also use the @code{expiry-wait} group parameter to selectively
9831 change the expiry period (@pxref{Group Parameters}).
9833 @vindex nnmail-keep-last-article
9834 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
9835 expire the final article in a mail newsgroup. This is to make life
9836 easier for procmail users.
9838 @vindex gnus-total-expirable-newsgroups
9839 By the way: That line up there, about Gnus never expiring non-expirable
9840 articles, is a lie. If you put @code{total-expire} in the group
9841 parameters, articles will not be marked as expirable, but all read
9842 articles will be put through the expiry process. Use with extreme
9843 caution. Even more dangerous is the
9844 @code{gnus-total-expirable-newsgroups} variable. All groups that match
9845 this regexp will have all read articles put through the expiry process,
9846 which means that @emph{all} old mail articles in the groups in question
9847 will be deleted after a while. Use with extreme caution, and don't come
9848 crying to me when you discover that the regexp you used matched the
9849 wrong group and all your important mail has disappeared. Be a
9850 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
9853 Most people make most of their mail groups total-expirable, though.
9857 @subsection Washing Mail
9858 @cindex mail washing
9859 @cindex list server brain damage
9860 @cindex incoming mail treatment
9862 Mailers and list servers are notorious for doing all sorts of really,
9863 really stupid things with mail. ``Hey, RFC822 doesn't explicitly
9864 prohibit us from adding the string @code{wE aRe ElItE!!!!!1!!} to the
9865 end of all lines passing through our server, so let's do that!!!!1!''
9866 Yes, but RFC822 wasn't designed to be read by morons. Things that were
9867 considered to be self-evident were not discussed. So. Here we are.
9869 Case in point: The German version of Microsoft Exchange adds @samp{AW:
9870 } to the subjects of replies instead of @samp{Re: }. I could pretend to
9871 be shocked and dismayed by this, but I haven't got the energy. It is to
9874 Gnus provides a plethora of functions for washing articles while
9875 displaying them, but it might be nicer to do the filtering before
9876 storing the mail to disc. For that purpose, we have three hooks and
9877 various functions that can be put in these hooks.
9880 @item nnmail-prepare-incoming-hook
9881 @vindex nnmail-prepare-incoming-hook
9882 This hook is called before doing anything with the mail and is meant for
9883 grand, sweeping gestures. Functions to be used include:
9886 @item nnheader-ms-strip-cr
9887 @findex nnheader-ms-strip-cr
9888 Remove trailing carriage returns from each line. This is default on
9889 Emacs running on MS machines.
9893 @item nnmail-prepare-incoming-header-hook
9894 @vindex nnmail-prepare-incoming-header-hook
9895 This hook is called narrowed to each header. It can be used when
9896 cleaning up the headers. Functions that can be used include:
9899 @item nnmail-remove-leading-whitespace
9900 @findex nnmail-remove-leading-whitespace
9901 Clear leading white space that ``helpful'' listservs have added to the
9902 headers to make them look nice. Aaah.
9904 @item nnmail-remove-list-identifiers
9905 @findex nnmail-remove-list-identifiers
9906 Some list servers add an identifier---for example, @samp{(idm)}---to the
9907 beginning of all @code{Subject} headers. I'm sure that's nice for
9908 people who use stone age mail readers. This function will remove
9909 strings that match the @code{nnmail-list-identifiers} regexp, which can
9910 also be a list of regexp.
9912 For instance, if you want to remove the @samp{(idm)} and the
9913 @samp{nagnagnag} identifiers:
9916 (setq nnmail-list-identifiers
9917 '("(idm)" "nagnagnag"))
9920 @item nnmail-remove-tabs
9921 @findex nnmail-remove-tabs
9922 Translate all @samp{TAB} characters into @samp{SPACE} characters.
9926 @item nnmail-prepare-incoming-message-hook
9927 @vindex nnmail-prepare-incoming-message-hook
9928 This hook is called narrowed to each message. Functions to be used
9932 @item article-de-quoted-unreadable
9933 @findex article-de-quoted-unreadable
9934 Decode Quoted Readable encoding.
9941 @subsection Duplicates
9943 @vindex nnmail-treat-duplicates
9944 @vindex nnmail-message-id-cache-length
9945 @vindex nnmail-message-id-cache-file
9946 @cindex duplicate mails
9947 If you are a member of a couple of mailing lists, you will sometimes
9948 receive two copies of the same mail. This can be quite annoying, so
9949 @code{nnmail} checks for and treats any duplicates it might find. To do
9950 this, it keeps a cache of old @code{Message-ID}s---
9951 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
9952 default. The approximate maximum number of @code{Message-ID}s stored
9953 there is controlled by the @code{nnmail-message-id-cache-length}
9954 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
9955 stored.) If all this sounds scary to you, you can set
9956 @code{nnmail-treat-duplicates} to @code{warn} (which is what it is by
9957 default), and @code{nnmail} won't delete duplicate mails. Instead it
9958 will insert a warning into the head of the mail saying that it thinks
9959 that this is a duplicate of a different message.
9961 This variable can also be a function. If that's the case, the function
9962 will be called from a buffer narrowed to the message in question with
9963 the @code{Message-ID} as a parameter. The function must return either
9964 @code{nil}, @code{warn}, or @code{delete}.
9966 You can turn this feature off completely by setting the variable to
9969 If you want all the duplicate mails to be put into a special
9970 @dfn{duplicates} group, you could do that using the normal mail split
9974 (setq nnmail-split-fancy
9975 '(| ;; Messages duplicates go to a separate group.
9976 ("gnus-warning" "duplication of message" "duplicate")
9977 ;; Message from daemons, postmaster, and the like to another.
9978 (any mail "mail.misc")
9985 (setq nnmail-split-methods
9986 '(("duplicates" "^Gnus-Warning:")
9991 Here's a neat feature: If you know that the recipient reads her mail
9992 with Gnus, and that she has @code{nnmail-treat-duplicates} set to
9993 @code{delete}, you can send her as many insults as you like, just by
9994 using a @code{Message-ID} of a mail that you know that she's already
9995 received. Think of all the fun! She'll never see any of it! Whee!
9998 @node Not Reading Mail
9999 @subsection Not Reading Mail
10001 If you start using any of the mail backends, they have the annoying
10002 habit of assuming that you want to read mail with them. This might not
10003 be unreasonable, but it might not be what you want.
10005 If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
10006 will ever attempt to read incoming mail, which should help.
10008 @vindex nnbabyl-get-new-mail
10009 @vindex nnmbox-get-new-mail
10010 @vindex nnml-get-new-mail
10011 @vindex nnmh-get-new-mail
10012 @vindex nnfolder-get-new-mail
10013 This might be too much, if, for instance, you are reading mail quite
10014 happily with @code{nnml} and just want to peek at some old @sc{rmail}
10015 file you have stashed away with @code{nnbabyl}. All backends have
10016 variables called backend-@code{get-new-mail}. If you want to disable
10017 the @code{nnbabyl} mail reading, you edit the virtual server for the
10018 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
10020 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
10021 narrowed to the article to be saved before saving it when reading
10025 @node Choosing a Mail Backend
10026 @subsection Choosing a Mail Backend
10028 Gnus will read the mail spool when you activate a mail group. The mail
10029 file is first copied to your home directory. What happens after that
10030 depends on what format you want to store your mail in.
10033 * Unix Mail Box:: Using the (quite) standard Un*x mbox.
10034 * Rmail Babyl:: Emacs programs use the rmail babyl format.
10035 * Mail Spool:: Store your mail in a private spool?
10036 * MH Spool:: An mhspool-like backend.
10037 * Mail Folders:: Having one file for each group.
10041 @node Unix Mail Box
10042 @subsubsection Unix Mail Box
10044 @cindex unix mail box
10046 @vindex nnmbox-active-file
10047 @vindex nnmbox-mbox-file
10048 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
10049 mail. @code{nnmbox} will add extra headers to each mail article to say
10050 which group it belongs in.
10052 Virtual server settings:
10055 @item nnmbox-mbox-file
10056 @vindex nnmbox-mbox-file
10057 The name of the mail box in the user's home directory.
10059 @item nnmbox-active-file
10060 @vindex nnmbox-active-file
10061 The name of the active file for the mail box.
10063 @item nnmbox-get-new-mail
10064 @vindex nnmbox-get-new-mail
10065 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
10071 @subsubsection Rmail Babyl
10075 @vindex nnbabyl-active-file
10076 @vindex nnbabyl-mbox-file
10077 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
10078 mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
10079 article to say which group it belongs in.
10081 Virtual server settings:
10084 @item nnbabyl-mbox-file
10085 @vindex nnbabyl-mbox-file
10086 The name of the rmail mbox file.
10088 @item nnbabyl-active-file
10089 @vindex nnbabyl-active-file
10090 The name of the active file for the rmail box.
10092 @item nnbabyl-get-new-mail
10093 @vindex nnbabyl-get-new-mail
10094 If non-@code{nil}, @code{nnbabyl} will read incoming mail.
10099 @subsubsection Mail Spool
10101 @cindex mail @sc{nov} spool
10103 The @dfn{nnml} spool mail format isn't compatible with any other known
10104 format. It should be used with some caution.
10106 @vindex nnml-directory
10107 If you use this backend, Gnus will split all incoming mail into files,
10108 one file for each mail, and put the articles into the corresponding
10109 directories under the directory specified by the @code{nnml-directory}
10110 variable. The default value is @file{~/Mail/}.
10112 You do not have to create any directories beforehand; Gnus will take
10115 If you have a strict limit as to how many files you are allowed to store
10116 in your account, you should not use this backend. As each mail gets its
10117 own file, you might very well occupy thousands of inodes within a few
10118 weeks. If this is no problem for you, and it isn't a problem for you
10119 having your friendly systems administrator walking around, madly,
10120 shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should
10121 know that this is probably the fastest format to use. You do not have
10122 to trudge through a big mbox file just to read your new mail.
10124 @code{nnml} is probably the slowest backend when it comes to article
10125 splitting. It has to create lots of files, and it also generates
10126 @sc{nov} databases for the incoming mails. This makes it the fastest
10127 backend when it comes to reading mail.
10129 Virtual server settings:
10132 @item nnml-directory
10133 @vindex nnml-directory
10134 All @code{nnml} directories will be placed under this directory.
10136 @item nnml-active-file
10137 @vindex nnml-active-file
10138 The active file for the @code{nnml} server.
10140 @item nnml-newsgroups-file
10141 @vindex nnml-newsgroups-file
10142 The @code{nnml} group descriptions file. @xref{Newsgroups File
10145 @item nnml-get-new-mail
10146 @vindex nnml-get-new-mail
10147 If non-@code{nil}, @code{nnml} will read incoming mail.
10149 @item nnml-nov-is-evil
10150 @vindex nnml-nov-is-evil
10151 If non-@code{nil}, this backend will ignore any @sc{nov} files.
10153 @item nnml-nov-file-name
10154 @vindex nnml-nov-file-name
10155 The name of the @sc{nov} files. The default is @file{.overview}.
10157 @item nnml-prepare-save-mail-hook
10158 @vindex nnml-prepare-save-mail-hook
10159 Hook run narrowed to an article before saving.
10163 @findex nnml-generate-nov-databases
10164 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
10165 you can do a complete update by typing @kbd{M-x
10166 nnml-generate-nov-databases}. This command will trawl through the
10167 entire @code{nnml} hierarchy, looking at each and every article, so it
10168 might take a while to complete. A better interface to this
10169 functionality can be found in the server buffer (@pxref{Server
10174 @subsubsection MH Spool
10176 @cindex mh-e mail spool
10178 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
10179 @sc{nov} databases and it doesn't keep an active file. This makes
10180 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
10181 makes it easier to write procmail scripts for.
10183 Virtual server settings:
10186 @item nnmh-directory
10187 @vindex nnmh-directory
10188 All @code{nnmh} directories will be located under this directory.
10190 @item nnmh-get-new-mail
10191 @vindex nnmh-get-new-mail
10192 If non-@code{nil}, @code{nnmh} will read incoming mail.
10195 @vindex nnmh-be-safe
10196 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
10197 sure that the articles in the folder are actually what Gnus thinks they
10198 are. It will check date stamps and stat everything in sight, so
10199 setting this to @code{t} will mean a serious slow-down. If you never
10200 use anything but Gnus to read the @code{nnmh} articles, you do not have
10201 to set this variable to @code{t}.
10206 @subsubsection Mail Folders
10208 @cindex mbox folders
10209 @cindex mail folders
10211 @code{nnfolder} is a backend for storing each mail group in a separate
10212 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
10213 will add extra headers to keep track of article numbers and arrival
10216 Virtual server settings:
10219 @item nnfolder-directory
10220 @vindex nnfolder-directory
10221 All the @code{nnfolder} mail boxes will be stored under this directory.
10223 @item nnfolder-active-file
10224 @vindex nnfolder-active-file
10225 The name of the active file.
10227 @item nnfolder-newsgroups-file
10228 @vindex nnfolder-newsgroups-file
10229 The name of the group descriptions file. @xref{Newsgroups File Format}.
10231 @item nnfolder-get-new-mail
10232 @vindex nnfolder-get-new-mail
10233 If non-@code{nil}, @code{nnfolder} will read incoming mail.
10236 @findex nnfolder-generate-active-file
10237 @kindex M-x nnfolder-generate-active-file
10238 If you have lots of @code{nnfolder}-like files you'd like to read with
10239 @code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
10240 command to make @code{nnfolder} aware of all likely files in
10241 @code{nnfolder-directory}.
10244 @node Other Sources
10245 @section Other Sources
10247 Gnus can do more than just read news or mail. The methods described
10248 below allow Gnus to view directories and files as if they were
10252 * Directory Groups:: You can read a directory as if it was a newsgroup.
10253 * Anything Groups:: Dired? Who needs dired?
10254 * Document Groups:: Single files can be the basis of a group.
10255 * SOUP:: Reading @sc{SOUP} packets ``offline''.
10256 * Web Searches:: Creating groups from articles that match a string.
10257 * Mail-To-News Gateways:: Posting articles via mail-to-news gateways.
10261 @node Directory Groups
10262 @subsection Directory Groups
10264 @cindex directory groups
10266 If you have a directory that has lots of articles in separate files in
10267 it, you might treat it as a newsgroup. The files have to have numerical
10270 This might be an opportune moment to mention @code{ange-ftp} (and its
10271 successor @code{efs}), that most wonderful of all wonderful Emacs
10272 packages. When I wrote @code{nndir}, I didn't think much about it---a
10273 backend to read directories. Big deal.
10275 @code{ange-ftp} changes that picture dramatically. For instance, if you
10276 enter the @code{ange-ftp} file name
10277 @file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name,
10278 @code{ange-ftp} or @code{efs} will actually allow you to read this
10279 directory over at @samp{sina} as a newsgroup. Distributed news ahoy!
10281 @code{nndir} will use @sc{nov} files if they are present.
10283 @code{nndir} is a ``read-only'' backend---you can't delete or expire
10284 articles with this method. You can use @code{nnmh} or @code{nnml} for
10285 whatever you use @code{nndir} for, so you could switch to any of those
10286 methods if you feel the need to have a non-read-only @code{nndir}.
10289 @node Anything Groups
10290 @subsection Anything Groups
10293 From the @code{nndir} backend (which reads a single spool-like
10294 directory), it's just a hop and a skip to @code{nneething}, which
10295 pretends that any arbitrary directory is a newsgroup. Strange, but
10298 When @code{nneething} is presented with a directory, it will scan this
10299 directory and assign article numbers to each file. When you enter such
10300 a group, @code{nneething} must create ``headers'' that Gnus can use.
10301 After all, Gnus is a newsreader, in case you're
10302 forgetting. @code{nneething} does this in a two-step process. First, it
10303 snoops each file in question. If the file looks like an article (i.e.,
10304 the first few lines look like headers), it will use this as the head.
10305 If this is just some arbitrary file without a head (e.g. a C source
10306 file), @code{nneething} will cobble up a header out of thin air. It
10307 will use file ownership, name and date and do whatever it can with these
10310 All this should happen automatically for you, and you will be presented
10311 with something that looks very much like a newsgroup. Totally like a
10312 newsgroup, to be precise. If you select an article, it will be displayed
10313 in the article buffer, just as usual.
10315 If you select a line that represents a directory, Gnus will pop you into
10316 a new summary buffer for this @code{nneething} group. And so on. You can
10317 traverse the entire disk this way, if you feel like, but remember that
10318 Gnus is not dired, really, and does not intend to be, either.
10320 There are two overall modes to this action---ephemeral or solid. When
10321 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
10322 will not store information on what files you have read, and what files
10323 are new, and so on. If you create a solid @code{nneething} group the
10324 normal way with @kbd{G m}, Gnus will store a mapping table between
10325 article numbers and file names, and you can treat this group like any
10326 other groups. When you activate a solid @code{nneething} group, you will
10327 be told how many unread articles it contains, etc., etc.
10332 @item nneething-map-file-directory
10333 @vindex nneething-map-file-directory
10334 All the mapping files for solid @code{nneething} groups will be stored
10335 in this directory, which defaults to @file{~/.nneething/}.
10337 @item nneething-exclude-files
10338 @vindex nneething-exclude-files
10339 All files that match this regexp will be ignored. Nice to use to exclude
10340 auto-save files and the like, which is what it does by default.
10342 @item nneething-map-file
10343 @vindex nneething-map-file
10344 Name of the map files.
10348 @node Document Groups
10349 @subsection Document Groups
10351 @cindex documentation group
10354 @code{nndoc} is a cute little thing that will let you read a single file
10355 as a newsgroup. Several files types are supported:
10362 The babyl (rmail) mail box.
10367 The standard Unix mbox file.
10369 @cindex MMDF mail box
10371 The MMDF mail box format.
10374 Several news articles appended into a file.
10377 @cindex rnews batch files
10378 The rnews batch transport format.
10379 @cindex forwarded messages
10382 Forwarded articles.
10386 @cindex MIME digest
10387 @cindex 1153 digest
10388 @cindex RFC 1153 digest
10389 @cindex RFC 341 digest
10390 MIME (RFC 1341) digest format.
10392 @item standard-digest
10393 The standard (RFC 1153) digest format.
10396 Non-standard digest format---matches most things, but does it badly.
10399 You can also use the special ``file type'' @code{guess}, which means
10400 that @code{nndoc} will try to guess what file type it is looking at.
10401 @code{digest} means that @code{nndoc} should guess what digest type the
10404 @code{nndoc} will not try to change the file or insert any extra headers into
10405 it---it will simply, like, let you use the file as the basis for a
10406 group. And that's it.
10408 If you have some old archived articles that you want to insert into your
10409 new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
10410 that. Say you have an old @file{RMAIL} file with mail that you now want
10411 to split into your new @code{nnml} groups. You look at that file using
10412 @code{nndoc} (using the @kbd{G f} command in the group buffer
10413 (@pxref{Foreign Groups})), set the process mark on all the articles in
10414 the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r})
10415 using @code{nnml}. If all goes well, all the mail in the @file{RMAIL}
10416 file is now also stored in lots of @code{nnml} directories, and you can
10417 delete that pesky @file{RMAIL} file. If you have the guts!
10419 Virtual server variables:
10422 @item nndoc-article-type
10423 @vindex nndoc-article-type
10424 This should be one of @code{mbox}, @code{babyl}, @code{digest},
10425 @code{news}, @code{rnews}, @code{mmdf}, @code{forward}, @code{rfc934},
10426 @code{rfc822-forward}, @code{mime-digest}, @code{standard-digest},
10427 @code{slack-digest}, @code{clari-briefs} or @code{guess}.
10429 @item nndoc-post-type
10430 @vindex nndoc-post-type
10431 This variable says whether Gnus is to consider the group a news group or
10432 a mail group. There are two valid values: @code{mail} (the default)
10437 * Document Server Internals:: How to add your own document types.
10441 @node Document Server Internals
10442 @subsubsection Document Server Internals
10444 Adding new document types to be recognized by @code{nndoc} isn't
10445 difficult. You just have to whip up a definition of what the document
10446 looks like, write a predicate function to recognize that document type,
10447 and then hook into @code{nndoc}.
10449 First, here's an example document type definition:
10453 (article-begin . "^\^A\^A\^A\^A\n")
10454 (body-end . "^\^A\^A\^A\^A\n"))
10457 The definition is simply a unique @dfn{name} followed by a series of
10458 regexp pseudo-variable settings. Below are the possible
10459 variables---don't be daunted by the number of variables; most document
10460 types can be defined with very few settings:
10463 @item first-article
10464 If present, @code{nndoc} will skip past all text until it finds
10465 something that match this regexp. All text before this will be
10468 @item article-begin
10469 This setting has to be present in all document type definitions. It
10470 says what the beginning of each article looks like.
10472 @item head-begin-function
10473 If present, this should be a function that moves point to the head of
10476 @item nndoc-head-begin
10477 If present, this should be a regexp that matches the head of the
10480 @item nndoc-head-end
10481 This should match the end of the head of the article. It defaults to
10482 @samp{^$}---the empty line.
10484 @item body-begin-function
10485 If present, this function should move point to the beginning of the body
10489 This should match the beginning of the body of the article. It defaults
10492 @item body-end-function
10493 If present, this function should move point to the end of the body of
10497 If present, this should match the end of the body of the article.
10500 If present, this should match the end of the file. All text after this
10501 regexp will be totally ignored.
10505 So, using these variables @code{nndoc} is able to dissect a document
10506 file into a series of articles, each with a head and a body. However, a
10507 few more variables are needed since not all document types are all that
10508 news-like---variables needed to transform the head or the body into
10509 something that's palatable for Gnus:
10512 @item prepare-body-function
10513 If present, this function will be called when requesting an article. It
10514 will be called with point at the start of the body, and is useful if the
10515 document has encoded some parts of its contents.
10517 @item article-transform-function
10518 If present, this function is called when requesting an article. It's
10519 meant to be used for more wide-ranging transformation of both head and
10520 body of the article.
10522 @item generate-head-function
10523 If present, this function is called to generate a head that Gnus can
10524 understand. It is called with the article number as a parameter, and is
10525 expected to generate a nice head for the article in question. It is
10526 called when requesting the headers of all articles.
10530 Let's look at the most complicated example I can come up with---standard
10535 (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+"))
10536 (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+"))
10537 (prepare-body-function . nndoc-unquote-dashes)
10538 (body-end-function . nndoc-digest-body-end)
10539 (head-end . "^ ?$")
10540 (body-begin . "^ ?\n")
10541 (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$")
10542 (subtype digest guess))
10545 We see that all text before a 70-width line of dashes is ignored; all
10546 text after a line that starts with that @samp{^End of} is also ignored;
10547 each article begins with a 30-width line of dashes; the line separating
10548 the head from the body may contain a single space; and that the body is
10549 run through @code{nndoc-unquote-dashes} before being delivered.
10551 To hook your own document definition into @code{nndoc}, use the
10552 @code{nndoc-add-type} function. It takes two parameters---the first is
10553 the definition itself and the second (optional) parameter says where in
10554 the document type definition alist to put this definition. The alist is
10555 traversed sequentially, and @code{nndoc-TYPE-type-p} is called for a given type @code{TYPE}. So @code{nndoc-mmdf-type-p} is called to see whether a document
10556 is of @code{mmdf} type, and so on. These type predicates should return
10557 @code{nil} if the document is not of the correct type; @code{t} if it is
10558 of the correct type; and a number if the document might be of the
10559 correct type. A high number means high probability; a low number means
10560 low probability with @samp{0} being the lowest valid number.
10568 In the PC world people often talk about ``offline'' newsreaders. These
10569 are thingies that are combined reader/news transport monstrosities.
10570 With built-in modem programs. Yecchh!
10572 Of course, us Unix Weenie types of human beans use things like
10573 @code{uucp} and, like, @code{nntpd} and set up proper news and mail
10574 transport things like Ghod intended. And then we just use normal
10577 However, it can sometimes be convenient to do something a that's a bit
10578 easier on the brain if you have a very slow modem, and you're not really
10579 that interested in doing things properly.
10581 A file format called @sc{soup} has been developed for transporting news
10582 and mail from servers to home machines and back again. It can be a bit
10585 First some terminology:
10590 This is the machine that is connected to the outside world and where you
10591 get news and/or mail from.
10594 This is the machine that you want to do the actual reading and responding
10595 on. It is typically not connected to the rest of the world in any way.
10598 Something that contains messages and/or commands. There are two kinds
10602 @item message packets
10603 These are packets made at the server, and typically contain lots of
10604 messages for you to read. These are called @file{SoupoutX.tgz} by
10605 default, where @var{X} is a number.
10607 @item response packets
10608 These are packets made at the home machine, and typically contains
10609 replies that you've written. These are called @file{SoupinX.tgz} by
10610 default, where @var{X} is a number.
10620 You log in on the server and create a @sc{soup} packet. You can either
10621 use a dedicated @sc{soup} thingie (like the @code{awk} program), or you
10622 can use Gnus to create the packet with its @sc{soup} commands (@kbd{O
10623 s} and/or @kbd{G s b}; and then @kbd{G s p}) (@pxref{SOUP Commands}).
10626 You transfer the packet home. Rail, boat, car or modem will do fine.
10629 You put the packet in your home directory.
10632 You fire up Gnus on your home machine using the @code{nnsoup} backend as
10633 the native or secondary server.
10636 You read articles and mail and answer and followup to the things you
10637 want (@pxref{SOUP Replies}).
10640 You do the @kbd{G s r} command to pack these replies into a @sc{soup}
10644 You transfer this packet to the server.
10647 You use Gnus to mail this packet out with the @kbd{G s s} command.
10650 You then repeat until you die.
10654 So you basically have a bipartite system---you use @code{nnsoup} for
10655 reading and Gnus for packing/sending these @sc{soup} packets.
10658 * SOUP Commands:: Commands for creating and sending @sc{soup} packets
10659 * SOUP Groups:: A backend for reading @sc{soup} packets.
10660 * SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
10664 @node SOUP Commands
10665 @subsubsection SOUP Commands
10667 These are commands for creating and manipulating @sc{soup} packets.
10671 @kindex G s b (Group)
10672 @findex gnus-group-brew-soup
10673 Pack all unread articles in the current group
10674 (@code{gnus-group-brew-soup}). This command understands the
10675 process/prefix convention.
10678 @kindex G s w (Group)
10679 @findex gnus-soup-save-areas
10680 Save all @sc{soup} data files (@code{gnus-soup-save-areas}).
10683 @kindex G s s (Group)
10684 @findex gnus-soup-send-replies
10685 Send all replies from the replies packet
10686 (@code{gnus-soup-send-replies}).
10689 @kindex G s p (Group)
10690 @findex gnus-soup-pack-packet
10691 Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
10694 @kindex G s r (Group)
10695 @findex nnsoup-pack-replies
10696 Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
10699 @kindex O s (Summary)
10700 @findex gnus-soup-add-article
10701 This summary-mode command adds the current article to a @sc{soup} packet
10702 (@code{gnus-soup-add-article}). It understands the process/prefix
10703 convention (@pxref{Process/Prefix}).
10708 There are a few variables to customize where Gnus will put all these
10713 @item gnus-soup-directory
10714 @vindex gnus-soup-directory
10715 Directory where Gnus will save intermediate files while composing
10716 @sc{soup} packets. The default is @file{~/SoupBrew/}.
10718 @item gnus-soup-replies-directory
10719 @vindex gnus-soup-replies-directory
10720 This is what Gnus will use as a temporary directory while sending our
10721 reply packets. @file{~/SoupBrew/SoupReplies/} is the default.
10723 @item gnus-soup-prefix-file
10724 @vindex gnus-soup-prefix-file
10725 Name of the file where Gnus stores the last used prefix. The default is
10726 @samp{gnus-prefix}.
10728 @item gnus-soup-packer
10729 @vindex gnus-soup-packer
10730 A format string command for packing a @sc{soup} packet. The default is
10731 @samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}.
10733 @item gnus-soup-unpacker
10734 @vindex gnus-soup-unpacker
10735 Format string command for unpacking a @sc{soup} packet. The default is
10736 @samp{gunzip -c %s | tar xvf -}.
10738 @item gnus-soup-packet-directory
10739 @vindex gnus-soup-packet-directory
10740 Where Gnus will look for reply packets. The default is @file{~/}.
10742 @item gnus-soup-packet-regexp
10743 @vindex gnus-soup-packet-regexp
10744 Regular expression matching @sc{soup} reply packets in
10745 @code{gnus-soup-packet-directory}.
10751 @subsubsection @sc{soup} Groups
10754 @code{nnsoup} is the backend for reading @sc{soup} packets. It will
10755 read incoming packets, unpack them, and put them in a directory where
10756 you can read them at leisure.
10758 These are the variables you can use to customize its behavior:
10762 @item nnsoup-tmp-directory
10763 @vindex nnsoup-tmp-directory
10764 When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this
10765 directory. (@file{/tmp/} by default.)
10767 @item nnsoup-directory
10768 @vindex nnsoup-directory
10769 @code{nnsoup} then moves each message and index file to this directory.
10770 The default is @file{~/SOUP/}.
10772 @item nnsoup-replies-directory
10773 @vindex nnsoup-replies-directory
10774 All replies will be stored in this directory before being packed into a
10775 reply packet. The default is @file{~/SOUP/replies/"}.
10777 @item nnsoup-replies-format-type
10778 @vindex nnsoup-replies-format-type
10779 The @sc{soup} format of the replies packets. The default is @samp{?n}
10780 (rnews), and I don't think you should touch that variable. I probably
10781 shouldn't even have documented it. Drats! Too late!
10783 @item nnsoup-replies-index-type
10784 @vindex nnsoup-replies-index-type
10785 The index type of the replies packet. The default is @samp{?n}, which
10786 means ``none''. Don't fiddle with this one either!
10788 @item nnsoup-active-file
10789 @vindex nnsoup-active-file
10790 Where @code{nnsoup} stores lots of information. This is not an ``active
10791 file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
10792 this file or mess it up in any way, you're dead. The default is
10793 @file{~/SOUP/active}.
10795 @item nnsoup-packer
10796 @vindex nnsoup-packer
10797 Format string command for packing a reply @sc{soup} packet. The default
10798 is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}.
10800 @item nnsoup-unpacker
10801 @vindex nnsoup-unpacker
10802 Format string command for unpacking incoming @sc{soup} packets. The
10803 default is @samp{gunzip -c %s | tar xvf -}.
10805 @item nnsoup-packet-directory
10806 @vindex nnsoup-packet-directory
10807 Where @code{nnsoup} will look for incoming packets. The default is
10810 @item nnsoup-packet-regexp
10811 @vindex nnsoup-packet-regexp
10812 Regular expression matching incoming @sc{soup} packets. The default is
10815 @item nnsoup-always-save
10816 @vindex nnsoup-always-save
10817 If non-@code{nil}, save the replies buffer after each posted message.
10823 @subsubsection SOUP Replies
10825 Just using @code{nnsoup} won't mean that your postings and mailings end
10826 up in @sc{soup} reply packets automagically. You have to work a bit
10827 more for that to happen.
10829 @findex nnsoup-set-variables
10830 The @code{nnsoup-set-variables} command will set the appropriate
10831 variables to ensure that all your followups and replies end up in the
10834 In specific, this is what it does:
10837 (setq message-send-news-function 'nnsoup-request-post)
10838 (setq message-send-mail-function 'nnsoup-request-mail)
10841 And that's it, really. If you only want news to go into the @sc{soup}
10842 system you just use the first line. If you only want mail to be
10843 @sc{soup}ed you use the second.
10847 @subsection Web Searches
10851 @cindex InReference
10852 @cindex Usenet searches
10853 @cindex searching the Usenet
10855 It's, like, too neat to search the Usenet for articles that match a
10856 string, but it, like, totally @emph{sucks}, like, totally, to use one of
10857 those, like, Web browsers, and you, like, have to, rilly, like, look at
10858 the commercials, so, like, with Gnus you can do @emph{rad}, rilly,
10859 searches without having to use a browser.
10861 The @code{nnweb} backend allows an easy interface to the mighty search
10862 engine. You create an @code{nnweb} group, enter a search pattern, and
10863 then enter the group and read the articles like you would any normal
10864 group. The @kbd{G w} command in the group buffer (@pxref{Foreign
10865 Groups}) will do this in an easy-to-use fashion.
10867 @code{nnweb} groups don't really lend themselves to being solid
10868 groups---they have a very fleeting idea of article numbers. In fact,
10869 each time you enter an @code{nnweb} group (not even changing the search
10870 pattern), you are likely to get the articles ordered in a different
10871 manner. Not even using duplicate suppression (@pxref{Duplicate
10872 Suppression}) will help, since @code{nnweb} doesn't even know the
10873 @code{Message-ID} of the articles before reading them using some search
10874 engines (DejaNews, for instance). The only possible way to keep track
10875 of which articles you've read is by scoring on the @code{Date}
10876 header---mark all articles posted before the last date you read the
10879 If the search engine changes its output substantially, @code{nnweb}
10880 won't be able to parse it and will fail. One could hardly fault the Web
10881 providers if they were to do this---their @emph{raison d'être} is to
10882 make money off of advertisements, not to provide services to the
10883 community. Since @code{nnweb} washes the ads off all the articles, one
10884 might think that the providers might be somewhat miffed. We'll see.
10886 You must have the @code{url} and @code{w3} package installed to be able
10887 to use @code{nnweb}.
10889 Virtual server variables:
10894 What search engine type is being used. The currently supported types
10895 are @code{dejanews}, @code{dejanewsold}, @code{altavista} and
10899 @vindex nnweb-search
10900 The search string to feed to the search engine.
10902 @item nnweb-max-hits
10903 @vindex nnweb-max-hits
10904 Advisory maximum number of hits per search to display. The default is
10907 @item nnweb-type-definition
10908 @vindex nnweb-type-definition
10909 Type-to-definition alist. This alist says what @code{nnweb} should do
10910 with the various search engine types. The following elements must be
10915 Function to decode the article and provide something that Gnus
10919 Function to create an article number to message header and URL alist.
10922 Function to send the search string to the search engine.
10925 The address the aforementioned function should send the search string
10929 Format string URL to fetch an article by @code{Message-ID}.
10936 @node Mail-To-News Gateways
10937 @subsection Mail-To-News Gateways
10938 @cindex mail-to-news gateways
10941 If your local @code{nntp} server doesn't allow posting, for some reason
10942 or other, you can post using one of the numerous mail-to-news gateways.
10943 The @code{nngateway} backend provides the interface.
10945 Note that you can't read anything from this backend---it can only be
10951 @item nngateway-address
10952 @vindex nngateway-address
10953 This is the address of the mail-to-news gateway.
10955 @item nngateway-header-transformation
10956 @vindex nngateway-header-transformation
10957 News headers often have to be transformed in some odd way or other
10958 for the mail-to-news gateway to accept it. This variable says what
10959 transformation should be called, and defaults to
10960 @code{nngateway-simple-header-transformation}. The function is called
10961 narrowed to the headers to be transformed and with one parameter---the
10964 This default function just inserts a new @code{To} header based on the
10965 @code{Newsgroups} header and the gateway address.
10966 For instance, an article with this @code{Newsgroups} header:
10969 Newsgroups: alt.religion.emacs
10972 will get this @code{From} header inserted:
10975 To: alt-religion-emacs@@GATEWAY
10980 So, to use this, simply say something like:
10983 (setq gnus-post-method '(nngateway "GATEWAY.ADDRESS"))
10987 @node Combined Groups
10988 @section Combined Groups
10990 Gnus allows combining a mixture of all the other group types into bigger
10994 * Virtual Groups:: Combining articles from many groups.
10995 * Kibozed Groups:: Looking through parts of the newsfeed for articles.
10999 @node Virtual Groups
11000 @subsection Virtual Groups
11002 @cindex virtual groups
11004 An @dfn{nnvirtual group} is really nothing more than a collection of
11007 For instance, if you are tired of reading many small groups, you can
11008 put them all in one big group, and then grow tired of reading one
11009 big, unwieldy group. The joys of computing!
11011 You specify @code{nnvirtual} as the method. The address should be a
11012 regexp to match component groups.
11014 All marks in the virtual group will stick to the articles in the
11015 component groups. So if you tick an article in a virtual group, the
11016 article will also be ticked in the component group from whence it came.
11017 (And vice versa---marks from the component groups will also be shown in
11018 the virtual group.)
11020 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
11021 newsgroups into one, big, happy newsgroup:
11024 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
11027 The component groups can be native or foreign; everything should work
11028 smoothly, but if your computer explodes, it was probably my fault.
11030 Collecting the same group from several servers might actually be a good
11031 idea if users have set the Distribution header to limit distribution.
11032 If you would like to read @samp{soc.motss} both from a server in Japan
11033 and a server in Norway, you could use the following as the group regexp:
11036 "^nntp\\+some\\.server\\.jp:soc\\.motss$\\|^nntp\\+some\\.server\\.no:soc\\.motss$"
11039 (Remember, though, that if you're creating the group with @kbd{G m}, you
11040 shouldn't double the backslashes, and you should leave off the quote
11041 characters at the beginning and the end of the string.)
11043 This should work kinda smoothly---all articles from both groups should
11044 end up in this one, and there should be no duplicates. Threading (and
11045 the rest) will still work as usual, but there might be problems with the
11046 sequence of articles. Sorting on date might be an option here
11047 (@pxref{Selecting a Group}).
11049 One limitation, however---all groups included in a virtual
11050 group have to be alive (i.e., subscribed or unsubscribed). Killed or
11051 zombie groups can't be component groups for @code{nnvirtual} groups.
11053 @vindex nnvirtual-always-rescan
11054 If the @code{nnvirtual-always-rescan} is non-@code{nil},
11055 @code{nnvirtual} will always scan groups for unread articles when
11056 entering a virtual group. If this variable is @code{nil} (which is the
11057 default) and you read articles in a component group after the virtual
11058 group has been activated, the read articles from the component group
11059 will show up when you enter the virtual group. You'll also see this
11060 effect if you have two virtual groups that have a component group in
11061 common. If that's the case, you should set this variable to @code{t}.
11062 Or you can just tap @code{M-g} on the virtual group every time before
11063 you enter it---it'll have much the same effect.
11066 @node Kibozed Groups
11067 @subsection Kibozed Groups
11071 @dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of)
11072 the news feed''. @code{nnkiboze} is a backend that will do this for
11073 you. Oh joy! Now you can grind any @sc{nntp} server down to a halt
11074 with useless requests! Oh happiness!
11076 @kindex G k (Group)
11077 To create a kibozed group, use the @kbd{G k} command in the group
11080 The address field of the @code{nnkiboze} method is, as with
11081 @code{nnvirtual}, a regexp to match groups to be ``included'' in the
11082 @code{nnkiboze} group. That's where most similarities between @code{nnkiboze}
11083 and @code{nnvirtual} end.
11085 In addition to this regexp detailing component groups, an @code{nnkiboze} group
11086 must have a score file to say what articles are to be included in
11087 the group (@pxref{Scoring}).
11089 @kindex M-x nnkiboze-generate-groups
11090 @findex nnkiboze-generate-groups
11091 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
11092 @code{nnkiboze} groups you want to have. This command will take time. Lots of
11093 time. Oodles and oodles of time. Gnus has to fetch the headers from
11094 all the articles in all the component groups and run them through the
11095 scoring process to determine if there are any articles in the groups
11096 that are to be part of the @code{nnkiboze} groups.
11098 Please limit the number of component groups by using restrictive
11099 regexps. Otherwise your sysadmin may become annoyed with you, and the
11100 @sc{nntp} site may throw you off and never let you back in again.
11101 Stranger things have happened.
11103 @code{nnkiboze} component groups do not have to be alive---they can be dead,
11104 and they can be foreign. No restrictions.
11106 @vindex nnkiboze-directory
11107 The generation of an @code{nnkiboze} group means writing two files in
11108 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
11109 contains the @sc{nov} header lines for all the articles in the group,
11110 and the other is an additional @file{.newsrc} file to store information
11111 on what groups have been searched through to find component articles.
11113 Articles marked as read in the @code{nnkiboze} group will have
11114 their @sc{nov} lines removed from the @sc{nov} file.
11117 @node Gnus Unplugged
11118 @section Gnus Unplugged
11123 @cindex Gnus Unplugged
11125 In olden times (ca. February '88), people used to run their newsreaders
11126 on big machines with permanent connections to the net. News transport
11127 was dealt with by news servers, and all the newsreaders had to do was to
11128 read news. Believe it or not.
11130 Nowadays most people read news and mail at home, and use some sort of
11131 modem to connect to the net. To avoid running up huge phone bills, it
11132 would be nice to have a way to slurp down all the news and mail, hang up
11133 the phone, read for several hours, and then upload any responses you
11134 have to make. And then you repeat the procedure.
11136 Of course, you can use news servers for doing this as well. I've used
11137 @code{inn} together with @code{slurp}, @code{pop} and @code{sendmail}
11138 for some years, but doing that's a bore. Moving the news server
11139 functionality up to the newsreader makes sense if you're the only person
11140 reading news on a machine.
11142 Using Gnus as an ``offline'' newsreader is quite simple.
11146 First, set up Gnus as you would do if you were running it on a machine
11147 that has full connection to the net. Go ahead. I'll still be waiting
11151 Then, put the following magical incantation at the end of your
11152 @file{.gnus.el} file:
11159 That's it. Gnus is now an ``offline'' newsreader.
11161 Of course, to use it as such, you have to learn a few new commands.
11164 * Agent Basics:: How it all is supposed to work.
11165 * Agent Categories:: How to tell the Gnus Agent what to download.
11166 * Agent Commands:: New commands for all the buffers.
11167 * Agent Expiry:: How to make old articles go away.
11168 * Outgoing Messages:: What happens when you post/mail something?
11169 * Agent Variables:: Customizing is fun.
11170 * Example Setup:: An example @file{.gnus.el} file for offline people.
11171 * Batching Agents:: How to fetch news from a @code{cron} job.
11176 @subsection Agent Basics
11178 First, let's get some terminology out of the way.
11180 The Gnus Agent is said to be @dfn{unplugged} when you have severed the
11181 connection to the net (and notified the Agent that this is the case).
11182 When the connection to the net is up again (and Gnus knows this), the
11183 Agent is @dfn{plugged}.
11185 The @dfn{local} machine is the one you're running on, and which isn't
11186 connected to the net continously.
11188 @dfn{Downloading} means fetching things from the net to your local
11189 machine. @dfn{Uploading} is doing the opposite.
11191 Let's take a typical Gnus session using the Agent.
11196 You start Gnus with @code{gnus-unplugged}. This brings up the Gnus
11197 Agent in a disconnected state. You can read all the news that you have
11198 already fetched while in this mode.
11201 You then decide to see whether any new news has arrived. You connect
11202 your machine to the net (using PPP or whatever), and then hit @kbd{J j}
11203 to make Gnus become @dfn{plugged}.
11206 You can then read the new news immediately, or you can download the news
11207 onto your local machine. If you want to do the latter, you press @kbd{J
11208 s} to fetch all the eligible articles in all the groups. (To let Gnus
11209 know which articles you want to download, @pxref{Agent Categories}.)
11212 After fetching the articles, you press @kbd{J j} to make Gnus become
11213 unplugged again, and you shut down the PPP thing (or whatever). And
11214 then you read the news offline.
11217 And then you go to step 2.
11220 Here are some things you should do the first time (or so) that you use
11226 Decide which servers should be covered by the Agent. If you have a mail
11227 backend, it would probably be nonsensical to have it covered by the
11228 Agent. Go to the server buffer (@kbd{^} in the group buffer) and press
11229 @kbd{J a} the server (or servers) that you wish to have covered by the
11230 Agent (@pxref{Server Agent Commands}). This will typically be only the
11231 primary select method, which is listed on the bottom in the buffer.
11234 Decide on download policy. @xref{Agent Categories}
11241 @node Agent Categories
11242 @subsection Agent Categories
11244 One of the main reasons to integrate the news transport layer into the
11245 newsreader is to allow greater control over what articles to download.
11246 There's not much point in downloading huge amounts of articles, just to
11247 find out that you're not interested in reading any of them. It's better
11248 to be somewhat more conservative in choosing what to download, and then
11249 mark the articles for downloading manually if it should turn out that
11250 you're interested in the articles anyway.
11252 The main way to control what is to be downloaded is to create a
11253 @dfn{category} and then assign some (or all) groups to this category.
11254 Gnus has its own buffer for creating and managing categories.
11257 * Category Syntax:: What a category looks like.
11258 * The Category Buffer:: A buffer for maintaining categories.
11259 * Category Variables:: Customize'r'Us.
11263 @node Category Syntax
11264 @subsubsection Category Syntax
11266 A category consists of two things.
11270 A predicate which (generally) gives a rough outline of which articles
11271 are eligible for downloading; and
11274 a score rule which (generally) gives you a finer granularity when
11275 deciding what articles to download. (Note that this @dfn{download
11276 score} is wholly unrelated to normal scores.)
11279 A predicate consists of predicates with logical operators sprinkled in
11282 Perhaps some examples are in order.
11284 Here's a simple predicate. (It's the default predicate, in fact, used
11285 for all groups that don't belong to any other category.)
11291 Quite simple, eh? This predicate is true if and only if the article is
11292 short (for some value of ``short'').
11294 Here's a more complex predicate:
11303 This means that an article should be downloaded if it has a high score,
11304 or if the score is not low and the article is not long. You get the
11307 The available logical operators are @code{or}, @code{and} and
11308 @code{not}. (If you prefer, you can use the more ``C''-ish operators
11309 @samp{|}, @code{&} and @code{!} instead.)
11311 The following predicates are pre-defined, but if none of these fit what
11312 you want to do, you can write your own.
11316 True iff the article is shorter than @code{gnus-agent-short-article}
11317 lines; default 100.
11320 True iff the article is longer than @code{gnus-agent-long-article}
11321 lines; default 200.
11324 True iff the article has a download score less than
11325 @code{gnus-agent-low-score}; default 0.
11328 True iff the article has a download score greater than
11329 @code{gnus-agent-high-score}; default 0.
11332 True iff the Gnus Agent guesses that the article is spam. The
11333 heuristics may change over time, but at present it just computes a
11334 checksum and sees whether articles match.
11343 If you want to create your own predicate function, here's what you have
11344 to know: The functions are called with no parameters, but the
11345 @code{gnus-headers} and @code{gnus-score} dynamic variables are bound to
11348 Now, the syntax of the download score is the same as the syntax of
11349 normal score files, except that all elements that require actually
11350 seeing the article itself are verboten. This means that only the
11351 following headers can be scored on: @code{From}, @code{Subject},
11352 @code{Date}, @code{Xref}, @code{Lines}, @code{Chars}, @code{Message-ID},
11353 and @code{References}.
11356 @node The Category Buffer
11357 @subsubsection The Category Buffer
11359 You'd normally do all category maintenance from the category buffer.
11360 When you enter it for the first time (with the @kbd{J c} command from
11361 the group buffer), you'll only see the @code{default} category.
11363 The following commands are available in this buffer:
11367 @kindex q (Category)
11368 @findex gnus-category-exit
11369 Return to the group buffer (@code{gnus-category-exit}).
11372 @kindex k (Category)
11373 @findex gnus-category-kill
11374 Kill the current category (@code{gnus-category-kill}).
11377 @kindex c (Category)
11378 @findex gnus-category-copy
11379 Copy the current category (@code{gnus-category-copy}).
11382 @kindex a (Category)
11383 @findex gnus-category-add
11384 Add a new category (@code{gnus-category-add}).
11387 @kindex p (Category)
11388 @findex gnus-category-edit-predicate
11389 Edit the predicate of the current category
11390 (@code{gnus-category-edit-predicate}).
11393 @kindex g (Category)
11394 @findex gnus-category-edit-groups
11395 Edit the list of groups belonging to the current category
11396 (@code{gnus-category-edit-groups}).
11399 @kindex s (Category)
11400 @findex gnus-category-edit-score
11401 Edit the download score rule of the current category
11402 (@code{gnus-category-edit-score}).
11405 @kindex l (Category)
11406 @findex gnus-category-list
11407 List all the categories (@code{gnus-category-list}).
11411 @node Category Variables
11412 @subsubsection Category Variables
11415 @item gnus-category-mode-hook
11416 @vindex gnus-category-mode-hook
11417 Hook run in category buffers.
11419 @item gnus-category-line-format
11420 @vindex gnus-category-line-format
11421 Format of the lines in the category buffer (@pxref{Formatting
11422 Variables}). Legal elements are:
11426 The name of the category.
11429 The number of groups in the category.
11432 @item gnus-category-mode-line-format
11433 @vindex gnus-category-mode-line-format
11434 Format of the category mode line.
11436 @item gnus-agent-short-article
11437 @vindex gnus-agent-short-article
11438 Articles that have fewer lines than this are short. Default 100.
11440 @item gnus-agent-long-article
11441 @vindex gnus-agent-long-article
11442 Articles that have more lines than this are long. Default 200.
11444 @item gnus-agent-low-score
11445 @vindex gnus-agent-low-score
11446 Articles that have a score lower than this have a low score. Default
11449 @item gnus-agent-high-score
11450 @vindex gnus-agent-high-score
11451 Articles that have a score higher than this have a high score. Default
11457 @node Agent Commands
11458 @subsection Agent Commands
11460 All the Gnus Agent commands are on the @kbd{J} submap. The @kbd{J j}
11461 (@code{gnus-agent-toggle-plugged} command works in all modes, and
11462 toggles the plugged/unplugged state of the Gnus Agent.
11466 * Group Agent Commands::
11467 * Summary Agent Commands::
11468 * Server Agent Commands::
11471 You can run a complete batch fetch from the command line with the
11472 following incantation:
11474 @cindex gnus-agent-batch-fetch
11476 $ emacs -batch -l ~/.gnus.el -f gnus-agent-batch-fetch
11481 @node Group Agent Commands
11482 @subsubsection Group Agent Commands
11486 @kindex J u (Agent Group)
11487 @findex gnus-agent-fetch-groups
11488 Fetch all eligible articles in the current group
11489 (@code{gnus-agent-fetch-groups}).
11492 @kindex J c (Agent Group)
11493 @findex gnus-enter-category-buffer
11494 Enter the Agent category buffer (@code{gnus-enter-category-buffer}).
11497 @kindex J s (Agent Group)
11498 @findex gnus-agent-fetch-session
11499 Fetch all eligible articles in all groups
11500 (@code{gnus-agent-fetch-session}).
11503 @kindex J S (Agent Group)
11504 @findex gnus-group-send-drafts
11505 Send all sendable messages in the draft group
11506 (@code{gnus-agent-fetch-session}). @xref{Drafts}
11509 @kindex J a (Agent Group)
11510 @findex gnus-agent-add-group
11511 Add the current group to an Agent category
11512 (@code{gnus-agent-add-group}).
11517 @node Summary Agent Commands
11518 @subsubsection Summary Agent Commands
11522 @kindex J # (Agent Summary)
11523 @findex gnus-agent-mark-article
11524 Mark the article for downloading (@code{gnus-agent-mark-article}).
11527 @kindex J M-# (Agent Summary)
11528 @findex gnus-agent-unmark-article
11529 Remove the downloading mark from the article
11530 (@code{gnus-agent-unmark-article}).
11533 @kindex @@ (Agent Summary)
11534 @findex gnus-agent-toggle-mark
11535 Toggle whether to download the article (@code{gnus-agent-toggle-mark}).
11538 @kindex J c (Agent Summary)
11539 @findex gnus-agent-catchup
11540 Mark all undownloaded articles as read (@code{gnus-agent-catchup}).
11545 @node Server Agent Commands
11546 @subsubsection Server Agent Commands
11550 @kindex J a (Agent Server)
11551 @findex gnus-agent-add-server
11552 Add the current server to the list of servers covered by the Gnus Agent
11553 (@code{gnus-agent-add-server}).
11556 @kindex J r (Agent Server)
11557 @findex gnus-agent-remove-server
11558 Remove the current server from the list of servers covered by the Gnus
11559 Agent (@code{gnus-agent-remove-server}).
11565 @subsection Agent Expiry
11567 @vindex gnus-agent-expiry-days
11568 @findex gnus-agent-expiry
11569 @kindex M-x gnus-agent-expiry
11570 @cindex Agent expiry
11571 @cindex Gnus Agent expiry
11574 @code{nnagent} doesn't handle expiry. Instead, there's a special
11575 @code{gnus-agent-expiry} command that will expire all read articles that
11576 are older than @code{gnus-agent-expiry-days} days. It can be run
11577 whenever you feel that you're running out of space. It's not
11578 particularly fast or efficient, and it's not a particularly good idea to
11579 interrupt it (with @kbd{C-g} or anything else) once you've started it.
11581 @vindex gnus-agent-expire-all
11582 if @code{gnus-agent-expire-all} is non-@code{nil}, this command will
11583 expire all articles---unread, read, ticked and dormant. If @code{nil}
11584 (which is the default), only read articles are eligible for expiry, and
11585 unread, ticked and dormant articles will be kept indefinitely.
11588 @node Outgoing Messages
11589 @subsection Outgoing Messages
11591 When Gnus is unplugged, all outgoing messages (both mail and news) are
11592 stored in the draft groups (@pxref{Drafts}). You can view them there
11593 after posting, and edit them at will.
11595 When Gnus is plugged again, you can send the messages either from the
11596 draft group with the special commands available there, or you can use
11597 the @kbd{J S} command in the group buffer to send all the sendable
11598 messages in the draft group.
11602 @node Agent Variables
11603 @subsection Agent Variables
11606 @item gnus-agent-directory
11607 @vindex gnus-agent-directory
11608 Where the Gnus Agent will store its files. The default is
11609 @file{~/News/agent/}.
11611 @item gnus-agent-handle-level
11612 @vindex gnus-agent-handle-level
11613 Groups on levels (@pxref{Group Levels}) higher than this variable will
11614 be ignored by the Agent. The default is @code{gnus-level-subscribed},
11615 which means that only subscribed group will be considered by the Agent
11618 @item gnus-agent-plugged-hook
11619 @vindex gnus-agent-plugged-hook
11620 Hook run when connecting to the network.
11622 @item gnus-agent-unplugged-hook
11623 @vindex gnus-agent-unplugged-hook
11624 Hook run when disconnecting from the network.
11629 @node Example Setup
11630 @subsection Example Setup
11632 If you don't want to read this manual, and you have a fairly standard
11633 setup, you may be able to use something like the following as your
11634 @file{.gnus.el} file to get started.
11637 ;;; Define how Gnus is to fetch news. We do this over NNTP
11638 ;;; from your ISP's server.
11639 (setq gnus-select-method '(nntp "nntp.your-isp.com"))
11641 ;;; Define how Gnus is to read your mail. We read mail from
11642 ;;; your ISP's POP server.
11643 (setenv "MAILHOST" "pop.your-isp.com")
11644 (setq nnmail-spool-file "po:username")
11646 ;;; Say how Gnus is to store the mail. We use nnml groups.
11647 (setq gnus-secondary-select-methods '((nnml "")))
11649 ;;; Make Gnus into an offline newsreader.
11653 That should be it, basically. Put that in your @file{~/.gnus.el} file,
11654 edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x
11657 If this is the first time you've run Gnus, you will be subscribed
11658 automatically to a few default newsgroups. You'll probably want to
11659 subscribe to more groups, and to do that, you have to query the
11660 @sc{nntp} server for a complete list of groups with the @kbd{A A}
11661 command. This usually takes quite a while, but you only have to do it
11664 After reading and parsing a while, you'll be presented with a list of
11665 groups. Subscribe to the ones you want to read with the @kbd{u}
11666 command. @kbd{l} to make all the killed groups disappear after you've
11667 subscribe to all the groups you want to read. (@kbd{A k} will bring
11668 back all the killed groups.)
11670 You can now read the groups at once, or you can download the articles
11671 with the @kbd{J s} command. And then read the rest of this manual to
11672 find out which of the other gazillion things you want to customize.
11675 @node Batching Agents
11676 @subsection Batching Agents
11678 Having the Gnus Agent fetch articles (and post whatever messages you've
11679 written) is quite easy once you've gotten things set up properly. The
11680 following shell script will do everything that is necessary:
11684 emacs -batch -l ~/.emacs -f gnus-agent-batch >/dev/null
11693 Other people use @dfn{kill files}, but we here at Gnus Towers like
11694 scoring better than killing, so we'd rather switch than fight. They do
11695 something completely different as well, so sit up straight and pay
11698 @vindex gnus-summary-mark-below
11699 All articles have a default score (@code{gnus-summary-default-score}),
11700 which is 0 by default. This score may be raised or lowered either
11701 interactively or by score files. Articles that have a score lower than
11702 @code{gnus-summary-mark-below} are marked as read.
11704 Gnus will read any @dfn{score files} that apply to the current group
11705 before generating the summary buffer.
11707 There are several commands in the summary buffer that insert score
11708 entries based on the current article. You can, for instance, ask Gnus to
11709 lower or increase the score of all articles with a certain subject.
11711 There are two sorts of scoring entries: Permanent and temporary.
11712 Temporary score entries are self-expiring entries. Any entries that are
11713 temporary and have not been used for, say, a week, will be removed
11714 silently to help keep the sizes of the score files down.
11717 * Summary Score Commands:: Adding score entries for the current group.
11718 * Group Score Commands:: General score commands.
11719 * Score Variables:: Customize your scoring. (My, what terminology).
11720 * Score File Format:: What a score file may contain.
11721 * Score File Editing:: You can edit score files by hand as well.
11722 * Adaptive Scoring:: Big Sister Gnus knows what you read.
11723 * Home Score File:: How to say where new score entries are to go.
11724 * Followups To Yourself:: Having Gnus notice when people answer you.
11725 * Scoring Tips:: How to score effectively.
11726 * Reverse Scoring:: That problem child of old is not problem.
11727 * Global Score Files:: Earth-spanning, ear-splitting score files.
11728 * Kill Files:: They are still here, but they can be ignored.
11729 * Converting Kill Files:: Translating kill files to score files.
11730 * GroupLens:: Getting predictions on what you like to read.
11731 * Advanced Scoring:: Using logical expressions to build score rules.
11732 * Score Decays:: It can be useful to let scores wither away.
11736 @node Summary Score Commands
11737 @section Summary Score Commands
11738 @cindex score commands
11740 The score commands that alter score entries do not actually modify real
11741 score files. That would be too inefficient. Gnus maintains a cache of
11742 previously loaded score files, one of which is considered the
11743 @dfn{current score file alist}. The score commands simply insert
11744 entries into this list, and upon group exit, this list is saved.
11746 The current score file is by default the group's local score file, even
11747 if no such score file actually exists. To insert score commands into
11748 some other score file (e.g. @file{all.SCORE}), you must first make this
11749 score file the current one.
11751 General score commands that don't actually change the score file:
11756 @kindex V s (Summary)
11757 @findex gnus-summary-set-score
11758 Set the score of the current article (@code{gnus-summary-set-score}).
11761 @kindex V S (Summary)
11762 @findex gnus-summary-current-score
11763 Display the score of the current article
11764 (@code{gnus-summary-current-score}).
11767 @kindex V t (Summary)
11768 @findex gnus-score-find-trace
11769 Display all score rules that have been used on the current article
11770 (@code{gnus-score-find-trace}).
11773 @kindex V R (Summary)
11774 @findex gnus-summary-rescore
11775 Run the current summary through the scoring process
11776 (@code{gnus-summary-rescore}). This might be useful if you're playing
11777 around with your score files behind Gnus' back and want to see the
11778 effect you're having.
11781 @kindex V a (Summary)
11782 @findex gnus-summary-score-entry
11783 Add a new score entry, and allow specifying all elements
11784 (@code{gnus-summary-score-entry}).
11787 @kindex V c (Summary)
11788 @findex gnus-score-change-score-file
11789 Make a different score file the current
11790 (@code{gnus-score-change-score-file}).
11793 @kindex V e (Summary)
11794 @findex gnus-score-edit-current-scores
11795 Edit the current score file (@code{gnus-score-edit-current-scores}).
11796 You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score
11800 @kindex V f (Summary)
11801 @findex gnus-score-edit-file
11802 Edit a score file and make this score file the current one
11803 (@code{gnus-score-edit-file}).
11806 @kindex V F (Summary)
11807 @findex gnus-score-flush-cache
11808 Flush the score cache (@code{gnus-score-flush-cache}). This is useful
11809 after editing score files.
11812 @kindex V C (Summary)
11813 @findex gnus-score-customize
11814 Customize a score file in a visually pleasing manner
11815 (@code{gnus-score-customize}).
11819 The rest of these commands modify the local score file.
11824 @kindex V m (Summary)
11825 @findex gnus-score-set-mark-below
11826 Prompt for a score, and mark all articles with a score below this as
11827 read (@code{gnus-score-set-mark-below}).
11830 @kindex V x (Summary)
11831 @findex gnus-score-set-expunge-below
11832 Prompt for a score, and add a score rule to the current score file to
11833 expunge all articles below this score
11834 (@code{gnus-score-set-expunge-below}).
11837 The keystrokes for actually making score entries follow a very regular
11838 pattern, so there's no need to list all the commands. (Hundreds of
11841 @findex gnus-summary-increase-score
11842 @findex gnus-summary-lower-score
11846 The first key is either @kbd{I} (upper case i) for increasing the score
11847 or @kbd{L} for lowering the score.
11849 The second key says what header you want to score on. The following
11850 keys are available:
11854 Score on the author name.
11857 Score on the subject line.
11860 Score on the Xref line---i.e., the cross-posting line.
11863 Score on thread---the References line.
11869 Score on the number of lines.
11872 Score on the Message-ID.
11875 Score on followups.
11885 The third key is the match type. Which match types are valid depends on
11886 what headers you are scoring on.
11898 Substring matching.
11901 Fuzzy matching (@pxref{Fuzzy Matching}).
11930 Greater than number.
11935 The fourth and final key says whether this is a temporary (i.e., expiring)
11936 score entry, or a permanent (i.e., non-expiring) score entry, or whether
11937 it is to be done immediately, without adding to the score file.
11941 Temporary score entry.
11944 Permanent score entry.
11947 Immediately scoring.
11952 So, let's say you want to increase the score on the current author with
11953 exact matching permanently: @kbd{I a e p}. If you want to lower the
11954 score based on the subject line, using substring matching, and make a
11955 temporary score entry: @kbd{L s s t}. Pretty easy.
11957 To make things a bit more complicated, there are shortcuts. If you use
11958 a capital letter on either the second or third keys, Gnus will use
11959 defaults for the remaining one or two keystrokes. The defaults are
11960 ``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s
11961 t}, and @kbd{I a R} is the same as @kbd{I a r t}.
11963 These functions take both the numerical prefix and the symbolic prefix
11964 (@pxref{Symbolic Prefixes}). A numerical prefix says how much to lower
11965 (or increase) the score of the article. A symbolic prefix of @code{a}
11966 says to use the @file{all.SCORE} file for the command instead of the
11967 current score file.
11969 @vindex gnus-score-mimic-keymap
11970 The @code{gnus-score-mimic-keymap} says whether these commands will
11971 pretend they are keymaps or not.
11974 @node Group Score Commands
11975 @section Group Score Commands
11976 @cindex group score commands
11978 There aren't many of these as yet, I'm afraid.
11983 @kindex W f (Group)
11984 @findex gnus-score-flush-cache
11985 Gnus maintains a cache of score alists to avoid having to reload them
11986 all the time. This command will flush the cache
11987 (@code{gnus-score-flush-cache}).
11991 You can do scoring from the command line by saying something like:
11993 @findex gnus-batch-score
11994 @cindex batch scoring
11996 $ emacs -batch -l ~/.emacs -l gnus -f gnus-batch-score
12000 @node Score Variables
12001 @section Score Variables
12002 @cindex score variables
12006 @item gnus-use-scoring
12007 @vindex gnus-use-scoring
12008 If @code{nil}, Gnus will not check for score files, and will not, in
12009 general, do any score-related work. This is @code{t} by default.
12011 @item gnus-kill-killed
12012 @vindex gnus-kill-killed
12013 If this variable is @code{nil}, Gnus will never apply score files to
12014 articles that have already been through the kill process. While this
12015 may save you lots of time, it also means that if you apply a kill file
12016 to a group, and then change the kill file and want to run it over you
12017 group again to kill more articles, it won't work. You have to set this
12018 variable to @code{t} to do that. (It is @code{t} by default.)
12020 @item gnus-kill-files-directory
12021 @vindex gnus-kill-files-directory
12022 All kill and score files will be stored in this directory, which is
12023 initialized from the @code{SAVEDIR} environment variable by default.
12024 This is @file{~/News/} by default.
12026 @item gnus-score-file-suffix
12027 @vindex gnus-score-file-suffix
12028 Suffix to add to the group name to arrive at the score file name
12029 (@samp{SCORE} by default.)
12031 @item gnus-score-uncacheable-files
12032 @vindex gnus-score-uncacheable-files
12033 @cindex score cache
12034 All score files are normally cached to avoid excessive re-loading of
12035 score files. However, if this might make you Emacs grow big and
12036 bloated, so this regexp can be used to weed out score files unlikely to be needed again. It would be a bad idea to deny caching of
12037 @file{all.SCORE}, while it might be a good idea to not cache
12038 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
12039 variable is @samp{ADAPT$} by default, so no adaptive score files will
12042 @item gnus-save-score
12043 @vindex gnus-save-score
12044 If you have really complicated score files, and do lots of batch
12045 scoring, then you might set this variable to @code{t}. This will make
12046 Gnus save the scores into the @file{.newsrc.eld} file.
12048 @item gnus-score-interactive-default-score
12049 @vindex gnus-score-interactive-default-score
12050 Score used by all the interactive raise/lower commands to raise/lower
12051 score with. Default is 1000, which may seem excessive, but this is to
12052 ensure that the adaptive scoring scheme gets enough room to play with.
12053 We don't want the small changes from the adaptive scoring to overwrite
12054 manually entered data.
12056 @item gnus-summary-default-score
12057 @vindex gnus-summary-default-score
12058 Default score of an article, which is 0 by default.
12060 @item gnus-summary-expunge-below
12061 @vindex gnus-summary-expunge-below
12062 Don't display the summary lines of articles that have scores lower than
12063 this variable. This is @code{nil} by default, which means that no
12064 articles will be hidden. This variable is local to the summary buffers,
12065 and has to be set from @code{gnus-summary-mode-hook}.
12067 @item gnus-score-over-mark
12068 @vindex gnus-score-over-mark
12069 Mark (in the third column) used for articles with a score over the
12070 default. Default is @samp{+}.
12072 @item gnus-score-below-mark
12073 @vindex gnus-score-below-mark
12074 Mark (in the third column) used for articles with a score below the
12075 default. Default is @samp{-}.
12077 @item gnus-score-find-score-files-function
12078 @vindex gnus-score-find-score-files-function
12079 Function used to find score files for the current group. This function
12080 is called with the name of the group as the argument.
12082 Predefined functions available are:
12085 @item gnus-score-find-single
12086 @findex gnus-score-find-single
12087 Only apply the group's own score file.
12089 @item gnus-score-find-bnews
12090 @findex gnus-score-find-bnews
12091 Apply all score files that match, using bnews syntax. This is the
12092 default. If the current group is @samp{gnu.emacs.gnus}, for instance,
12093 @file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and
12094 @file{gnu.all.SCORE} would all apply. In short, the instances of
12095 @samp{all} in the score file names are translated into @samp{.*}, and
12096 then a regexp match is done.
12098 This means that if you have some score entries that you want to apply to
12099 all groups, then you put those entries in the @file{all.SCORE} file.
12101 The score files are applied in a semi-random order, although Gnus will
12102 try to apply the more general score files before the more specific score
12103 files. It does this by looking at the number of elements in the score
12104 file names---discarding the @samp{all} elements.
12106 @item gnus-score-find-hierarchical
12107 @findex gnus-score-find-hierarchical
12108 Apply all score files from all the parent groups. This means that you
12109 can't have score files like @file{all.SCORE}, but you can have
12110 @file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE}.
12113 This variable can also be a list of functions. In that case, all these
12114 functions will be called, and all the returned lists of score files will
12115 be applied. These functions can also return lists of score alists
12116 directly. In that case, the functions that return these non-file score
12117 alists should probably be placed before the ``real'' score file
12118 functions, to ensure that the last score file returned is the local
12121 @item gnus-score-expiry-days
12122 @vindex gnus-score-expiry-days
12123 This variable says how many days should pass before an unused score file
12124 entry is expired. If this variable is @code{nil}, no score file entries
12125 are expired. It's 7 by default.
12127 @item gnus-update-score-entry-dates
12128 @vindex gnus-update-score-entry-dates
12129 If this variable is non-@code{nil}, matching score entries will have
12130 their dates updated. (This is how Gnus controls expiry---all
12131 non-matching entries will become too old while matching entries will
12132 stay fresh and young.) However, if you set this variable to @code{nil},
12133 even matching entries will grow old and will have to face that oh-so
12136 @item gnus-score-after-write-file-function
12137 @vindex gnus-score-after-write-file-function
12138 Function called with the name of the score file just written.
12140 @item gnus-score-thread-simplify
12141 @vindex gnus-score-thread-simplify
12142 If this variable is non-@code{nil}, article subjects will be simplified
12143 for subject scoring purposes in the same manner as with
12144 threading---according to the current value of
12145 gnus-simplify-subject-functions. If the scoring entry uses
12146 @code{substring} or @code{exact} matching, the match will also be
12147 simplified in this manner.
12152 @node Score File Format
12153 @section Score File Format
12154 @cindex score file format
12156 A score file is an @code{emacs-lisp} file that normally contains just a
12157 single form. Casual users are not expected to edit these files;
12158 everything can be changed from the summary buffer.
12160 Anyway, if you'd like to dig into it yourself, here's an example:
12164 ("Lars Ingebrigtsen" -10000)
12166 ("larsi\\|lmi" -50000 nil R))
12168 ("Ding is Badd" nil 728373))
12170 ("alt.politics" -1000 728372 s))
12175 (mark-and-expunge -10)
12179 (files "/hom/larsi/News/gnu.SCORE")
12180 (exclude-files "all.SCORE")
12181 (local (gnus-newsgroup-auto-expire t)
12182 (gnus-summary-make-false-root empty))
12186 This example demonstrates most score file elements. For a different
12187 approach, see @pxref{Advanced Scoring}.
12189 Even though this looks much like lisp code, nothing here is actually
12190 @code{eval}ed. The lisp reader is used to read this form, though, so it
12191 has to be valid syntactically, if not semantically.
12193 Six keys are supported by this alist:
12198 If the key is a string, it is the name of the header to perform the
12199 match on. Scoring can only be performed on these eight headers:
12200 @code{From}, @code{Subject}, @code{References}, @code{Message-ID},
12201 @code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to
12202 these headers, there are three strings to tell Gnus to fetch the entire
12203 article and do the match on larger parts of the article: @code{Body}
12204 will perform the match on the body of the article, @code{Head} will
12205 perform the match on the head of the article, and @code{All} will
12206 perform the match on the entire article. Note that using any of these
12207 last three keys will slow down group entry @emph{considerably}. The
12208 final ``header'' you can score on is @code{Followup}. These score
12209 entries will result in new score entries being added for all follow-ups
12210 to articles that matches these score entries.
12212 Following this key is a arbitrary number of score entries, where each
12213 score entry has one to four elements.
12217 The first element is the @dfn{match element}. On most headers this will
12218 be a string, but on the Lines and Chars headers, this must be an
12222 If the second element is present, it should be a number---the @dfn{score
12223 element}. This number should be an integer in the neginf to posinf
12224 interval. This number is added to the score of the article if the match
12225 is successful. If this element is not present, the
12226 @code{gnus-score-interactive-default-score} number will be used
12227 instead. This is 1000 by default.
12230 If the third element is present, it should be a number---the @dfn{date
12231 element}. This date says when the last time this score entry matched,
12232 which provides a mechanism for expiring the score entries. It this
12233 element is not present, the score entry is permanent. The date is
12234 represented by the number of days since December 31, 1 BCE.
12237 If the fourth element is present, it should be a symbol---the @dfn{type
12238 element}. This element specifies what function should be used to see
12239 whether this score entry matches the article. What match types that can
12240 be used depends on what header you wish to perform the match on.
12243 @item From, Subject, References, Xref, Message-ID
12244 For most header types, there are the @code{r} and @code{R} (regexp), as
12245 well as @code{s} and @code{S} (substring) types, and @code{e} and
12246 @code{E} (exact match), and @code{w} (word match) types. If this
12247 element is not present, Gnus will assume that substring matching should
12248 be used. @code{R}, @code{S}, and @code{E} differ from the others in
12249 that the matches will be done in a case-sensitive manner. All these
12250 one-letter types are really just abbreviations for the @code{regexp},
12251 @code{string}, @code{exact}, and @code{word} types, which you can use
12252 instead, if you feel like.
12255 These two headers use different match types: @code{<}, @code{>},
12256 @code{=}, @code{>=} and @code{<=}. When matching on @code{Lines}, be
12257 careful because some backends (like @code{nndir}) do not generate
12258 @code{Lines} header, so every article ends up being marked as having 0
12259 lines. This can lead to strange results if you happen to lower score of
12260 the articles with few lines.
12263 For the Date header we have three kinda silly match types:
12264 @code{before}, @code{at} and @code{after}. I can't really imagine this
12265 ever being useful, but, like, it would feel kinda silly not to provide
12266 this function. Just in case. You never know. Better safe than sorry.
12267 Once burnt, twice shy. Don't judge a book by its cover. Never not have
12268 sex on a first date. (I have been told that at least one person, and I
12269 quote, ``found this function indispensable'', however.)
12273 A more useful match type is @code{regexp}. With it, you can match the
12274 date string using a regular expression. The date is normalized to
12275 ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. If
12276 you want to match all articles that have been posted on April 1st in
12277 every year, you could use @samp{....0401.........} as a match string,
12278 for instance. (Note that the date is kept in its original time zone, so
12279 this will match articles that were posted when it was April 1st where
12280 the article was posted from. Time zones are such wholesome fun for the
12283 @item Head, Body, All
12284 These three match keys use the same match types as the @code{From} (etc)
12288 This match key is somewhat special, in that it will match the
12289 @code{From} header, and affect the score of not only the matching
12290 articles, but also all followups to the matching articles. This allows
12291 you e.g. increase the score of followups to your own articles, or
12292 decrease the score of followups to the articles of some known
12293 trouble-maker. Uses the same match types as the @code{From} header
12294 uses. (Using this match key will lead to creation of @file{ADAPT}
12298 This match key works along the same lines as the @code{Followup} match
12299 key. If you say that you want to score on a (sub-)thread started by an article with a @code{Message-ID} @var{X}, then you add a
12300 @samp{thread} match. This will add a new @samp{thread} match for each
12301 article that has @var{X} in its @code{References} header. (These new
12302 @samp{thread} matches will use the @code{Message-ID}s of these matching
12303 articles.) This will ensure that you can raise/lower the score of an
12304 entire thread, even though some articles in the thread may not have
12305 complete @code{References} headers. Note that using this may lead to
12306 undeterministic scores of the articles in the thread. (Using this match
12307 key will lead to creation of @file{ADAPT} files.)
12311 @cindex Score File Atoms
12313 The value of this entry should be a number. Any articles with a score
12314 lower than this number will be marked as read.
12317 The value of this entry should be a number. Any articles with a score
12318 lower than this number will be removed from the summary buffer.
12320 @item mark-and-expunge
12321 The value of this entry should be a number. Any articles with a score
12322 lower than this number will be marked as read and removed from the
12325 @item thread-mark-and-expunge
12326 The value of this entry should be a number. All articles that belong to
12327 a thread that has a total score below this number will be marked as read
12328 and removed from the summary buffer. @code{gnus-thread-score-function}
12329 says how to compute the total score for a thread.
12332 The value of this entry should be any number of file names. These files
12333 are assumed to be score files as well, and will be loaded the same way
12336 @item exclude-files
12337 The clue of this entry should be any number of files. These files will
12338 not be loaded, even though they would normally be so, for some reason or
12342 The value of this entry will be @code{eval}el. This element will be
12343 ignored when handling global score files.
12346 Read-only score files will not be updated or saved. Global score files
12347 should feature this atom (@pxref{Global Score Files}). (Note:
12348 @dfn{Global} here really means @dfn{global}; not your personal
12349 apply-to-all-groups score files.)
12352 The value of this entry should be a number. Articles that do not have
12353 parents will get this number added to their scores. Imagine you follow
12354 some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you
12355 will only follow a few of the threads, also want to see any new threads.
12357 You can do this with the following two score file entries:
12361 (mark-and-expunge -100)
12364 When you enter the group the first time, you will only see the new
12365 threads. You then raise the score of the threads that you find
12366 interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the
12367 rest. Next time you enter the group, you will see new articles in the
12368 interesting threads, plus any new threads.
12370 I.e.---the orphan score atom is for high-volume groups where there
12371 exist a few interesting threads which can't be found automatically by
12372 ordinary scoring rules.
12375 This entry controls the adaptive scoring. If it is @code{t}, the
12376 default adaptive scoring rules will be used. If it is @code{ignore}, no
12377 adaptive scoring will be performed on this group. If it is a list, this
12378 list will be used as the adaptive scoring rules. If it isn't present,
12379 or is something other than @code{t} or @code{ignore}, the default
12380 adaptive scoring rules will be used. If you want to use adaptive
12381 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
12382 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
12383 not want adaptive scoring. If you only want adaptive scoring in a few
12384 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
12385 insert @code{(adapt t)} in the score files of the groups where you want
12389 All adaptive score entries will go to the file named by this entry. It
12390 will also be applied when entering the group. This atom might be handy
12391 if you want to adapt on several groups at once, using the same adaptive
12392 file for a number of groups.
12395 @cindex local variables
12396 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
12397 Each @var{var} will be made buffer-local to the current summary buffer,
12398 and set to the value specified. This is a convenient, if somewhat
12399 strange, way of setting variables in some groups if you don't like hooks
12400 much. Note that the @var{value} won't be evaluated.
12404 @node Score File Editing
12405 @section Score File Editing
12407 You normally enter all scoring commands from the summary buffer, but you
12408 might feel the urge to edit them by hand as well, so we've supplied you
12409 with a mode for that.
12411 It's simply a slightly customized @code{emacs-lisp} mode, with these
12412 additional commands:
12417 @kindex C-c C-c (Score)
12418 @findex gnus-score-edit-done
12419 Save the changes you have made and return to the summary buffer
12420 (@code{gnus-score-edit-done}).
12423 @kindex C-c C-d (Score)
12424 @findex gnus-score-edit-insert-date
12425 Insert the current date in numerical format
12426 (@code{gnus-score-edit-insert-date}). This is really the day number, if
12427 you were wondering.
12430 @kindex C-c C-p (Score)
12431 @findex gnus-score-pretty-print
12432 The adaptive score files are saved in an unformatted fashion. If you
12433 intend to read one of these files, you want to @dfn{pretty print} it
12434 first. This command (@code{gnus-score-pretty-print}) does that for
12439 Type @kbd{M-x gnus-score-mode} to use this mode.
12441 @vindex gnus-score-mode-hook
12442 @code{gnus-score-menu-hook} is run in score mode buffers.
12444 In the summary buffer you can use commands like @kbd{V f} and @kbd{V
12445 e} to begin editing score files.
12448 @node Adaptive Scoring
12449 @section Adaptive Scoring
12450 @cindex adaptive scoring
12452 If all this scoring is getting you down, Gnus has a way of making it all
12453 happen automatically---as if by magic. Or rather, as if by artificial
12454 stupidity, to be precise.
12456 @vindex gnus-use-adaptive-scoring
12457 When you read an article, or mark an article as read, or kill an
12458 article, you leave marks behind. On exit from the group, Gnus can sniff
12459 these marks and add score elements depending on what marks it finds.
12460 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
12461 @code{t} or @code{(line)}. If you want score adaptively on separate
12462 words appearing in the subjects, you should set this variable to
12463 @code{(word)}. If you want to use both adaptive methods, set this
12464 variable to @code{(word line)}.
12466 @vindex gnus-default-adaptive-score-alist
12467 To give you complete control over the scoring process, you can customize
12468 the @code{gnus-default-adaptive-score-alist} variable. For instance, it
12469 might look something like this:
12472 (defvar gnus-default-adaptive-score-alist
12473 '((gnus-unread-mark)
12474 (gnus-ticked-mark (from 4))
12475 (gnus-dormant-mark (from 5))
12476 (gnus-del-mark (from -4) (subject -1))
12477 (gnus-read-mark (from 4) (subject 2))
12478 (gnus-expirable-mark (from -1) (subject -1))
12479 (gnus-killed-mark (from -1) (subject -3))
12480 (gnus-kill-file-mark)
12481 (gnus-ancient-mark)
12482 (gnus-low-score-mark)
12483 (gnus-catchup-mark (from -1) (subject -1))))
12486 As you see, each element in this alist has a mark as a key (either a
12487 variable name or a ``real'' mark---a character). Following this key is
12488 a arbitrary number of header/score pairs. If there are no header/score
12489 pairs following the key, no adaptive scoring will be done on articles
12490 that have that key as the article mark. For instance, articles with
12491 @code{gnus-unread-mark} in the example above will not get adaptive score
12494 Each article can have only one mark, so just a single of these rules
12495 will be applied to each article.
12497 To take @code{gnus-del-mark} as an example---this alist says that all
12498 articles that have that mark (i.e., are marked with @samp{D}) will have a
12499 score entry added to lower based on the @code{From} header by -4, and
12500 lowered by @code{Subject} by -1. Change this to fit your prejudices.
12502 If you have marked 10 articles with the same subject with
12503 @code{gnus-del-mark}, the rule for that mark will be applied ten times.
12504 That means that that subject will get a score of ten times -1, which
12505 should be, unless I'm much mistaken, -10.
12507 If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all
12508 the read articles will be marked with the @samp{E} mark. This'll
12509 probably make adaptive scoring slightly impossible, so auto-expiring and
12510 adaptive scoring doesn't really mix very well.
12512 The headers you can score on are @code{from}, @code{subject},
12513 @code{message-id}, @code{references}, @code{xref}, @code{lines},
12514 @code{chars} and @code{date}. In addition, you can score on
12515 @code{followup}, which will create an adaptive score entry that matches
12516 on the @code{References} header using the @code{Message-ID} of the
12517 current article, thereby matching the following thread.
12519 You can also score on @code{thread}, which will try to score all
12520 articles that appear in a thread. @code{thread} matches uses a
12521 @code{Message-ID} to match on the @code{References} header of the
12522 article. If the match is made, the @code{Message-ID} of the article is
12523 added to the @code{thread} rule. (Think about it. I'd recommend two
12524 aspirins afterwards.)
12526 If you use this scheme, you should set the score file atom @code{mark}
12527 to something small---like -300, perhaps, to avoid having small random
12528 changes result in articles getting marked as read.
12530 After using adaptive scoring for a week or so, Gnus should start to
12531 become properly trained and enhance the authors you like best, and kill
12532 the authors you like least, without you having to say so explicitly.
12534 You can control what groups the adaptive scoring is to be performed on
12535 by using the score files (@pxref{Score File Format}). This will also
12536 let you use different rules in different groups.
12538 @vindex gnus-adaptive-file-suffix
12539 The adaptive score entries will be put into a file where the name is the
12540 group name with @code{gnus-adaptive-file-suffix} appended. The default
12543 @vindex gnus-score-exact-adapt-limit
12544 When doing adaptive scoring, substring or fuzzy matching would probably
12545 give you the best results in most cases. However, if the header one
12546 matches is short, the possibility for false positives is great, so if
12547 the length of the match is less than
12548 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
12549 this variable is @code{nil}, exact matching will always be used to avoid
12552 @vindex gnus-default-adaptive-word-score-alist
12553 As mentioned above, you can adapt either on individual words or entire
12554 headers. If you adapt on words, the
12555 @code{gnus-default-adaptive-word-score-alist} variable says what score
12556 each instance of a word should add given a mark.
12559 (setq gnus-default-adaptive-word-score-alist
12560 `((,gnus-read-mark . 30)
12561 (,gnus-catchup-mark . -10)
12562 (,gnus-killed-mark . -20)
12563 (,gnus-del-mark . -15)))
12566 This is the default value. If you have adaption on words enabled, every
12567 word that appears in subjects of articles marked with
12568 @code{gnus-read-mark} will result in a score rule that increase the
12569 score with 30 points.
12571 @vindex gnus-default-ignored-adaptive-words
12572 @vindex gnus-ignored-adaptive-words
12573 Words that appear in the @code{gnus-default-ignored-adaptive-words} list
12574 will be ignored. If you wish to add more words to be ignored, use the
12575 @code{gnus-ignored-adaptive-words} list instead.
12577 @vindex gnus-adaptive-word-syntax-table
12578 When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the
12579 syntax table in effect. It is similar to the standard syntax table, but
12580 it considers numbers to be non-word-constituent characters.
12582 @vindex gnus-adaptive-word-minimum
12583 If @code{gnus-adaptive-word-minimum} is set to a number, the adaptive
12584 word scoring process will never bring down the score of an article to
12585 below this number. The default is @code{nil}.
12587 After using this scheme for a while, it might be nice to write a
12588 @code{gnus-psychoanalyze-user} command to go through the rules and see
12589 what words you like and what words you don't like. Or perhaps not.
12591 Note that the adaptive word scoring thing is highly experimental and is
12592 likely to change in the future. Initial impressions seem to indicate
12593 that it's totally useless as it stands. Some more work (involving more
12594 rigorous statistical methods) will have to be done to make this useful.
12597 @node Home Score File
12598 @section Home Score File
12600 The score file where new score file entries will go is called the
12601 @dfn{home score file}. This is normally (and by default) the score file
12602 for the group itself. For instance, the home score file for
12603 @samp{gnu.emacs.gnus} is @file{gnu.emacs.gnus.SCORE}.
12605 However, this may not be what you want. It is often convenient to share
12606 a common home score file among many groups---all @samp{emacs} groups
12607 could perhaps use the same home score file.
12609 @vindex gnus-home-score-file
12610 The variable that controls this is @code{gnus-home-score-file}. It can
12615 A string. Then this file will be used as the home score file for all
12619 A function. The result of this function will be used as the home score
12620 file. The function will be called with the name of the group as the
12624 A list. The elements in this list can be:
12628 @var{(regexp file-name)}. If the @var{regexp} matches the group name,
12629 the @var{file-name} will will be used as the home score file.
12632 A function. If the function returns non-nil, the result will be used as
12633 the home score file.
12636 A string. Use the string as the home score file.
12639 The list will be traversed from the beginning towards the end looking
12644 So, if you want to use just a single score file, you could say:
12647 (setq gnus-home-score-file
12648 "my-total-score-file.SCORE")
12651 If you want to use @file{gnu.SCORE} for all @samp{gnu} groups and
12652 @file{rec.SCORE} for all @samp{rec} groups (and so on), you can say:
12655 (setq gnus-home-score-file
12656 'gnus-hierarchial-home-score-file)
12659 This is a ready-made function provided for your convenience.
12661 If you want to have one score file for the @samp{emacs} groups and
12662 another for the @samp{comp} groups, while letting all other groups use
12663 their own home score files:
12666 (setq gnus-home-score-file
12667 ;; All groups that match the regexp "\\.emacs"
12668 '("\\.emacs" "emacs.SCORE")
12669 ;; All the comp groups in one score file
12670 ("^comp" "comp.SCORE"))
12673 @vindex gnus-home-adapt-file
12674 @code{gnus-home-adapt-file} works exactly the same way as
12675 @code{gnus-home-score-file}, but says what the home adaptive score file
12676 is instead. All new adaptive file entries will go into the file
12677 specified by this variable, and the same syntax is allowed.
12679 In addition to using @code{gnus-home-score-file} and
12680 @code{gnus-home-adapt-file}, you can also use group parameters
12681 (@pxref{Group Parameters}) and topic parameters (@pxref{Topic
12682 Parameters}) to achieve much the same. Group and topic parameters take
12683 precedence over this variable.
12686 @node Followups To Yourself
12687 @section Followups To Yourself
12689 Gnus offers two commands for picking out the @code{Message-ID} header in
12690 the current buffer. Gnus will then add a score rule that scores using
12691 this @code{Message-ID} on the @code{References} header of other
12692 articles. This will, in effect, increase the score of all articles that
12693 respond to the article in the current buffer. Quite useful if you want
12694 to easily note when people answer what you've said.
12698 @item gnus-score-followup-article
12699 @findex gnus-score-followup-article
12700 This will add a score to articles that directly follow up your own
12703 @item gnus-score-followup-thread
12704 @findex gnus-score-followup-thread
12705 This will add a score to all articles that appear in a thread ``below''
12709 @vindex message-sent-hook
12710 These two functions are both primarily meant to be used in hooks like
12711 @code{message-sent-hook}.
12713 If you look closely at your own @code{Message-ID}, you'll notice that
12714 the first two or three characters are always the same. Here's two of
12718 <x6u3u47icf.fsf@@eyesore.no>
12719 <x6sp9o7ibw.fsf@@eyesore.no>
12722 So ``my'' ident on this machine is @samp{x6}. This can be
12723 exploited---the following rule will raise the score on all followups to
12728 ("<x6[0-9a-z]+\\.fsf\\(_-_\\)?@@.*eyesore.no>"
12732 Whether it's the first two or first three characters that are ``yours''
12733 is system-dependent.
12737 @section Scoring Tips
12738 @cindex scoring tips
12744 @cindex scoring crossposts
12745 If you want to lower the score of crossposts, the line to match on is
12746 the @code{Xref} header.
12748 ("xref" (" talk.politics.misc:" -1000))
12751 @item Multiple crossposts
12752 If you want to lower the score of articles that have been crossposted to
12753 more than, say, 3 groups:
12755 ("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
12758 @item Matching on the body
12759 This is generally not a very good idea---it takes a very long time.
12760 Gnus actually has to fetch each individual article from the server. But
12761 you might want to anyway, I guess. Even though there are three match
12762 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
12763 and stick with it in each score file. If you use any two, each article
12764 will be fetched @emph{twice}. If you want to match a bit on the
12765 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
12768 @item Marking as read
12769 You will probably want to mark articles that has a score below a certain
12770 number as read. This is most easily achieved by putting the following
12771 in your @file{all.SCORE} file:
12775 You may also consider doing something similar with @code{expunge}.
12777 @item Negated character classes
12778 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
12779 That will match newlines, which might lead to, well, The Unknown. Say
12780 @code{[^abcd\n]*} instead.
12784 @node Reverse Scoring
12785 @section Reverse Scoring
12786 @cindex reverse scoring
12788 If you want to keep just articles that have @samp{Sex with Emacs} in the
12789 subject header, and expunge all other articles, you could put something
12790 like this in your score file:
12794 ("Sex with Emacs" 2))
12799 So, you raise all articles that match @samp{Sex with Emacs} and mark the
12800 rest as read, and expunge them to boot.
12803 @node Global Score Files
12804 @section Global Score Files
12805 @cindex global score files
12807 Sure, other newsreaders have ``global kill files''. These are usually
12808 nothing more than a single kill file that applies to all groups, stored
12809 in the user's home directory. Bah! Puny, weak newsreaders!
12811 What I'm talking about here are Global Score Files. Score files from
12812 all over the world, from users everywhere, uniting all nations in one
12813 big, happy score file union! Ange-score! New and untested!
12815 @vindex gnus-global-score-files
12816 All you have to do to use other people's score files is to set the
12817 @code{gnus-global-score-files} variable. One entry for each score file,
12818 or each score file directory. Gnus will decide by itself what score
12819 files are applicable to which group.
12821 Say you want to use the score file
12822 @file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and
12823 all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory:
12826 (setq gnus-global-score-files
12827 '("/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE"
12828 "/ftp@@ftp.some-where:/pub/score/"))
12831 @findex gnus-score-search-global-directories
12832 Simple, eh? Directory names must end with a @samp{/}. These
12833 directories are typically scanned only once during each Gnus session.
12834 If you feel the need to manually re-scan the remote directories, you can
12835 use the @code{gnus-score-search-global-directories} command.
12837 Note that, at present, using this option will slow down group entry
12838 somewhat. (That is---a lot.)
12840 If you want to start maintaining score files for other people to use,
12841 just put your score file up for anonymous ftp and announce it to the
12842 world. Become a retro-moderator! Participate in the retro-moderator
12843 wars sure to ensue, where retro-moderators battle it out for the
12844 sympathy of the people, luring them to use their score files on false
12845 premises! Yay! The net is saved!
12847 Here are some tips for the would-be retro-moderator, off the top of my
12853 Articles heavily crossposted are probably junk.
12855 To lower a single inappropriate article, lower by @code{Message-ID}.
12857 Particularly brilliant authors can be raised on a permanent basis.
12859 Authors that repeatedly post off-charter for the group can safely be
12860 lowered out of existence.
12862 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
12863 articles completely.
12866 Use expiring score entries to keep the size of the file down. You
12867 should probably have a long expiry period, though, as some sites keep
12868 old articles for a long time.
12871 ... I wonder whether other newsreaders will support global score files
12872 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
12873 Wave, xrn and 1stReader are bound to implement scoring. Should we start
12874 holding our breath yet?
12878 @section Kill Files
12881 Gnus still supports those pesky old kill files. In fact, the kill file
12882 entries can now be expiring, which is something I wrote before Daniel
12883 Quinlan thought of doing score files, so I've left the code in there.
12885 In short, kill processing is a lot slower (and I do mean @emph{a lot})
12886 than score processing, so it might be a good idea to rewrite your kill
12887 files into score files.
12889 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
12890 forms into this file, which means that you can use kill files as some
12891 sort of primitive hook function to be run on group entry, even though
12892 that isn't a very good idea.
12894 Normal kill files look like this:
12897 (gnus-kill "From" "Lars Ingebrigtsen")
12898 (gnus-kill "Subject" "ding")
12902 This will mark every article written by me as read, and remove the
12903 marked articles from the summary buffer. Very useful, you'll agree.
12905 Other programs use a totally different kill file syntax. If Gnus
12906 encounters what looks like a @code{rn} kill file, it will take a stab at
12909 Two summary functions for editing a GNUS kill file:
12914 @kindex M-k (Summary)
12915 @findex gnus-summary-edit-local-kill
12916 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
12919 @kindex M-K (Summary)
12920 @findex gnus-summary-edit-global-kill
12921 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
12924 Two group mode functions for editing the kill files:
12929 @kindex M-k (Group)
12930 @findex gnus-group-edit-local-kill
12931 Edit this group's kill file (@code{gnus-group-edit-local-kill}).
12934 @kindex M-K (Group)
12935 @findex gnus-group-edit-global-kill
12936 Edit the general kill file (@code{gnus-group-edit-global-kill}).
12939 Kill file variables:
12942 @item gnus-kill-file-name
12943 @vindex gnus-kill-file-name
12944 A kill file for the group @samp{soc.motss} is normally called
12945 @file{soc.motss.KILL}. The suffix appended to the group name to get
12946 this file name is detailed by the @code{gnus-kill-file-name} variable.
12947 The ``global'' kill file (not in the score file sense of ``global'', of
12948 course) is just called @file{KILL}.
12950 @vindex gnus-kill-save-kill-file
12951 @item gnus-kill-save-kill-file
12952 If this variable is non-@code{nil}, Gnus will save the
12953 kill file after processing, which is necessary if you use expiring
12956 @item gnus-apply-kill-hook
12957 @vindex gnus-apply-kill-hook
12958 @findex gnus-apply-kill-file-unless-scored
12959 @findex gnus-apply-kill-file
12960 A hook called to apply kill files to a group. It is
12961 @code{(gnus-apply-kill-file)} by default. If you want to ignore the
12962 kill file if you have a score file for the same group, you can set this
12963 hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want
12964 kill files to be processed, you should set this variable to @code{nil}.
12966 @item gnus-kill-file-mode-hook
12967 @vindex gnus-kill-file-mode-hook
12968 A hook called in kill-file mode buffers.
12973 @node Converting Kill Files
12974 @section Converting Kill Files
12976 @cindex converting kill files
12978 If you have loads of old kill files, you may want to convert them into
12979 score files. If they are ``regular'', you can use
12980 the @file{gnus-kill-to-score.el} package; if not, you'll have to do it
12983 The kill to score conversion package isn't included in Gnus by default.
12984 You can fetch it from
12985 @file{http://www.ifi.uio.no/~larsi/ding-other/gnus-kill-to-score}.
12987 If your old kill files are very complex---if they contain more
12988 non-@code{gnus-kill} forms than not, you'll have to convert them by
12989 hand. Or just let them be as they are. Gnus will still use them as
12997 GroupLens is a collaborative filtering system that helps you work
12998 together with other people to find the quality news articles out of the
12999 huge volume of news articles generated every day.
13001 To accomplish this the GroupLens system combines your opinions about
13002 articles you have already read with the opinions of others who have done
13003 likewise and gives you a personalized prediction for each unread news
13004 article. Think of GroupLens as a matchmaker. GroupLens watches how you
13005 rate articles, and finds other people that rate articles the same way.
13006 Once it has found some people you agree with it tells you, in the form
13007 of a prediction, what they thought of the article. You can use this
13008 prediction to help you decide whether or not you want to read the
13012 * Using GroupLens:: How to make Gnus use GroupLens.
13013 * Rating Articles:: Letting GroupLens know how you rate articles.
13014 * Displaying Predictions:: Displaying predictions given by GroupLens.
13015 * GroupLens Variables:: Customizing GroupLens.
13019 @node Using GroupLens
13020 @subsection Using GroupLens
13022 To use GroupLens you must register a pseudonym with your local Better
13024 @samp{http://www.cs.umn.edu/Research/GroupLens/bbb.html} is the only
13025 better bit in town at the moment.
13027 Once you have registered you'll need to set a couple of variables.
13031 @item gnus-use-grouplens
13032 @vindex gnus-use-grouplens
13033 Setting this variable to a non-@code{nil} value will make Gnus hook into
13034 all the relevant GroupLens functions.
13036 @item grouplens-pseudonym
13037 @vindex grouplens-pseudonym
13038 This variable should be set to the pseudonym you got when registering
13039 with the Better Bit Bureau.
13041 @item grouplens-newsgroups
13042 @vindex grouplens-newsgroups
13043 A list of groups that you want to get GroupLens predictions for.
13047 That's the minimum of what you need to get up and running with GroupLens.
13048 Once you've registered, GroupLens will start giving you scores for
13049 articles based on the average of what other people think. But, to get
13050 the real benefit of GroupLens you need to start rating articles
13051 yourself. Then the scores GroupLens gives you will be personalized for
13052 you, based on how the people you usually agree with have already rated.
13055 @node Rating Articles
13056 @subsection Rating Articles
13058 In GroupLens, an article is rated on a scale from 1 to 5, inclusive.
13059 Where 1 means something like this article is a waste of bandwidth and 5
13060 means that the article was really good. The basic question to ask
13061 yourself is, "on a scale from 1 to 5 would I like to see more articles
13064 There are four ways to enter a rating for an article in GroupLens.
13069 @kindex r (GroupLens)
13070 @findex bbb-summary-rate-article
13071 This function will prompt you for a rating on a scale of one to five.
13074 @kindex k (GroupLens)
13075 @findex grouplens-score-thread
13076 This function will prompt you for a rating, and rate all the articles in
13077 the thread. This is really useful for some of those long running giant
13078 threads in rec.humor.
13082 The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be
13083 the score of the article you're reading.
13088 @kindex n (GroupLens)
13089 @findex grouplens-next-unread-article
13090 Rate the article and go to the next unread article.
13093 @kindex , (GroupLens)
13094 @findex grouplens-best-unread-article
13095 Rate the article and go to the next unread article with the highest score.
13099 If you want to give the current article a score of 4 and then go to the
13100 next article, just type @kbd{4 n}.
13103 @node Displaying Predictions
13104 @subsection Displaying Predictions
13106 GroupLens makes a prediction for you about how much you will like a
13107 news article. The predictions from GroupLens are on a scale from 1 to
13108 5, where 1 is the worst and 5 is the best. You can use the predictions
13109 from GroupLens in one of three ways controlled by the variable
13110 @code{gnus-grouplens-override-scoring}.
13112 @vindex gnus-grouplens-override-scoring
13113 There are three ways to display predictions in grouplens. You may
13114 choose to have the GroupLens scores contribute to, or override the
13115 regular gnus scoring mechanism. override is the default; however, some
13116 people prefer to see the Gnus scores plus the grouplens scores. To get
13117 the separate scoring behavior you need to set
13118 @code{gnus-grouplens-override-scoring} to @code{'separate}. To have the
13119 GroupLens predictions combined with the grouplens scores set it to
13120 @code{'override} and to combine the scores set
13121 @code{gnus-grouplens-override-scoring} to @code{'combine}. When you use
13122 the combine option you will also want to set the values for
13123 @code{grouplens-prediction-offset} and
13124 @code{grouplens-score-scale-factor}.
13126 @vindex grouplens-prediction-display
13127 In either case, GroupLens gives you a few choices for how you would like
13128 to see your predictions displayed. The display of predictions is
13129 controlled by the @code{grouplens-prediction-display} variable.
13131 The following are valid values for that variable.
13134 @item prediction-spot
13135 The higher the prediction, the further to the right an @samp{*} is
13138 @item confidence-interval
13139 A numeric confidence interval.
13141 @item prediction-bar
13142 The higher the prediction, the longer the bar.
13144 @item confidence-bar
13145 Numerical confidence.
13147 @item confidence-spot
13148 The spot gets bigger with more confidence.
13150 @item prediction-num
13151 Plain-old numeric value.
13153 @item confidence-plus-minus
13154 Prediction +/- confidence.
13159 @node GroupLens Variables
13160 @subsection GroupLens Variables
13164 @item gnus-summary-grouplens-line-format
13165 The summary line format used in GroupLens-enhanced summary buffers. It
13166 accepts the same specs as the normal summary line format (@pxref{Summary
13167 Buffer Lines}). The default is @samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%)
13170 @item grouplens-bbb-host
13171 Host running the bbbd server. @samp{grouplens.cs.umn.edu} is the
13174 @item grouplens-bbb-port
13175 Port of the host running the bbbd server. The default is 9000.
13177 @item grouplens-score-offset
13178 Offset the prediction by this value. In other words, subtract the
13179 prediction value by this number to arrive at the effective score. The
13182 @item grouplens-score-scale-factor
13183 This variable allows the user to magnify the effect of GroupLens scores.
13184 The scale factor is applied after the offset. The default is 1.
13189 @node Advanced Scoring
13190 @section Advanced Scoring
13192 Scoring on Subjects and From headers is nice enough, but what if you're
13193 really interested in what a person has to say only when she's talking
13194 about a particular subject? Or what if you really don't want to
13195 read what person A has to say when she's following up to person B, but
13196 want to read what she says when she's following up to person C?
13198 By using advanced scoring rules you may create arbitrarily complex
13202 * Advanced Scoring Syntax:: A definition.
13203 * Advanced Scoring Examples:: What they look like.
13204 * Advanced Scoring Tips:: Getting the most out of it.
13208 @node Advanced Scoring Syntax
13209 @subsection Advanced Scoring Syntax
13211 Ordinary scoring rules have a string as the first element in the rule.
13212 Advanced scoring rules have a list as the first element. The second
13213 element is the score to be applied if the first element evaluated to a
13214 non-@code{nil} value.
13216 These lists may consist of three logical operators, one redirection
13217 operator, and various match operators.
13224 This logical operator will evaluate each of its arguments until it finds
13225 one that evaluates to @code{false}, and then it'll stop. If all arguments
13226 evaluate to @code{true} values, then this operator will return
13231 This logical operator will evaluate each of its arguments until it finds
13232 one that evaluates to @code{true}. If no arguments are @code{true},
13233 then this operator will return @code{false}.
13238 This logical operator only takes a single argument. It returns the
13239 logical negation of the value of its argument.
13243 There is an @dfn{indirection operator} that will make its arguments
13244 apply to the ancestors of the current article being scored. For
13245 instance, @code{1-} will make score rules apply to the parent of the
13246 current article. @code{2-} will make score rules apply to the
13247 grandparent of the current article. Alternatively, you can write
13248 @code{^^}, where the number of @code{^}s (carets) says how far back into
13249 the ancestry you want to go.
13251 Finally, we have the match operators. These are the ones that do the
13252 real work. Match operators are header name strings followed by a match
13253 and a match type. A typical match operator looks like @samp{("from"
13254 "Lars Ingebrigtsen" s)}. The header names are the same as when using
13255 simple scoring, and the match types are also the same.
13258 @node Advanced Scoring Examples
13259 @subsection Advanced Scoring Examples
13261 Let's say you want to increase the score of articles written by Lars
13262 when he's talking about Gnus:
13266 ("from" "Lars Ingebrigtsen")
13267 ("subject" "Gnus"))
13273 When he writes long articles, he sometimes has something nice to say:
13277 ("from" "Lars Ingebrigtsen")
13284 However, when he responds to things written by Reig Eigil Logge, you
13285 really don't want to read what he's written:
13289 ("from" "Lars Ingebrigtsen")
13290 (1- ("from" "Reig Eigir Logge")))
13294 Everybody that follows up Redmondo when he writes about disappearing
13295 socks should have their scores raised, but only when they talk about
13296 white socks. However, when Lars talks about socks, it's usually not
13303 ("from" "redmondo@@.*no" r)
13304 ("body" "disappearing.*socks" t)))
13305 (! ("from" "Lars Ingebrigtsen"))
13306 ("body" "white.*socks"))
13310 The possibilities are endless.
13313 @node Advanced Scoring Tips
13314 @subsection Advanced Scoring Tips
13316 The @code{&} and @code{|} logical operators do short-circuit logic.
13317 That is, they stop processing their arguments when it's clear what the
13318 result of the operation will be. For instance, if one of the arguments
13319 of an @code{&} evaluates to @code{false}, there's no point in evaluating
13320 the rest of the arguments. This means that you should put slow matches
13321 (@samp{body}, @samp{header}) last and quick matches (@samp{from},
13322 @samp{subject}) first.
13324 The indirection arguments (@code{1-} and so on) will make their
13325 arguments work on previous generations of the thread. If you say
13336 Then that means "score on the from header of the grandparent of the
13337 current article". An indirection is quite fast, but it's better to say:
13343 ("subject" "Gnus")))
13350 (1- ("from" "Lars"))
13351 (1- ("subject" "Gnus")))
13356 @section Score Decays
13357 @cindex score decays
13360 You may find that your scores have a tendency to grow without
13361 bounds, especially if you're using adaptive scoring. If scores get too
13362 big, they lose all meaning---they simply max out and it's difficult to
13363 use them in any sensible way.
13365 @vindex gnus-decay-scores
13366 @findex gnus-decay-score
13367 @vindex gnus-score-decay-function
13368 Gnus provides a mechanism for decaying scores to help with this problem.
13369 When score files are loaded and @code{gnus-decay-scores} is
13370 non-@code{nil}, Gnus will run the score files through the decaying
13371 mechanism thereby lowering the scores of all non-permanent score rules.
13372 The decay itself if performed by the @code{gnus-score-decay-function}
13373 function, which is @code{gnus-decay-score} by default. Here's the
13374 definition of that function:
13377 (defun gnus-decay-score (score)
13378 "Decay SCORE according to `gnus-score-decay-constant' and `gnus-score-decay-scale'."
13381 (* (if (< score 0) 1 -1)
13383 (max gnus-score-decay-constant
13385 gnus-score-decay-scale)))))))
13388 @vindex gnus-score-decay-scale
13389 @vindex gnus-score-decay-constant
13390 @code{gnus-score-decay-constant} is 3 by default and
13391 @code{gnus-score-decay-scale} is 0.05. This should cause the following:
13395 Scores between -3 and 3 will be set to 0 when this function is called.
13398 Scores with magnitudes between 3 and 60 will be shrunk by 3.
13401 Scores with magnitudes greater than 60 will be shrunk by 5% of the
13405 If you don't like this decay function, write your own. It is called
13406 with the score to be decayed as its only parameter, and it should return
13407 the new score, which should be an integer.
13409 Gnus will try to decay scores once a day. If you haven't run Gnus for
13410 four days, Gnus will decay the scores four times, for instance.
13417 * Process/Prefix:: A convention used by many treatment commands.
13418 * Interactive:: Making Gnus ask you many questions.
13419 * Symbolic Prefixes:: How to supply some Gnus functions with options.
13420 * Formatting Variables:: You can specify what buffers should look like.
13421 * Windows Configuration:: Configuring the Gnus buffer windows.
13422 * Faces and Fonts:: How to change how faces look.
13423 * Compilation:: How to speed Gnus up.
13424 * Mode Lines:: Displaying information in the mode lines.
13425 * Highlighting and Menus:: Making buffers look all nice and cozy.
13426 * Buttons:: Get tendonitis in ten easy steps!
13427 * Daemons:: Gnus can do things behind your back.
13428 * NoCeM:: How to avoid spam and other fatty foods.
13429 * Undo:: Some actions can be undone.
13430 * Moderation:: What to do if you're a moderator.
13431 * XEmacs Enhancements:: There are more pictures and stuff under XEmacs.
13432 * Fuzzy Matching:: What's the big fuzz?
13433 * Thwarting Email Spam:: A how-to on avoiding unsolited commercial email.
13434 * Various Various:: Things that are really various.
13438 @node Process/Prefix
13439 @section Process/Prefix
13440 @cindex process/prefix convention
13442 Many functions, among them functions for moving, decoding and saving
13443 articles, use what is known as the @dfn{Process/Prefix convention}.
13445 This is a method for figuring out what articles the user wants the
13446 command to be performed on.
13450 If the numeric prefix is N, perform the operation on the next N
13451 articles, starting with the current one. If the numeric prefix is
13452 negative, perform the operation on the previous N articles, starting
13453 with the current one.
13455 @vindex transient-mark-mode
13456 If @code{transient-mark-mode} in non-@code{nil} and the region is
13457 active, all articles in the region will be worked upon.
13459 If there is no numeric prefix, but some articles are marked with the
13460 process mark, perform the operation on the articles marked with
13463 If there is neither a numeric prefix nor any articles marked with the
13464 process mark, just perform the operation on the current article.
13466 Quite simple, really, but it needs to be made clear so that surprises
13469 Commands that react to the process mark will push the current list of
13470 process marked articles onto a stack and will then clear all process
13471 marked articles. You can restore the previous configuration with the
13472 @kbd{M P y} command (@pxref{Setting Process Marks}).
13474 @vindex gnus-summary-goto-unread
13475 One thing that seems to shock & horrify lots of people is that, for
13476 instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
13477 Since each @kbd{d} (which marks the current article as read) by default
13478 goes to the next unread article after marking, this means that @kbd{3 d}
13479 will mark the next three unread articles as read, no matter what the
13480 summary buffer looks like. Set @code{gnus-summary-goto-unread} to
13481 @code{nil} for a more straightforward action.
13485 @section Interactive
13486 @cindex interaction
13490 @item gnus-novice-user
13491 @vindex gnus-novice-user
13492 If this variable is non-@code{nil}, you are either a newcomer to the
13493 World of Usenet, or you are very cautious, which is a nice thing to be,
13494 really. You will be given questions of the type ``Are you sure you want
13495 to do this?'' before doing anything dangerous. This is @code{t} by
13498 @item gnus-expert-user
13499 @vindex gnus-expert-user
13500 If this variable is non-@code{nil}, you will seldom be asked any
13501 questions by Gnus. It will simply assume you know what you're doing, no
13502 matter how strange.
13504 @item gnus-interactive-catchup
13505 @vindex gnus-interactive-catchup
13506 Require confirmation before catching up a group if non-@code{nil}. It
13507 is @code{t} by default.
13509 @item gnus-interactive-exit
13510 @vindex gnus-interactive-exit
13511 Require confirmation before exiting Gnus. This variable is @code{t} by
13516 @node Symbolic Prefixes
13517 @section Symbolic Prefixes
13518 @cindex symbolic prefixes
13520 Quite a lot of Emacs commands react to the (numeric) prefix. For
13521 instance, @kbd{C-u 4 C-f} moves point four charaters forward, and
13522 @kbd{C-u 9 0 0 I s s p} adds a permanent @code{Subject} substring score
13523 rule of 900 to the current article.
13525 This is all nice and well, but what if you want to give a command some
13526 additional information? Well, what most commands do is interpret the
13527 ``raw'' prefix in some special way. @kbd{C-u 0 C-x C-s} means that one
13528 doesn't want a backup file to be created when saving the current buffer,
13529 for instance. But what if you want to save without making a backup
13530 file, and you want Emacs to flash lights and play a nice tune at the
13531 same time? You can't, and you're probably perfectly happy that way.
13533 @kindex M-i (Summary)
13534 @findex gnus-symbolic-argument
13535 I'm not, so I've added a second prefix---the @dfn{symbolic prefix}. The
13536 prefix key is @kbd{M-i} (@code{gnus-symbolic-argument}), and the next
13537 character typed in is the value. You can stack as many @kbd{M-i}
13538 prefixes as you want. @kbd{M-i a M-C-u} means ``feed the @kbd{M-C-u}
13539 command the symbolic prefix @code{a}''. @kbd{M-i a M-i b M-C-u} means
13540 ``feed the @kbd{M-C-u} command the symbolic prefixes @code{a} and
13541 @code{b}''. You get the drift.
13543 Typing in symbolic prefixes to commands that don't accept them doesn't
13544 hurt, but it doesn't do any good either. Currently not many Gnus
13545 functions make use of the symbolic prefix.
13547 If you're interested in how Gnus implements this, @pxref{Extended
13551 @node Formatting Variables
13552 @section Formatting Variables
13553 @cindex formatting variables
13555 Throughout this manual you've probably noticed lots of variables called things like @code{gnus-group-line-format} and
13556 @code{gnus-summary-mode-line-format}. These control how Gnus is to
13557 output lines in the various buffers. There's quite a lot of them.
13558 Fortunately, they all use the same syntax, so there's not that much to
13561 Here's an example format spec (from the group buffer): @samp{%M%S%5y:
13562 %(%g%)\n}. We see that it is indeed extremely ugly, and that there are
13563 lots of percentages everywhere.
13566 * Formatting Basics:: A formatting variable is basically a format string.
13567 * Advanced Formatting:: Modifying output in various ways.
13568 * User-Defined Specs:: Having Gnus call your own functions.
13569 * Formatting Fonts:: Making the formatting look colorful and nice.
13572 Currently Gnus uses the following formatting variables:
13573 @code{gnus-group-line-format}, @code{gnus-summary-line-format},
13574 @code{gnus-server-line-format}, @code{gnus-topic-line-format},
13575 @code{gnus-group-mode-line-format},
13576 @code{gnus-summary-mode-line-format},
13577 @code{gnus-article-mode-line-format},
13578 @code{gnus-server-mode-line-format}, and
13579 @code{gnus-summary-pick-line-format}.
13581 All these format variables can also be arbitrary elisp forms. In that
13582 case, they will be @code{eval}ed to insert the required lines.
13584 @kindex M-x gnus-update-format
13585 @findex gnus-update-format
13586 Gnus includes a command to help you while creating your own format
13587 specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
13588 update the spec in question and pop you to a buffer where you can
13589 examine the resulting lisp code to be run to generate the line.
13593 @node Formatting Basics
13594 @subsection Formatting Basics
13596 Each @samp{%} element will be replaced by some string or other when the
13597 buffer in question is generated. @samp{%5y} means ``insert the @samp{y}
13598 spec, and pad with spaces to get a 5-character field''.
13600 As with normal C and Emacs Lisp formatting strings, the numerical
13601 modifier between the @samp{%} and the formatting type character will
13602 @dfn{pad} the output so that it is always at least that long.
13603 @samp{%5y} will make the field always (at least) five characters wide by
13604 padding with spaces to the left. If you say @samp{%-5y}, it will pad to
13607 You may also wish to limit the length of the field to protect against
13608 particularly wide values. For that you can say @samp{%4,6y}, which
13609 means that the field will never be more than 6 characters wide and never
13610 less than 4 characters wide.
13613 @node Advanced Formatting
13614 @subsection Advanced Formatting
13616 It is frequently useful to post-process the fields in some way.
13617 Padding, limiting, cutting off parts and suppressing certain values can
13618 be achieved by using @dfn{tilde modifiers}. A typical tilde spec might
13619 look like @samp{%~(cut 3)~(ignore "0")y}.
13621 These are the valid modifiers:
13626 Pad the field to the left with spaces until it reaches the required
13630 Pad the field to the right with spaces until it reaches the required
13635 Cut off characters from the left until it reaches the specified length.
13638 Cut off characters from the right until it reaches the specified
13643 Cut off the specified number of characters from the left.
13646 Cut off the specified number of characters from the right.
13649 Return an empty string if the field is equal to the specified value.
13652 Use the specified form as the field value when the @samp{@@} spec is
13656 Let's take an example. The @samp{%o} spec in the summary mode lines
13657 will return a date in compact ISO8601 format---@samp{19960809T230410}.
13658 This is quite a mouthful, so we want to shave off the century number and
13659 the time, leaving us with a six-character date. That would be
13660 @samp{%~(cut-left 2)~(max-right 6)~(pad 6)o}. (Cutting is done before
13661 maxing, and we need the padding to ensure that the date is never less
13662 than 6 characters to make it look nice in columns.)
13664 Ignoring is done first; then cutting; then maxing; and then as the very
13665 last operation, padding.
13667 If you use lots of these advanced thingies, you'll find that Gnus gets
13668 quite slow. This can be helped enormously by running @kbd{M-x
13669 gnus-compile} when you are satisfied with the look of your lines.
13670 @xref{Compilation}.
13673 @node User-Defined Specs
13674 @subsection User-Defined Specs
13676 All the specs allow for inserting user defined specifiers---@samp{u}.
13677 The next character in the format string should be a letter. Gnus
13678 will call the function @code{gnus-user-format-function-}@samp{X}, where
13679 @samp{X} is the letter following @samp{%u}. The function will be passed
13680 a single parameter---what the parameter means depends on what buffer
13681 it's being called from. The function should return a string, which will
13682 be inserted into the buffer just like information from any other
13683 specifier. This function may also be called with dummy values, so it
13684 should protect against that.
13686 You can also use tilde modifiers (@pxref{Advanced Formatting} to achieve
13687 much the same without defining new functions. Here's an example:
13688 @samp{%~(form (count-lines (point-min) (point)))@@}. The form
13689 given here will be evaluated to yield the current line number, and then
13693 @node Formatting Fonts
13694 @subsection Formatting Fonts
13696 There are specs for highlighting, and these are shared by all the format
13697 variables. Text inside the @samp{%(} and @samp{%)} specifiers will get
13698 the special @code{mouse-face} property set, which means that it will be
13699 highlighted (with @code{gnus-mouse-face}) when you put the mouse pointer
13702 Text inside the @samp{%[} and @samp{%]} specifiers will have their
13703 normal faces set using @code{gnus-face-0}, which is @code{bold} by
13704 default. If you say @samp{%1[}, you'll get @code{gnus-face-1} instead,
13705 and so on. Create as many faces as you wish. The same goes for the
13706 @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
13707 @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
13709 Here's an alternative recipe for the group buffer:
13712 ;; Create three face types.
13713 (setq gnus-face-1 'bold)
13714 (setq gnus-face-3 'italic)
13716 ;; We want the article count to be in
13717 ;; a bold and green face. So we create
13718 ;; a new face called `my-green-bold'.
13719 (copy-face 'bold 'my-green-bold)
13721 (set-face-foreground 'my-green-bold "ForestGreen")
13722 (setq gnus-face-2 'my-green-bold)
13724 ;; Set the new & fancy format.
13725 (setq gnus-group-line-format
13726 "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
13729 I'm sure you'll be able to use this scheme to create totally unreadable
13730 and extremely vulgar displays. Have fun!
13732 Note that the @samp{%(} specs (and friends) do not make any sense on the
13733 mode-line variables.
13736 @node Windows Configuration
13737 @section Windows Configuration
13738 @cindex windows configuration
13740 No, there's nothing here about X, so be quiet.
13742 @vindex gnus-use-full-window
13743 If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
13744 other windows and occupy the entire Emacs screen by itself. It is
13745 @code{t} by default.
13747 @vindex gnus-buffer-configuration
13748 @code{gnus-buffer-configuration} describes how much space each Gnus
13749 buffer should be given. Here's an excerpt of this variable:
13752 ((group (vertical 1.0 (group 1.0 point)
13753 (if gnus-carpal (group-carpal 4))))
13754 (article (vertical 1.0 (summary 0.25 point)
13758 This is an alist. The @dfn{key} is a symbol that names some action or
13759 other. For instance, when displaying the group buffer, the window
13760 configuration function will use @code{group} as the key. A full list of
13761 possible names is listed below.
13763 The @dfn{value} (i.e., the @dfn{split}) says how much space each buffer
13764 should occupy. To take the @code{article} split as an example -
13767 (article (vertical 1.0 (summary 0.25 point)
13771 This @dfn{split} says that the summary buffer should occupy 25% of upper
13772 half of the screen, and that it is placed over the article buffer. As
13773 you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
13774 reaching for that calculator there). However, the special number
13775 @code{1.0} is used to signal that this buffer should soak up all the
13776 rest of the space available after the rest of the buffers have taken
13777 whatever they need. There should be only one buffer with the @code{1.0}
13778 size spec per split.
13780 Point will be put in the buffer that has the optional third element
13781 @code{point}. In a @code{frame} split, the last subsplit having a leaf
13782 split where the tag @code{frame-focus} is a member (i.e. is the third or
13783 fourth element in the list, depending on whether the @code{point} tag is
13784 present) gets focus.
13786 Here's a more complicated example:
13789 (article (vertical 1.0 (group 4)
13790 (summary 0.25 point)
13791 (if gnus-carpal (summary-carpal 4))
13795 If the size spec is an integer instead of a floating point number,
13796 then that number will be used to say how many lines a buffer should
13797 occupy, not a percentage.
13799 If the @dfn{split} looks like something that can be @code{eval}ed (to be
13800 precise---if the @code{car} of the split is a function or a subr), this
13801 split will be @code{eval}ed. If the result is non-@code{nil}, it will
13802 be used as a split. This means that there will be three buffers if
13803 @code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
13806 Not complicated enough for you? Well, try this on for size:
13809 (article (horizontal 1.0
13814 (summary 0.25 point)
13819 Whoops. Two buffers with the mystery 100% tag. And what's that
13820 @code{horizontal} thingie?
13822 If the first element in one of the split is @code{horizontal}, Gnus will
13823 split the window horizontally, giving you two windows side-by-side.
13824 Inside each of these strips you may carry on all you like in the normal
13825 fashion. The number following @code{horizontal} says what percentage of
13826 the screen is to be given to this strip.
13828 For each split, there @emph{must} be one element that has the 100% tag.
13829 The splitting is never accurate, and this buffer will eat any leftover
13830 lines from the splits.
13832 To be slightly more formal, here's a definition of what a valid split
13836 split = frame | horizontal | vertical | buffer | form
13837 frame = "(frame " size *split ")"
13838 horizontal = "(horizontal " size *split ")"
13839 vertical = "(vertical " size *split ")"
13840 buffer = "(" buffer-name " " size *[ "point" ] *[ "frame-focus"] ")"
13841 size = number | frame-params
13842 buffer-name = group | article | summary ...
13845 The limitations are that the @code{frame} split can only appear as the
13846 top-level split. @var{form} should be an Emacs Lisp form that should
13847 return a valid split. We see that each split is fully recursive, and
13848 may contain any number of @code{vertical} and @code{horizontal} splits.
13850 @vindex gnus-window-min-width
13851 @vindex gnus-window-min-height
13852 @cindex window height
13853 @cindex window width
13854 Finding the right sizes can be a bit complicated. No window may be less
13855 than @code{gnus-window-min-height} (default 1) characters high, and all
13856 windows must be at least @code{gnus-window-min-width} (default 1)
13857 characters wide. Gnus will try to enforce this before applying the
13858 splits. If you want to use the normal Emacs window width/height limit,
13859 you can just set these two variables to @code{nil}.
13861 If you're not familiar with Emacs terminology, @code{horizontal} and
13862 @code{vertical} splits may work the opposite way of what you'd expect.
13863 Windows inside a @code{horizontal} split are shown side-by-side, and
13864 windows within a @code{vertical} split are shown above each other.
13866 @findex gnus-configure-frame
13867 If you want to experiment with window placement, a good tip is to call
13868 @code{gnus-configure-frame} directly with a split. This is the function
13869 that does all the real work when splitting buffers. Below is a pretty
13870 nonsensical configuration with 5 windows; two for the group buffer and
13871 three for the article buffer. (I said it was nonsensical.) If you
13872 @code{eval} the statement below, you can get an idea of how that would
13873 look straight away, without going through the normal Gnus channels.
13874 Play with it until you're satisfied, and then use
13875 @code{gnus-add-configuration} to add your new creation to the buffer
13876 configuration list.
13879 (gnus-configure-frame
13883 (article 0.3 point))
13891 You might want to have several frames as well. No prob---just use the
13892 @code{frame} split:
13895 (gnus-configure-frame
13898 (summary 0.25 point frame-focus)
13900 (vertical ((height . 5) (width . 15)
13901 (user-position . t)
13902 (left . -1) (top . 1))
13907 This split will result in the familiar summary/article window
13908 configuration in the first (or ``main'') frame, while a small additional
13909 frame will be created where picons will be shown. As you can see,
13910 instead of the normal @code{1.0} top-level spec, each additional split
13911 should have a frame parameter alist as the size spec.
13912 @xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp
13913 Reference Manual}. Under XEmacs, a frame property list will be
13914 accepted, too---for instance, @code{(height 5 width 15 left -1 top 1)}
13917 Here's a list of all possible keys for
13918 @code{gnus-buffer-configuration}:
13920 @code{group}, @code{summary}, @code{article}, @code{server},
13921 @code{browse}, @code{message}, @code{pick}, @code{info},
13922 @code{summary-faq}, @code{edit-group}, @code{edit-server},
13923 @code{edit-score}, @code{post}, @code{reply}, @code{forward},
13924 @code{reply-yank}, @code{mail-bounce}, @code{draft}, @code{pipe},
13925 @code{bug}, @code{compose-bounce}, and @code{score-trace}.
13927 Note that the @code{message} key is used for both
13928 @code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If
13929 it is desirable to distinguish between the two, something like this
13933 (message (horizontal 1.0
13934 (vertical 1.0 (message 1.0 point))
13936 (if (buffer-live-p gnus-summary-buffer)
13941 @findex gnus-add-configuration
13942 Since the @code{gnus-buffer-configuration} variable is so long and
13943 complicated, there's a function you can use to ease changing the config
13944 of a single setting: @code{gnus-add-configuration}. If, for instance,
13945 you want to change the @code{article} setting, you could say:
13948 (gnus-add-configuration
13949 '(article (vertical 1.0
13951 (summary .25 point)
13955 You'd typically stick these @code{gnus-add-configuration} calls in your
13956 @file{.gnus.el} file or in some startup hook---they should be run after
13957 Gnus has been loaded.
13959 @vindex gnus-always-force-window-configuration
13960 If all windows mentioned in the configuration are already visible, Gnus
13961 won't change the window configuration. If you always want to force the
13962 ``right'' window configuration, you can set
13963 @code{gnus-always-force-window-configuration} to non-@code{nil}.
13966 @node Faces and Fonts
13967 @section Faces and Fonts
13972 Fiddling with fonts and faces used to be very difficult, but these days
13973 it is very simple. You simply say @kbd{M-x customize-face}, pick out
13974 the face you want to alter, and alter it via the standard Customize
13979 @section Compilation
13980 @cindex compilation
13981 @cindex byte-compilation
13983 @findex gnus-compile
13985 Remember all those line format specification variables?
13986 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
13987 on. Now, Gnus will of course heed whatever these variables are, but,
13988 unfortunately, changing them will mean a quite significant slow-down.
13989 (The default values of these variables have byte-compiled functions
13990 associated with them, while the user-generated versions do not, of
13993 To help with this, you can run @kbd{M-x gnus-compile} after you've
13994 fiddled around with the variables and feel that you're (kind of)
13995 satisfied. This will result in the new specs being byte-compiled, and
13996 you'll get top speed again. Gnus will save these compiled specs in the
13997 @file{.newsrc.eld} file. (User-defined functions aren't compiled by
13998 this function, though---you should compile them yourself by sticking
13999 them into the @code{.gnus.el} file and byte-compiling that file.)
14003 @section Mode Lines
14006 @vindex gnus-updated-mode-lines
14007 @code{gnus-updated-mode-lines} says what buffers should keep their mode
14008 lines updated. It is a list of symbols. Supported symbols include
14009 @code{group}, @code{article}, @code{summary}, @code{server},
14010 @code{browse}, and @code{tree}. If the corresponding symbol is present,
14011 Gnus will keep that mode line updated with information that may be
14012 pertinent. If this variable is @code{nil}, screen refresh may be
14015 @cindex display-time
14017 @vindex gnus-mode-non-string-length
14018 By default, Gnus displays information on the current article in the mode
14019 lines of the summary and article buffers. The information Gnus wishes
14020 to display (e.g. the subject of the article) is often longer than the
14021 mode lines, and therefore have to be cut off at some point. The
14022 @code{gnus-mode-non-string-length} variable says how long the other
14023 elements on the line is (i.e., the non-info part). If you put
14024 additional elements on the mode line (e.g. a clock), you should modify
14027 @c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
14029 (add-hook 'display-time-hook
14030 (lambda () (setq gnus-mode-non-string-length
14032 (if line-number-mode 5 0)
14033 (if column-number-mode 4 0)
14034 (length display-time-string)))))
14037 If this variable is @code{nil} (which is the default), the mode line
14038 strings won't be chopped off, and they won't be padded either. Note
14039 that the default is unlikely to be desirable, as even the percentage
14040 complete in the buffer may be crowded off the mode line; the user should
14041 configure this variable appropriately for her configuration.
14044 @node Highlighting and Menus
14045 @section Highlighting and Menus
14047 @cindex highlighting
14050 @vindex gnus-visual
14051 The @code{gnus-visual} variable controls most of the Gnus-prettifying
14052 aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy
14053 colors or fonts. This will also inhibit loading the @file{gnus-vis.el}
14056 This variable can be a list of visual properties that are enabled. The
14057 following elements are valid, and are all included by default:
14060 @item group-highlight
14061 Do highlights in the group buffer.
14062 @item summary-highlight
14063 Do highlights in the summary buffer.
14064 @item article-highlight
14065 Do highlights in the article buffer.
14067 Turn on highlighting in all buffers.
14069 Create menus in the group buffer.
14071 Create menus in the summary buffers.
14073 Create menus in the article buffer.
14075 Create menus in the browse buffer.
14077 Create menus in the server buffer.
14079 Create menus in the score buffers.
14081 Create menus in all buffers.
14084 So if you only want highlighting in the article buffer and menus in all
14085 buffers, you could say something like:
14088 (setq gnus-visual '(article-highlight menu))
14091 If you want highlighting only and no menus whatsoever, you'd say:
14094 (setq gnus-visual '(highlight))
14097 If @code{gnus-visual} is @code{t}, highlighting and menus will be used
14098 in all Gnus buffers.
14100 Other general variables that influence the look of all buffers include:
14103 @item gnus-mouse-face
14104 @vindex gnus-mouse-face
14105 This is the face (i.e., font) used for mouse highlighting in Gnus. No
14106 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
14110 There are hooks associated with the creation of all the different menus:
14114 @item gnus-article-menu-hook
14115 @vindex gnus-article-menu-hook
14116 Hook called after creating the article mode menu.
14118 @item gnus-group-menu-hook
14119 @vindex gnus-group-menu-hook
14120 Hook called after creating the group mode menu.
14122 @item gnus-summary-menu-hook
14123 @vindex gnus-summary-menu-hook
14124 Hook called after creating the summary mode menu.
14126 @item gnus-server-menu-hook
14127 @vindex gnus-server-menu-hook
14128 Hook called after creating the server mode menu.
14130 @item gnus-browse-menu-hook
14131 @vindex gnus-browse-menu-hook
14132 Hook called after creating the browse mode menu.
14134 @item gnus-score-menu-hook
14135 @vindex gnus-score-menu-hook
14136 Hook called after creating the score mode menu.
14147 Those new-fangled @dfn{mouse} contraptions is very popular with the
14148 young, hep kids who don't want to learn the proper way to do things
14149 these days. Why, I remember way back in the summer of '89, when I was
14150 using Emacs on a Tops 20 system. Three hundred users on one single
14151 machine, and every user was running Simula compilers. Bah!
14155 @vindex gnus-carpal
14156 Well, you can make Gnus display bufferfuls of buttons you can click to
14157 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
14158 really. Tell the chiropractor I sent you.
14163 @item gnus-carpal-mode-hook
14164 @vindex gnus-carpal-mode-hook
14165 Hook run in all carpal mode buffers.
14167 @item gnus-carpal-button-face
14168 @vindex gnus-carpal-button-face
14169 Face used on buttons.
14171 @item gnus-carpal-header-face
14172 @vindex gnus-carpal-header-face
14173 Face used on carpal buffer headers.
14175 @item gnus-carpal-group-buffer-buttons
14176 @vindex gnus-carpal-group-buffer-buttons
14177 Buttons in the group buffer.
14179 @item gnus-carpal-summary-buffer-buttons
14180 @vindex gnus-carpal-summary-buffer-buttons
14181 Buttons in the summary buffer.
14183 @item gnus-carpal-server-buffer-buttons
14184 @vindex gnus-carpal-server-buffer-buttons
14185 Buttons in the server buffer.
14187 @item gnus-carpal-browse-buffer-buttons
14188 @vindex gnus-carpal-browse-buffer-buttons
14189 Buttons in the browse buffer.
14192 All the @code{buttons} variables are lists. The elements in these list
14193 are either cons cells where the @code{car} contains a text to be displayed and
14194 the @code{cdr} contains a function symbol, or a simple string.
14202 Gnus, being larger than any program ever written (allegedly), does lots
14203 of strange stuff that you may wish to have done while you're not
14204 present. For instance, you may want it to check for new mail once in a
14205 while. Or you may want it to close down all connections to all servers
14206 when you leave Emacs idle. And stuff like that.
14208 Gnus will let you do stuff like that by defining various
14209 @dfn{handlers}. Each handler consists of three elements: A
14210 @var{function}, a @var{time}, and an @var{idle} parameter.
14212 Here's an example of a handler that closes connections when Emacs has
14213 been idle for thirty minutes:
14216 (gnus-demon-close-connections nil 30)
14219 Here's a handler that scans for PGP headers every hour when Emacs is
14223 (gnus-demon-scan-pgp 60 t)
14226 This @var{time} parameter and than @var{idle} parameter work together
14227 in a strange, but wonderful fashion. Basically, if @var{idle} is
14228 @code{nil}, then the function will be called every @var{time} minutes.
14230 If @var{idle} is @code{t}, then the function will be called after
14231 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
14232 the function will never be called. But once Emacs goes idle, the
14233 function will be called every @var{time} minutes.
14235 If @var{idle} is a number and @var{time} is a number, the function will
14236 be called every @var{time} minutes only when Emacs has been idle for
14237 @var{idle} minutes.
14239 If @var{idle} is a number and @var{time} is @code{nil}, the function
14240 will be called once every time Emacs has been idle for @var{idle}
14243 And if @var{time} is a string, it should look like @samp{07:31}, and
14244 the function will then be called once every day somewhere near that
14245 time. Modified by the @var{idle} parameter, of course.
14247 @vindex gnus-demon-timestep
14248 (When I say ``minute'' here, I really mean @code{gnus-demon-timestep}
14249 seconds. This is 60 by default. If you change that variable,
14250 all the timings in the handlers will be affected.)
14252 @vindex gnus-use-demon
14253 To set the whole thing in motion, though, you have to set
14254 @code{gnus-use-demon} to @code{t}.
14256 So, if you want to add a handler, you could put something like this in
14257 your @file{.gnus} file:
14259 @findex gnus-demon-add-handler
14261 (gnus-demon-add-handler 'gnus-demon-close-connections 30 t)
14264 @findex gnus-demon-add-nocem
14265 @findex gnus-demon-add-scanmail
14266 @findex gnus-demon-add-rescan
14267 @findex gnus-demon-add-scan-timestamps
14268 @findex gnus-demon-add-disconnection
14269 Some ready-made functions to do this have been created:
14270 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection},
14271 @code{gnus-demon-add-nntp-close-connection},
14272 @code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and
14273 @code{gnus-demon-add-scanmail}. Just put those functions in your
14274 @file{.gnus} if you want those abilities.
14276 @findex gnus-demon-init
14277 @findex gnus-demon-cancel
14278 @vindex gnus-demon-handlers
14279 If you add handlers to @code{gnus-demon-handlers} directly, you should
14280 run @code{gnus-demon-init} to make the changes take hold. To cancel all
14281 daemons, you can use the @code{gnus-demon-cancel} function.
14283 Note that adding daemons can be pretty naughty if you overdo it. Adding
14284 functions that scan all news and mail from all servers every two seconds
14285 is a sure-fire way of getting booted off any respectable system. So
14294 @dfn{Spamming} is posting the same article lots and lots of times.
14295 Spamming is bad. Spamming is evil.
14297 Spamming is usually canceled within a day or so by various anti-spamming
14298 agencies. These agencies usually also send out @dfn{NoCeM} messages.
14299 NoCeM is pronounced ``no see-'em'', and means what the name
14300 implies---these are messages that make the offending articles, like, go
14303 What use are these NoCeM messages if the articles are canceled anyway?
14304 Some sites do not honor cancel messages and some sites just honor cancels
14305 from a select few people. Then you may wish to make use of the NoCeM
14306 messages, which are distributed in the @samp{alt.nocem.misc} newsgroup.
14308 Gnus can read and parse the messages in this group automatically, and
14309 this will make spam disappear.
14311 There are some variables to customize, of course:
14314 @item gnus-use-nocem
14315 @vindex gnus-use-nocem
14316 Set this variable to @code{t} to set the ball rolling. It is @code{nil}
14319 @item gnus-nocem-groups
14320 @vindex gnus-nocem-groups
14321 Gnus will look for NoCeM messages in the groups in this list. The
14322 default is @code{("news.lists.filters" "news.admin.net-abuse.bulletins"
14323 "alt.nocem.misc" "news.admin.net-abuse.announce")}.
14325 @item gnus-nocem-issuers
14326 @vindex gnus-nocem-issuers
14327 There are many people issuing NoCeM messages. This list says what
14328 people you want to listen to. The default is @code{("Automoose-1"
14329 "rbraver@@ohww.norman.ok.us" "clewis@@ferret.ocunix.on.ca"
14330 "jem@@xpat.com" "snowhare@@xmission.com" "red@@redpoll.mrfs.oh.us
14331 (Richard E. Depew)")}; fine, upstanding citizens all of them.
14333 Known despammers that you can put in this list include:
14336 @item clewis@@ferret.ocunix.on.ca;
14337 @cindex Chris Lewis
14338 Chris Lewis---Major Canadian despammer who has probably canceled more
14339 usenet abuse than anybody else.
14342 @cindex CancelMoose[tm]
14343 The CancelMoose[tm] on autopilot. The CancelMoose[tm] is reputed to be
14344 Norwegian, and was the person(s) who invented NoCeM.
14346 @item jem@@xpat.com;
14348 John Milburn---despammer located in Korea who is getting very busy these
14351 @item red@@redpoll.mrfs.oh.us (Richard E. Depew)
14352 Richard E. Depew---lone American despammer. He mostly cancels binary
14353 postings to non-binary groups and removes spews (regurgitated articles).
14356 You do not have to heed NoCeM messages from all these people---just the
14357 ones you want to listen to. You also don't have to accept all NoCeM
14358 messages from the people you like. Each NoCeM message has a @dfn{type}
14359 header that gives the message a (more or less, usually less) rigorous
14360 definition. Common types are @samp{spam}, @samp{spew}, @samp{mmf},
14361 @samp{binary}, and @samp{troll}. To specify this, you have to use
14362 @var{(issuer conditions ...)} elements in the list. Each condition is
14363 either a string (which is a regexp that matches types you want to use)
14364 or a list on the form @code{(not STRING)}, where @var{string} is a
14365 regexp that matches types you don't want to use.
14367 For instance, if you want all NoCeM messages from Chris Lewis except his
14368 @samp{troll} messages, you'd say:
14371 ("clewis@@ferret.ocunix.on.ca" ".*" (not "troll"))
14374 On the other hand, if you just want nothing but his @samp{spam} and
14375 @samp{spew} messages, you'd say:
14378 ("clewis@@ferret.ocunix.on.ca" (not ".*") "spew" "spam")
14381 The specs are applied left-to-right.
14384 @item gnus-nocem-verifyer
14385 @vindex gnus-nocem-verifyer
14387 This should be a function for verifying that the NoCeM issuer is who she
14388 says she is. The default is @code{mc-verify}, which is a Mailcrypt
14389 function. If this is too slow and you don't care for verification
14390 (which may be dangerous), you can set this variable to @code{nil}.
14392 If you want signed NoCeM messages to be verified and unsigned messages
14393 not to be verified (but used anyway), you could do something like:
14396 (setq gnus-nocem-verifyer 'my-gnus-mc-verify)
14398 (defun my-gnus-mc-verify ()
14406 This might be dangerous, though.
14408 @item gnus-nocem-directory
14409 @vindex gnus-nocem-directory
14410 This is where Gnus will store its NoCeM cache files. The default is
14411 @file{~/News/NoCeM/}.
14413 @item gnus-nocem-expiry-wait
14414 @vindex gnus-nocem-expiry-wait
14415 The number of days before removing old NoCeM entries from the cache.
14416 The default is 15. If you make it shorter Gnus will be faster, but you
14417 might then see old spam.
14421 Using NoCeM could potentially be a memory hog. If you have many living
14422 (i. e., subscribed or unsubscribed groups), your Emacs process will grow
14423 big. If this is a problem, you should kill off all (or most) of your
14424 unsubscribed groups (@pxref{Subscription Commands}).
14431 It is very useful to be able to undo actions one has done. In normal
14432 Emacs buffers, it's easy enough---you just push the @code{undo} button.
14433 In Gnus buffers, however, it isn't that simple.
14435 The things Gnus displays in its buffer is of no value whatsoever to
14436 Gnus---it's all just data designed to look nice to the user.
14437 Killing a group in the group buffer with @kbd{C-k} makes the line
14438 disappear, but that's just a side-effect of the real action---the
14439 removal of the group in question from the internal Gnus structures.
14440 Undoing something like that can't be done by the normal Emacs
14441 @code{undo} function.
14443 Gnus tries to remedy this somewhat by keeping track of what the user
14444 does and coming up with actions that would reverse the actions the user
14445 takes. When the user then presses the @code{undo} key, Gnus will run
14446 the code to reverse the previous action, or the previous actions.
14447 However, not all actions are easily reversible, so Gnus currently offers
14448 a few key functions to be undoable. These include killing groups,
14449 yanking groups, and changing the list of read articles of groups.
14450 That's it, really. More functions may be added in the future, but each
14451 added function means an increase in data to be stored, so Gnus will
14452 never be totally undoable.
14454 @findex gnus-undo-mode
14455 @vindex gnus-use-undo
14457 The undoability is provided by the @code{gnus-undo-mode} minor mode. It
14458 is used if @code{gnus-use-undo} is non-@code{nil}, which is the
14459 default. The @kbd{M-C-_} key performs the @code{gnus-undo} command
14460 command, which should feel kinda like the normal Emacs @code{undo}
14465 @section Moderation
14468 If you are a moderator, you can use the @file{gnus-mdrtn.el} package.
14469 It is not included in the standard Gnus package. Write a mail to
14470 @samp{larsi@@gnus.org} and state what group you moderate, and you'll
14473 The moderation package is implemented as a minor mode for summary
14477 (add-hook 'gnus-summary-mode-hook 'gnus-moderate)
14480 in your @file{.gnus.el} file.
14482 If you are the moderator of @samp{rec.zoofle}, this is how it's
14487 You split your incoming mail by matching on
14488 @samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted
14489 articles in some mail group---for instance, @samp{nnml:rec.zoofle}.
14492 You enter that group once in a while and post articles using the @kbd{e}
14493 (edit-and-post) or @kbd{s} (just send unedited) commands.
14496 If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some
14497 articles that weren't approved by you, you can cancel them with the
14501 To use moderation mode in these two groups, say:
14504 (setq gnus-moderated-list
14505 "^nnml:rec.zoofle$\\|^rec.zoofle$")
14509 @node XEmacs Enhancements
14510 @section XEmacs Enhancements
14513 XEmacs is able to display pictures and stuff, so Gnus has taken
14517 * Picons:: How to display pictures of what your reading.
14518 * Smileys:: Show all those happy faces the way they were meant to be shown.
14519 * Toolbar:: Click'n'drool.
14520 * XVarious:: Other XEmacsy Gnusey variables.
14533 So... You want to slow down your news reader even more! This is a
14534 good way to do so. Its also a great way to impress people staring
14535 over your shoulder as you read news.
14538 * Picon Basics:: What are picons and How do I get them.
14539 * Picon Requirements:: Don't go further if you aren't using XEmacs.
14540 * Easy Picons:: Displaying Picons---the easy way.
14541 * Hard Picons:: The way you should do it. You'll learn something.
14542 * Picon Useless Configuration:: Other variables you can trash/tweak/munge/play with.
14547 @subsubsection Picon Basics
14549 What are Picons? To quote directly from the Picons Web site:
14558 @dfn{Picons} is short for ``personal icons''. They're small,
14559 constrained images used to represent users and domains on the net,
14560 organized into databases so that the appropriate image for a given
14561 e-mail address can be found. Besides users and domains, there are picon
14562 databases for Usenet newsgroups and weather forecasts. The picons are
14563 in either monochrome @code{XBM} format or color @code{XPM} and
14564 @code{GIF} formats.
14567 @vindex gnus-picons-piconsearch-url
14568 If you have a permanent connection to the Internet you can use Steve
14569 Kinzler's Picons Search engine by setting
14570 @code{gnus-picons-piconsearch-url} to the string
14571 @file{http://www.cs.indiana.edu/picons/search.html}.
14573 @vindex gnus-picons-database
14574 Otherwise you need a local copy of his database. For instructions on
14575 obtaining and installing the picons databases, point your Web browser at
14576 @file{http://www.cs.indiana.edu/picons/ftp/index.html}. Gnus expects
14577 picons to be installed into a location pointed to by
14578 @code{gnus-picons-database}.
14581 @node Picon Requirements
14582 @subsubsection Picon Requirements
14584 To have Gnus display Picons for you, you must be running XEmacs
14585 19.13 or greater since all other versions of Emacs aren't yet able to
14588 Additionally, you must have @code{x} support compiled into XEmacs. To
14589 display color picons which are much nicer than the black & white one,
14590 you also need one of @code{xpm} or @code{gif} compiled into XEmacs.
14592 @vindex gnus-picons-convert-x-face
14593 If you want to display faces from @code{X-Face} headers, you should have
14594 the @code{xface} support compiled into XEmacs. Otherwise you must have
14595 the @code{netpbm} utilities installed, or munge the
14596 @code{gnus-picons-convert-x-face} variable to use something else.
14600 @subsubsection Easy Picons
14602 To enable displaying picons, simply put the following line in your
14603 @file{~/.gnus} file and start Gnus.
14606 (setq gnus-use-picons t)
14607 (add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
14608 (add-hook 'gnus-article-display-hook 'gnus-picons-article-display-x-face)
14611 and make sure @code{gnus-picons-database} points to the directory
14612 containing the Picons databases.
14614 Alternatively if you want to use the web piconsearch engine add this:
14617 (setq gnus-picons-piconsearch-url "http://www.cs.indiana.edu:800/piconsearch")
14622 @subsubsection Hard Picons
14630 Gnus can display picons for you as you enter and leave groups and
14631 articles. It knows how to interact with three sections of the picons
14632 database. Namely, it can display the picons newsgroup pictures,
14633 author's face picture(s), and the authors domain. To enable this
14634 feature, you need to select where to get the picons from, and where to
14639 @item gnus-picons-database
14640 @vindex gnus-picons-database
14641 The location of the picons database. Should point to a directory
14642 containing the @file{news}, @file{domains}, @file{users} (and so on)
14643 subdirectories. This is only useful if
14644 @code{gnus-picons-piconsearch-url} is @code{nil}. Defaults to
14645 @file{/usr/local/faces/}.
14647 @item gnus-picons-piconsearch-url
14648 @vindex gnus-picons-piconsearch-url
14649 The URL for the web picons search engine. The only currently known
14650 engine is @file{http://www.cs.indiana.edu:800/piconsearch}. To
14651 workaround network delays, icons will be fetched in the background. If
14652 this is @code{nil} 'the default), then picons are fetched from local
14653 database indicated by @code{gnus-picons-database}.
14655 @item gnus-picons-display-where
14656 @vindex gnus-picons-display-where
14657 Where the picon images should be displayed. It is @code{picons} by
14658 default (which by default maps to the buffer @samp{*Picons*}). Other
14659 valid places could be @code{article}, @code{summary}, or
14660 @samp{*scratch*} for all I care. Just make sure that you've made the
14661 buffer visible using the standard Gnus window configuration
14662 routines---@pxref{Windows Configuration}.
14664 @item gnus-picons-group-excluded-groups
14665 @vindex gnus-picons-group-excluded-groups
14666 Groups that are matched by this regexp won't have their group icons
14671 Note: If you set @code{gnus-use-picons} to @code{t}, it will set up your
14672 window configuration for you to include the @code{picons} buffer.
14674 Now that you've made those decision, you need to add the following
14675 functions to the appropriate hooks so these pictures will get displayed
14678 @vindex gnus-article-display-hook
14679 @vindex gnus-picons-display-where
14681 @item gnus-article-display-picons
14682 @findex gnus-article-display-picons
14683 Looks up and displays the picons for the author and the author's domain
14684 in the @code{gnus-picons-display-where} buffer. Should be added to the
14685 @code{gnus-article-display-hook}.
14687 @item gnus-picons-article-display-x-face
14688 @findex gnus-article-display-picons
14689 Decodes and displays the X-Face header if present. This function
14690 should be added to @code{gnus-article-display-hook}.
14694 Note: You must append them to the hook, so make sure to specify 't'
14695 for the append flag of @code{add-hook}:
14698 (add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
14702 @node Picon Useless Configuration
14703 @subsubsection Picon Useless Configuration
14711 The following variables offer further control over how things are
14712 done, where things are located, and other useless stuff you really
14713 don't need to worry about.
14717 @item gnus-picons-news-directories
14718 @vindex gnus-picons-news-directories
14719 List of subdirectories to search in @code{gnus-picons-database} for
14720 newsgroups faces. @code{("news")} is the default.
14722 @item gnus-picons-user-directories
14723 @vindex gnus-picons-user-directories
14724 List of subdirectories to search in @code{gnus-picons-database} for user
14725 faces. @code{("local" "users" "usenix" "misc")} is the default.
14727 @item gnus-picons-domain-directories
14728 @vindex gnus-picons-domain-directories
14729 List of subdirectories to search in @code{gnus-picons-database} for
14730 domain name faces. Defaults to @code{("domains")}. Some people may
14731 want to add @samp{"unknown"} to this list.
14733 @item gnus-picons-convert-x-face
14734 @vindex gnus-picons-convert-x-face
14735 If you don't have @code{xface} support builtin XEmacs, this is the
14736 command to use to convert the @code{X-Face} header to an X bitmap
14737 (@code{xbm}). Defaults to @code{(format "@{ echo '/* Width=48,
14738 Height=48 */'; uncompface; @} | icontopbm | pbmtoxbm > %s"
14739 gnus-picons-x-face-file-name)}
14741 @item gnus-picons-x-face-file-name
14742 @vindex gnus-picons-x-face-file-name
14743 Names a temporary file to store the @code{X-Face} bitmap in. Defaults
14744 to @code{(format "/tmp/picon-xface.%s.xbm" (user-login-name))}.
14746 @item gnus-picons-has-modeline-p
14747 @vindex gnus-picons-has-modeline-p
14748 If you have set @code{gnus-picons-display-where} to @code{picons}, your
14749 XEmacs frame will become really cluttered. To alleviate this a bit you
14750 can set @code{gnus-picons-has-modeline-p} to @code{nil}; this will
14751 remove the mode line from the Picons buffer. This is only useful if
14752 @code{gnus-picons-display-where} is @code{picons}.
14754 @item gnus-picons-refresh-before-display
14755 @vindex gnus-picons-refresh-before-display
14756 If non-nil, display the article buffer before computing the picons.
14757 Defaults to @code{nil}.
14759 @item gnus-picons-display-as-address
14760 @vindex gnus-picons-display-as-address
14761 If @code{t} display textual email addresses along with pictures.
14762 Defaults to @code{t}.
14764 @item gnus-picons-file-suffixes
14765 @vindex gnus-picons-file-suffixes
14766 Ordered list of suffixes on picon file names to try. Defaults to
14767 @code{("xpm" "gif" "xbm")} minus those not builtin your XEmacs.
14769 @item gnus-picons-display-article-move-p
14770 @vindex gnus-picons-display-article-move-p
14771 Whether to move point to first empty line when displaying picons. This
14772 has only an effect if `gnus-picons-display-where' has value `article'.
14774 @item gnus-picons-clear-cache-on-shutdown
14775 @vindex gnus-picons-clear-cache-on-shutdown
14776 Whether to clear the picons cache when exiting gnus. Gnus caches every
14777 picons it finds while it is running. This saves some time in the search
14778 process but eats some memory. If this variable is set to @code{nil},
14779 Gnus will never clear the cache itself; you will have to manually call
14780 @code{gnus-picons-clear-cache} to clear it. Otherwise the cache will be
14781 cleared every time you exit Gnus. Defaults to @code{t}.
14792 @subsection Smileys
14797 \gnusfig{-3cm}{0.5cm}{\epsfig{figure=tmp/BigFace.ps,height=20cm}}
14802 @dfn{Smiley} is a package separate from Gnus, but since Gnus is
14803 currently the only package that uses Smiley, it is documented here.
14805 In short---to use Smiley in Gnus, put the following in your
14806 @file{.gnus.el} file:
14809 (add-hook 'gnus-article-display-hook 'gnus-smiley-display t)
14812 Smiley maps text smiley faces---@samp{:-)}, @samp{:-=}, @samp{:-(} and
14813 the like---to pictures and displays those instead of the text smiley
14814 faces. The conversion is controlled by a list of regexps that matches
14815 text and maps that to file names.
14817 @vindex smiley-nosey-regexp-alist
14818 @vindex smiley-deformed-regexp-alist
14819 Smiley supplies two example conversion alists by default:
14820 @code{smiley-deformed-regexp-alist} (which matches @samp{:)}, @samp{:(}
14821 and so on), and @code{smiley-nosey-regexp-alist} (which matches
14822 @samp{:-)}, @samp{:-(} and so on).
14824 The alist used is specified by the @code{smiley-regexp-alist} variable,
14825 which defaults to the value of @code{smiley-deformed-regexp-alist}.
14827 The first item in each element is the regexp to be matched; the second
14828 element is the regexp match group that is to be replaced by the picture;
14829 and the third element is the name of the file to be displayed.
14831 The following variables customize where Smiley will look for these
14832 files, as well as the color to be used and stuff:
14836 @item smiley-data-directory
14837 @vindex smiley-data-directory
14838 Where Smiley will look for smiley faces files.
14840 @item smiley-flesh-color
14841 @vindex smiley-flesh-color
14842 Skin color. The default is @samp{yellow}, which is really racist.
14844 @item smiley-features-color
14845 @vindex smiley-features-color
14846 Color of the features of the face. The default is @samp{black}.
14848 @item smiley-tongue-color
14849 @vindex smiley-tongue-color
14850 Color of the tongue. The default is @samp{red}.
14852 @item smiley-circle-color
14853 @vindex smiley-circle-color
14854 Color of the circle around the face. The default is @samp{black}.
14856 @item smiley-mouse-face
14857 @vindex smiley-mouse-face
14858 Face used for mouse highlighting over the smiley face.
14864 @subsection Toolbar
14874 @item gnus-use-toolbar
14875 @vindex gnus-use-toolbar
14876 If @code{nil}, don't display toolbars. If non-@code{nil}, it should be
14877 one of @code{default-toolbar}, @code{top-toolbar}, @code{bottom-toolbar},
14878 @code{right-toolbar}, or @code{left-toolbar}.
14880 @item gnus-group-toolbar
14881 @vindex gnus-group-toolbar
14882 The toolbar in the group buffer.
14884 @item gnus-summary-toolbar
14885 @vindex gnus-summary-toolbar
14886 The toolbar in the summary buffer.
14888 @item gnus-summary-mail-toolbar
14889 @vindex gnus-summary-mail-toolbar
14890 The toolbar in the summary buffer of mail groups.
14896 @subsection Various XEmacs Variables
14899 @item gnus-xmas-glyph-directory
14900 @vindex gnus-xmas-glyph-directory
14901 This is where Gnus will look for pictures. Gnus will normally
14902 auto-detect this directory, but you may set it manually if you have an
14903 unusual directory structure.
14905 @item gnus-xmas-logo-color-alist
14906 @vindex gnus-xmas-logo-color-alist
14907 This is an alist where the key is a type symbol and the values are the
14908 foreground and background color of the splash page glyph.
14910 @item gnus-xmas-logo-color-style
14911 @vindex gnus-xmas-logo-color-style
14912 This is the key used to look up the color in the alist described above.
14913 Legal values include @code{flame}, @code{pine}, @code{moss},
14914 @code{irish}, @code{sky}, @code{tin}, @code{velvet}, @code{grape},
14915 @code{labia}, @code{berry}, @code{neutral}, and @code{september}.
14917 @item gnus-xmas-modeline-glyph
14918 @vindex gnus-xmas-modeline-glyph
14919 A glyph displayed in all Gnus mode lines. It is a tiny gnu head by
14933 @node Fuzzy Matching
14934 @section Fuzzy Matching
14935 @cindex fuzzy matching
14937 Gnus provides @dfn{fuzzy matching} of @code{Subject} lines when doing
14938 things like scoring, thread gathering and thread comparison.
14940 As opposed to regular expression matching, fuzzy matching is very fuzzy.
14941 It's so fuzzy that there's not even a definition of what @dfn{fuzziness}
14942 means, and the implementation has changed over time.
14944 Basically, it tries to remove all noise from lines before comparing.
14945 @samp{Re: }, parenthetical remarks, white space, and so on, are filtered
14946 out of the strings before comparing the results. This often leads to
14947 adequate results---even when faced with strings generated by text
14948 manglers masquerading as newsreaders.
14951 @node Thwarting Email Spam
14952 @section Thwarting Email Spam
14956 @cindex unsolicited commercial email
14958 In these last days of the Usenet, commercial vultures are hanging about
14959 and grepping through news like crazy to find email addresses they can
14960 foist off their scams and products to. As a reaction to this, many
14961 people have started putting nonsense addresses into their @code{From}
14962 lines. I think this is counterproductive---it makes it difficult for
14963 people to send you legitimate mail in response to things you write, as
14964 well as making it difficult to see who wrote what. This rewriting may
14965 perhaps be a bigger menace than the unsolicited commercial email itself
14968 The biggest problem I have with email spam is that it comes in under
14969 false pretenses. I press @kbd{g} and Gnus merrily informs me that I
14970 have 10 new emails. I say ``Golly gee! Happy is me!'' and select the
14971 mail group, only to find two pyramid schemes, seven advertisements
14972 (``New! Miracle tonic for growing full, lustrouos hair on your toes!'')
14973 and one mail asking me to repent and find some god.
14977 The way to deal with this is having Gnus split out all spam into a
14978 @samp{spam} mail group (@pxref{Splitting Mail}).
14980 First, pick one (1) valid mail address that you can be reached at, and
14981 put it in your @code{From} header of all your news articles. (I've
14982 chosen @samp{larsi@@trym.ifi.uio.no}, but for many addresses on the form
14983 @samp{larsi+usenet@@ifi.uio.no} will be a better choice. Ask your
14984 sysadm whether your sendmail installation accepts keywords in the local
14985 part of the mail address.)
14988 (setq message-default-news-headers
14989 "From: Lars Magne Ingebrigtsen <larsi@@trym.ifi.uio.no>\n")
14992 Then put the following split rule in @code{nnmail-split-fancy}
14993 (@pxref{Fancy Mail Splitting}):
14998 (to "larsi@@trym.ifi.uio.no"
14999 (| ("subject" "re:.*" "misc")
15000 ("references" ".*@@.*" "misc")
15006 This says that all mail to this address is suspect, but if it has a
15007 @code{Subject} that starts with a @samp{Re:} or has a @code{References}
15008 header, it's probably ok. All the rest goes to the @samp{spam} group.
15009 (This idea probably comes from Tim Pierce.)
15011 In addition, many mail spammers talk directly to your @code{smtp} server
15012 and do not include your email address explicitly in the @code{To}
15013 header. Why they do this is unknown---perhaps it's to thwart this
15014 twarting scheme? In any case, this is trivial to deal with---you just
15015 put anything not addressed to you in the @samp{spam} group by ending
15016 your fancy split rule in this way:
15021 (to "larsi" "misc")
15025 In my experience, this will sort virtually everything into the right
15026 group. You still have to check the @samp{spam} group from time to time to
15027 check for legitimate mail, though. If you feel like being a good net
15028 citizen, you can even send off complaints to the proper authorities on
15029 each unsolicited commercial email---at your leisure.
15031 If you are also a lazy net citizen, you will probably prefer complaining
15032 automatically with the @file{gnus-junk.el} package, availiable FOR FREE
15033 at @file{<URL:http://stud2.tuwien.ac.at/~e9426626/gnus-junk.html>}.
15034 Since most e-mail spam is sent automatically, this may reconcile the
15035 cosmic balance somewhat.
15037 This works for me. It allows people an easy way to contact me (they can
15038 just press @kbd{r} in the usual way), and I'm not bothered at all with
15039 spam. It's a win-win situation. Forging @code{From} headers to point
15040 to non-existant domains is yucky, in my opinion.
15043 @node Various Various
15044 @section Various Various
15050 @item gnus-home-directory
15051 All Gnus path variables will be initialized from this variable, which
15052 defaults to @file{~/}.
15054 @item gnus-directory
15055 @vindex gnus-directory
15056 Most Gnus storage path variables will be initialized from this variable,
15057 which defaults to the @samp{SAVEDIR} environment variable, or
15058 @file{~/News/} if that variable isn't set.
15060 @item gnus-default-directory
15061 @vindex gnus-default-directory
15062 Not related to the above variable at all---this variable says what the
15063 default directory of all Gnus buffers should be. If you issue commands
15064 like @kbd{C-x C-f}, the prompt you'll get starts in the current buffer's
15065 default directory. If this variable is @code{nil} (which is the
15066 default), the default directory will be the default directory of the
15067 buffer you were in when you started Gnus.
15070 @vindex gnus-verbose
15071 This variable is an integer between zero and ten. The higher the value,
15072 the more messages will be displayed. If this variable is zero, Gnus
15073 will never flash any messages, if it is seven (which is the default),
15074 most important messages will be shown, and if it is ten, Gnus won't ever
15075 shut up, but will flash so many messages it will make your head swim.
15077 @item gnus-verbose-backends
15078 @vindex gnus-verbose-backends
15079 This variable works the same way as @code{gnus-verbose}, but it applies
15080 to the Gnus backends instead of Gnus proper.
15082 @item nnheader-max-head-length
15083 @vindex nnheader-max-head-length
15084 When the backends read straight heads of articles, they all try to read
15085 as little as possible. This variable (default 4096) specifies
15086 the absolute max length the backends will try to read before giving up
15087 on finding a separator line between the head and the body. If this
15088 variable is @code{nil}, there is no upper read bound. If it is
15089 @code{t}, the backends won't try to read the articles piece by piece,
15090 but read the entire articles. This makes sense with some versions of
15091 @code{ange-ftp} or @code{efs}.
15093 @item nnheader-head-chop-length
15094 @vindex nnheader-head-chop-length
15095 This variable (default 2048) says how big a piece of each article to
15096 read when doing the operation described above.
15098 @item nnheader-file-name-translation-alist
15099 @vindex nnheader-file-name-translation-alist
15101 @cindex invalid characters in file names
15102 @cindex characters in file names
15103 This is an alist that says how to translate characters in file names.
15104 For instance, if @samp{:} is invalid as a file character in file names
15105 on your system (you OS/2 user you), you could say something like:
15108 (setq nnheader-file-name-translation-alist
15112 In fact, this is the default value for this variable on OS/2 and MS
15113 Windows (phooey) systems.
15115 @item gnus-hidden-properties
15116 @vindex gnus-hidden-properties
15117 This is a list of properties to use to hide ``invisible'' text. It is
15118 @code{(invisible t intangible t)} by default on most systems, which
15119 makes invisible text invisible and intangible.
15121 @item gnus-parse-headers-hook
15122 @vindex gnus-parse-headers-hook
15123 A hook called before parsing headers. It can be used, for instance, to
15124 gather statistics on the headers fetched, or perhaps you'd like to prune
15125 some headers. I don't see why you'd want that, though.
15127 @item gnus-shell-command-separator
15128 @vindex gnus-shell-command-separator
15129 String used to separate two shell commands. The default is @samp{;}.
15138 Well, that's the manual---you can get on with your life now. Keep in
15139 touch. Say hello to your cats from me.
15141 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
15143 Ol' Charles Reznikoff said it pretty well, so I leave the floor to him:
15149 Not because of victories @*
15152 but for the common sunshine,@*
15154 the largess of the spring.
15158 but for the day's work done@*
15159 as well as I was able;@*
15160 not for a seat upon the dais@*
15161 but at the common table.@*
15166 @chapter Appendices
15169 * History:: How Gnus got where it is today.
15170 * Terminology:: We use really difficult, like, words here.
15171 * Customization:: Tailoring Gnus to your needs.
15172 * Troubleshooting:: What you might try if things do not work.
15173 * A Programmers Guide to Gnus:: Rilly, rilly technical stuff.
15174 * Emacs for Heathens:: A short introduction to Emacsian terms.
15175 * Frequently Asked Questions:: A question-and-answer session.
15183 @sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in
15184 '94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
15186 If you want to investigate the person responsible for this outrage, you
15187 can point your (feh!) web browser to
15188 @file{http://www.ifi.uio.no/~larsi/}. This is also the primary
15189 distribution point for the new and spiffy versions of Gnus, and is known
15190 as The Site That Destroys Newsrcs And Drives People Mad.
15192 During the first extended alpha period of development, the new Gnus was
15193 called ``(ding) Gnus''. @dfn{(ding)} is, of course, short for
15194 @dfn{ding is not Gnus}, which is a total and utter lie, but who cares?
15195 (Besides, the ``Gnus'' in this abbreviation should probably be
15196 pronounced ``news'' as @sc{Umeda} intended, which makes it a more
15197 appropriate name, don't you think?)
15199 In any case, after spending all that energy on coming up with a new and
15200 spunky name, we decided that the name was @emph{too} spunky, so we
15201 renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs.
15202 ``@sc{gnus}''. New vs. old.
15204 The first ``proper'' release of Gnus 5 was done in November 1995 when it
15205 was included in the Emacs 19.30 distribution (132 (ding) Gnus releases
15206 plus 15 Gnus 5.0 releases).
15208 In May 1996 the next Gnus generation (aka. ``September Gnus'' (after 99
15209 releases)) was released under the name ``Gnus 5.2'' (40 releases).
15211 On July 28th 1996 work on Red Gnus was begun, and it was released on
15212 January 25th 1997 (after 84 releases) as ``Gnus 5.4''.
15214 If you happen upon a version of Gnus that has a prefixed name --
15215 ``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'' --
15216 don't panic. Don't let it know that you're frightened. Back away.
15217 Slowly. Whatever you do, don't run. Walk away, calmly, until you're
15218 out of its reach. Find a proper released version of Gnus and snuggle up
15222 * Why?:: What's the point of Gnus?
15223 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
15224 * Conformity:: Gnus tries to conform to all standards.
15225 * Emacsen:: Gnus can be run on a few modern Emacsen.
15226 * Contributors:: Oodles of people.
15227 * New Features:: Pointers to some of the new stuff in Gnus.
15228 * Newest Features:: Features so new that they haven't been written yet.
15235 What's the point of Gnus?
15237 I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep''
15238 newsreader, that lets you do anything you can think of. That was my
15239 original motivation, but while working on Gnus, it has become clear to
15240 me that this generation of newsreaders really belong in the stone age.
15241 Newsreaders haven't developed much since the infancy of the net. If the
15242 volume continues to rise with the current rate of increase, all current
15243 newsreaders will be pretty much useless. How do you deal with
15244 newsgroups that have thousands of new articles each day? How do you
15245 keep track of millions of people who post?
15247 Gnus offers no real solutions to these questions, but I would very much
15248 like to see Gnus being used as a testing ground for new methods of
15249 reading and fetching news. Expanding on @sc{Umeda}-san's wise decision
15250 to separate the newsreader from the backends, Gnus now offers a simple
15251 interface for anybody who wants to write new backends for fetching mail
15252 and news from different sources. I have added hooks for customizations
15253 everywhere I could imagine it being useful. By doing so, I'm inviting
15254 every one of you to explore and invent.
15256 May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs} and
15257 @kbd{C-u 100 M-x all-hail-xemacs}.
15260 @node Compatibility
15261 @subsection Compatibility
15263 @cindex compatibility
15264 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
15265 bindings have been kept. More key bindings have been added, of course,
15266 but only in one or two obscure cases have old bindings been changed.
15271 @center In a cloud bones of steel.
15275 All commands have kept their names. Some internal functions have changed
15278 The @code{gnus-uu} package has changed drastically. @xref{Decoding
15281 One major compatibility question is the presence of several summary
15282 buffers. All variables relevant while reading a group are
15283 buffer-local to the summary buffer they belong in. Although many
15284 important variables have their values copied into their global
15285 counterparts whenever a command is executed in the summary buffer, this
15286 change might lead to incorrect values being used unless you are careful.
15288 All code that relies on knowledge of @sc{gnus} internals will probably
15289 fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or
15290 changing it in any way, as a matter of fact) is strictly verboten. Gnus
15291 maintains a hash table that points to the entries in this alist (which
15292 speeds up many functions), and changing the alist directly will lead to
15296 @cindex highlighting
15297 Old hilit19 code does not work at all. In fact, you should probably
15298 remove all hilit code from all Gnus hooks
15299 (@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}).
15300 Gnus provides various integrated functions for highlighting. These are
15301 faster and more accurate. To make life easier for everybody, Gnus will
15302 by default remove all hilit calls from all hilit hooks. Uncleanliness!
15305 Packages like @code{expire-kill} will no longer work. As a matter of
15306 fact, you should probably remove all old @sc{gnus} packages (and other
15307 code) when you start using Gnus. More likely than not, Gnus already
15308 does what you have written code to make @sc{gnus} do. (Snicker.)
15310 Even though old methods of doing things are still supported, only the
15311 new methods are documented in this manual. If you detect a new method of
15312 doing something while reading this manual, that does not mean you have
15313 to stop doing it the old way.
15315 Gnus understands all @sc{gnus} startup files.
15317 @kindex M-x gnus-bug
15319 @cindex reporting bugs
15321 Overall, a casual user who hasn't written much code that depends on
15322 @sc{gnus} internals should suffer no problems. If problems occur,
15323 please let me know by issuing that magic command @kbd{M-x gnus-bug}.
15327 @subsection Conformity
15329 No rebels without a clue here, ma'am. We conform to all standards known
15330 to (wo)man. Except for those standards and/or conventions we disagree
15337 There are no known breaches of this standard.
15341 There are no known breaches of this standard, either.
15343 @item Son-of-RFC 1036
15344 @cindex Son-of-RFC 1036
15345 We do have some breaches to this one.
15350 Gnus does no MIME handling, and this standard-to-be seems to think that
15351 MIME is the bees' knees, so we have major breakage here.
15354 This is considered to be a ``vanity header'', while I consider it to be
15355 consumer information. After seeing so many badly formatted articles
15356 coming from @code{tin} and @code{Netscape} I know not to use either of
15357 those for posting articles. I would not have known that if it wasn't
15358 for the @code{X-Newsreader} header.
15363 If you ever notice Gnus acting non-compliant with regards to the texts
15364 mentioned above, don't hesitate to drop a note to Gnus Towers and let us
15369 @subsection Emacsen
15375 Gnus should work on :
15380 Emacs 19.32 and up.
15383 XEmacs 19.14 and up.
15386 Mule versions based on Emacs 19.32 and up.
15390 Gnus will absolutely not work on any Emacsen older than that. Not
15391 reliably, at least.
15393 There are some vague differences between Gnus on the various
15394 platforms---XEmacs features more graphics (a logo and a toolbar)---but
15395 other than that, things should look pretty much the same under all
15400 @subsection Contributors
15401 @cindex contributors
15403 The new Gnus version couldn't have been done without the help of all the
15404 people on the (ding) mailing list. Every day for over a year I have
15405 gotten billions of nice bug reports from them, filling me with joy,
15406 every single one of them. Smooches. The people on the list have been
15407 tried beyond endurance, what with my ``oh, that's a neat idea <type
15408 type>, yup, I'll release it right away <ship off> no wait, that doesn't
15409 work at all <type type>, yup, I'll ship that one off right away <ship
15410 off> no, wait, that absolutely does not work'' policy for releases.
15411 Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that
15412 ``worser''? ``much worser''? ``worsest''?)
15414 I would like to take this opportunity to thank the Academy for... oops,
15420 Masanobu @sc{Umeda}---the writer of the original @sc{gnus}.
15423 Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as
15424 well as numerous other things).
15427 Luis Fernandes---design and graphics.
15430 Erik Naggum---help, ideas, support, code and stuff.
15433 Wes Hardaker---@file{gnus-picon.el} and the manual section on
15434 @dfn{picons} (@pxref{Picons}).
15437 Kim-Minh Kaplan---further work on the picon code.
15440 Brad Miller---@file{gnus-gl.el} and the GroupLens manual section
15441 (@pxref{GroupLens}).
15444 Sudish Joseph---innumerable bug fixes.
15447 Ilja Weis---@file{gnus-topic.el}.
15450 Steven L. Baur---lots and lots and lots of bugs detections and fixes.
15453 Vladimir Alexiev---the refcard and reference booklets.
15456 Felix Lee & Jamie Zawinsky---I stole some pieces from the XGnus
15457 distribution by Felix Lee and JWZ.
15460 Scott Byer---@file{nnfolder.el} enhancements & rewrite.
15463 Peter Mutsaers---orphan article scoring code.
15466 Ken Raeburn---POP mail support.
15469 Hallvard B Furuseth---various bits and pieces, especially dealing with
15473 Brian Edmonds---@file{gnus-bbdb.el}.
15476 David Moore---rewrite of @file{nnvirtual.el} and many other things.
15479 Kevin Davidson---came up with the name @dfn{ding}, so blame him.
15482 François Pinard---many, many interesting and thorough bug reports, as
15483 well as autoconf support.
15487 This manual was proof-read by Adrian Aichner, with Ricardo Nassif, Mark
15488 Borges, and Jost Krieger proof-reading parts of the manual.
15490 The following people have contributed many patches and suggestions:
15499 Jason L. Tibbitts, III,
15503 Also thanks to the following for patches and stuff:
15522 Massimo Campostrini,
15527 Geoffrey T. Dairiki,
15533 Michael Welsh Duggan,
15536 Enami Tsugutomo, @c Enami
15540 Nelson Jose dos Santos Ferreira,
15545 Arne Georg Gleditsch,
15547 Michelangelo Grigni,
15550 Kenichi Handa, @c Handa
15552 Hisashige Kenji, @c Hisashige
15557 François Felix Ingrand,
15558 Ishikawa Ichiro, @c Ishikawa
15560 Iwamuro Motonori, @c Iwamuro
15568 Peter Skov Knudsen,
15569 Shuhei Kobayashi, @c Kobayashi
15570 Thor Kristoffersen,
15572 Seokchan Lee, @c Lee
15588 Morioka Tomohiko, @c Morioka
15589 Erik Toubro Nielsen,
15596 Masaharu Onishi, @c Onishi
15600 Jens-Ulrik Holger Petersen,
15602 John McClary Prevost,
15605 Lars Balker Rasmussen,
15610 Christian von Roques,
15617 Philippe Schnoebelen,
15618 Randal L. Schwartz,
15646 Katsumi Yamaoka. @c Yamaoka
15648 For a full overview of what each person has done, the ChangeLogs
15649 included in the Gnus alpha distributions should give ample reading
15650 (550kB and counting).
15652 Apologies to everybody that I've forgotten, of which there are many, I'm
15655 Gee, that's quite a list of people. I guess that must mean that there
15656 actually are people who are using Gnus. Who'd'a thunk it!
15660 @subsection New Features
15661 @cindex new features
15664 * ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus.
15665 * September Gnus:: The Thing Formally Known As Gnus 5.3/5.3.
15666 * Red Gnus:: Third time best---Gnus 5.4/5.5.
15667 * Quassia Gnus:: Two times two is four, or Gnus 5.6.3.
15670 These lists are, of course, just @emph{short} overviews of the
15671 @emph{most} important new features. No, really. There are tons more.
15672 Yes, we have feeping creaturism in full effect.
15676 @subsubsection (ding) Gnus
15678 New features in Gnus 5.0/5.1:
15683 The look of all buffers can be changed by setting format-like variables
15684 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
15687 Local spool and several @sc{nntp} servers can be used at once
15688 (@pxref{Select Methods}).
15691 You can combine groups into virtual groups (@pxref{Virtual Groups}).
15694 You can read a number of different mail formats (@pxref{Getting Mail}).
15695 All the mail backends implement a convenient mail expiry scheme
15696 (@pxref{Expiring Mail}).
15699 Gnus can use various strategies for gathering threads that have lost
15700 their roots (thereby gathering loose sub-threads into one thread) or it
15701 can go back and retrieve enough headers to build a complete thread
15702 (@pxref{Customizing Threading}).
15705 Killed groups can be displayed in the group buffer, and you can read
15706 them as well (@pxref{Listing Groups}).
15709 Gnus can do partial group updates---you do not have to retrieve the
15710 entire active file just to check for new articles in a few groups
15711 (@pxref{The Active File}).
15714 Gnus implements a sliding scale of subscribedness to groups
15715 (@pxref{Group Levels}).
15718 You can score articles according to any number of criteria
15719 (@pxref{Scoring}). You can even get Gnus to find out how to score
15720 articles for you (@pxref{Adaptive Scoring}).
15723 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
15724 manner, so it should be difficult to lose much data on what you have
15725 read if your machine should go down (@pxref{Auto Save}).
15728 Gnus now has its own startup file (@file{.gnus}) to avoid cluttering up
15729 the @file{.emacs} file.
15732 You can set the process mark on both groups and articles and perform
15733 operations on all the marked items (@pxref{Process/Prefix}).
15736 You can grep through a subset of groups and create a group from the
15737 results (@pxref{Kibozed Groups}).
15740 You can list subsets of groups according to, well, anything
15741 (@pxref{Listing Groups}).
15744 You can browse foreign servers and subscribe to groups from those
15745 servers (@pxref{Browse Foreign Server}).
15748 Gnus can fetch articles, asynchronously, on a second connection to the
15749 server (@pxref{Asynchronous Fetching}).
15752 You can cache articles locally (@pxref{Article Caching}).
15755 The uudecode functions have been expanded and generalized
15756 (@pxref{Decoding Articles}).
15759 You can still post uuencoded articles, which was a little-known feature
15760 of @sc{gnus}' past (@pxref{Uuencoding and Posting}).
15763 Fetching parents (and other articles) now actually works without
15764 glitches (@pxref{Finding the Parent}).
15767 Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
15770 Digests (and other files) can be used as the basis for groups
15771 (@pxref{Document Groups}).
15774 Articles can be highlighted and customized (@pxref{Customizing
15778 URLs and other external references can be buttonized (@pxref{Article
15782 You can do lots of strange stuff with the Gnus window & frame
15783 configuration (@pxref{Windows Configuration}).
15786 You can click on buttons instead of using the keyboard
15792 @node September Gnus
15793 @subsubsection September Gnus
15797 \gnusfig{-28cm}{0cm}{\epsfig{figure=tmp/september.ps,height=20cm}}
15801 New features in Gnus 5.2/5.3:
15806 A new message composition mode is used. All old customization variables
15807 for @code{mail-mode}, @code{rnews-reply-mode} and @code{gnus-msg} are
15811 Gnus is now able to generate @dfn{sparse} threads---threads where
15812 missing articles are represented by empty nodes (@pxref{Customizing
15816 (setq gnus-build-sparse-threads 'some)
15820 Outgoing articles are stored on a special archive server
15821 (@pxref{Archived Messages}).
15824 Partial thread regeneration now happens when articles are
15828 Gnus can make use of GroupLens predictions (@pxref{GroupLens}).
15831 Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}).
15834 A @code{trn}-like tree buffer can be displayed (@pxref{Tree Display}).
15837 (setq gnus-use-trees t)
15841 An @code{nn}-like pick-and-read minor mode is available for the summary
15842 buffers (@pxref{Pick and Read}).
15845 (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
15849 In binary groups you can use a special binary minor mode (@pxref{Binary
15853 Groups can be grouped in a folding topic hierarchy (@pxref{Group
15857 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
15861 Gnus can re-send and bounce mail (@pxref{Summary Mail Commands}).
15864 Groups can now have a score, and bubbling based on entry frequency
15865 is possible (@pxref{Group Score}).
15868 (add-hook 'gnus-summary-exit-hook 'gnus-summary-bubble-group)
15872 Groups can be process-marked, and commands can be performed on
15873 groups of groups (@pxref{Marking Groups}).
15876 Caching is possible in virtual groups.
15879 @code{nndoc} now understands all kinds of digests, mail boxes, rnews
15880 news batches, ClariNet briefs collections, and just about everything
15881 else (@pxref{Document Groups}).
15884 Gnus has a new backend (@code{nnsoup}) to create/read SOUP packets
15888 The Gnus cache is much faster.
15891 Groups can be sorted according to many criteria (@pxref{Sorting
15895 New group parameters have been introduced to set list-addresses and
15896 expiry times (@pxref{Group Parameters}).
15899 All formatting specs allow specifying faces to be used
15900 (@pxref{Formatting Fonts}).
15903 There are several more commands for setting/removing/acting on process
15904 marked articles on the @kbd{M P} submap (@pxref{Setting Process Marks}).
15907 The summary buffer can be limited to show parts of the available
15908 articles based on a wide range of criteria. These commands have been
15909 bound to keys on the @kbd{/} submap (@pxref{Limiting}).
15912 Articles can be made persistent with the @kbd{*} command
15913 (@pxref{Persistent Articles}).
15916 All functions for hiding article elements are now toggles.
15919 Article headers can be buttonized (@pxref{Article Washing}).
15922 (add-hook 'gnus-article-display-hook
15923 'gnus-article-add-buttons-to-head)
15927 All mail backends support fetching articles by @code{Message-ID}.
15930 Duplicate mail can now be treated properly (@pxref{Duplicates}).
15933 All summary mode commands are available directly from the article
15934 buffer (@pxref{Article Keymap}).
15937 Frames can be part of @code{gnus-buffer-configuration} (@pxref{Windows
15941 Mail can be re-scanned by a daemonic process (@pxref{Daemons}).
15944 \marginpar[\mbox{}\hfill\epsfig{figure=tmp/fseptember.ps,height=5cm}]{\epsfig{figure=tmp/fseptember.ps,height=5cm}}
15949 Gnus can make use of NoCeM files to weed out spam (@pxref{NoCeM}).
15952 (setq gnus-use-nocem t)
15956 Groups can be made permanently visible (@pxref{Listing Groups}).
15959 (setq gnus-permanently-visible-groups "^nnml:")
15963 Many new hooks have been introduced to make customizing easier.
15966 Gnus respects the @code{Mail-Copies-To} header.
15969 Threads can be gathered by looking at the @code{References} header
15970 (@pxref{Customizing Threading}).
15973 (setq gnus-summary-thread-gathering-function
15974 'gnus-gather-threads-by-references)
15978 Read articles can be stored in a special backlog buffer to avoid
15979 refetching (@pxref{Article Backlog}).
15982 (setq gnus-keep-backlog 50)
15986 A clean copy of the current article is always stored in a separate
15987 buffer to allow easier treatment.
15990 Gnus can suggest where to save articles (@pxref{Saving Articles}).
15993 Gnus doesn't have to do as much prompting when saving (@pxref{Saving
15997 (setq gnus-prompt-before-saving t)
16001 @code{gnus-uu} can view decoded files asynchronously while fetching
16002 articles (@pxref{Other Decode Variables}).
16005 (setq gnus-uu-grabbed-file-functions 'gnus-uu-grab-view)
16009 Filling in the article buffer now works properly on cited text
16010 (@pxref{Article Washing}).
16013 Hiding cited text adds buttons to toggle hiding, and how much
16014 cited text to hide is now customizable (@pxref{Article Hiding}).
16017 (setq gnus-cited-lines-visible 2)
16021 Boring headers can be hidden (@pxref{Article Hiding}).
16024 (add-hook 'gnus-article-display-hook
16025 'gnus-article-hide-boring-headers t)
16029 Default scoring values can now be set from the menu bar.
16032 Further syntax checking of outgoing articles have been added.
16038 @subsubsection Red Gnus
16040 New features in Gnus 5.4/5.5:
16044 \gnusfig{-5.5cm}{-4cm}{\epsfig{figure=tmp/red.ps,height=20cm}}
16051 @file{nntp.el} has been totally rewritten in an asynchronous fashion.
16054 Article prefetching functionality has been moved up into
16055 Gnus (@pxref{Asynchronous Fetching}).
16058 Scoring can now be performed with logical operators like @code{and},
16059 @code{or}, @code{not}, and parent redirection (@pxref{Advanced
16063 Article washing status can be displayed in the
16064 article mode line (@pxref{Misc Article}).
16067 @file{gnus.el} has been split into many smaller files.
16070 Suppression of duplicate articles based on Message-ID can be done
16071 (@pxref{Duplicate Suppression}).
16074 (setq gnus-suppress-duplicates t)
16078 New variables for specifying what score and adapt files are to be
16079 considered home score and adapt files (@pxref{Home Score File}) have
16083 @code{nndoc} was rewritten to be easily extendable (@pxref{Document
16084 Server Internals}).
16087 Groups can inherit group parameters from parent topics (@pxref{Topic
16091 Article editing has been revamped and is now actually usable.
16094 Signatures can be recognized in more intelligent fashions
16095 (@pxref{Article Signature}).
16098 Summary pick mode has been made to look more @code{nn}-like. Line
16099 numbers are displayed and the @kbd{.} command can be used to pick
16100 articles (@code{Pick and Read}).
16103 Commands for moving the @file{.newsrc.eld} from one server to
16104 another have been added (@pxref{Changing Servers}).
16107 There's a way now to specify that ``uninteresting'' fields be suppressed
16108 when generating lines in buffers (@pxref{Advanced Formatting}).
16111 Several commands in the group buffer can be undone with @kbd{M-C-_}
16115 Scoring can be done on words using the new score type @code{w}
16116 (@pxref{Score File Format}).
16119 Adaptive scoring can be done on a Subject word-by-word basis
16120 (@pxref{Adaptive Scoring}).
16123 (setq gnus-use-adaptive-scoring '(word))
16127 Scores can be decayed (@pxref{Score Decays}).
16130 (setq gnus-decay-scores t)
16134 Scoring can be performed using a regexp on the Date header. The Date is
16135 normalized to compact ISO 8601 format first (@pxref{Score File Format}).
16138 A new command has been added to remove all data on articles from
16139 the native server (@pxref{Changing Servers}).
16142 A new command for reading collections of documents
16143 (@code{nndoc} with @code{nnvirtual} on top) has been added---@kbd{M-C-d}
16144 (@pxref{Really Various Summary Commands}).
16147 Process mark sets can be pushed and popped (@pxref{Setting Process
16151 A new mail-to-news backend makes it possible to post even when the NNTP
16152 server doesn't allow posting (@pxref{Mail-To-News Gateways}).
16155 A new backend for reading searches from Web search engines
16156 (@dfn{DejaNews}, @dfn{Alta Vista}, @dfn{InReference}) has been added
16157 (@pxref{Web Searches}).
16160 Groups inside topics can now be sorted using the standard sorting
16161 functions, and each topic can be sorted independently (@pxref{Topic
16165 Subsets of the groups can be sorted independently (@code{Sorting
16169 Cached articles can be pulled into the groups (@pxref{Summary Generation
16173 \marginpar[\mbox{}\hfill\epsfig{figure=tmp/fred.ps,width=3cm}]{\epsfig{figure=tmp/fred.ps,width=3cm}}
16178 Score files are now applied in a more reliable order (@pxref{Score
16182 Reports on where mail messages end up can be generated (@pxref{Splitting
16186 More hooks and functions have been added to remove junk from incoming
16187 mail before saving the mail (@pxref{Washing Mail}).
16190 Emphasized text can be properly fontisized:
16193 (add-hook 'gnus-article-display-hook 'gnus-article-emphasize)
16200 @subsubsection Quassia Gnus
16202 New features in Gnus 5.6.3:
16207 New functionality for using Gnus as an offline newsreader has been
16208 added. A plethora of new commands and modes have been added. See
16209 @pxref{Gnus Unplugged} for the full story.
16212 The @code{nndraft} backend has returned, but works differently than
16213 before. All Message buffers are now also articles in the @code{nndraft}
16214 group, which is created automatically.
16217 @code{gnus-alter-header-function} can now be used to alter header
16221 @code{gnus-summary-goto-article} now accept Message-ID's.
16224 A new Message command for deleting text in the body of a message
16225 outside the region: @kbd{C-c C-v}.
16228 You can now post to component group in @code{nnvirtual} groups with
16232 @code{nntp-rlogin-program}---new variable to ease customization.
16235 @code{C-u C-c C-c} in @code{gnus-article-edit-mode} will now inhibit
16236 re-highlighting of the article buffer.
16239 New element in @code{gnus-boring-article-headers}---@code{long-to}.
16242 @kbd{M-i} symbolic prefix command. See the section "Symbolic
16243 Prefixes" in the Gnus manual for details.
16246 @kbd{L} and @kbd{I} in the summary buffer now take the symbolic prefix
16247 @kbd{a} to add the score rule to the "all.SCORE" file.
16250 @code{gnus-simplify-subject-functions} variable to allow greater
16251 control over simplification.
16254 @kbd{A T}---new command for fetching the current thread.
16257 @kbd{/ T}---new command for including the current thread in the
16261 @kbd{M-RET} is a new Message command for breaking cited text.
16264 @samp{\\1}-expressions are now valid in @code{nnmail-split-methods}.
16267 The @code{custom-face-lookup} function has been removed.
16268 If you used this function in your initialization files, you must
16269 rewrite them to use @code{face-spec-set} instead.
16272 Cancelling now uses the current select method. Symbolic prefix
16273 @kbd{a} forces normal posting method.
16276 New command to translate M******** sm*rtq**t*s into proper
16280 For easier debugging of @code{nntp}, you can set
16281 @code{nntp-record-commands} to a non-@code{nil} value.
16284 @code{nntp} now uses @file{~/.authinfo}, a @file{.netrc}-like file, for
16285 controlling where and how to send @sc{authinfo} to @sc{nntp} servers.
16288 A command for editing group parameters from the summary buffer
16292 A history of where mails have been split is available.
16295 A new article date command has been added---@code{article-date-iso8601}.
16298 Subjects can be simplified when threading by setting
16299 @code{gnus-score-thread-simplify}.
16302 A new function for citing in Message has been
16303 added---@code{message-cite-original-without-signature}.
16306 @code{article-strip-all-blank-lines}---new article command.
16309 A new Message command to kill to the end of the article has
16313 A minimum adaptive score can be specified by using the
16314 @code{gnus-adaptive-word-minimum} variable.
16317 The "lapsed date" article header can be kept continually
16318 updated by the @code{gnus-start-date-timer} command.
16321 Web listserv archives can be read with the @code{nnlistserv} backend.
16324 Old dejanews archives can now be read by @code{nnweb}.
16329 @node Newest Features
16330 @subsection Newest Features
16333 Also known as the @dfn{todo list}. Sure to be implemented before the
16336 Be afraid. Be very afraid.
16338 (That a feature appears in this list doesn't necessarily mean that I've
16339 decided to actually implement it. It just means that I think it sounds
16342 (Yes, this is the actual, up-to-the-second todo list.)
16347 Native @sc{mime} support is something that should be done.
16350 Really do unbinhexing.
16353 I would like the zombie-page to contain an URL to the source of the
16354 latest version of gnus or some explanation on where to find it.
16357 A way to continue editing the latest Message composition.
16360 http://www.sonicnet.com/feature/ari3/
16363 facep is not declared.
16366 Include a section in the manual on why the number of articles
16367 isn't the same in the group buffer and on the SPC prompt.
16370 Interacting with rmail fcc isn't easy.
16375 <URL:http://www.falch.no/people/pepper/DSSSL-Lite/archives/>
16376 <URL:http://www.eit.com/software/hypermail/hypermail.html>
16377 <URL:http://homer.ncm.com/>
16378 <URL:http://www.yahoo.com/Computers_and_Internet/Internet/World_Wide_Web/HTML_Converters/>
16379 http://www.uwsg.indiana.edu/hypermail/linux/kernel/9610/index.html
16380 <URL:http://union.ncsa.uiuc.edu/HyperNews/get/www/html/converters.html>
16381 http://www.miranova.com/gnus-list/
16386 @samp{^-- } is made into - in LaTeX.
16389 gnus-kill is much slower than it was in GNUS 4.1.3.
16392 when expunging articles on low score, the sparse nodes keep hanging on?
16394 starting the first time seems to hang Gnus on some systems. Does
16395 NEWGROUPS answer too fast?
16397 nndir doesn't read gzipped files.
16399 FAQ doesn't have an up node?
16401 when moving mail from a procmail spool to the crash-box,
16402 the crash-box is only appropriate to one specific group.
16404 `t' `t' makes X-Faces disappear.
16406 nnmh-be-safe means that crossposted articles will
16407 be marked as unread.
16409 Orphan score entries dont show on "V t" score trace
16411 when clearing out data, the cache data should also be reset.
16413 rewrite gnus-summary-limit-children to be non-recursive
16414 to avoid exceeding lisp nesting on huge groups.
16416 expinged articles are counted when computing scores.
16418 implement gnus-batch-brew-soup
16420 ticked articles aren't easy to read in pick mode -- `n' and
16421 stuff just skips past them. Read articles are the same.
16423 topics that contain just groups with ticked
16424 articles aren't displayed.
16426 nndoc should always allocate unique Message-IDs.
16428 implement gnus-score-thread
16430 If there are mail groups the first time you use Gnus, Gnus'll
16431 make the mail groups killed.
16433 no "no news is good news" when using topics.
16435 when doing crosspost marking, the cache has to be consulted
16436 and articles have to be removed.
16438 nnweb should fetch complete articles when they are split into several
16441 scoring on head immediate doesn't work.
16443 finding short score file names takes forever.
16445 canceling articles in foreign groups.
16447 nntp-open-rlogin no longer works.
16449 C-u C-x C-s (Summary) switches to the group buffer.
16451 move nnmail-split-history out to the backends.
16453 nnweb doesn't work properly.
16455 using a virtual server name as `gnus-select-method' doesn't work?
16457 when killing/yanking a group from one topic to another in a slave, the
16458 master will yank it first to one topic and then add it to another.
16462 warn user about `=' redirection of a group in the active file?
16464 really unbinhex binhex files.
16466 take over the XEmacs menubar and offer a toggle between the XEmacs
16467 bar and the Gnus bar.
16470 push active file and NOV file parsing down into C code.
16471 `(canonize-message-id id)'
16472 `(mail-parent-message-id references n)'
16473 `(parse-news-nov-line &optional dependency-hashtb)'
16474 `(parse-news-nov-region beg end &optional dependency-hashtb fullp)'
16475 `(parse-news-active-region beg end hashtb)'
16480 nnml .overview directory with splits.
16484 postponed commands.
16486 the selected article show have its Subject displayed in its summary line.
16488 when entering groups, get the real number of unread articles from
16491 sort after gathering threads -- make false roots have the
16492 headers of the oldest orhpan with a 0 article number?
16494 nndoc groups should inherit the score files of their parents? Also
16495 inherit copy prompts and save files.
16497 command to start up Gnus (if not running) and enter a mail mode buffer.
16499 allow editing the group description from the group buffer
16500 for backends that support that.
16502 gnus-hide,show-all-topics
16504 groups and sub-topics should be allowed to mingle inside each topic,
16505 and not just list all subtopics at the end.
16507 a command to remove all read articles that are not needed to connect
16508 threads -- `gnus-summary-limit-to-sparse-unread'?
16510 a variable to turn off limiting/cutting of threads in the tree buffer.
16512 a variable to limit how many files are uudecoded.
16514 add zombie groups to a special "New Groups" topic.
16516 server mode command: close/open all connections
16518 put a file date in gnus-score-alist and check whether the file
16519 has been changed before using it.
16521 on exit from a digest group, go to the next article in the parent group.
16523 hide (sub)threads with low score.
16525 when expiring, remove all marks from expired articles.
16527 gnus-summary-limit-to-body
16529 a regexp alist that says what level groups are to be subscribed
16530 on. Eg. -- `(("nnml:" . 1))'.
16532 easier interface to nnkiboze to create ephemeral groups that
16533 contaion groups that match a regexp.
16535 allow newlines in <URL:> urls, but remove them before using
16538 If there is no From line, the mail backends should fudge one from the
16541 fuzzy simplifying should strip all non-alpha-numerical info
16542 from subject lines.
16544 gnus-soup-brew-soup-with-high-scores.
16546 nntp-ping-before-connect
16548 command to check whether NOV is evil. "list overview.fmt".
16550 when entering a group, Gnus should look through the score
16551 files very early for `local' atoms and set those local variables.
16553 message annotations.
16555 topics are always yanked before groups, and that's not good.
16557 (set-extent-property extent 'help-echo "String to display in minibuf")
16558 to display help in the minibuffer on buttons under XEmacs.
16560 allow group line format spec to say how many articles there
16565 support qmail maildir spools
16567 `run-with-idle-timer' in gnus-demon.
16569 stop using invisible text properties and start using overlays instead
16571 C-c C-f C-e to add an Expires header.
16573 go from one group to the next; everything is expunged; go to the
16574 next group instead of going to the group buffer.
16576 gnus-renumber-cache -- to renumber the cache using "low" numbers.
16578 record topic changes in the dribble buffer.
16580 `nnfolder-generate-active-file' should look at the folders it
16581 finds and generate proper active ranges.
16583 nneething-look-in-files-for-article-heads variable to control
16584 whether nneething should sniff all files in the directories.
16586 gnus-fetch-article -- start Gnus, enter group, display article
16588 gnus-dont-move-articles-to-same-group variable when respooling.
16590 when messages are crossposted between several auto-expirable groups,
16591 articles aren't properly marked as expirable.
16593 nneething should allow deletion/moving.
16595 TAB on the last button should go to the first button.
16597 if the car of an element in `mail-split-methods' is a function,
16598 and the function returns non-nil, use that as the name of the group(s) to
16601 command for listing all score files that have been applied.
16603 a command in the article buffer to return to `summary' config.
16605 `gnus-always-post-using-current-server' -- variable to override
16606 `C-c C-c' when posting.
16608 nnmail-group-spool-alist -- says where each group should use
16611 when an article is crossposted to an auto-expirable group, the article
16612 should be marker as expirable.
16614 article mode command/menu for "send region as URL to browser".
16616 on errors, jump to info nodes that explain the error. For instance,
16617 on invalid From headers, or on error messages from the nntp server.
16619 when gathering threads, make the article that has no "Re: " the parent.
16620 Also consult Date headers.
16622 a token in splits to call shrink-window-if-larger-than-buffer
16624 `1 0 A M' to do matches on the active hashtb.
16626 duplicates -- command to remove Gnus-Warning header, use the read
16627 Message-ID, delete the "original".
16629 when replying to several messages at once, put the "other" message-ids
16630 into a See-Also header.
16632 support setext: URL:http://www.bsdi.com/setext/
16634 support ProleText: <URL:http://proletext.clari.net/prole/proletext.html>
16636 when browsing a foreign server, the groups that are already subscribed
16637 should be listed as such and not as "K".
16639 generate font names dynamically.
16641 score file mode auto-alist.
16643 allow nndoc to change/add/delete things from documents. Implement
16644 methods for each format for adding an article to the document.
16646 `gnus-fetch-old-headers' `all' value to incorporate
16647 absolutely all headers there is.
16649 function like `|', but concatenate all marked articles
16650 and pipe them to the process.
16652 cache the list of killed (or active) groups in a separate file. Update
16653 the file whenever we read the active file or the list
16654 of killed groups in the .eld file reaches a certain length.
16656 function for starting to edit a file to put into
16657 the current mail group.
16659 score-find-trace should display the total score of the article.
16661 "ghettozie" -- score on Xref header and nix it out after using it
16662 to avoid marking as read in other groups it has been crossposted to.
16664 look at procmail splitting. The backends should create
16665 the groups automatically if a spool file exists for that group.
16667 function for backends to register themselves with Gnus.
16669 when replying to several process-marked articles,
16670 have all the From end up in Cc headers? Variable to toggle.
16672 command to delete a crossposted mail article from all
16673 groups it has been mailed to.
16675 `B c' and `B m' should be crosspost aware.
16677 hide-pgp should also hide PGP public key blocks.
16679 Command in the group buffer to respoll process-marked groups.
16681 `gnus-summary-find-matching' should accept
16682 pseudo-"headers" like "body", "head" and "all"
16684 When buttifying <URL: > things, all white space (including
16685 newlines) should be ignored.
16687 Process-marking all groups in a topic should process-mark
16688 groups in subtopics as well.
16690 Add non-native groups to the list of killed groups when killing them.
16692 nntp-suggest-kewl-config to probe the nntp server and suggest
16695 add edit and forward secondary marks.
16697 nnml shouldn't visit its .overview files.
16699 allow customizing sorting within gathered threads.
16701 `B q' shouldn't select the current article.
16703 nnmbox should support a newsgroups file for descriptions.
16705 allow fetching mail from several pop servers.
16707 Be able to specify whether the saving commands save the original
16708 or the formatted article.
16710 a command to reparent with the child process-marked (cf. `T ^'.).
16712 I think the possibility to send a password with nntp-open-rlogin
16713 should be a feature in Red Gnus.
16715 The `Z n' command should be possible to execute from a mouse click.
16717 more limiting functions -- date, etc.
16719 be able to limit on a random header; on body; using reverse matches.
16721 a group parameter (`absofucking-total-expiry') that will make Gnus expire
16722 even unread articles.
16724 a command to print the article buffer as postscript.
16726 variable to disable password fetching when opening by nntp-open-telnet.
16728 manual: more example servers -- nntp with rlogin, telnet
16730 checking for bogus groups should clean topic alists as well.
16732 cancelling articles in foreign groups.
16734 article number in folded topics isn't properly updated by
16737 Movement in the group buffer to the next unread group should go to the
16738 next closed topic with unread messages if no group can be found.
16740 Extensive info pages generated on the fly with help everywhere --
16741 in the "*Gnus edit*" buffers, for instance.
16743 Topic movement commands -- like thread movement. Up, down, forward, next.
16745 a way to tick/mark as read Gcc'd articles.
16747 a way to say that all groups within a specific topic comes
16748 from a particular server? Hm.
16750 `gnus-article-fill-if-long-lines' -- a function to fill
16751 the article buffer if there are any looong lines there.
16753 `T h' should jump to the parent topic and fold it.
16755 a command to create an ephemeral nndoc group out of a file,
16756 and then splitting it/moving it to some other group/backend.
16758 a group parameter for nnkiboze groups that says that
16759 all kibozed articles should be entered into the cache.
16761 It should also probably be possible to delimit what
16762 `gnus-jog-cache' does -- for instance, work on just some groups, or on
16763 some levels, and entering just articles that have a score higher than
16766 nnfolder should append to the folder instead of re-writing
16767 the entire folder to disk when accepting new messages.
16769 allow all backends to do the proper thing with .gz files.
16771 a backend for reading collections of babyl files nnbabylfolder?
16773 a command for making the native groups into foreign groups.
16775 server mode command for clearing read marks from all groups
16778 when following up mulitple articles, include all To, Cc, etc headers
16781 a command for deciding what the total score of the current
16782 thread is. Also a way to highlight based on this.
16784 command to show and edit group scores
16786 a gnus-tree-minimize-horizontal to minimize tree buffers
16789 command to generate nnml overview file for one group.
16791 `C-u C-u a' -- prompt for many crossposted groups.
16793 keep track of which mail groups have received new articles (in this session).
16794 Be able to generate a report and perhaps do some marking in the group
16797 gnus-build-sparse-threads to a number -- build only sparse threads
16798 that are of that length.
16800 have nnmh respect mh's unseen sequence in .mh_profile.
16802 cache the newsgroups descriptions locally.
16804 asynchronous posting under nntp.
16806 be able to control word adaptive scoring from the score files.
16808 a variable to make `C-c C-c' post using the "current" select method.
16810 `limit-exclude-low-scored-articles'.
16812 if `gnus-summary-show-thread' is a number, hide threads that have
16813 a score lower than this number.
16815 split newsgroup subscription variable up into "order" and "method".
16817 buttonize ange-ftp file names.
16819 a command to make a duplicate copy of the current article
16820 so that each copy can be edited separately.
16822 nnweb should allow fetching from the local nntp server.
16824 record the sorting done in the summary buffer so that
16825 it can be repeated when limiting/regenerating the buffer.
16827 nnml-generate-nov-databses should generate for
16830 when the user does commands in the group buffer, check
16831 the modification time of the .newsrc.eld file and use
16832 ask-user-about-supersession-threat. Also warn when trying
16833 to save .newsrc.eld and it has changed.
16835 M-g on a topic will display all groups with 0 articles in
16838 command to remove all topic stuff.
16840 allow exploding incoming digests when reading incoming mail
16841 and splitting the resulting digests.
16843 nnsoup shouldn't set the `message-' variables.
16845 command to nix out all nnoo state information.
16847 nnmail-process-alist that calls functions if group names
16848 matches an alist -- before saving.
16850 use buffer-invisibility-spec everywhere for hiding text.
16852 variable to activate each group before entering them
16853 to get the (new) number of articles. `gnus-activate-before-entering'.
16855 command to fetch a Message-ID from any buffer, even
16856 starting Gnus first if necessary.
16858 when posting and checking whether a group exists or not, just
16859 ask the nntp server instead of relying on the active hashtb.
16861 buttonize the output of `C-c C-a' in an apropos-like way.
16863 `G p' should understand process/prefix, and allow editing
16864 of several groups at once.
16866 command to create an ephemeral nnvirtual group that
16867 matches some regexp(s).
16869 nndoc should understand "Content-Type: message/rfc822" forwarded messages.
16871 it should be possible to score "thread" on the From header.
16873 hitting RET on a "gnus-uu-archive" pseudo article should unpack it.
16875 `B i' should display the article at once in the summary buffer.
16877 remove the "*" mark at once when unticking an article.
16879 `M-s' should highlight the matching text.
16881 when checking for duplicated mails, use Resent-Message-ID if present.
16883 killing and yanking groups in topics should be better. If killing one copy
16884 of a group that exists in multiple topics, only that copy should
16885 be removed. Yanking should insert the copy, and yanking topics
16886 should be possible to be interspersed with the other yankings.
16888 command for enter a group just to read the cached articles. A way to say
16889 "ignore the nntp connection; just read from the cache."
16891 `X u' should decode base64 articles.
16893 a way to hide all "inner" cited text, leaving just the most
16894 recently cited text.
16896 nnvirtual should be asynchronous.
16898 after editing an article, gnus-original-article-buffer should
16901 there should probably be a way to make Gnus not connect to the
16902 server and just read the articles in the server
16904 allow a `set-default' (or something) to change the default
16905 value of nnoo variables.
16907 a command to import group infos from a .newsrc.eld file.
16909 groups from secondary servers have the entire select method
16910 listed in each group info.
16912 a command for just switching from the summary buffer to the group
16915 a way to specify that some incoming mail washing functions
16916 should only be applied to some groups.
16918 Message `C-f C-t' should ask the user whether to heed
16919 mail-copies-to: never.
16921 new group parameter -- `post-to-server' that says to post
16922 using the current server. Also a variable to do the same.
16924 the slave dribble files should autosave to the slave file names.
16926 a group parameter that says what articles to display on group entry, based
16929 a way to visually distinguish slave Gnusae from masters. (Whip instead
16932 Use DJ Bernstein "From " quoting/dequoting, where appliccable.
16934 Why is hide-citation-maybe and hide-citation different? Also
16937 group user-defined meta-parameters.
16941 From: John Griffith <griffith@@sfs.nphil.uni-tuebingen.de>
16943 I like the option for trying to retrieve the FAQ for a group and I was
16944 thinking it would be great if for those newsgroups that had archives
16945 you could also try to read the archive for that group. Part of the
16946 problem is that archives are spread all over the net, unlike FAQs.
16947 What would be best I suppose is to find the one closest to your site.
16949 In any case, there is a list of general news group archives at
16950 ftp://ftp.neosoft.com/pub/users/claird/news.lists/newsgroup_archives.html
16957 From: Jason L Tibbitts III <tibbs@@hpc.uh.edu>
16958 (add-hook 'gnus-select-group-hook
16960 (gnus-group-add-parameter group
16961 (cons 'gnus-group-date-last-entered (list (current-time-string))))))
16963 (defun gnus-user-format-function-d (headers)
16964 "Return the date the group was last read."
16965 (cond ((car (gnus-group-get-parameter gnus-tmp-group 'gnus-group-date-last-entered)))
16970 tanken var at når du bruker `gnus-startup-file' som prefix (FOO) til å lete
16971 opp en fil FOO-SERVER, FOO-SERVER.el, FOO-SERVER.eld, kan du la den være en
16972 liste hvor du bruker hvert element i listen som FOO, istedet. da kunne man
16973 hatt forskjellige serveres startup-filer forskjellige steder.
16977 LMI> Well, nnbabyl could alter the group info to heed labels like
16978 LMI> answered and read, I guess.
16980 It could also keep them updated (the same for the Status: header of
16983 They could be used like this:
16987 `M l <name> RET' add label <name> to current message.
16988 `M u <name> RET' remove label <name> from current message.
16989 `/ l <expr> RET' limit summary buffer according to <expr>.
16991 <expr> would be a boolean expression on the labels, e.g.
16993 `/ l bug & !fixed RET'
16996 would show all the messages which are labeled `bug' but not labeled
16999 One could also immagine the labels being used for highliting, or
17000 affect the summary line format.
17004 Sender: abraham@@dina.kvl.dk
17006 I'd like a gnus-find-file which work like find file, except that it
17007 would recognize things that looks like messages or folders:
17009 - If it is a directory containing numbered files, create an nndir
17012 - For other directories, create a nneething summaru buffer.
17014 - For files matching "\\`From ", create a nndoc/mbox summary.
17016 - For files matching "\\`BABYL OPTIONS:", create a nndoc/baby summary.
17018 - For files matching "\\`[^ \t\n]+:", create an *Article* buffer.
17020 - For other files, just find them normally.
17022 I'd like `nneething' to use this function, so it would work on a
17023 directory potentially containing mboxes or babyl files.
17026 Please send a mail to bwarsaw@@cnri.reston.va.us (Barry A. Warsaw) and
17027 tell him what you are doing.
17030 Currently, I get prompted:
17034 decend into sci.something ?
17038 The problem above is that since there is really only one subsection of
17039 science, shouldn't it prompt you for only decending sci.something? If
17040 there was a sci.somethingelse group or section, then it should prompt
17041 for sci? first the sci.something? then sci.somethingelse?...
17044 Ja, det burde være en måte å si slikt. Kanskje en ny variabel?
17045 `gnus-use-few-score-files'? SÃ¥ kunne score-regler legges til den
17046 "mest" lokale score-fila. F. eks. ville no-gruppene betjenes av
17047 "no.all.SCORE", osv.
17050 What i want is for Gnus to treat any sequence or combination of the following
17051 as a single spoiler warning and hide it all, replacing it with a "Next Page"
17057 more than n blank lines
17059 more than m identical lines
17060 (which should be replaced with button to show them)
17062 any whitespace surrounding any of the above
17066 Well, we could allow a new value to `gnus-thread-ignore-subject' --
17067 `spaces', or something. (We could even default to that.) And then
17068 subjects that differ in white space only could be considered the
17069 "same" subject for threading purposes.
17072 Modes to preprocess the contents (e.g. jka-compr) use the second form
17073 "(REGEXP FUNCTION NON-NIL)" while ordinary modes (e.g. tex) use the first
17074 form "(REGEXP . FUNCTION)", so you could use it to distinguish between
17075 those two types of modes. (auto-modes-alist, insert-file-contents-literally.)
17078 Under XEmacs -- do funny article marks:
17081 soup - bowl of soup
17082 score below - dim light bulb
17083 score over - bright light bulb
17086 Yes. I think the algorithm is as follows:
17091 show-list-of-articles-in-group
17092 if (key-pressed == SPACE)
17093 if (no-more-articles-in-group-to-select)
17094 if (articles-selected)
17095 start-reading-selected-articles;
17096 junk-unread-articles;
17101 else if (key-pressed = '.')
17102 if (consolidated-menus) # same as hide-thread in Gnus
17103 select-thread-under-cursor;
17105 select-article-under-cursor;
17109 if (key-pressed == SPACE)
17110 if (more-pages-in-article)
17112 else if (more-selected-articles-to-read)
17119 My precise need here would have been to limit files to Incoming*.
17120 One could think of some `nneething-only-files' variable, but I guess
17121 it would have been unacceptable if one was using many unrelated such
17124 A more useful approach would be to, in response to the `G D' prompt, be
17125 allowed to say something like: `~/.mail/Incoming*', somewhat limiting
17126 the top-level directory only (in case directories would be matched by
17127 the wildcard expression).
17130 It would be nice if it also handled
17132 <URL:news://sunsite.auc.dk/>
17134 which should correspond to `B nntp RET sunsite.auc.dk' in *Group*.
17139 Take a look at w3-menu.el in the Emacs-W3 distribution - this works out
17140 really well. Each menu is 'named' by a symbol that would be on a
17141 gnus-*-menus (where * would be whatever, but at least group, summary, and
17142 article versions) variable.
17144 So for gnus-summary-menus, I would set to '(sort mark dispose ...)
17146 A value of '1' would just put _all_ the menus in a single 'GNUS' menu in
17147 the main menubar. This approach works really well for Emacs-W3 and VM.
17151 nndoc should take care to create unique Message-IDs for all its
17154 gnus-score-followup-article only works when you have a summary buffer
17155 active. Make it work when posting from the group buffer as well.
17156 (message-sent-hook).
17158 rewrite gnus-demon to use run-with-idle-timers.
17161 * Enhancements to Gnus:
17165 * gnus-servers (gnus-start-server-buffer?)--enters Gnus and goes
17166 straight to the server buffer, without opening any connections to
17169 * gnus-server-read-server-newsrc--produces a buffer very similar to
17170 the group buffer, but with only groups from that server listed;
17171 quitting this buffer returns to the server buffer.
17174 add a command to check the integrity of an nnfolder folder --
17175 go through the article numbers and see that there are no duplicates,
17179 `unsmileyfy-buffer' to undo smileification.
17182 a command to give all relevant info on an article, including all
17186 when doing `-request-accept-article', the backends should do
17187 the nnmail duplicate checking.
17190 allow `message-signature-file' to be a function to return the
17191 value of the signature file.
17194 In addition, I would love it if I could configure message-tab so that it
17195 could call `bbdb-complete-name' in other headers. So, some sort of
17198 (setq message-tab-alist
17199 '((message-header-regexp message-expand-group)
17200 ("^\\(To\\|[cC]c\\|[bB]cc\\)" bbdb-complete-name)))
17202 then you could run the relevant function to complete the information in
17206 cache the newsgroups file locally to avoid reloading it all the time.
17209 a command to import a buffer into a group.
17212 nnweb should allow fetching by Message-ID from servers.
17215 point in the article buffer doesn't always go to the
17216 beginning of the buffer when selecting new articles.
17219 a command to process mark all unread articles.
17222 `gnus-gather-threads-by-references-and-subject' -- first
17223 do gathering by references, and then go through the dummy roots and
17224 do more gathering by subject.
17227 gnus-uu-mark-in-numerical-order -- process mark articles in
17228 article numerical order.
17231 (gnus-thread-total-score
17232 (gnus-id-to-thread (mail-header-id (gnus-summary-article-header))))
17236 sorting by score is wrong when using sparse threads.
17239 a command to fetch an arbitrary article -- without having to be
17240 in the summary buffer.
17243 a new nncvs backend. Each group would show an article, using
17244 version branches as threading, checkin date as the date, etc.
17247 http://www.dejanews.com/forms/dnsetfilter_exp.html ?
17248 This filter allows one to construct advance queries on the Dejanews
17249 database such as specifying start and end dates, subject, author,
17250 and/or newsgroup name.
17253 new Date header scoring type -- older, newer
17256 use the summary toolbar in the article buffer.
17259 a command to fetch all articles that are less than X days old.
17262 in pick mode, `q' should save the list of selected articles in the
17263 group info. The next time the group is selected, these articles
17264 will automatically get the process mark.
17267 Isn't it possible to (also?) allow M-^ to automatically try the
17268 default server if it fails on the current server? (controlled by a
17269 user variable, (nil, t, 'ask)).
17272 make it possible to cancel articles using the select method for the
17276 `gnus-summary-select-article-on-entry' or something. It'll default
17277 to t and will select whatever article decided by `gnus-auto-select-first'.
17280 a new variable to control which selection commands should be unselecting.
17281 `first', `best', `next', `prev', `next-unread', `prev-unread' are
17285 be able to select groups that have no articles in them
17286 to be able to post in them (using the current select method).
17289 be able to post via DejaNews.
17292 `x' should retain any sortings that have been performed.
17295 allow the user to specify the presedence of the secondary marks. Also
17296 allow them to be displayed separately.
17299 gnus-summary-save-in-pipe should concatenate the results from
17300 the processes when doing a process marked pipe.
17303 a new match type, like Followup, but which adds Thread matches on all
17304 articles that match a certain From header.
17307 a function that can be read from kill-emacs-query-functions to offer
17308 saving living summary buffers.
17311 a function for selecting a particular group which will contain
17312 the articles listed in a list of article numbers/id's.
17315 a battery of character translation functions to translate common
17316 Mac, MS (etc) characters into ISO 8859-1.
17319 (defun article-fix-m$word ()
17320 "Fix M$Word smartquotes in an article."
17323 (let ((buffer-read-only nil))
17324 (goto-char (point-min))
17325 (while (search-forward "\221" nil t)
17326 (replace-match "`" t t))
17327 (goto-char (point-min))
17328 (while (search-forward "\222" nil t)
17329 (replace-match "'" t t))
17330 (goto-char (point-min))
17331 (while (search-forward "\223" nil t)
17332 (replace-match "\"" t t))
17333 (goto-char (point-min))
17334 (while (search-forward "\224" nil t)
17335 (replace-match "\"" t t)))))
17340 (add-hook 'gnus-exit-query-functions
17342 (if (and (file-exists-p nnmail-spool-file)
17343 (> (nnheader-file-size nnmail-spool-file) 0))
17344 (yes-or-no-p "New mail has arrived. Quit Gnus anyways? ")
17345 (y-or-n-p "Are you sure you want to quit Gnus? "))))
17349 allow message-default-headers to be a function.
17352 new Date score match types -- < > = (etc) that take floating point
17353 numbers and match on the age of the article.
17356 gnus-cacheable-groups
17360 > > > If so, I've got one gripe: It seems that when I fire up gnus 5.2.25
17361 > > > under xemacs-19.14, it's creating a new frame, but is erasing the
17362 > > > buffer in the frame that it was called from =:-O
17364 > > Hm. How do you start up Gnus? From the toolbar or with
17365 > > `M-x gnus-other-frame'?
17367 > I normally start it up from the toolbar; at
17368 > least that's the way I've caught it doing the
17373 all commands that react to the process mark should push
17374 the current process mark set onto the stack.
17377 gnus-article-hide-pgp
17378 Selv ville jeg nok ha valgt å slette den dersom teksten matcher
17380 "\\(This\s+\\)?[^ ]+ has been automatically signed by"
17382 og det er maks hundre tegn mellom match-end og ----linja. Men -det-
17383 er min type heuristikk og langt fra alles.
17386 `gnus-subscribe-sorted' -- insert new groups where they would have been
17387 sorted to if `gnus-group-sort-function' were run.
17390 gnus-(group,summary)-highlight should respect any `face' text props set
17394 use run-with-idle-timer for gnus-demon instead of the
17395 home-brewed stuff for better reliability.
17398 add a way to select which NoCeM type to apply -- spam, troll, etc.
17401 nndraft-request-group should tally autosave files.
17404 implement nntp-retry-on-break and nntp-command-timeout.
17407 gnus-article-highlight-limit that says when not to highlight (long)
17411 (nnoo-set SERVER VARIABLE VALUE)
17417 interrupitng agent fetching of articles should save articles.
17420 command to open a digest group, and copy all the articles there to the
17424 a variable to disable article body highlights if there's more than
17425 X characters in the body.
17428 handle 480/381 authinfo requests separately.
17431 include the texi/dir file in the distribution.
17434 format spec to "tab" to a position.
17437 Move all prompting to the new `M-n' default style.
17440 command to display all dormant articles.
17443 gnus-auto-select-next makeover -- list of things it should do.
17446 a score match type that adds scores matching on From if From has replied
17447 to something someone else has said.
17450 Read Netscape discussion groups:
17451 snews://secnews.netscape.com/netscape.communicator.unix
17454 One command to edit the original version if an article, and one to edit
17455 the displayed version.
17458 @kbd{T v} -- make all process-marked articles the children of the
17462 Switch from initial text to the new default text mechanism.
17465 How about making it possible to expire local articles? Will it be
17466 possible to make various constraints on when an article can be
17467 expired, e.g. (read), (age > 14 days), or the more interesting (read
17471 New limit command---limit to articles that have a certain string
17472 in the head or body.
17475 Allow breaking lengthy NNTP commands.
17478 gnus-article-highlight-limit, to disable highlighting in big articles.
17481 Editing an article should put the article to be edited
17482 in a special, unique buffer.
17485 A command to send a mail to the admin-address group param.
17488 Solve the halting problem.
17497 @section The Manual
17501 This manual was generated from a TeXinfo file and then run through
17502 either @code{texi2dvi}
17504 or my own home-brewed TeXinfo to \LaTeX\ transformer,
17505 and then run through @code{latex} and @code{dvips}
17507 to get what you hold in your hands now.
17509 The following conventions have been used:
17514 This is a @samp{string}
17517 This is a @kbd{keystroke}
17520 This is a @file{file}
17523 This is a @code{symbol}
17527 So if I were to say ``set @code{flargnoze} to @samp{yes}'', that would
17531 (setq flargnoze "yes")
17534 If I say ``set @code{flumphel} to @code{yes}'', that would mean:
17537 (setq flumphel 'yes)
17540 @samp{yes} and @code{yes} are two @emph{very} different things---don't
17541 ever get them confused.
17545 Of course, everything in this manual is of vital interest, so you should
17546 read it all. Several times. However, if you feel like skimming the
17547 manual, look for that gnu head you should see in the margin over
17548 there---it means that what's being discussed is of more importance than
17549 the rest of the stuff. (On the other hand, if everything is infinitely
17550 important, how can anything be more important than that? Just one more
17551 of the mysteries of this world, I guess.)
17559 @section Terminology
17561 @cindex terminology
17566 This is what you are supposed to use this thing for---reading news.
17567 News is generally fetched from a nearby @sc{nntp} server, and is
17568 generally publicly available to everybody. If you post news, the entire
17569 world is likely to read just what you have written, and they'll all
17570 snigger mischievously. Behind your back.
17574 Everything that's delivered to you personally is mail. Some news/mail
17575 readers (like Gnus) blur the distinction between mail and news, but
17576 there is a difference. Mail is private. News is public. Mailing is
17577 not posting, and replying is not following up.
17581 Send a mail to the person who has written what you are reading.
17585 Post an article to the current newsgroup responding to the article you
17590 Gnus gets fed articles from a number of backends, both news and mail
17591 backends. Gnus does not handle the underlying media, so to speak---this
17592 is all done by the backends.
17596 Gnus will always use one method (and backend) as the @dfn{native}, or
17597 default, way of getting news.
17601 You can also have any number of foreign groups active at the same time.
17602 These are groups that use non-native non-secondary backends for getting
17607 Secondary backends are somewhere half-way between being native and being
17608 foreign, but they mostly act like they are native.
17612 A message that has been posted as news.
17615 @cindex mail message
17616 A message that has been mailed.
17620 A mail message or news article
17624 The top part of a message, where administrative information (etc.) is
17629 The rest of an article. Everything not in the head is in the
17634 A line from the head of an article.
17638 A collection of such lines, or a collection of heads. Or even a
17639 collection of @sc{nov} lines.
17643 When Gnus enters a group, it asks the backend for the headers of all
17644 unread articles in the group. Most servers support the News OverView
17645 format, which is more compact and much faster to read and parse than the
17646 normal @sc{head} format.
17650 Each group is subscribed at some @dfn{level} or other (1-9). The ones
17651 that have a lower level are ``more'' subscribed than the groups with a
17652 higher level. In fact, groups on levels 1-5 are considered
17653 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
17654 are @dfn{killed}. Commands for listing groups and scanning for new
17655 articles will all use the numeric prefix as @dfn{working level}.
17657 @item killed groups
17658 @cindex killed groups
17659 No information on killed groups is stored or updated, which makes killed
17660 groups much easier to handle than subscribed groups.
17662 @item zombie groups
17663 @cindex zombie groups
17664 Just like killed groups, only slightly less dead.
17667 @cindex active file
17668 The news server has to keep track of what articles it carries, and what
17669 groups exist. All this information in stored in the active file, which
17670 is rather large, as you might surmise.
17673 @cindex bogus groups
17674 A group that exists in the @file{.newsrc} file, but isn't known to the
17675 server (i.e., it isn't in the active file), is a @emph{bogus group}.
17676 This means that the group probably doesn't exist (any more).
17679 @cindex activating groups
17680 The act of asking the server for info on a group and computing the
17681 number of unread articles is called @dfn{activating the group}.
17682 Un-activated groups are listed with @samp{*} in the group buffer.
17686 A machine one can connect to and get news (or mail) from.
17688 @item select method
17689 @cindex select method
17690 A structure that specifies the backend, the server and the virtual
17693 @item virtual server
17694 @cindex virtual server
17695 A named select method. Since a select method defines all there is to
17696 know about connecting to a (physical) server, taking the thing as a
17697 whole is a virtual server.
17701 Taking a buffer and running it through a filter of some sort. The
17702 result will (more often than not) be cleaner and more pleasing than the
17705 @item ephemeral groups
17706 @cindex ephemeral groups
17707 Most groups store data on what articles you have read. @dfn{Ephemeral}
17708 groups are groups that will have no data stored---when you exit the
17709 group, it'll disappear into the aether.
17712 @cindex solid groups
17713 This is the opposite of ephemeral groups. All groups listed in the
17714 group buffer are solid groups.
17716 @item sparse articles
17717 @cindex sparse articles
17718 These are article placeholders shown in the summary buffer when
17719 @code{gnus-build-sparse-threads} has been switched on.
17723 To put responses to articles directly after the articles they respond
17724 to---in a hierarchical fashion.
17728 @cindex thread root
17729 The first article in a thread is the root. It is the ancestor of all
17730 articles in the thread.
17734 An article that has responses.
17738 An article that responds to a different article---its parent.
17742 A collection of messages in one file. The most common digest format is
17743 specified by RFC1153.
17749 @node Customization
17750 @section Customization
17751 @cindex general customization
17753 All variables are properly documented elsewhere in this manual. This
17754 section is designed to give general pointers on how to customize Gnus
17755 for some quite common situations.
17758 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
17759 * Slow Terminal Connection:: You run a remote Emacs.
17760 * Little Disk Space:: You feel that having large setup files is icky.
17761 * Slow Machine:: You feel like buying a faster machine.
17765 @node Slow/Expensive Connection
17766 @subsection Slow/Expensive @sc{nntp} Connection
17768 If you run Emacs on a machine locally, and get your news from a machine
17769 over some very thin strings, you want to cut down on the amount of data
17770 Gnus has to get from the @sc{nntp} server.
17774 @item gnus-read-active-file
17775 Set this to @code{nil}, which will inhibit Gnus from requesting the
17776 entire active file from the server. This file is often v. large. You
17777 also have to set @code{gnus-check-new-newsgroups} and
17778 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
17779 doesn't suddenly decide to fetch the active file anyway.
17781 @item gnus-nov-is-evil
17782 This one has to be @code{nil}. If not, grabbing article headers from
17783 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
17784 support @sc{xover}; Gnus will detect this by itself.
17788 @node Slow Terminal Connection
17789 @subsection Slow Terminal Connection
17791 Let's say you use your home computer for dialing up the system that runs
17792 Emacs and Gnus. If your modem is slow, you want to reduce (as much as
17793 possible) the amount of data sent over the wires.
17797 @item gnus-auto-center-summary
17798 Set this to @code{nil} to inhibit Gnus from re-centering the summary
17799 buffer all the time. If it is @code{vertical}, do only vertical
17800 re-centering. If it is neither @code{nil} nor @code{vertical}, do both
17801 horizontal and vertical recentering.
17803 @item gnus-visible-headers
17804 Cut down on the headers included in the articles to the
17805 minimum. You can, in fact, make do without them altogether---most of the
17806 useful data is in the summary buffer, anyway. Set this variable to
17807 @samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need.
17809 @item gnus-article-display-hook
17810 Set this hook to all the available hiding commands:
17812 (setq gnus-article-display-hook
17813 '(gnus-article-hide-headers gnus-article-hide-signature
17814 gnus-article-hide-citation))
17817 @item gnus-use-full-window
17818 By setting this to @code{nil}, you can make all the windows smaller.
17819 While this doesn't really cut down much generally, it means that you
17820 have to see smaller portions of articles before deciding that you didn't
17821 want to read them anyway.
17823 @item gnus-thread-hide-subtree
17824 If this is non-@code{nil}, all threads in the summary buffer will be
17827 @item gnus-updated-mode-lines
17828 If this is @code{nil}, Gnus will not put information in the buffer mode
17829 lines, which might save some time.
17833 @node Little Disk Space
17834 @subsection Little Disk Space
17837 The startup files can get rather large, so you may want to cut their
17838 sizes a bit if you are running out of space.
17842 @item gnus-save-newsrc-file
17843 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
17844 only save @file{.newsrc.eld}. This means that you will not be able to
17845 use any other newsreaders than Gnus. This variable is @code{t} by
17848 @item gnus-save-killed-list
17849 If this is @code{nil}, Gnus will not save the list of dead groups. You
17850 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
17851 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
17852 variable to @code{nil}. This variable is @code{t} by default.
17858 @subsection Slow Machine
17859 @cindex slow machine
17861 If you have a slow machine, or are just really impatient, there are a
17862 few things you can do to make Gnus run faster.
17864 Set @code{gnus-check-new-newsgroups} and
17865 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
17867 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
17868 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
17869 summary buffer faster.
17871 Set @code{gnus-article-display-hook} to @code{nil} to make article
17872 processing a bit faster.
17876 @node Troubleshooting
17877 @section Troubleshooting
17878 @cindex troubleshooting
17880 Gnus works @emph{so} well straight out of the box---I can't imagine any
17888 Make sure your computer is switched on.
17891 Make sure that you really load the current Gnus version. If you have
17892 been running @sc{gnus}, you need to exit Emacs and start it up again before
17896 Try doing an @kbd{M-x gnus-version}. If you get something that looks
17897 like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
17898 on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
17899 flee}, you have some old @file{.el} files lying around. Delete these.
17902 Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
17906 @vindex max-lisp-eval-depth
17907 Gnus works on many recursive structures, and in some extreme (and very
17908 rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at
17909 you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or
17910 something like that.
17913 If all else fails, report the problem as a bug.
17916 @cindex reporting bugs
17918 @kindex M-x gnus-bug
17920 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
17921 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
17922 me the backtrace. I will fix bugs, but I can only fix them if you send
17923 me a precise description as to how to reproduce the bug.
17925 You really can never be too detailed in a bug report. Always use the
17926 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
17927 a 10Kb mail each time you use it, and even if you have sent me your
17928 environment 500 times before. I don't care. I want the full info each
17931 It is also important to remember that I have no memory whatsoever. If
17932 you send a bug report, and I send you a reply, and then you just send
17933 back ``No, it's not! Moron!'', I will have no idea what you are
17934 insulting me about. Always over-explain everything. It's much easier
17935 for all of us---if I don't have all the information I need, I will just
17936 mail you and ask for more info, and everything takes more time.
17938 If the problem you're seeing is very visual, and you can't quite explain
17939 it, copy the Emacs window to a file (with @code{xwd}, for instance), put
17940 it somewhere it can be reached, and include the URL of the picture in
17943 If you just need help, you are better off asking on
17944 @samp{gnu.emacs.gnus}. I'm not very helpful.
17946 @cindex gnu.emacs.gnus
17947 @cindex ding mailing list
17948 You can also ask on the ding mailing list---@samp{ding@@gnus.org}.
17949 Write to @samp{ding-request@@gnus.org} to subscribe.
17953 @node A Programmers Guide to Gnus
17954 @section A Programmer@'s Guide to Gnus
17956 It is my hope that other people will figure out smart stuff that Gnus
17957 can do, and that other people will write those smart things as well. To
17958 facilitate that I thought it would be a good idea to describe the inner
17959 workings of Gnus. And some of the not-so-inner workings, while I'm at
17962 You can never expect the internals of a program not to change, but I
17963 will be defining (in some details) the interface between Gnus and its
17964 backends (this is written in stone), the format of the score files
17965 (ditto), data structures (some are less likely to change than others)
17966 and general methods of operation.
17969 * Gnus Utility Functions:: Common functions and variable to use.
17970 * Backend Interface:: How Gnus communicates with the servers.
17971 * Score File Syntax:: A BNF definition of the score file standard.
17972 * Headers:: How Gnus stores headers internally.
17973 * Ranges:: A handy format for storing mucho numbers.
17974 * Group Info:: The group info format.
17975 * Extended Interactive:: Symbolic prefixes and stuff.
17976 * Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen.
17977 * Various File Formats:: Formats of files that Gnus use.
17981 @node Gnus Utility Functions
17982 @subsection Gnus Utility Functions
17983 @cindex Gnus utility functions
17984 @cindex utility functions
17986 @cindex internal variables
17988 When writing small functions to be run from hooks (and stuff), it's
17989 vital to have access to the Gnus internal functions and variables.
17990 Below is a list of the most common ones.
17994 @item gnus-newsgroup-name
17995 @vindex gnus-newsgroup-name
17996 This variable holds the name of the current newsgroup.
17998 @item gnus-find-method-for-group
17999 @findex gnus-find-method-for-group
18000 A function that returns the select method for @var{group}.
18002 @item gnus-group-real-name
18003 @findex gnus-group-real-name
18004 Takes a full (prefixed) Gnus group name, and returns the unprefixed
18007 @item gnus-group-prefixed-name
18008 @findex gnus-group-prefixed-name
18009 Takes an unprefixed group name and a select method, and returns the full
18010 (prefixed) Gnus group name.
18012 @item gnus-get-info
18013 @findex gnus-get-info
18014 Returns the group info list for @var{group}.
18016 @item gnus-add-current-to-buffer-list
18017 @findex gnus-add-current-to-buffer-list
18018 Adds the current buffer to the list of buffers to be killed on Gnus
18021 @item gnus-continuum-version
18022 @findex gnus-continuum-version
18023 Takes a Gnus version string as a parameter and returns a floating point
18024 number. Earlier versions will always get a lower number than later
18027 @item gnus-group-read-only-p
18028 @findex gnus-group-read-only-p
18029 Says whether @var{group} is read-only or not.
18031 @item gnus-news-group-p
18032 @findex gnus-news-group-p
18033 Says whether @var{group} came from a news backend.
18035 @item gnus-ephemeral-group-p
18036 @findex gnus-ephemeral-group-p
18037 Says whether @var{group} is ephemeral or not.
18039 @item gnus-server-to-method
18040 @findex gnus-server-to-method
18041 Returns the select method corresponding to @var{server}.
18043 @item gnus-server-equal
18044 @findex gnus-server-equal
18045 Says whether two virtual servers are equal.
18047 @item gnus-group-native-p
18048 @findex gnus-group-native-p
18049 Says whether @var{group} is native or not.
18051 @item gnus-group-secondary-p
18052 @findex gnus-group-secondary-p
18053 Says whether @var{group} is secondary or not.
18055 @item gnus-group-foreign-p
18056 @findex gnus-group-foreign-p
18057 Says whether @var{group} is foreign or not.
18059 @item group-group-find-parameter
18060 @findex group-group-find-parameter
18061 Returns the parameter list of @var{group}. If given a second parameter,
18062 returns the value of that parameter for @var{group}.
18064 @item gnus-group-set-parameter
18065 @findex gnus-group-set-parameter
18066 Takes three parameters; @var{group}, @var{parameter} and @var{value}.
18068 @item gnus-narrow-to-body
18069 @findex gnus-narrow-to-body
18070 Narrows the current buffer to the body of the article.
18072 @item gnus-check-backend-function
18073 @findex gnus-check-backend-function
18074 Takes two parameters, @var{function} and @var{group}. If the backend
18075 @var{group} comes from supports @var{function}, return non-@code{nil}.
18078 (gnus-check-backend-function "request-scan" "nnml:misc")
18082 @item gnus-read-method
18083 @findex gnus-read-method
18084 Prompts the user for a select method.
18089 @node Backend Interface
18090 @subsection Backend Interface
18092 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
18093 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
18094 server is a @dfn{backend} and some @dfn{backend variables}. As examples
18095 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
18096 examples of the latter we have @code{nntp-port-number} and
18097 @code{nnmbox-directory}.
18099 When Gnus asks for information from a backend---say @code{nntp}---on
18100 something, it will normally include a virtual server name in the
18101 function parameters. (If not, the backend should use the ``current''
18102 virtual server.) For instance, @code{nntp-request-list} takes a virtual
18103 server as its only (optional) parameter. If this virtual server hasn't
18104 been opened, the function should fail.
18106 Note that a virtual server name has no relation to some physical server
18107 name. Take this example:
18111 (nntp-address "ifi.uio.no")
18112 (nntp-port-number 4324))
18115 Here the virtual server name is @samp{odd-one} while the name of
18116 the physical server is @samp{ifi.uio.no}.
18118 The backends should be able to switch between several virtual servers.
18119 The standard backends implement this by keeping an alist of virtual
18120 server environments that they pull down/push up when needed.
18122 There are two groups of interface functions: @dfn{required functions},
18123 which must be present, and @dfn{optional functions}, which Gnus will
18124 always check for presence before attempting to call 'em.
18126 All these functions are expected to return data in the buffer
18127 @code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat
18128 unfortunately named, but we'll have to live with it. When I talk about
18129 @dfn{resulting data}, I always refer to the data in that buffer. When I
18130 talk about @dfn{return value}, I talk about the function value returned by
18131 the function call. Functions that fail should return @code{nil} as the
18134 Some backends could be said to be @dfn{server-forming} backends, and
18135 some might be said not to be. The latter are backends that generally
18136 only operate on one group at a time, and have no concept of ``server''
18137 -- they have a group, and they deliver info on that group and nothing
18140 In the examples and definitions I will refer to the imaginary backend
18143 @cindex @code{nnchoke}
18146 * Required Backend Functions:: Functions that must be implemented.
18147 * Optional Backend Functions:: Functions that need not be implemented.
18148 * Error Messaging:: How to get messages and report errors.
18149 * Writing New Backends:: Extending old backends.
18150 * Hooking New Backends Into Gnus:: What has to be done on the Gnus end.
18151 * Mail-like Backends:: Some tips on mail backends.
18155 @node Required Backend Functions
18156 @subsubsection Required Backend Functions
18160 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
18162 @var{articles} is either a range of article numbers or a list of
18163 @code{Message-ID}s. Current backends do not fully support either---only
18164 sequences (lists) of article numbers, and most backends do not support
18165 retrieval of @code{Message-ID}s. But they should try for both.
18167 The result data should either be HEADs or NOV lines, and the result
18168 value should either be @code{headers} or @code{nov} to reflect this.
18169 This might later be expanded to @code{various}, which will be a mixture
18170 of HEADs and NOV lines, but this is currently not supported by Gnus.
18172 If @var{fetch-old} is non-@code{nil} it says to try fetching "extra
18173 headers", in some meaning of the word. This is generally done by
18174 fetching (at most) @var{fetch-old} extra headers less than the smallest
18175 article number in @code{articles}, and filling the gaps as well. The
18176 presence of this parameter can be ignored if the backend finds it
18177 cumbersome to follow the request. If this is non-@code{nil} and not a
18178 number, do maximum fetches.
18180 Here's an example HEAD:
18183 221 1056 Article retrieved.
18184 Path: ifi.uio.no!sturles
18185 From: sturles@@ifi.uio.no (Sturle Sunde)
18186 Newsgroups: ifi.discussion
18187 Subject: Re: Something very droll
18188 Date: 27 Oct 1994 14:02:57 +0100
18189 Organization: Dept. of Informatics, University of Oslo, Norway
18191 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
18192 References: <38jdmq$4qu@@visbur.ifi.uio.no>
18193 NNTP-Posting-Host: holmenkollen.ifi.uio.no
18197 So a @code{headers} return value would imply that there's a number of
18198 these in the data buffer.
18200 Here's a BNF definition of such a buffer:
18204 head = error / valid-head
18205 error-message = [ "4" / "5" ] 2number " " <error message> eol
18206 valid-head = valid-message *header "." eol
18207 valid-message = "221 " <number> " Article retrieved." eol
18208 header = <text> eol
18211 If the return value is @code{nov}, the data buffer should contain
18212 @dfn{network overview database} lines. These are basically fields
18216 nov-buffer = *nov-line
18217 nov-line = 8*9 [ field <TAB> ] eol
18218 field = <text except TAB>
18221 For a closer look at what should be in those fields,
18225 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
18227 @var{server} is here the virtual server name. @var{definitions} is a
18228 list of @code{(VARIABLE VALUE)} pairs that define this virtual server.
18230 If the server can't be opened, no error should be signaled. The backend
18231 may then choose to refuse further attempts at connecting to this
18232 server. In fact, it should do so.
18234 If the server is opened already, this function should return a
18235 non-@code{nil} value. There should be no data returned.
18238 @item (nnchoke-close-server &optional SERVER)
18240 Close connection to @var{server} and free all resources connected
18241 to it. Return @code{nil} if the server couldn't be closed for some
18244 There should be no data returned.
18247 @item (nnchoke-request-close)
18249 Close connection to all servers and free all resources that the backend
18250 have reserved. All buffers that have been created by that backend
18251 should be killed. (Not the @code{nntp-server-buffer}, though.) This
18252 function is generally only called when Gnus is shutting down.
18254 There should be no data returned.
18257 @item (nnchoke-server-opened &optional SERVER)
18259 If @var{server} is the current virtual server, and the connection to the
18260 physical server is alive, then this function should return a
18261 non-@code{nil} vlue. This function should under no circumstances
18262 attempt to reconnect to a server we have lost connection to.
18264 There should be no data returned.
18267 @item (nnchoke-status-message &optional SERVER)
18269 This function should return the last error message from @var{server}.
18271 There should be no data returned.
18274 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
18276 The result data from this function should be the article specified by
18277 @var{article}. This might either be a @code{Message-ID} or a number.
18278 It is optional whether to implement retrieval by @code{Message-ID}, but
18279 it would be nice if that were possible.
18281 If @var{to-buffer} is non-@code{nil}, the result data should be returned
18282 in this buffer instead of the normal data buffer. This is to make it
18283 possible to avoid copying large amounts of data from one buffer to
18284 another, while Gnus mainly requests articles to be inserted directly
18285 into its article buffer.
18287 If it is at all possible, this function should return a cons cell where
18288 the @code{car} is the group name the article was fetched from, and the @code{cdr} is
18289 the article number. This will enable Gnus to find out what the real
18290 group and article numbers are when fetching articles by
18291 @code{Message-ID}. If this isn't possible, @code{t} should be returned
18292 on successful article retrieval.
18295 @item (nnchoke-request-group GROUP &optional SERVER FAST)
18297 Get data on @var{group}. This function also has the side effect of
18298 making @var{group} the current group.
18300 If @var{FAST}, don't bother to return useful data, just make @var{group}
18303 Here's an example of some result data and a definition of the same:
18306 211 56 1000 1059 ifi.discussion
18309 The first number is the status, which should be 211. Next is the
18310 total number of articles in the group, the lowest article number, the
18311 highest article number, and finally the group name. Note that the total
18312 number of articles may be less than one might think while just
18313 considering the highest and lowest article numbers, but some articles
18314 may have been canceled. Gnus just discards the total-number, so
18315 whether one should take the bother to generate it properly (if that is a
18316 problem) is left as an exercise to the reader.
18319 group-status = [ error / info ] eol
18320 error = [ "4" / "5" ] 2<number> " " <Error message>
18321 info = "211 " 3* [ <number> " " ] <string>
18325 @item (nnchoke-close-group GROUP &optional SERVER)
18327 Close @var{group} and free any resources connected to it. This will be
18328 a no-op on most backends.
18330 There should be no data returned.
18333 @item (nnchoke-request-list &optional SERVER)
18335 Return a list of all groups available on @var{server}. And that means
18338 Here's an example from a server that only carries two groups:
18341 ifi.test 0000002200 0000002000 y
18342 ifi.discussion 3324 3300 n
18345 On each line we have a group name, then the highest article number in
18346 that group, the lowest article number, and finally a flag.
18349 active-file = *active-line
18350 active-line = name " " <number> " " <number> " " flags eol
18352 flags = "n" / "y" / "m" / "x" / "j" / "=" name
18355 The flag says whether the group is read-only (@samp{n}), is moderated
18356 (@samp{m}), is dead (@samp{x}), is aliased to some other group
18357 (@samp{=other-group}) or none of the above (@samp{y}).
18360 @item (nnchoke-request-post &optional SERVER)
18362 This function should post the current buffer. It might return whether
18363 the posting was successful or not, but that's not required. If, for
18364 instance, the posting is done asynchronously, it has generally not been
18365 completed by the time this function concludes. In that case, this
18366 function should set up some kind of sentinel to beep the user loud and
18367 clear if the posting could not be completed.
18369 There should be no result data from this function.
18374 @node Optional Backend Functions
18375 @subsubsection Optional Backend Functions
18379 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
18381 @var{groups} is a list of groups, and this function should request data
18382 on all those groups. How it does it is of no concern to Gnus, but it
18383 should attempt to do this in a speedy fashion.
18385 The return value of this function can be either @code{active} or
18386 @code{group}, which says what the format of the result data is. The
18387 former is in the same format as the data from
18388 @code{nnchoke-request-list}, while the latter is a buffer full of lines
18389 in the same format as @code{nnchoke-request-group} gives.
18392 group-buffer = *active-line / *group-status
18396 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
18398 A Gnus group info (@pxref{Group Info}) is handed to the backend for
18399 alterations. This comes in handy if the backend really carries all the
18400 information (as is the case with virtual and imap groups). This
18401 function should destructively alter the info to suit its needs, and
18402 should return the (altered) group info.
18404 There should be no result data from this function.
18407 @item (nnchoke-request-type GROUP &optional ARTICLE)
18409 When the user issues commands for ``sending news'' (@kbd{F} in the
18410 summary buffer, for instance), Gnus has to know whether the article the
18411 user is following up on is news or mail. This function should return
18412 @code{news} if @var{article} in @var{group} is news, @code{mail} if it
18413 is mail and @code{unknown} if the type can't be decided. (The
18414 @var{article} parameter is necessary in @code{nnvirtual} groups which
18415 might very well combine mail groups and news groups.) Both @var{group}
18416 and @var{article} may be @code{nil}.
18418 There should be no result data from this function.
18421 @item (nnchoke-request-update-mark GROUP ARTICLE MARK)
18423 If the user tries to set a mark that the backend doesn't like, this
18424 function may change the mark. Gnus will use whatever this function
18425 returns as the mark for @var{article} instead of the original
18426 @var{mark}. If the backend doesn't care, it must return the original
18427 @var{mark}, and not @code{nil} or any other type of garbage.
18429 The only use for this I can see is what @code{nnvirtual} does with
18430 it---if a component group is auto-expirable, marking an article as read
18431 in the virtual group should result in the article being marked as
18434 There should be no result data from this function.
18437 @item (nnchoke-request-scan &optional GROUP SERVER)
18439 This function may be called at any time (by Gnus or anything else) to
18440 request that the backend check for incoming articles, in one way or
18441 another. A mail backend will typically read the spool file or query the
18442 POP server when this function is invoked. The @var{group} doesn't have
18443 to be heeded---if the backend decides that it is too much work just
18444 scanning for a single group, it may do a total scan of all groups. It
18445 would be nice, however, to keep things local if that's practical.
18447 There should be no result data from this function.
18450 @item (nnchoke-request-group-description GROUP &optional SERVER)
18452 The result data from this function should be a description of
18456 description-line = name <TAB> description eol
18458 description = <text>
18461 @item (nnchoke-request-list-newsgroups &optional SERVER)
18463 The result data from this function should be the description of all
18464 groups available on the server.
18467 description-buffer = *description-line
18471 @item (nnchoke-request-newgroups DATE &optional SERVER)
18473 The result data from this function should be all groups that were
18474 created after @samp{date}, which is in normal human-readable date
18475 format. The data should be in the active buffer format.
18478 @item (nnchoke-request-create-group GROUP &optional SERVER)
18480 This function should create an empty group with name @var{group}.
18482 There should be no return data.
18485 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
18487 This function should run the expiry process on all articles in the
18488 @var{articles} range (which is currently a simple list of article
18489 numbers.) It is left up to the backend to decide how old articles
18490 should be before they are removed by this function. If @var{force} is
18491 non-@code{nil}, all @var{articles} should be deleted, no matter how new
18494 This function should return a list of articles that it did not/was not
18497 There should be no result data returned.
18500 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
18503 This function should move @var{article} (which is a number) from
18504 @var{group} by calling @var{accept-form}.
18506 This function should ready the article in question for moving by
18507 removing any header lines it has added to the article, and generally
18508 should ``tidy up'' the article. Then it should @code{eval}
18509 @var{accept-form} in the buffer where the ``tidy'' article is. This
18510 will do the actual copying. If this @code{eval} returns a
18511 non-@code{nil} value, the article should be removed.
18513 If @var{last} is @code{nil}, that means that there is a high likelihood
18514 that there will be more requests issued shortly, so that allows some
18517 The function should return a cons where the @code{car} is the group name and
18518 the @code{cdr} is the article number that the article was entered as.
18520 There should be no data returned.
18523 @item (nnchoke-request-accept-article GROUP &optional SERVER LAST)
18525 This function takes the current buffer and inserts it into @var{group}.
18526 If @var{last} in @code{nil}, that means that there will be more calls to
18527 this function in short order.
18529 The function should return a cons where the @code{car} is the group name and
18530 the @code{cdr} is the article number that the article was entered as.
18532 There should be no data returned.
18535 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
18537 This function should remove @var{article} (which is a number) from
18538 @var{group} and insert @var{buffer} there instead.
18540 There should be no data returned.
18543 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
18545 This function should delete @var{group}. If @var{force}, it should
18546 really delete all the articles in the group, and then delete the group
18547 itself. (If there is such a thing as ``the group itself''.)
18549 There should be no data returned.
18552 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
18554 This function should rename @var{group} into @var{new-name}. All
18555 articles in @var{group} should move to @var{new-name}.
18557 There should be no data returned.
18562 @node Error Messaging
18563 @subsubsection Error Messaging
18565 @findex nnheader-report
18566 @findex nnheader-get-report
18567 The backends should use the function @code{nnheader-report} to report
18568 error conditions---they should not raise errors when they aren't able to
18569 perform a request. The first argument to this function is the backend
18570 symbol, and the rest are interpreted as arguments to @code{format} if
18571 there are multiple of them, or just a string if there is one of them.
18572 This function must always returns @code{nil}.
18575 (nnheader-report 'nnchoke "You did something totally bogus")
18577 (nnheader-report 'nnchoke "Could not request group %s" group)
18580 Gnus, in turn, will call @code{nnheader-get-report} when it gets a
18581 @code{nil} back from a server, and this function returns the most
18582 recently reported message for the backend in question. This function
18583 takes one argument---the server symbol.
18585 Internally, these functions access @var{backend}@code{-status-string},
18586 so the @code{nnchoke} backend will have its error message stored in
18587 @code{nnchoke-status-string}.
18590 @node Writing New Backends
18591 @subsubsection Writing New Backends
18593 Many backends are quite similar. @code{nnml} is just like
18594 @code{nnspool}, but it allows you to edit the articles on the server.
18595 @code{nnmh} is just like @code{nnml}, but it doesn't use an active file,
18596 and it doesn't maintain overview databases. @code{nndir} is just like
18597 @code{nnml}, but it has no concept of ``groups'', and it doesn't allow
18600 It would make sense if it were possible to ``inherit'' functions from
18601 backends when writing new backends. And, indeed, you can do that if you
18602 want to. (You don't have to if you don't want to, of course.)
18604 All the backends declare their public variables and functions by using a
18605 package called @code{nnoo}.
18607 To inherit functions from other backends (and allow other backends to
18608 inherit functions from the current backend), you should use the
18614 This macro declares the first parameter to be a child of the subsequent
18615 parameters. For instance:
18618 (nnoo-declare nndir
18622 @code{nndir} has declared here that it intends to inherit functions from
18623 both @code{nnml} and @code{nnmh}.
18626 This macro is equivalent to @code{defvar}, but registers the variable as
18627 a public server variable. Most state-oriented variables should be
18628 declared with @code{defvoo} instead of @code{defvar}.
18630 In addition to the normal @code{defvar} parameters, it takes a list of
18631 variables in the parent backends to map the variable to when executing
18632 a function in those backends.
18635 (defvoo nndir-directory nil
18636 "Where nndir will look for groups."
18637 nnml-current-directory nnmh-current-directory)
18640 This means that @code{nnml-current-directory} will be set to
18641 @code{nndir-directory} when an @code{nnml} function is called on behalf
18642 of @code{nndir}. (The same with @code{nnmh}.)
18644 @item nnoo-define-basics
18645 This macro defines some common functions that almost all backends should
18649 (nnoo-define-basics nndir)
18653 This macro is just like @code{defun} and takes the same parameters. In
18654 addition to doing the normal @code{defun} things, it registers the
18655 function as being public so that other backends can inherit it.
18657 @item nnoo-map-functions
18658 This macro allows mapping of functions from the current backend to
18659 functions from the parent backends.
18662 (nnoo-map-functions nndir
18663 (nnml-retrieve-headers 0 nndir-current-group 0 0)
18664 (nnmh-request-article 0 nndir-current-group 0 0))
18667 This means that when @code{nndir-retrieve-headers} is called, the first,
18668 third, and fourth parameters will be passed on to
18669 @code{nnml-retrieve-headers}, while the second parameter is set to the
18670 value of @code{nndir-current-group}.
18673 This macro allows importing functions from backends. It should be the
18674 last thing in the source file, since it will only define functions that
18675 haven't already been defined.
18681 nnmh-request-newgroups)
18685 This means that calls to @code{nndir-request-list} should just be passed
18686 on to @code{nnmh-request-list}, while all public functions from
18687 @code{nnml} that haven't been defined in @code{nndir} yet should be
18692 Below is a slightly shortened version of the @code{nndir} backend.
18695 ;;; nndir.el --- single directory newsgroup access for Gnus
18696 ;; Copyright (C) 1995,96 Free Software Foundation, Inc.
18700 (require 'nnheader)
18704 (eval-when-compile (require 'cl))
18706 (nnoo-declare nndir
18709 (defvoo nndir-directory nil
18710 "Where nndir will look for groups."
18711 nnml-current-directory nnmh-current-directory)
18713 (defvoo nndir-nov-is-evil nil
18714 "*Non-nil means that nndir will never retrieve NOV headers."
18717 (defvoo nndir-current-group "" nil nnml-current-group nnmh-current-group)
18718 (defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
18719 (defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)
18721 (defvoo nndir-status-string "" nil nnmh-status-string)
18722 (defconst nndir-version "nndir 1.0")
18724 ;;; Interface functions.
18726 (nnoo-define-basics nndir)
18728 (deffoo nndir-open-server (server &optional defs)
18729 (setq nndir-directory
18730 (or (cadr (assq 'nndir-directory defs))
18732 (unless (assq 'nndir-directory defs)
18733 (push `(nndir-directory ,server) defs))
18734 (push `(nndir-current-group
18735 ,(file-name-nondirectory (directory-file-name nndir-directory)))
18737 (push `(nndir-top-directory
18738 ,(file-name-directory (directory-file-name nndir-directory)))
18740 (nnoo-change-server 'nndir server defs))
18742 (nnoo-map-functions nndir
18743 (nnml-retrieve-headers 0 nndir-current-group 0 0)
18744 (nnmh-request-article 0 nndir-current-group 0 0)
18745 (nnmh-request-group nndir-current-group 0 0)
18746 (nnmh-close-group nndir-current-group 0))
18750 nnmh-status-message
18752 nnmh-request-newgroups))
18758 @node Hooking New Backends Into Gnus
18759 @subsubsection Hooking New Backends Into Gnus
18761 @vindex gnus-valid-select-methods
18762 Having Gnus start using your new backend is rather easy---you just
18763 declare it with the @code{gnus-declare-backend} functions. This will
18764 enter the backend into the @code{gnus-valid-select-methods} variable.
18766 @code{gnus-declare-backend} takes two parameters---the backend name and
18767 an arbitrary number of @dfn{abilities}.
18772 (gnus-declare-backend "nnchoke" 'mail 'respool 'address)
18775 The abilities can be:
18779 This is a mailish backend---followups should (probably) go via mail.
18781 This is a newsish backend---followups should (probably) go via news.
18783 This backend supports both mail and news.
18785 This is neither a post nor mail backend---it's something completely
18788 It supports respooling---or rather, it is able to modify its source
18789 articles and groups.
18791 The name of the server should be in the virtual server name. This is
18792 true for almost all backends.
18793 @item prompt-address
18794 The user should be prompted for an address when doing commands like
18795 @kbd{B} in the group buffer. This is true for backends like
18796 @code{nntp}, but not @code{nnmbox}, for instance.
18800 @node Mail-like Backends
18801 @subsubsection Mail-like Backends
18803 One of the things that separate the mail backends from the rest of the
18804 backends is the heavy dependence by the mail backends on common
18805 functions in @file{nnmail.el}. For instance, here's the definition of
18806 @code{nnml-request-scan}:
18809 (deffoo nnml-request-scan (&optional group server)
18810 (setq nnml-article-file-alist nil)
18811 (nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group))
18814 It simply calls @code{nnmail-get-new-mail} with a few parameters,
18815 and @code{nnmail} takes care of all the moving and splitting of the
18818 This function takes four parameters.
18822 This should be a symbol to designate which backend is responsible for
18825 @item exit-function
18826 This function should be called after the splitting has been performed.
18828 @item temp-directory
18829 Where the temporary files should be stored.
18832 This optional argument should be a group name if the splitting is to be
18833 performed for one group only.
18836 @code{nnmail-get-new-mail} will call @var{backend}@code{-save-mail} to
18837 save each article. @var{backend}@code{-active-number} will be called to
18838 find the article number assigned to this article.
18840 The function also uses the following variables:
18841 @var{backend}@code{-get-new-mail} (to see whether to get new mail for
18842 this backend); and @var{backend}@code{-group-alist} and
18843 @var{backend}@code{-active-file} to generate the new active file.
18844 @var{backend}@code{-group-alist} should be a group-active alist, like
18848 (("a-group" (1 . 10))
18849 ("some-group" (34 . 39)))
18853 @node Score File Syntax
18854 @subsection Score File Syntax
18856 Score files are meant to be easily parsable, but yet extremely
18857 mallable. It was decided that something that had the same read syntax
18858 as an Emacs Lisp list would fit that spec.
18860 Here's a typical score file:
18864 ("win95" -10000 nil s)
18871 BNF definition of a score file:
18874 score-file = "" / "(" *element ")"
18875 element = rule / atom
18876 rule = string-rule / number-rule / date-rule
18877 string-rule = "(" quote string-header quote space *string-match ")"
18878 number-rule = "(" quote number-header quote space *number-match ")"
18879 date-rule = "(" quote date-header quote space *date-match ")"
18881 string-header = "subject" / "from" / "references" / "message-id" /
18882 "xref" / "body" / "head" / "all" / "followup"
18883 number-header = "lines" / "chars"
18884 date-header = "date"
18885 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
18886 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
18887 score = "nil" / <integer>
18888 date = "nil" / <natural number>
18889 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
18890 "r" / "regex" / "R" / "Regex" /
18891 "e" / "exact" / "E" / "Exact" /
18892 "f" / "fuzzy" / "F" / "Fuzzy"
18893 number-match = "(" <integer> [ "" / [ space score [ "" /
18894 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
18895 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
18896 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
18897 space date [ "" / [ space date-match-t ] ] ] ] ")"
18898 date-match-t = "nil" / "at" / "before" / "after"
18899 atom = "(" [ required-atom / optional-atom ] ")"
18900 required-atom = mark / expunge / mark-and-expunge / files /
18901 exclude-files / read-only / touched
18902 optional-atom = adapt / local / eval
18903 mark = "mark" space nil-or-number
18904 nil-or-number = "nil" / <integer>
18905 expunge = "expunge" space nil-or-number
18906 mark-and-expunge = "mark-and-expunge" space nil-or-number
18907 files = "files" *[ space <string> ]
18908 exclude-files = "exclude-files" *[ space <string> ]
18909 read-only = "read-only" [ space "nil" / space "t" ]
18910 adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ]
18911 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
18912 local = "local" *[ space "(" <string> space <form> ")" ]
18913 eval = "eval" space <form>
18914 space = *[ " " / <TAB> / <NEWLINE> ]
18917 Any unrecognized elements in a score file should be ignored, but not
18920 As you can see, white space is needed, but the type and amount of white
18921 space is irrelevant. This means that formatting of the score file is
18922 left up to the programmer---if it's simpler to just spew it all out on
18923 one looong line, then that's ok.
18925 The meaning of the various atoms are explained elsewhere in this
18926 manual (@pxref{Score File Format}).
18930 @subsection Headers
18932 Internally Gnus uses a format for storing article headers that
18933 corresponds to the @sc{nov} format in a mysterious fashion. One could
18934 almost suspect that the author looked at the @sc{nov} specification and
18935 just shamelessly @emph{stole} the entire thing, and one would be right.
18937 @dfn{Header} is a severely overloaded term. ``Header'' is used in
18938 RFC1036 to talk about lines in the head of an article (e.g.,
18939 @code{From}). It is used by many people as a synonym for
18940 ``head''---``the header and the body''. (That should be avoided, in my
18941 opinion.) And Gnus uses a format internally that it calls ``header'',
18942 which is what I'm talking about here. This is a 9-element vector,
18943 basically, with each header (ouch) having one slot.
18945 These slots are, in order: @code{number}, @code{subject}, @code{from},
18946 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
18947 @code{xref}. There are macros for accessing and setting these
18948 slots---they all have predictable names beginning with
18949 @code{mail-header-} and @code{mail-header-set-}, respectively.
18951 The @code{xref} slot is really a @code{misc} slot. Any extra info will
18958 @sc{gnus} introduced a concept that I found so useful that I've started
18959 using it a lot and have elaborated on it greatly.
18961 The question is simple: If you have a large amount of objects that are
18962 identified by numbers (say, articles, to take a @emph{wild} example)
18963 that you want to qualify as being ``included'', a normal sequence isn't
18964 very useful. (A 200,000 length sequence is a bit long-winded.)
18966 The solution is as simple as the question: You just collapse the
18970 (1 2 3 4 5 6 10 11 12)
18973 is transformed into
18976 ((1 . 6) (10 . 12))
18979 To avoid having those nasty @samp{(13 . 13)} elements to denote a
18980 lonesome object, a @samp{13} is a valid element:
18983 ((1 . 6) 7 (10 . 12))
18986 This means that comparing two ranges to find out whether they are equal
18987 is slightly tricky:
18990 ((1 . 5) 7 8 (10 . 12))
18996 ((1 . 5) (7 . 8) (10 . 12))
18999 are equal. In fact, any non-descending list is a range:
19005 is a perfectly valid range, although a pretty long-winded one. This is
19012 and is equal to the previous range.
19014 Here's a BNF definition of ranges. Of course, one must remember the
19015 semantic requirement that the numbers are non-descending. (Any number
19016 of repetition of the same number is allowed, but apt to disappear in
19020 range = simple-range / normal-range
19021 simple-range = "(" number " . " number ")"
19022 normal-range = "(" start-contents ")"
19023 contents = "" / simple-range *[ " " contents ] /
19024 number *[ " " contents ]
19027 Gnus currently uses ranges to keep track of read articles and article
19028 marks. I plan on implementing a number of range operators in C if The
19029 Powers That Be are willing to let me. (I haven't asked yet, because I
19030 need to do some more thinking on what operators I need to make life
19031 totally range-based without ever having to convert back to normal
19036 @subsection Group Info
19038 Gnus stores all permanent info on groups in a @dfn{group info} list.
19039 This list is from three to six elements (or more) long and exhaustively
19040 describes the group.
19042 Here are two example group infos; one is a very simple group while the
19043 second is a more complex one:
19046 ("no.group" 5 (1 . 54324))
19048 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
19049 ((tick (15 . 19)) (replied 3 6 (19 . 3)))
19051 ((auto-expire . t) (to-address . "ding@@gnus.org")))
19054 The first element is the @dfn{group name}---as Gnus knows the group,
19055 anyway. The second element is the @dfn{subscription level}, which
19056 normally is a small integer. (It can also be the @dfn{rank}, which is a
19057 cons cell where the @code{car} is the level and the @code{cdr} is the
19058 score.) The third element is a list of ranges of read articles. The
19059 fourth element is a list of lists of article marks of various kinds.
19060 The fifth element is the select method (or virtual server, if you like).
19061 The sixth element is a list of @dfn{group parameters}, which is what
19062 this section is about.
19064 Any of the last three elements may be missing if they are not required.
19065 In fact, the vast majority of groups will normally only have the first
19066 three elements, which saves quite a lot of cons cells.
19068 Here's a BNF definition of the group info format:
19071 info = "(" group space ralevel space read
19072 [ "" / [ space marks-list [ "" / [ space method [ "" /
19073 space parameters ] ] ] ] ] ")"
19074 group = quote <string> quote
19075 ralevel = rank / level
19076 level = <integer in the range of 1 to inf>
19077 rank = "(" level "." score ")"
19078 score = <integer in the range of 1 to inf>
19080 marks-lists = nil / "(" *marks ")"
19081 marks = "(" <string> range ")"
19082 method = "(" <string> *elisp-forms ")"
19083 parameters = "(" *elisp-forms ")"
19086 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
19087 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
19090 If you have a Gnus info and want to access the elements, Gnus offers a
19091 series of macros for getting/setting these elements.
19094 @item gnus-info-group
19095 @itemx gnus-info-set-group
19096 @findex gnus-info-group
19097 @findex gnus-info-set-group
19098 Get/set the group name.
19100 @item gnus-info-rank
19101 @itemx gnus-info-set-rank
19102 @findex gnus-info-rank
19103 @findex gnus-info-set-rank
19104 Get/set the group rank (@pxref{Group Score}).
19106 @item gnus-info-level
19107 @itemx gnus-info-set-level
19108 @findex gnus-info-level
19109 @findex gnus-info-set-level
19110 Get/set the group level.
19112 @item gnus-info-score
19113 @itemx gnus-info-set-score
19114 @findex gnus-info-score
19115 @findex gnus-info-set-score
19116 Get/set the group score (@pxref{Group Score}).
19118 @item gnus-info-read
19119 @itemx gnus-info-set-read
19120 @findex gnus-info-read
19121 @findex gnus-info-set-read
19122 Get/set the ranges of read articles.
19124 @item gnus-info-marks
19125 @itemx gnus-info-set-marks
19126 @findex gnus-info-marks
19127 @findex gnus-info-set-marks
19128 Get/set the lists of ranges of marked articles.
19130 @item gnus-info-method
19131 @itemx gnus-info-set-method
19132 @findex gnus-info-method
19133 @findex gnus-info-set-method
19134 Get/set the group select method.
19136 @item gnus-info-params
19137 @itemx gnus-info-set-params
19138 @findex gnus-info-params
19139 @findex gnus-info-set-params
19140 Get/set the group parameters.
19143 All the getter functions take one parameter---the info list. The setter
19144 functions take two parameters---the info list and the new value.
19146 The last three elements in the group info aren't mandatory, so it may be
19147 necessary to extend the group info before setting the element. If this
19148 is necessary, you can just pass on a non-@code{nil} third parameter to
19149 the three final setter functions to have this happen automatically.
19152 @node Extended Interactive
19153 @subsection Extended Interactive
19154 @cindex interactive
19155 @findex gnus-interactive
19157 Gnus extends the standard Emacs @code{interactive} specification
19158 slightly to allow easy use of the symbolic prefix (@pxref{Symbolic
19159 Prefixes}). Here's an example of how this is used:
19162 (defun gnus-summary-increase-score (&optional score symp)
19163 (interactive (gnus-interactive "P\ny"))
19168 The best thing to do would have been to implement
19169 @code{gnus-interactive} as a macro which would have returned an
19170 @code{interactive} form, but this isn't possible since Emacs checks
19171 whether a function is interactive or not by simply doing an @code{assq}
19172 on the lambda form. So, instead we have @code{gnus-interactive}
19173 function that takes a string and returns values that are usable to
19174 @code{interactive}.
19176 This function accepts (almost) all normal @code{interactive} specs, but
19181 @vindex gnus-current-prefix-symbol
19182 The current symbolic prefix---the @code{gnus-current-prefix-symbol}
19186 @vindex gnus-current-prefix-symbols
19187 A list of the current symbolic prefixes---the
19188 @code{gnus-current-prefix-symbol} variable.
19191 The current article number---the @code{gnus-summary-article-number}
19195 The current article header---the @code{gnus-summary-article-header}
19199 The current group name---the @code{gnus-group-group-name}
19205 @node Emacs/XEmacs Code
19206 @subsection Emacs/XEmacs Code
19210 While Gnus runs under Emacs, XEmacs and Mule, I decided that one of the
19211 platforms must be the primary one. I chose Emacs. Not because I don't
19212 like XEmacs or Mule, but because it comes first alphabetically.
19214 This means that Gnus will byte-compile under Emacs with nary a warning,
19215 while XEmacs will pump out gigabytes of warnings while byte-compiling.
19216 As I use byte-compilation warnings to help me root out trivial errors in
19217 Gnus, that's very useful.
19219 I've also consistently used Emacs function interfaces, but have used
19220 Gnusey aliases for the functions. To take an example: Emacs defines a
19221 @code{run-at-time} function while XEmacs defines a @code{start-itimer}
19222 function. I then define a function called @code{gnus-run-at-time} that
19223 takes the same parameters as the Emacs @code{run-at-time}. When running
19224 Gnus under Emacs, the former function is just an alias for the latter.
19225 However, when running under XEmacs, the former is an alias for the
19226 following function:
19229 (defun gnus-xmas-run-at-time (time repeat function &rest args)
19233 (,function ,@@args))
19237 This sort of thing has been done for bunches of functions. Gnus does
19238 not redefine any native Emacs functions while running under XEmacs---it
19239 does this @code{defalias} thing with Gnus equivalents instead. Cleaner
19242 In the cases where the XEmacs function interface was obviously cleaner,
19243 I used it instead. For example @code{gnus-region-active-p} is an alias
19244 for @code{region-active-p} in XEmacs, whereas in Emacs it is a function.
19246 Of course, I could have chosen XEmacs as my native platform and done
19247 mapping functions the other way around. But I didn't. The performance
19248 hit these indirections impose on Gnus under XEmacs should be slight.
19251 @node Various File Formats
19252 @subsection Various File Formats
19255 * Active File Format:: Information on articles and groups available.
19256 * Newsgroups File Format:: Group descriptions.
19260 @node Active File Format
19261 @subsubsection Active File Format
19263 The active file lists all groups available on the server in
19264 question. It also lists the highest and lowest current article numbers
19267 Here's an excerpt from a typical active file:
19270 soc.motss 296030 293865 y
19271 alt.binaries.pictures.fractals 3922 3913 n
19272 comp.sources.unix 1605 1593 m
19273 comp.binaries.ibm.pc 5097 5089 y
19274 no.general 1000 900 y
19277 Here's a pseudo-BNF definition of this file:
19280 active = *group-line
19281 group-line = group space high-number space low-number space flag <NEWLINE>
19282 group = <non-white-space string>
19284 high-number = <non-negative integer>
19285 low-number = <positive integer>
19286 flag = "y" / "n" / "m" / "j" / "x" / "=" group
19289 For a full description of this file, see the manual pages for
19290 @samp{innd}, in particular @samp{active(5)}.
19293 @node Newsgroups File Format
19294 @subsubsection Newsgroups File Format
19296 The newsgroups file lists groups along with their descriptions. Not all
19297 groups on the server have to be listed, and not all groups in the file
19298 have to exist on the server. The file is meant purely as information to
19301 The format is quite simple; a group name, a tab, and the description.
19302 Here's the definition:
19306 line = group tab description <NEWLINE>
19307 group = <non-white-space string>
19309 description = <string>
19314 @node Emacs for Heathens
19315 @section Emacs for Heathens
19317 Believe it or not, but some people who use Gnus haven't really used
19318 Emacs much before they embarked on their journey on the Gnus Love Boat.
19319 If you are one of those unfortunates whom ``@kbd{M-C-a}'', ``kill the
19320 region'', and ``set @code{gnus-flargblossen} to an alist where the key
19321 is a regexp that is used for matching on the group name'' are magical
19322 phrases with little or no meaning, then this appendix is for you. If
19323 you are already familiar with Emacs, just ignore this and go fondle your
19327 * Keystrokes:: Entering text and executing commands.
19328 * Emacs Lisp:: The built-in Emacs programming language.
19333 @subsection Keystrokes
19337 Q: What is an experienced Emacs user?
19340 A: A person who wishes that the terminal had pedals.
19343 Yes, when you use Emacs, you are apt to use the control key, the shift
19344 key and the meta key a lot. This is very annoying to some people
19345 (notably @code{vi}le users), and the rest of us just love the hell out
19346 of it. Just give up and submit. Emacs really does stand for
19347 ``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you
19348 may have heard from other disreputable sources (like the Emacs author).
19350 The shift keys are normally located near your pinky fingers, and are
19351 normally used to get capital letters and stuff. You probably use it all
19352 the time. The control key is normally marked ``CTRL'' or something like
19353 that. The meta key is, funnily enough, never marked as such on any
19354 keyboard. The one I'm currently at has a key that's marked ``Alt'',
19355 which is the meta key on this keyboard. It's usually located somewhere
19356 to the left hand side of the keyboard, usually on the bottom row.
19358 Now, us Emacs people don't say ``press the meta-control-m key'',
19359 because that's just too inconvenient. We say ``press the @kbd{M-C-m}
19360 key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the
19361 prefix that means ``control''. So ``press @kbd{C-k}'' means ``press
19362 down the control key, and hold it down while you press @kbd{k}''.
19363 ``Press @kbd{M-C-k}'' means ``press down and hold down the meta key and
19364 the control key and then press @kbd{k}''. Simple, ay?
19366 This is somewhat complicated by the fact that not all keyboards have a
19367 meta key. In that case you can use the ``escape'' key. Then @kbd{M-k}
19368 means ``press escape, release escape, press @kbd{k}''. That's much more
19369 work than if you have a meta key, so if that's the case, I respectfully
19370 suggest you get a real keyboard with a meta key. You can't live without
19376 @subsection Emacs Lisp
19378 Emacs is the King of Editors because it's really a Lisp interpreter.
19379 Each and every key you tap runs some Emacs Lisp code snippet, and since
19380 Emacs Lisp is an interpreted language, that means that you can configure
19381 any key to run any arbitrary code. You just, like, do it.
19383 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
19384 functions. (These are byte-compiled for speed, but it's still
19385 interpreted.) If you decide that you don't like the way Gnus does
19386 certain things, it's trivial to have it do something a different way.
19387 (Well, at least if you know how to write Lisp code.) However, that's
19388 beyond the scope of this manual, so we are simply going to talk about
19389 some common constructs that you normally use in your @file{.emacs} file
19392 If you want to set the variable @code{gnus-florgbnize} to four (4), you
19393 write the following:
19396 (setq gnus-florgbnize 4)
19399 This function (really ``special form'') @code{setq} is the one that can
19400 set a variable to some value. This is really all you need to know. Now
19401 you can go and fill your @code{.emacs} file with lots of these to change
19404 If you have put that thing in your @code{.emacs} file, it will be read
19405 and @code{eval}ed (which is lisp-ese for ``run'') the next time you
19406 start Emacs. If you want to change the variable right away, simply say
19407 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
19408 previous ``form'', which is a simple @code{setq} statement here.
19410 Go ahead---just try it, if you're located at your Emacs. After you
19411 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
19412 is the return value of the form you @code{eval}ed.
19416 If the manual says ``set @code{gnus-read-active-file} to @code{some}'',
19420 (setq gnus-read-active-file 'some)
19423 On the other hand, if the manual says ``set @code{gnus-nntp-server} to
19424 @samp{nntp.ifi.uio.no}'', that means:
19427 (setq gnus-nntp-server "nntp.ifi.uio.no")
19430 So be careful not to mix up strings (the latter) with symbols (the
19431 former). The manual is unambiguous, but it can be confusing.
19434 @include gnus-faq.texi