1 \input texinfo @c -*-texinfo-*- -*- coding: iso-latin-1 -*-
4 @settitle T-gnus 6.15 Manual
10 * Gnus: (gnus). The newsreader Gnus.
15 @setchapternewpage odd
19 \documentclass[twoside,a4paper,openright,11pt]{book}
20 \usepackage[latin1]{inputenc}
21 \usepackage{pagestyle}
29 \newcommand{\gnuschaptername}{}
30 \newcommand{\gnussectionname}{}
32 \newcommand{\gnusbackslash}{/}
34 \newcommand{\gnusref}[1]{``#1'' on page \pageref{#1}}
35 \newcommand{\gnusuref}[1]{\gnustt{#1}}
36 \newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}}
37 \newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}}
39 \newcommand{\gnuskindex}[1]{\index{#1}}
40 \newcommand{\gnusindex}[1]{\index{#1}}
42 \newcommand{\gnustt}[1]{{\fontfamily{pfu}\fontsize{10pt}{10}\selectfont #1}}
43 \newcommand{\gnuscode}[1]{\gnustt{#1}}
44 \newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\fontfamily{pfu}\fontsize{10pt}{10}\selectfont #1}''}
45 \newcommand{\gnuslisp}[1]{\gnustt{#1}}
46 \newcommand{\gnuskbd}[1]{`\gnustt{#1}'}
47 \newcommand{\gnusfile}[1]{`\gnustt{#1}'}
48 \newcommand{\gnusdfn}[1]{\textit{#1}}
49 \newcommand{\gnusi}[1]{\textit{#1}}
50 \newcommand{\gnusstrong}[1]{\textbf{#1}}
51 \newcommand{\gnusemph}[1]{\textit{#1}}
52 \newcommand{\gnusvar}[1]{{\fontsize{10pt}{10}\selectfont\textsl{\textsf{#1}}}}
53 \newcommand{\gnussc}[1]{\textsc{#1}}
54 \newcommand{\gnustitle}[1]{{\huge\textbf{#1}}}
55 \newcommand{\gnusauthor}[1]{{\large\textbf{#1}}}
56 \newcommand{\gnusresult}[1]{\gnustt{=> #1}}
58 \newcommand{\gnusbullet}{{${\bullet}$}}
59 \newcommand{\gnusdollar}{\$}
60 \newcommand{\gnusampersand}{\&}
61 \newcommand{\gnuspercent}{\%}
62 \newcommand{\gnushash}{\#}
63 \newcommand{\gnushat}{\symbol{"5E}}
64 \newcommand{\gnusunderline}{\symbol{"5F}}
65 \newcommand{\gnusnot}{$\neg$}
66 \newcommand{\gnustilde}{\symbol{"7E}}
67 \newcommand{\gnusless}{{$<$}}
68 \newcommand{\gnusgreater}{{$>$}}
69 \newcommand{\gnusbraceleft}{{$>$}}
70 \newcommand{\gnusbraceright}{{$>$}}
72 \newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=ps/gnus-head.eps,height=1cm}}}
73 \newcommand{\gnusinteresting}{
74 \marginpar[\mbox{}\hfill\gnushead]{\gnushead}
77 \newcommand{\gnuscleardoublepage}{\ifodd\count0\mbox{}\clearpage\thispagestyle{empty}\mbox{}\clearpage\else\clearpage\fi}
79 \newcommand{\gnuspagechapter}[1]{
86 \newcommand{\gnuschapter}[2]{
88 \ifdim \gnusdimen = 0pt\setcounter{page}{1}\pagestyle{gnus}\pagenumbering{arabic} \gnusdimen 1pt\fi
90 \renewcommand{\gnussectionname}{}
91 \renewcommand{\gnuschaptername}{#2}
94 \begin{picture}(500,500)(0,0)
95 \put(480,350){\makebox(0,0)[tr]{#1}}
96 \put(40,300){\makebox(500,50)[bl]{{\Huge\bf{#2}}}}
101 \newcommand{\gnusfigure}[3]{
103 \mbox{}\ifodd\count0\hspace*{-0.8cm}\else\hspace*{-3cm}\fi\begin{picture}(440,#2)
110 \newcommand{\gnusicon}[1]{
111 \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}}}
114 \newcommand{\gnuspicon}[1]{
115 \margindex{\epsfig{figure=#1,width=2cm}}
118 \newcommand{\gnusxface}[2]{
119 \margindex{\epsfig{figure=#1,width=1cm}\epsfig{figure=#2,width=1cm}}
122 \newcommand{\gnussmiley}[2]{
123 \margindex{\makebox[2cm]{\hfill\epsfig{figure=#1,width=0.5cm}\hfill\epsfig{figure=#2,width=0.5cm}\hfill}}
126 \newcommand{\gnusitemx}[1]{\mbox{}\vspace*{-\itemsep}\vspace*{-\parsep}\item#1}
128 \newcommand{\gnussection}[1]{
129 \renewcommand{\gnussectionname}{#1}
133 \newenvironment{codelist}%
138 \newenvironment{kbdlist}%
144 \newenvironment{dfnlist}%
149 \newenvironment{stronglist}%
154 \newenvironment{samplist}%
159 \newenvironment{varlist}%
164 \newenvironment{emphlist}%
169 \newlength\gnusheadtextwidth
170 \setlength{\gnusheadtextwidth}{\headtextwidth}
171 \addtolength{\gnusheadtextwidth}{1cm}
173 \newpagestyle{gnuspreamble}%
178 \hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\mbox{}}\textbf{\hfill\roman{page}}}
182 \hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\roman{page}\hfill\mbox{}}}
191 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
193 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
198 \newpagestyle{gnusindex}%
203 \hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\gnuschaptername\hfill\arabic{page}}}}
207 \hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}
215 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
217 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
227 \makebox[12cm]{\hspace*{3.1cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{chapter}.\arabic{section}} \textbf{\gnussectionname\hfill\arabic{page}}}}}
231 \makebox[12cm]{\hspace*{-2.95cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}}
239 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
241 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
246 \pagenumbering{roman}
247 \pagestyle{gnuspreamble}
257 %\addtolength{\oddsidemargin}{-5cm}
258 %\addtolength{\evensidemargin}{-5cm}
260 \addtolength{\textheight}{2cm}
262 \gnustitle{\gnustitlename}\\
265 \hspace*{0cm}\epsfig{figure=ps/gnus-big-logo.eps,height=15cm}
268 \gnusauthor{by Lars Magne Ingebrigtsen}
275 \thispagestyle{empty}
277 Copyright \copyright{} 1995, 1996, 1997, 1998, 1999, 2000
278 Free Software Foundation, Inc.
281 Permission is granted to copy, distribute and/or modify this document
282 under the terms of the GNU Free Documentation License, Version 1.1 or
283 any later version published by the Free Software Foundation; with no
284 Invariant Sections, with the Front-Cover texts being ``A GNU
285 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
286 license is included in the section entitled ``GNU Free Documentation
287 License'' in the Emacs manual.
289 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
290 this GNU Manual, like GNU software. Copies published by the Free
291 Software Foundation raise funds for GNU development.''
293 This document is part of a collection distributed under the GNU Free
294 Documentation License. If you want to distribute this document
295 separately from the collection, you can do so by adding a copy of the
296 license to the document, as described in section 6 of the license.
304 This file documents gnus, the GNU Emacs newsreader.
306 Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
308 Permission is granted to copy, distribute and/or modify this document
309 under the terms of the GNU Free Documentation License, Version 1.1 or
310 any later version published by the Free Software Foundation; with the
311 Invariant Sections being none, with the Front-Cover texts being ``A GNU
312 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
313 license is included in the section entitled ``GNU Free Documentation
314 License'' in the Emacs manual.
316 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
317 this GNU Manual, like GNU software. Copies published by the Free
318 Software Foundation raise funds for GNU development.''
320 This document is part of a collection distributed under the GNU Free
321 Documentation License. If you want to distribute this document
322 separately from the collection, you can do so by adding a copy of the
323 license to the document, as described in section 6 of the license.
329 @title T-gnus 6.15 Manual
331 @author by Lars Magne Ingebrigtsen
334 @vskip 0pt plus 1filll
335 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
337 Permission is granted to copy, distribute and/or modify this document
338 under the terms of the GNU Free Documentation License, Version 1.1 or
339 any later version published by the Free Software Foundation; with no
340 Invariant Sections, with the Front-Cover texts being ``A GNU
341 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
342 license is included in the section entitled ``GNU Free Documentation
343 License'' in the Emacs manual.
345 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
346 this GNU Manual, like GNU software. Copies published by the Free
347 Software Foundation raise funds for GNU development.''
349 This document is part of a collection distributed under the GNU Free
350 Documentation License. If you want to distribute this document
351 separately from the collection, you can do so by adding a copy of the
352 license to the document, as described in section 6 of the license.
361 @top The gnus Newsreader
365 You can read news (and mail) from within Emacs by using gnus. The news
366 can be gotten by any nefarious means you can think of---@sc{nntp}, local
367 spool or your mbox file. All at the same time, if you want to push your
370 T-gnus provides MIME features based on SEMI API. So T-gnus supports
371 your right to read strange messages including big images or other
372 various kinds of formats. T-gnus also supports
373 internationalization/localization and multiscript features based on MULE
374 API. So T-gnus does not discriminate various language communities.
375 Oh, if you are a Klingon, please wait Unicode Next Generation.
377 This manual corresponds to T-gnus 6.15.
388 Gnus is the advanced, self-documenting, customizable, extensible
389 unreal-time newsreader for GNU Emacs.
391 Oops. That sounds oddly familiar, so let's start over again to avoid
392 being accused of plagiarism:
394 Gnus is a message-reading laboratory. It will let you look at just
395 about anything as if it were a newsgroup. You can read mail with it,
396 you can browse directories with it, you can @code{ftp} with it---you
397 can even read news with it!
399 Gnus tries to empower people who read news the same way Emacs empowers
400 people who edit text. Gnus sets no limits to what the user should be
401 allowed to do. Users are encouraged to extend gnus to make it behave
402 like they want it to behave. A program should not control people;
403 people should be empowered to do what they want by using (or abusing)
409 * Starting Up:: Finding news can be a pain.
410 * Group Buffer:: Selecting, subscribing and killing groups.
411 * Summary Buffer:: Reading, saving and posting articles.
412 * Article Buffer:: Displaying and handling articles.
413 * Composing Messages:: Information on sending mail and news.
414 * Select Methods:: Gnus reads all messages from various select methods.
415 * Scoring:: Assigning values to articles.
416 * Various:: General purpose settings.
417 * The End:: Farewell and goodbye.
418 * Appendices:: Terminology, Emacs intro, FAQ, History, Internals.
419 * Index:: Variable, function and concept index.
420 * Key Index:: Key Index.
423 --- The Detailed Node Listing ---
427 * Finding the News:: Choosing a method for getting news.
428 * The First Time:: What does Gnus do the first time you start it?
429 * The Server is Down:: How can I read my mail then?
430 * Slave Gnusae:: You can have more than one Gnus active at a time.
431 * Fetching a Group:: Starting Gnus just to read a group.
432 * New Groups:: What is Gnus supposed to do with new groups?
433 * Startup Files:: Those pesky startup files---@file{.newsrc}.
434 * Auto Save:: Recovering from a crash.
435 * The Active File:: Reading the active file over a slow line Takes Time.
436 * Changing Servers:: You may want to move from one server to another.
437 * Startup Variables:: Other variables you might change.
441 * Checking New Groups:: Determining what groups are new.
442 * Subscription Methods:: What Gnus should do with new groups.
443 * Filtering New Groups:: Making Gnus ignore certain new groups.
447 * Group Buffer Format:: Information listed and how you can change it.
448 * Group Maneuvering:: Commands for moving in the group buffer.
449 * Selecting a Group:: Actually reading news.
450 * Group Data:: Changing the info for a group.
451 * Subscription Commands:: Unsubscribing, killing, subscribing.
452 * Group Levels:: Levels? What are those, then?
453 * Group Score:: A mechanism for finding out what groups you like.
454 * Marking Groups:: You can mark groups for later processing.
455 * Foreign Groups:: Creating and editing groups.
456 * Group Parameters:: Each group may have different parameters set.
457 * Listing Groups:: Gnus can list various subsets of the groups.
458 * Sorting Groups:: Re-arrange the group order.
459 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
460 * Browse Foreign Server:: You can browse a server. See what it has to offer.
461 * Exiting Gnus:: Stop reading news and get some work done.
462 * Group Topics:: A folding group mode divided into topics.
463 * Misc Group Stuff:: Other stuff that you can to do.
467 * Group Line Specification:: Deciding how the group buffer is to look.
468 * Group Modeline Specification:: The group buffer modeline.
469 * Group Highlighting:: Having nice colors in the group buffer.
473 * Topic Variables:: How to customize the topics the Lisp Way.
474 * Topic Commands:: Interactive E-Z commands.
475 * Topic Sorting:: Sorting each topic individually.
476 * Topic Topology:: A map of the world.
477 * Topic Parameters:: Parameters that apply to all groups in a topic.
481 * Scanning New Messages:: Asking Gnus to see whether new messages have arrived.
482 * Group Information:: Information and help on groups and Gnus.
483 * Group Timestamp:: Making Gnus keep track of when you last read a group.
484 * File Commands:: Reading and writing the Gnus files.
488 * Summary Buffer Format:: Deciding how the summary buffer is to look.
489 * Summary Maneuvering:: Moving around the summary buffer.
490 * Choosing Articles:: Reading articles.
491 * Paging the Article:: Scrolling the current article.
492 * Reply Followup and Post:: Posting articles.
493 * Marking Articles:: Marking articles as read, expirable, etc.
494 * Limiting:: You can limit the summary buffer.
495 * Threading:: How threads are made.
496 * Sorting the Summary Buffer:: How articles and threads are sorted.
497 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
498 * Article Caching:: You may store articles in a cache.
499 * Persistent Articles:: Making articles expiry-resistant.
500 * Article Backlog:: Having already read articles hang around.
501 * Saving Articles:: Ways of customizing article saving.
502 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
503 * Article Treatment:: The article buffer can be mangled at will.
504 * MIME Commands:: Doing MIMEy things with the articles.
505 * Charsets:: Character set issues.
506 * Article Commands:: Doing various things with the article buffer.
507 * Summary Sorting:: Sorting the summary buffer in various ways.
508 * Finding the Parent:: No child support? Get the parent.
509 * Alternative Approaches:: Reading using non-default summaries.
510 * Tree Display:: A more visual display of threads.
511 * Mail Group Commands:: Some commands can only be used in mail groups.
512 * Various Summary Stuff:: What didn't fit anywhere else.
513 * Exiting the Summary Buffer:: Returning to the Group buffer.
514 * Crosspost Handling:: How crossposted articles are dealt with.
515 * Duplicate Suppression:: An alternative when crosspost handling fails.
516 * Security:: Decrypt and Verify.
517 * Mailing List:: Mailing list minor mode.
519 Summary Buffer Format
521 * Summary Buffer Lines:: You can specify how summary lines should look.
522 * To From Newsgroups:: How to not display your own name.
523 * Summary Buffer Mode Line:: You can say how the mode line should look.
524 * Summary Highlighting:: Making the summary buffer all pretty and nice.
528 * Choosing Commands:: Commands for choosing articles.
529 * Choosing Variables:: Variables that influence these commands.
531 Reply, Followup and Post
533 * Summary Mail Commands:: Sending mail.
534 * Summary Post Commands:: Sending news.
535 * Summary Message Commands:: Other Message-related commands.
536 * Canceling and Superseding:: ``Whoops, I shouldn't have called him that.''
540 * Unread Articles:: Marks for unread articles.
541 * Read Articles:: Marks for read articles.
542 * Other Marks:: Marks that do not affect readedness.
543 * Setting Marks:: How to set and remove marks.
544 * Generic Marking Commands:: How to customize the marking.
545 * Setting Process Marks:: How to mark articles for later processing.
549 * Customizing Threading:: Variables you can change to affect the threading.
550 * Thread Commands:: Thread based commands in the summary buffer.
552 Customizing Threading
554 * Loose Threads:: How Gnus gathers loose threads into bigger threads.
555 * Filling In Threads:: Making the threads displayed look fuller.
556 * More Threading:: Even more variables for fiddling with threads.
557 * Low-Level Threading:: You thought it was over... but you were wrong!
561 * Uuencoded Articles:: Uudecode articles.
562 * Shell Archives:: Unshar articles.
563 * PostScript Files:: Split PostScript.
564 * Other Files:: Plain save and binhex.
565 * Decoding Variables:: Variables for a happy decoding.
566 * Viewing Files:: You want to look at the result of the decoding?
570 * Rule Variables:: Variables that say how a file is to be viewed.
571 * Other Decode Variables:: Other decode variables.
572 * Uuencoding and Posting:: Variables for customizing uuencoding.
576 * Article Highlighting:: You want to make the article look like fruit salad.
577 * Article Fontisizing:: Making emphasized text look nice.
578 * Article Hiding:: You also want to make certain info go away.
579 * Article Washing:: Lots of way-neat functions to make life better.
580 * Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
581 * Article Date:: Grumble, UT!
582 * Article Signature:: What is a signature?
583 * Article Miscellania:: Various other stuff.
585 Alternative Approaches
587 * Pick and Read:: First mark articles and then read them.
588 * Binary Groups:: Auto-decode all articles.
590 Various Summary Stuff
592 * Summary Group Information:: Information oriented commands.
593 * Searching for Articles:: Multiple article commands.
594 * Summary Generation Commands:: (Re)generating the summary buffer.
595 * Really Various Summary Commands:: Those pesky non-conformant commands.
599 * Hiding Headers:: Deciding what headers should be displayed.
600 * Using MIME:: Pushing articles through @sc{mime} before reading them.
601 * Customizing Articles:: Tailoring the look of the articles.
602 * Article Keymap:: Keystrokes available in the article buffer.
603 * Misc Article:: Other stuff.
607 * Mail:: Mailing and replying.
608 * Posting Server:: What server should you post via?
609 * Mail and Post:: Mailing and posting at the same time.
610 * Archived Messages:: Where Gnus stores the messages you've sent.
611 * Posting Styles:: An easier way to specify who you are.
612 * Drafts:: Postponing messages and rejected messages.
613 * Rejected Articles:: What happens if the server doesn't like your article?
614 * Using GPG:: How to use GPG and MML to sign and encrypt messages
618 * Server Buffer:: Making and editing virtual servers.
619 * Getting News:: Reading USENET news with Gnus.
620 * Getting Mail:: Reading your personal mail with Gnus.
621 * Browsing the Web:: Getting messages from a plethora of Web sources.
622 * Other Sources:: Reading directories, files, SOUP packets.
623 * Combined Groups:: Combining groups into one group.
624 * Gnus Unplugged:: Reading news and mail offline.
628 * Server Buffer Format:: You can customize the look of this buffer.
629 * Server Commands:: Commands to manipulate servers.
630 * Example Methods:: Examples server specifications.
631 * Creating a Virtual Server:: An example session.
632 * Server Variables:: Which variables to set.
633 * Servers and Methods:: You can use server names as select methods.
634 * Unavailable Servers:: Some servers you try to contact may be down.
638 * NNTP:: Reading news from an @sc{nntp} server.
639 * News Spool:: Reading news from the local spool.
643 * Mail in a Newsreader:: Important introductory notes.
644 * Getting Started Reading Mail:: A simple cookbook example.
645 * Splitting Mail:: How to create mail groups.
646 * Mail Sources:: How to tell Gnus where to get mail from.
647 * Mail Backend Variables:: Variables for customizing mail handling.
648 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
649 * Group Mail Splitting:: Use group customize to drive mail splitting.
650 * Incorporating Old Mail:: What about the old mail you have?
651 * Expiring Mail:: Getting rid of unwanted mail.
652 * Washing Mail:: Removing cruft from the mail you get.
653 * Duplicates:: Dealing with duplicated mail.
654 * Not Reading Mail:: Using mail backends for reading other files.
655 * Choosing a Mail Backend:: Gnus can read a variety of mail formats.
659 * Mail Source Specifiers:: How to specify what a mail source is.
660 * Mail Source Customization:: Some variables that influence things.
661 * Fetching Mail:: Using the mail source specifiers.
663 Choosing a Mail Backend
665 * Unix Mail Box:: Using the (quite) standard Un*x mbox.
666 * Rmail Babyl:: Emacs programs use the rmail babyl format.
667 * Mail Spool:: Store your mail in a private spool?
668 * MH Spool:: An mhspool-like backend.
669 * Mail Folders:: Having one file for each group.
670 * Comparing Mail Backends:: An in-depth looks at pros and cons.
674 * Web Searches:: Creating groups from articles that match a string.
675 * Slashdot:: Reading the Slashdot comments.
676 * Ultimate:: The Ultimate Bulletin Board systems.
677 * Web Archive:: Reading mailing list archived on web.
678 * RSS:: Reading RDF site summary.
679 * Customizing w3:: Doing stuff to Emacs/w3 from Gnus.
683 * Directory Groups:: You can read a directory as if it was a newsgroup.
684 * Anything Groups:: Dired? Who needs dired?
685 * Document Groups:: Single files can be the basis of a group.
686 * SOUP:: Reading @sc{soup} packets ``offline''.
687 * Mail-To-News Gateways:: Posting articles via mail-to-news gateways.
688 * IMAP:: Using Gnus as a @sc{imap} client.
692 * Document Server Internals:: How to add your own document types.
696 * SOUP Commands:: Commands for creating and sending @sc{soup} packets
697 * SOUP Groups:: A backend for reading @sc{soup} packets.
698 * SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
702 * Splitting in IMAP:: Splitting mail with nnimap.
703 * Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
704 * Expunging mailboxes:: Equivalent of a "compress mailbox" button.
708 * Virtual Groups:: Combining articles from many groups.
709 * Kibozed Groups:: Looking through parts of the newsfeed for articles.
713 * Agent Basics:: How it all is supposed to work.
714 * Agent Categories:: How to tell the Gnus Agent what to download.
715 * Agent Commands:: New commands for all the buffers.
716 * Agent Expiry:: How to make old articles go away.
717 * Agent and IMAP:: How to use the Agent with IMAP.
718 * Outgoing Messages:: What happens when you post/mail something?
719 * Agent Variables:: Customizing is fun.
720 * Example Setup:: An example @file{.gnus.el} file for offline people.
721 * Batching Agents:: How to fetch news from a @code{cron} job.
722 * Agent Caveats:: What you think it'll do and what it does.
726 * Category Syntax:: What a category looks like.
727 * Category Buffer:: A buffer for maintaining categories.
728 * Category Variables:: Customize'r'Us.
732 * Group Agent Commands::
733 * Summary Agent Commands::
734 * Server Agent Commands::
738 * Summary Score Commands:: Adding score entries for the current group.
739 * Group Score Commands:: General score commands.
740 * Score Variables:: Customize your scoring. (My, what terminology).
741 * Score File Format:: What a score file may contain.
742 * Score File Editing:: You can edit score files by hand as well.
743 * Adaptive Scoring:: Big Sister Gnus knows what you read.
744 * Home Score File:: How to say where new score entries are to go.
745 * Followups To Yourself:: Having Gnus notice when people answer you.
746 * Scoring Tips:: How to score effectively.
747 * Reverse Scoring:: That problem child of old is not problem.
748 * Global Score Files:: Earth-spanning, ear-splitting score files.
749 * Kill Files:: They are still here, but they can be ignored.
750 * Converting Kill Files:: Translating kill files to score files.
751 * GroupLens:: Getting predictions on what you like to read.
752 * Advanced Scoring:: Using logical expressions to build score rules.
753 * Score Decays:: It can be useful to let scores wither away.
757 * Using GroupLens:: How to make Gnus use GroupLens.
758 * Rating Articles:: Letting GroupLens know how you rate articles.
759 * Displaying Predictions:: Displaying predictions given by GroupLens.
760 * GroupLens Variables:: Customizing GroupLens.
764 * Advanced Scoring Syntax:: A definition.
765 * Advanced Scoring Examples:: What they look like.
766 * Advanced Scoring Tips:: Getting the most out of it.
770 * Process/Prefix:: A convention used by many treatment commands.
771 * Interactive:: Making Gnus ask you many questions.
772 * Symbolic Prefixes:: How to supply some Gnus functions with options.
773 * Formatting Variables:: You can specify what buffers should look like.
774 * Windows Configuration:: Configuring the Gnus buffer windows.
775 * Faces and Fonts:: How to change how faces look.
776 * Compilation:: How to speed Gnus up.
777 * Mode Lines:: Displaying information in the mode lines.
778 * Highlighting and Menus:: Making buffers look all nice and cozy.
779 * Buttons:: Get tendinitis in ten easy steps!
780 * Daemons:: Gnus can do things behind your back.
781 * NoCeM:: How to avoid spam and other fatty foods.
782 * Undo:: Some actions can be undone.
783 * Moderation:: What to do if you're a moderator.
784 * XEmacs Enhancements:: There are more pictures and stuff under XEmacs.
785 * Fuzzy Matching:: What's the big fuzz?
786 * Thwarting Email Spam:: A how-to on avoiding unsolicited commercial email.
787 * Various Various:: Things that are really various.
791 * Formatting Basics:: A formatting variable is basically a format string.
792 * Mode Line Formatting:: Some rules about mode line formatting variables.
793 * Advanced Formatting:: Modifying output in various ways.
794 * User-Defined Specs:: Having Gnus call your own functions.
795 * Formatting Fonts:: Making the formatting look colorful and nice.
799 * Picons:: How to display pictures of what your reading.
800 * Smileys:: Show all those happy faces the way they were meant to be shown.
801 * Toolbar:: Click'n'drool.
802 * XVarious:: Other XEmacsy Gnusey variables.
806 * Picon Basics:: What are picons and How do I get them.
807 * Picon Requirements:: Don't go further if you aren't using XEmacs.
808 * Easy Picons:: Displaying Picons---the easy way.
809 * Hard Picons:: The way you should do it. You'll learn something.
810 * Picon Useless Configuration:: Other variables you can trash/tweak/munge/play with.
814 * History:: How Gnus got where it is today.
815 * On Writing Manuals:: Why this is not a beginner's guide.
816 * Terminology:: We use really difficult, like, words here.
817 * Customization:: Tailoring Gnus to your needs.
818 * Troubleshooting:: What you might try if things do not work.
819 * Gnus Reference Guide:: Rilly, rilly technical stuff.
820 * Emacs for Heathens:: A short introduction to Emacsian terms.
821 * Frequently Asked Questions:: A question-and-answer session.
825 * Gnus Versions:: What Gnus versions have been released.
826 * Other Gnus Versions:: Other Gnus versions that also have been released.
827 * Why?:: What's the point of Gnus?
828 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
829 * Conformity:: Gnus tries to conform to all standards.
830 * Emacsen:: Gnus can be run on a few modern Emacsen.
831 * Gnus Development:: How Gnus is developed.
832 * Contributors:: Oodles of people.
833 * New Features:: Pointers to some of the new stuff in Gnus.
837 * ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus.
838 * September Gnus:: The Thing Formally Known As Gnus 5.2/5.3.
839 * Red Gnus:: Third time best---Gnus 5.4/5.5.
840 * Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7.
841 * Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9.
845 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
846 * Slow Terminal Connection:: You run a remote Emacs.
847 * Little Disk Space:: You feel that having large setup files is icky.
848 * Slow Machine:: You feel like buying a faster machine.
852 * Gnus Utility Functions:: Common functions and variable to use.
853 * Backend Interface:: How Gnus communicates with the servers.
854 * Score File Syntax:: A BNF definition of the score file standard.
855 * Headers:: How Gnus stores headers internally.
856 * Ranges:: A handy format for storing mucho numbers.
857 * Group Info:: The group info format.
858 * Extended Interactive:: Symbolic prefixes and stuff.
859 * Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen.
860 * Various File Formats:: Formats of files that Gnus use.
864 * Required Backend Functions:: Functions that must be implemented.
865 * Optional Backend Functions:: Functions that need not be implemented.
866 * Error Messaging:: How to get messages and report errors.
867 * Writing New Backends:: Extending old backends.
868 * Hooking New Backends Into Gnus:: What has to be done on the Gnus end.
869 * Mail-like Backends:: Some tips on mail backends.
873 * Active File Format:: Information on articles and groups available.
874 * Newsgroups File Format:: Group descriptions.
878 * Keystrokes:: Entering text and executing commands.
879 * Emacs Lisp:: The built-in Emacs programming language.
885 @chapter Starting gnus
890 If your system administrator has set things up properly, starting gnus
891 and reading news is extremely easy---you just type @kbd{M-x gnus} in
894 @findex gnus-other-frame
895 @kindex M-x gnus-other-frame
896 If you want to start gnus in a different frame, you can use the command
897 @kbd{M-x gnus-other-frame} instead.
899 If things do not go smoothly at startup, you have to twiddle some
900 variables in your @file{~/.gnus} file. This file is similar to
901 @file{~/.emacs}, but is read when gnus starts.
903 If you puzzle at any terms used in this manual, please refer to the
904 terminology section (@pxref{Terminology}).
907 * Finding the News:: Choosing a method for getting news.
908 * The First Time:: What does gnus do the first time you start it?
909 * The Server is Down:: How can I read my mail then?
910 * Slave Gnusae:: You can have more than one gnus active at a time.
911 * Fetching a Group:: Starting gnus just to read a group.
912 * New Groups:: What is gnus supposed to do with new groups?
913 * Startup Files:: Those pesky startup files---@file{.newsrc}.
914 * Auto Save:: Recovering from a crash.
915 * The Active File:: Reading the active file over a slow line Takes Time.
916 * Changing Servers:: You may want to move from one server to another.
917 * Startup Variables:: Other variables you might change.
921 @node Finding the News
922 @section Finding the News
925 @vindex gnus-select-method
927 The @code{gnus-select-method} variable says where gnus should look for
928 news. This variable should be a list where the first element says
929 @dfn{how} and the second element says @dfn{where}. This method is your
930 native method. All groups not fetched with this method are
933 For instance, if the @samp{news.somewhere.edu} @sc{nntp} server is where
934 you want to get your daily dosage of news from, you'd say:
937 (setq gnus-select-method '(nntp "news.somewhere.edu"))
940 If you want to read directly from the local spool, say:
943 (setq gnus-select-method '(nnspool ""))
946 If you can use a local spool, you probably should, as it will almost
947 certainly be much faster.
949 @vindex gnus-nntpserver-file
951 @cindex @sc{nntp} server
952 If this variable is not set, gnus will take a look at the
953 @code{NNTPSERVER} environment variable. If that variable isn't set,
954 gnus will see whether @code{gnus-nntpserver-file}
955 (@file{/etc/nntpserver} by default) has any opinions on the matter. If
956 that fails as well, gnus will try to use the machine running Emacs as an @sc{nntp} server. That's a long shot, though.
958 @vindex gnus-nntp-server
959 If @code{gnus-nntp-server} is set, this variable will override
960 @code{gnus-select-method}. You should therefore set
961 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
963 @vindex gnus-secondary-servers
964 @vindex gnus-nntp-server
965 You can also make gnus prompt you interactively for the name of an
966 @sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
967 (i.e., @kbd{C-u M-x gnus}), gnus will let you choose between the servers
968 in the @code{gnus-secondary-servers} list (if any). You can also just
969 type in the name of any server you feel like visiting. (Note that this
970 will set @code{gnus-nntp-server}, which means that if you then @kbd{M-x
971 gnus} later in the same Emacs session, Gnus will contact the same
974 @findex gnus-group-browse-foreign-server
976 However, if you use one @sc{nntp} server regularly and are just
977 interested in a couple of groups from a different server, you would be
978 better served by using the @kbd{B} command in the group buffer. It will
979 let you have a look at what groups are available, and you can subscribe
980 to any of the groups you want to. This also makes @file{.newsrc}
981 maintenance much tidier. @xref{Foreign Groups}.
983 @vindex gnus-secondary-select-methods
985 A slightly different approach to foreign groups is to set the
986 @code{gnus-secondary-select-methods} variable. The select methods
987 listed in this variable are in many ways just as native as the
988 @code{gnus-select-method} server. They will also be queried for active
989 files during startup (if that's required), and new newsgroups that
990 appear on these servers will be subscribed (or not) just as native
993 For instance, if you use the @code{nnmbox} backend to read your mail, you
994 would typically set this variable to
997 (setq gnus-secondary-select-methods '((nnmbox "")))
1001 @node The First Time
1002 @section The First Time
1003 @cindex first time usage
1005 If no startup files exist, gnus will try to determine what groups should
1006 be subscribed by default.
1008 @vindex gnus-default-subscribed-newsgroups
1009 If the variable @code{gnus-default-subscribed-newsgroups} is set, gnus
1010 will subscribe you to just those groups in that list, leaving the rest
1011 killed. Your system administrator should have set this variable to
1014 Since she hasn't, gnus will just subscribe you to a few arbitrarily
1015 picked groups (i.e., @samp{*.newusers}). (@dfn{Arbitrary} is defined
1016 here as @dfn{whatever Lars thinks you should read}.)
1018 You'll also be subscribed to the gnus documentation group, which should
1019 help you with most common problems.
1021 If @code{gnus-default-subscribed-newsgroups} is @code{t}, gnus will just
1022 use the normal functions for handling new groups, and not do anything
1026 @node The Server is Down
1027 @section The Server is Down
1028 @cindex server errors
1030 If the default server is down, gnus will understandably have some
1031 problems starting. However, if you have some mail groups in addition to
1032 the news groups, you may want to start gnus anyway.
1034 Gnus, being the trusting sort of program, will ask whether to proceed
1035 without a native select method if that server can't be contacted. This
1036 will happen whether the server doesn't actually exist (i.e., you have
1037 given the wrong address) or the server has just momentarily taken ill
1038 for some reason or other. If you decide to continue and have no foreign
1039 groups, you'll find it difficult to actually do anything in the group
1040 buffer. But, hey, that's your problem. Blllrph!
1042 @findex gnus-no-server
1043 @kindex M-x gnus-no-server
1045 If you know that the server is definitely down, or you just want to read
1046 your mail without bothering with the server at all, you can use the
1047 @code{gnus-no-server} command to start gnus. That might come in handy
1048 if you're in a hurry as well. This command will not attempt to contact
1049 your primary server---instead, it will just activate all groups on level
1050 1 and 2. (You should preferably keep no native groups on those two
1051 levels.) Also @pxref{Group Levels}.
1055 @section Slave Gnusae
1058 You might want to run more than one Emacs with more than one gnus at the
1059 same time. If you are using different @file{.newsrc} files (e.g., if you
1060 are using the two different gnusae to read from two different servers),
1061 that is no problem whatsoever. You just do it.
1063 The problem appears when you want to run two Gnusae that use the same
1064 @code{.newsrc} file.
1066 To work around that problem some, we here at the Think-Tank at the gnus
1067 Towers have come up with a new concept: @dfn{Masters} and
1068 @dfn{slaves}. (We have applied for a patent on this concept, and have
1069 taken out a copyright on those words. If you wish to use those words in
1070 conjunction with each other, you have to send $1 per usage instance to
1071 me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
1072 Applications}) will be much more expensive, of course.)
1074 Anyway, you start one gnus up the normal way with @kbd{M-x gnus} (or
1075 however you do it). Each subsequent slave gnusae should be started with
1076 @kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
1077 files, but instead save @dfn{slave files} that contain information only
1078 on what groups have been read in the slave session. When a master gnus
1079 starts, it will read (and delete) these slave files, incorporating all
1080 information from them. (The slave files will be read in the sequence
1081 they were created, so the latest changes will have precedence.)
1083 Information from the slave files has, of course, precedence over the
1084 information in the normal (i.e., master) @code{.newsrc} file.
1087 @node Fetching a Group
1088 @section Fetching a Group
1089 @cindex fetching a group
1091 @findex gnus-fetch-group
1092 It is sometimes convenient to be able to just say ``I want to read this
1093 group and I don't care whether gnus has been started or not''. This is
1094 perhaps more useful for people who write code than for users, but the
1095 command @code{gnus-fetch-group} provides this functionality in any case.
1096 It takes the group name as a parameter.
1102 @cindex subscription
1104 @vindex gnus-check-new-newsgroups
1105 If you are satisfied that you really never want to see any new groups,
1106 you can set @code{gnus-check-new-newsgroups} to @code{nil}. This will
1107 also save you some time at startup. Even if this variable is
1108 @code{nil}, you can always subscribe to the new groups just by pressing
1109 @kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
1110 is @code{ask-server} by default. If you set this variable to
1111 @code{always}, then gnus will query the backends for new groups even
1112 when you do the @kbd{g} command (@pxref{Scanning New Messages}).
1115 * Checking New Groups:: Determining what groups are new.
1116 * Subscription Methods:: What gnus should do with new groups.
1117 * Filtering New Groups:: Making gnus ignore certain new groups.
1121 @node Checking New Groups
1122 @subsection Checking New Groups
1124 Gnus normally determines whether a group is new or not by comparing the
1125 list of groups from the active file(s) with the lists of subscribed and
1126 dead groups. This isn't a particularly fast method. If
1127 @code{gnus-check-new-newsgroups} is @code{ask-server}, gnus will ask the
1128 server for new groups since the last time. This is both faster and
1129 cheaper. This also means that you can get rid of the list of killed
1130 groups altogether, so you may set @code{gnus-save-killed-list} to
1131 @code{nil}, which will save time both at startup, at exit, and all over.
1132 Saves disk space, too. Why isn't this the default, then?
1133 Unfortunately, not all servers support this command.
1135 I bet I know what you're thinking now: How do I find out whether my
1136 server supports @code{ask-server}? No? Good, because I don't have a
1137 fail-safe answer. I would suggest just setting this variable to
1138 @code{ask-server} and see whether any new groups appear within the next
1139 few days. If any do, then it works. If none do, then it doesn't
1140 work. I could write a function to make gnus guess whether the server
1141 supports @code{ask-server}, but it would just be a guess. So I won't.
1142 You could @code{telnet} to the server and say @code{HELP} and see
1143 whether it lists @samp{NEWGROUPS} among the commands it understands. If
1144 it does, then it might work. (But there are servers that lists
1145 @samp{NEWGROUPS} without supporting the function properly.)
1147 This variable can also be a list of select methods. If so, gnus will
1148 issue an @code{ask-server} command to each of the select methods, and
1149 subscribe them (or not) using the normal methods. This might be handy
1150 if you are monitoring a few servers for new groups. A side effect is
1151 that startup will take much longer, so you can meditate while waiting.
1152 Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss.
1155 @node Subscription Methods
1156 @subsection Subscription Methods
1158 @vindex gnus-subscribe-newsgroup-method
1159 What gnus does when it encounters a new group is determined by the
1160 @code{gnus-subscribe-newsgroup-method} variable.
1162 This variable should contain a function. This function will be called
1163 with the name of the new group as the only parameter.
1165 Some handy pre-fab functions are:
1169 @item gnus-subscribe-zombies
1170 @vindex gnus-subscribe-zombies
1171 Make all new groups zombies. This is the default. You can browse the
1172 zombies later (with @kbd{A z}) and either kill them all off properly
1173 (with @kbd{S z}), or subscribe to them (with @kbd{u}).
1175 @item gnus-subscribe-randomly
1176 @vindex gnus-subscribe-randomly
1177 Subscribe all new groups in arbitrary order. This really means that all
1178 new groups will be added at ``the top'' of the group buffer.
1180 @item gnus-subscribe-alphabetically
1181 @vindex gnus-subscribe-alphabetically
1182 Subscribe all new groups in alphabetical order.
1184 @item gnus-subscribe-hierarchically
1185 @vindex gnus-subscribe-hierarchically
1186 Subscribe all new groups hierarchically. The difference between this
1187 function and @code{gnus-subscribe-alphabetically} is slight.
1188 @code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly
1189 alphabetical fashion, while this function will enter groups into its
1190 hierarchy. So if you want to have the @samp{rec} hierarchy before the
1191 @samp{comp} hierarchy, this function will not mess that configuration
1192 up. Or something like that.
1194 @item gnus-subscribe-interactively
1195 @vindex gnus-subscribe-interactively
1196 Subscribe new groups interactively. This means that gnus will ask
1197 you about @strong{all} new groups. The groups you choose to subscribe
1198 to will be subscribed hierarchically.
1200 @item gnus-subscribe-killed
1201 @vindex gnus-subscribe-killed
1202 Kill all new groups.
1204 @item gnus-subscribe-topics
1205 @vindex gnus-subscribe-topics
1206 Put the groups into the topic that has a matching @code{subscribe} topic
1207 parameter (@pxref{Topic Parameters}). For instance, a @code{subscribe}
1208 topic parameter that looks like
1214 will mean that all groups that match that regex will be subscribed under
1217 If no topics match the groups, the groups will be subscribed in the
1222 @vindex gnus-subscribe-hierarchical-interactive
1223 A closely related variable is
1224 @code{gnus-subscribe-hierarchical-interactive}. (That's quite a
1225 mouthful.) If this variable is non-@code{nil}, gnus will ask you in a
1226 hierarchical fashion whether to subscribe to new groups or not. Gnus
1227 will ask you for each sub-hierarchy whether you want to descend the
1230 One common mistake is to set the variable a few paragraphs above
1231 (@code{gnus-subscribe-newsgroup-method}) to
1232 @code{gnus-subscribe-hierarchical-interactive}. This is an error. This
1233 will not work. This is ga-ga. So don't do it.
1236 @node Filtering New Groups
1237 @subsection Filtering New Groups
1239 A nice and portable way to control which new newsgroups should be
1240 subscribed (or ignored) is to put an @dfn{options} line at the start of
1241 the @file{.newsrc} file. Here's an example:
1244 options -n !alt.all !rec.all sci.all
1247 @vindex gnus-subscribe-options-newsgroup-method
1248 This line obviously belongs to a serious-minded intellectual scientific
1249 person (or she may just be plain old boring), because it says that all
1250 groups that have names beginning with @samp{alt} and @samp{rec} should
1251 be ignored, and all groups with names beginning with @samp{sci} should
1252 be subscribed. Gnus will not use the normal subscription method for
1253 subscribing these groups.
1254 @code{gnus-subscribe-options-newsgroup-method} is used instead. This
1255 variable defaults to @code{gnus-subscribe-alphabetically}.
1257 @vindex gnus-options-not-subscribe
1258 @vindex gnus-options-subscribe
1259 If you don't want to mess with your @file{.newsrc} file, you can just
1260 set the two variables @code{gnus-options-subscribe} and
1261 @code{gnus-options-not-subscribe}. These two variables do exactly the
1262 same as the @file{.newsrc} @samp{options -n} trick. Both are regexps,
1263 and if the new group matches the former, it will be unconditionally
1264 subscribed, and if it matches the latter, it will be ignored.
1266 @vindex gnus-auto-subscribed-groups
1267 Yet another variable that meddles here is
1268 @code{gnus-auto-subscribed-groups}. It works exactly like
1269 @code{gnus-options-subscribe}, and is therefore really superfluous, but I
1270 thought it would be nice to have two of these. This variable is more
1271 meant for setting some ground rules, while the other variable is used
1272 more for user fiddling. By default this variable makes all new groups
1273 that come from mail backends (@code{nnml}, @code{nnbabyl},
1274 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
1275 don't like that, just set this variable to @code{nil}.
1277 New groups that match this regexp are subscribed using
1278 @code{gnus-subscribe-options-newsgroup-method}.
1281 @node Changing Servers
1282 @section Changing Servers
1283 @cindex changing servers
1285 Sometimes it is necessary to move from one @sc{nntp} server to another.
1286 This happens very rarely, but perhaps you change jobs, or one server is
1287 very flaky and you want to use another.
1289 Changing the server is pretty easy, right? You just change
1290 @code{gnus-select-method} to point to the new server?
1294 Article numbers are not (in any way) kept synchronized between different
1295 @sc{nntp} servers, and the only way Gnus keeps track of what articles
1296 you have read is by keeping track of article numbers. So when you
1297 change @code{gnus-select-method}, your @file{.newsrc} file becomes
1300 Gnus provides a few functions to attempt to translate a @file{.newsrc}
1301 file from one server to another. They all have one thing in
1302 common---they take a looong time to run. You don't want to use these
1303 functions more than absolutely necessary.
1305 @kindex M-x gnus-change-server
1306 @findex gnus-change-server
1307 If you have access to both servers, Gnus can request the headers for all
1308 the articles you have read and compare @code{Message-ID}s and map the
1309 article numbers of the read articles and article marks. The @kbd{M-x
1310 gnus-change-server} command will do this for all your native groups. It
1311 will prompt for the method you want to move to.
1313 @kindex M-x gnus-group-move-group-to-server
1314 @findex gnus-group-move-group-to-server
1315 You can also move individual groups with the @kbd{M-x
1316 gnus-group-move-group-to-server} command. This is useful if you want to
1317 move a (foreign) group from one server to another.
1319 @kindex M-x gnus-group-clear-data-on-native-groups
1320 @findex gnus-group-clear-data-on-native-groups
1321 If you don't have access to both the old and new server, all your marks
1322 and read ranges have become worthless. You can use the @kbd{M-x
1323 gnus-group-clear-data-on-native-groups} command to clear out all data
1324 that you have on your native groups. Use with caution.
1326 After changing servers, you @strong{must} move the cache hierarchy away,
1327 since the cached articles will have wrong article numbers, which will
1328 affect which articles Gnus thinks are read.
1332 @section Startup Files
1333 @cindex startup files
1338 Now, you all know about the @file{.newsrc} file. All subscription
1339 information is traditionally stored in this file.
1341 Things got a bit more complicated with @sc{gnus}. In addition to
1342 keeping the @file{.newsrc} file updated, it also used a file called
1343 @file{.newsrc.el} for storing all the information that didn't fit into
1344 the @file{.newsrc} file. (Actually, it also duplicated everything in
1345 the @file{.newsrc} file.) @sc{gnus} would read whichever one of these
1346 files was the most recently saved, which enabled people to swap between
1347 @sc{gnus} and other newsreaders.
1349 That was kinda silly, so Gnus went one better: In addition to the
1350 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
1351 @file{.newsrc.eld}. It will read whichever of these files that are most
1352 recent, but it will never write a @file{.newsrc.el} file. You should
1353 never delete the @file{.newsrc.eld} file---it contains much information
1354 not stored in the @file{.newsrc} file.
1356 @vindex gnus-save-newsrc-file
1357 @vindex gnus-read-newsrc-file
1358 You can turn off writing the @file{.newsrc} file by setting
1359 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
1360 the file and save some space, as well as exiting from gnus faster.
1361 However, this will make it impossible to use other newsreaders than
1362 gnus. But hey, who would want to, right? Similarly, setting
1363 @code{gnus-read-newsrc-file} to @code{nil} makes gnus ignore the
1364 @file{.newsrc} file and any @file{.newsrc-SERVER} files, which is
1365 convenient if you have a tendency to use Netscape once in a while.
1367 @vindex gnus-save-killed-list
1368 If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus
1369 will not save the list of killed groups to the startup file. This will
1370 save both time (when starting and quitting) and space (on disk). It
1371 will also mean that Gnus has no record of what groups are new or old,
1372 so the automatic new groups subscription methods become meaningless.
1373 You should always set @code{gnus-check-new-newsgroups} to @code{nil} or
1374 @code{ask-server} if you set this variable to @code{nil} (@pxref{New
1375 Groups}). This variable can also be a regular expression. If that's
1376 the case, remove all groups that do not match this regexp before
1377 saving. This can be useful in certain obscure situations that involve
1378 several servers where not all servers support @code{ask-server}.
1380 @vindex gnus-startup-file
1381 The @code{gnus-startup-file} variable says where the startup files are.
1382 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
1383 file being whatever that one is, with a @samp{.eld} appended.
1385 @vindex gnus-save-newsrc-hook
1386 @vindex gnus-save-quick-newsrc-hook
1387 @vindex gnus-save-standard-newsrc-hook
1388 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
1389 files, while @code{gnus-save-quick-newsrc-hook} is called just before
1390 saving the @file{.newsrc.eld} file, and
1391 @code{gnus-save-standard-newsrc-hook} is called just before saving the
1392 @file{.newsrc} file. The latter two are commonly used to turn version
1393 control on or off. Version control is on by default when saving the
1394 startup files. If you want to turn backup creation off, say something like:
1397 (defun turn-off-backup ()
1398 (set (make-local-variable 'backup-inhibited) t))
1400 (add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup)
1401 (add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup)
1404 @vindex gnus-init-file
1405 When gnus starts, it will read the @code{gnus-site-init-file}
1406 (@file{.../site-lisp/gnus} by default) and @code{gnus-init-file}
1407 (@file{~/.gnus} by default) files. These are normal Emacs Lisp files
1408 and can be used to avoid cluttering your @file{~/.emacs} and
1409 @file{site-init} files with gnus stuff. Gnus will also check for files
1410 with the same names as these, but with @file{.elc} and @file{.el}
1411 suffixes. In other words, if you have set @code{gnus-init-file} to
1412 @file{~/.gnus}, it will look for @file{~/.gnus.elc}, @file{~/.gnus.el},
1413 and finally @file{~/.gnus} (in this order).
1419 @cindex dribble file
1422 Whenever you do something that changes the gnus data (reading articles,
1423 catching up, killing/subscribing groups), the change is added to a
1424 special @dfn{dribble buffer}. This buffer is auto-saved the normal
1425 Emacs way. If your Emacs should crash before you have saved the
1426 @file{.newsrc} files, all changes you have made can be recovered from
1429 If gnus detects this file at startup, it will ask the user whether to
1430 read it. The auto save file is deleted whenever the real startup file is
1433 @vindex gnus-use-dribble-file
1434 If @code{gnus-use-dribble-file} is @code{nil}, gnus won't create and
1435 maintain a dribble buffer. The default is @code{t}.
1437 @vindex gnus-dribble-directory
1438 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
1439 this variable is @code{nil}, which it is by default, gnus will dribble
1440 into the directory where the @file{.newsrc} file is located. (This is
1441 normally the user's home directory.) The dribble file will get the same
1442 file permissions as the @code{.newsrc} file.
1444 @vindex gnus-always-read-dribble-file
1445 If @code{gnus-always-read-dribble-file} is non-@code{nil}, Gnus will
1446 read the dribble file on startup without querying the user.
1449 @node The Active File
1450 @section The Active File
1452 @cindex ignored groups
1454 When gnus starts, or indeed whenever it tries to determine whether new
1455 articles have arrived, it reads the active file. This is a very large
1456 file that lists all the active groups and articles on the server.
1458 @vindex gnus-ignored-newsgroups
1459 Before examining the active file, gnus deletes all lines that match the
1460 regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
1461 any groups with bogus names, but you can use this variable to make gnus
1462 ignore hierarchies you aren't ever interested in. However, this is not
1463 recommended. In fact, it's highly discouraged. Instead, @pxref{New
1464 Groups} for an overview of other variables that can be used instead.
1467 @c @code{nil} by default, and will slow down active file handling somewhat
1468 @c if you set it to anything else.
1470 @vindex gnus-read-active-file
1472 The active file can be rather Huge, so if you have a slow network, you
1473 can set @code{gnus-read-active-file} to @code{nil} to prevent gnus from
1474 reading the active file. This variable is @code{some} by default.
1476 Gnus will try to make do by getting information just on the groups that
1477 you actually subscribe to.
1479 Note that if you subscribe to lots and lots of groups, setting this
1480 variable to @code{nil} will probably make gnus slower, not faster. At
1481 present, having this variable @code{nil} will slow gnus down
1482 considerably, unless you read news over a 2400 baud modem.
1484 This variable can also have the value @code{some}. Gnus will then
1485 attempt to read active info only on the subscribed groups. On some
1486 servers this is quite fast (on sparkling, brand new INN servers that
1487 support the @code{LIST ACTIVE group} command), on others this isn't fast
1488 at all. In any case, @code{some} should be faster than @code{nil}, and
1489 is certainly faster than @code{t} over slow lines.
1491 Some news servers (old versions of Leafnode and old versions of INN, for
1492 instance) do not support the @code{LIST ACTIVE group}. For these
1493 servers, @code{nil} is probably the most efficient value for this
1496 If this variable is @code{nil}, gnus will ask for group info in total
1497 lock-step, which isn't very fast. If it is @code{some} and you use an
1498 @sc{nntp} server, gnus will pump out commands as fast as it can, and
1499 read all the replies in one swoop. This will normally result in better
1500 performance, but if the server does not support the aforementioned
1501 @code{LIST ACTIVE group} command, this isn't very nice to the server.
1503 If you think that starting up Gnus takes too long, try all the three
1504 different values for this variable and see what works best for you.
1506 In any case, if you use @code{some} or @code{nil}, you should definitely
1507 kill all groups that you aren't interested in to speed things up.
1509 Note that this variable also affects active file retrieval from
1510 secondary select methods.
1513 @node Startup Variables
1514 @section Startup Variables
1518 @item gnus-load-hook
1519 @vindex gnus-load-hook
1520 A hook run while gnus is being loaded. Note that this hook will
1521 normally be run just once in each Emacs session, no matter how many
1522 times you start gnus.
1524 @item gnus-before-startup-hook
1525 @vindex gnus-before-startup-hook
1526 A hook run after starting up gnus successfully.
1528 @item gnus-startup-hook
1529 @vindex gnus-startup-hook
1530 A hook run as the very last thing after starting up gnus
1532 @item gnus-started-hook
1533 @vindex gnus-started-hook
1534 A hook that is run as the very last thing after starting up gnus
1537 @item gnus-setup-news-hook
1538 @vindex gnus-setup-news-hook
1539 A hook that is run after reading the @file{.newsrc} file(s), but before
1540 generating the group buffer.
1542 @item gnus-check-bogus-newsgroups
1543 @vindex gnus-check-bogus-newsgroups
1544 If non-@code{nil}, gnus will check for and delete all bogus groups at
1545 startup. A @dfn{bogus group} is a group that you have in your
1546 @file{.newsrc} file, but doesn't exist on the news server. Checking for
1547 bogus groups can take quite a while, so to save time and resources it's
1548 best to leave this option off, and do the checking for bogus groups once
1549 in a while from the group buffer instead (@pxref{Group Maintenance}).
1551 @item gnus-inhibit-startup-message
1552 @vindex gnus-inhibit-startup-message
1553 If non-@code{nil}, the startup message won't be displayed. That way,
1554 your boss might not notice as easily that you are reading news instead
1555 of doing your job. Note that this variable is used before
1556 @file{.gnus.el} is loaded, so it should be set in @code{.emacs} instead.
1558 @item gnus-no-groups-message
1559 @vindex gnus-no-groups-message
1560 Message displayed by gnus when no groups are available.
1562 @item gnus-play-startup-jingle
1563 @vindex gnus-play-startup-jingle
1564 If non-@code{nil}, play the gnus jingle at startup.
1566 @item gnus-startup-jingle
1567 @vindex gnus-startup-jingle
1568 Jingle to be played if the above variable is non-@code{nil}. The
1569 default is @samp{Tuxedomoon.Jingle4.au}.
1575 @chapter Group Buffer
1576 @cindex group buffer
1578 The @dfn{group buffer} lists all (or parts) of the available groups. It
1579 is the first buffer shown when gnus starts, and will never be killed as
1580 long as gnus is active.
1584 \gnusfigure{The Group Buffer}{320}{
1585 \put(75,50){\epsfig{figure=tmp/group.ps,height=9cm}}
1586 \put(120,37){\makebox(0,0)[t]{Buffer name}}
1587 \put(120,38){\vector(1,2){10}}
1588 \put(40,60){\makebox(0,0)[r]{Mode line}}
1589 \put(40,58){\vector(1,0){30}}
1590 \put(200,28){\makebox(0,0)[t]{Native select method}}
1591 \put(200,26){\vector(-1,2){15}}
1597 * Group Buffer Format:: Information listed and how you can change it.
1598 * Group Maneuvering:: Commands for moving in the group buffer.
1599 * Selecting a Group:: Actually reading news.
1600 * Group Data:: Changing the info for a group.
1601 * Subscription Commands:: Unsubscribing, killing, subscribing.
1602 * Group Levels:: Levels? What are those, then?
1603 * Group Score:: A mechanism for finding out what groups you like.
1604 * Marking Groups:: You can mark groups for later processing.
1605 * Foreign Groups:: Creating and editing groups.
1606 * Group Parameters:: Each group may have different parameters set.
1607 * Listing Groups:: Gnus can list various subsets of the groups.
1608 * Sorting Groups:: Re-arrange the group order.
1609 * Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
1610 * Browse Foreign Server:: You can browse a server. See what it has to offer.
1611 * Exiting Gnus:: Stop reading news and get some work done.
1612 * Group Topics:: A folding group mode divided into topics.
1613 * Misc Group Stuff:: Other stuff that you can to do.
1617 @node Group Buffer Format
1618 @section Group Buffer Format
1621 * Group Line Specification:: Deciding how the group buffer is to look.
1622 * Group Modeline Specification:: The group buffer modeline.
1623 * Group Highlighting:: Having nice colors in the group buffer.
1627 @node Group Line Specification
1628 @subsection Group Line Specification
1629 @cindex group buffer format
1631 The default format of the group buffer is nice and dull, but you can
1632 make it as exciting and ugly as you feel like.
1634 Here's a couple of example group lines:
1637 25: news.announce.newusers
1638 * 0: alt.fan.andrea-dworkin
1643 You can see that there are 25 unread articles in
1644 @samp{news.announce.newusers}. There are no unread articles, but some
1645 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1646 asterisk at the beginning of the line?).
1648 @vindex gnus-group-line-format
1649 You can change that format to whatever you want by fiddling with the
1650 @code{gnus-group-line-format} variable. This variable works along the
1651 lines of a @code{format} specification, which is pretty much the same as
1652 a @code{printf} specifications, for those of you who use (feh!) C.
1653 @xref{Formatting Variables}.
1655 @samp{%M%S%5y: %(%g%)\n} is the value that produced those lines above.
1657 There should always be a colon on the line; the cursor always moves to
1658 the colon after performing an operation. Nothing else is required---not
1659 even the group name. All displayed text is just window dressing, and is
1660 never examined by gnus. Gnus stores all real information it needs using
1663 (Note that if you make a really strange, wonderful, spreadsheet-like
1664 layout, everybody will believe you are hard at work with the accounting
1665 instead of wasting time reading news.)
1667 Here's a list of all available format characters:
1672 An asterisk if the group only has marked articles.
1675 Whether the group is subscribed.
1678 Level of subscribedness.
1681 Number of unread articles.
1684 Number of dormant articles.
1687 Number of ticked articles.
1690 Number of read articles.
1693 Estimated total number of articles. (This is really @var{max-number}
1694 minus @var{min-number} plus 1.)
1696 Gnus uses this estimation because the NNTP protocol provides efficient
1697 access to @var{max-number} and @var{min-number} but getting the true
1698 unread message count is not possible efficiently. For hysterical
1699 raisins, even the mail backends, where the true number of unread
1700 messages might be available efficiently, use the same limited
1701 interface. To remove this restriction from Gnus means that the
1702 backend interface has to be changed, which is not an easy job. If you
1703 want to work on this, please contact the Gnus mailing list.
1706 Number of unread, unticked, non-dormant articles.
1709 Number of ticked and dormant articles.
1718 Newsgroup description.
1721 @samp{m} if moderated.
1724 @samp{(m)} if moderated.
1733 A string that looks like @samp{<%s:%n>} if a foreign select method is
1737 Indentation based on the level of the topic (@pxref{Group Topics}).
1740 @vindex gnus-group-uncollapsed-levels
1741 Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels}
1742 variable says how many levels to leave at the end of the group name.
1743 The default is 1---this will mean that group names like
1744 @samp{gnu.emacs.gnus} will be shortened to @samp{g.e.gnus}.
1747 @vindex gnus-new-mail-mark
1749 @samp{%} (@code{gnus-new-mail-mark}) if there has arrived new mail to
1753 @samp{#} (@code{gnus-process-mark}) if the group is process marked.
1756 A string that says when you last read the group (@pxref{Group
1760 User defined specifier. The next character in the format string should
1761 be a letter. Gnus will call the function
1762 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1763 following @samp{%u}. The function will be passed a single dummy
1764 parameter as argument. The function should return a string, which will
1765 be inserted into the buffer just like information from any other
1770 All the ``number-of'' specs will be filled with an asterisk (@samp{*})
1771 if no info is available---for instance, if it is a non-activated foreign
1772 group, or a bogus native group.
1775 @node Group Modeline Specification
1776 @subsection Group Modeline Specification
1777 @cindex group modeline
1779 @vindex gnus-group-mode-line-format
1780 The mode line can be changed by setting
1781 @code{gnus-group-mode-line-format} (@pxref{Mode Line Formatting}). It
1782 doesn't understand that many format specifiers:
1786 The native news server.
1788 The native select method.
1792 @node Group Highlighting
1793 @subsection Group Highlighting
1794 @cindex highlighting
1795 @cindex group highlighting
1797 @vindex gnus-group-highlight
1798 Highlighting in the group buffer is controlled by the
1799 @code{gnus-group-highlight} variable. This is an alist with elements
1800 that look like @code{(@var{form} . @var{face})}. If @var{form} evaluates to
1801 something non-@code{nil}, the @var{face} will be used on the line.
1803 Here's an example value for this variable that might look nice if the
1807 (cond (window-system
1808 (setq custom-background-mode 'light)
1809 (defface my-group-face-1
1810 '((t (:foreground "Red" :bold t))) "First group face")
1811 (defface my-group-face-2
1812 '((t (:foreground "DarkSeaGreen4" :bold t))) "Second group face")
1813 (defface my-group-face-3
1814 '((t (:foreground "Green4" :bold t))) "Third group face")
1815 (defface my-group-face-4
1816 '((t (:foreground "SteelBlue" :bold t))) "Fourth group face")
1817 (defface my-group-face-5
1818 '((t (:foreground "Blue" :bold t))) "Fifth group face")))
1820 (setq gnus-group-highlight
1821 '(((> unread 200) . my-group-face-1)
1822 ((and (< level 3) (zerop unread)) . my-group-face-2)
1823 ((< level 3) . my-group-face-3)
1824 ((zerop unread) . my-group-face-4)
1825 (t . my-group-face-5)))
1828 Also @pxref{Faces and Fonts}.
1830 Variables that are dynamically bound when the forms are evaluated
1837 The number of unread articles in the group.
1841 Whether the group is a mail group.
1843 The level of the group.
1845 The score of the group.
1847 The number of ticked articles in the group.
1849 The total number of articles in the group. Or rather, MAX-NUMBER minus
1850 MIN-NUMBER plus one.
1852 When using the topic minor mode, this variable is bound to the current
1853 topic being inserted.
1856 When the forms are @code{eval}ed, point is at the beginning of the line
1857 of the group in question, so you can use many of the normal gnus
1858 functions for snarfing info on the group.
1860 @vindex gnus-group-update-hook
1861 @findex gnus-group-highlight-line
1862 @code{gnus-group-update-hook} is called when a group line is changed.
1863 It will not be called when @code{gnus-visual} is @code{nil}. This hook
1864 calls @code{gnus-group-highlight-line} by default.
1867 @node Group Maneuvering
1868 @section Group Maneuvering
1869 @cindex group movement
1871 All movement commands understand the numeric prefix and will behave as
1872 expected, hopefully.
1878 @findex gnus-group-next-unread-group
1879 Go to the next group that has unread articles
1880 (@code{gnus-group-next-unread-group}).
1886 @findex gnus-group-prev-unread-group
1887 Go to the previous group that has unread articles
1888 (@code{gnus-group-prev-unread-group}).
1892 @findex gnus-group-next-group
1893 Go to the next group (@code{gnus-group-next-group}).
1897 @findex gnus-group-prev-group
1898 Go to the previous group (@code{gnus-group-prev-group}).
1902 @findex gnus-group-next-unread-group-same-level
1903 Go to the next unread group on the same (or lower) level
1904 (@code{gnus-group-next-unread-group-same-level}).
1908 @findex gnus-group-prev-unread-group-same-level
1909 Go to the previous unread group on the same (or lower) level
1910 (@code{gnus-group-prev-unread-group-same-level}).
1913 Three commands for jumping to groups:
1919 @findex gnus-group-jump-to-group
1920 Jump to a group (and make it visible if it isn't already)
1921 (@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
1926 @findex gnus-group-best-unread-group
1927 Jump to the unread group with the lowest level
1928 (@code{gnus-group-best-unread-group}).
1932 @findex gnus-group-first-unread-group
1933 Jump to the first group with unread articles
1934 (@code{gnus-group-first-unread-group}).
1937 @vindex gnus-group-goto-unread
1938 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
1939 commands will move to the next group, not the next unread group. Even
1940 the commands that say they move to the next unread group. The default
1944 @node Selecting a Group
1945 @section Selecting a Group
1946 @cindex group selection
1951 @kindex SPACE (Group)
1952 @findex gnus-group-read-group
1953 Select the current group, switch to the summary buffer and display the
1954 first unread article (@code{gnus-group-read-group}). If there are no
1955 unread articles in the group, or if you give a non-numerical prefix to
1956 this command, gnus will offer to fetch all the old articles in this
1957 group from the server. If you give a numerical prefix @var{N}, @var{N}
1958 determines the number of articles gnus will fetch. If @var{N} is
1959 positive, gnus fetches the @var{N} newest articles, if @var{N} is
1960 negative, Gnus fetches the @code{abs(@var{N})} oldest articles.
1962 Thus, @kbd{SPC} enters the group normally, @kbd{C-u SPC} offers old
1963 articles, @kbd{C-u 4 2 SPC} fetches the 42 newest articles, and @kbd{C-u
1964 - 4 2 SPC} fetches the 42 oldest ones.
1966 When you are in the group (in the Summary buffer), you can type
1967 @kbd{M-g} to fetch new articles, or @kbd{C-u M-g} to also show the old
1972 @findex gnus-group-select-group
1973 Select the current group and switch to the summary buffer
1974 (@code{gnus-group-select-group}). Takes the same arguments as
1975 @code{gnus-group-read-group}---the only difference is that this command
1976 does not display the first unread article automatically upon group
1980 @kindex M-RET (Group)
1981 @findex gnus-group-quick-select-group
1982 This does the same as the command above, but tries to do it with the
1983 minimum amount of fuzz (@code{gnus-group-quick-select-group}). No
1984 scoring/killing will be performed, there will be no highlights and no
1985 expunging. This might be useful if you're in a real hurry and have to
1986 enter some humongous group. If you give a 0 prefix to this command
1987 (i.e., @kbd{0 M-RET}), gnus won't even generate the summary buffer,
1988 which is useful if you want to toggle threading before generating the
1989 summary buffer (@pxref{Summary Generation Commands}).
1992 @kindex M-SPACE (Group)
1993 @findex gnus-group-visible-select-group
1994 This is yet one more command that does the same as the @kbd{RET}
1995 command, but this one does it without expunging and hiding dormants
1996 (@code{gnus-group-visible-select-group}).
1999 @kindex M-C-RET (Group)
2000 @findex gnus-group-select-group-ephemerally
2001 Finally, this command selects the current group ephemerally without
2002 doing any processing of its contents
2003 (@code{gnus-group-select-group-ephemerally}). Even threading has been
2004 turned off. Everything you do in the group after selecting it in this
2005 manner will have no permanent effects.
2009 @vindex gnus-large-newsgroup
2010 The @code{gnus-large-newsgroup} variable says what gnus should consider
2011 to be a big group. This is 200 by default. If the group has more
2012 (unread and/or ticked) articles than this, gnus will query the user
2013 before entering the group. The user can then specify how many articles
2014 should be fetched from the server. If the user specifies a negative
2015 number (@code{-n}), the @code{n} oldest articles will be fetched. If it
2016 is positive, the @code{n} articles that have arrived most recently will
2019 @vindex gnus-select-group-hook
2020 @vindex gnus-auto-select-first
2021 @code{gnus-auto-select-first} control whether any articles are selected
2022 automatically when entering a group with the @kbd{SPACE} command.
2027 Don't select any articles when entering the group. Just display the
2028 full summary buffer.
2031 Select the first unread article when entering the group.
2034 Select the highest scored article in the group when entering the
2039 This variable can also be a function. In that case, that function will
2040 be called to place point on a subject line, and/or select some article.
2041 Useful functions include:
2044 @item gnus-summary-first-unread-subject
2045 Place point on the subject line of the first unread article, but
2046 don't select the article.
2048 @item gnus-summary-first-unread-article
2049 Select the first unread article.
2051 @item gnus-summary-best-unread-article
2052 Select the highest-scored unread article.
2056 If you want to prevent automatic selection in some group (say, in a
2057 binary group with Huge articles) you can set this variable to @code{nil}
2058 in @code{gnus-select-group-hook}, which is called when a group is
2062 @node Subscription Commands
2063 @section Subscription Commands
2064 @cindex subscription
2072 @findex gnus-group-unsubscribe-current-group
2073 @c @icon{gnus-group-unsubscribe}
2074 Toggle subscription to the current group
2075 (@code{gnus-group-unsubscribe-current-group}).
2081 @findex gnus-group-unsubscribe-group
2082 Prompt for a group to subscribe, and then subscribe it. If it was
2083 subscribed already, unsubscribe it instead
2084 (@code{gnus-group-unsubscribe-group}).
2090 @findex gnus-group-kill-group
2091 @c @icon{gnus-group-kill-group}
2092 Kill the current group (@code{gnus-group-kill-group}).
2098 @findex gnus-group-yank-group
2099 Yank the last killed group (@code{gnus-group-yank-group}).
2102 @kindex C-x C-t (Group)
2103 @findex gnus-group-transpose-groups
2104 Transpose two groups (@code{gnus-group-transpose-groups}). This isn't
2105 really a subscription command, but you can use it instead of a
2106 kill-and-yank sequence sometimes.
2112 @findex gnus-group-kill-region
2113 Kill all groups in the region (@code{gnus-group-kill-region}).
2117 @findex gnus-group-kill-all-zombies
2118 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
2121 @kindex S C-k (Group)
2122 @findex gnus-group-kill-level
2123 Kill all groups on a certain level (@code{gnus-group-kill-level}).
2124 These groups can't be yanked back after killing, so this command should
2125 be used with some caution. The only time where this command comes in
2126 really handy is when you have a @file{.newsrc} with lots of unsubscribed
2127 groups that you want to get rid off. @kbd{S C-k} on level 7 will
2128 kill off all unsubscribed groups that do not have message numbers in the
2129 @file{.newsrc} file.
2133 Also @pxref{Group Levels}.
2143 @findex gnus-group-catchup-current
2144 @vindex gnus-group-catchup-group-hook
2145 @c @icon{gnus-group-catchup-current}
2146 Mark all unticked articles in this group as read
2147 (@code{gnus-group-catchup-current}).
2148 @code{gnus-group-catchup-group-hook} is called when catching up a group from
2153 @findex gnus-group-catchup-current-all
2154 Mark all articles in this group, even the ticked ones, as read
2155 (@code{gnus-group-catchup-current-all}).
2159 @findex gnus-group-clear-data
2160 Clear the data from the current group---nix out marks and the list of
2161 read articles (@code{gnus-group-clear-data}).
2163 @item M-x gnus-group-clear-data-on-native-groups
2164 @kindex M-x gnus-group-clear-data-on-native-groups
2165 @findex gnus-group-clear-data-on-native-groups
2166 If you have switched from one @sc{nntp} server to another, all your marks
2167 and read ranges have become worthless. You can use this command to
2168 clear out all data that you have on your native groups. Use with
2175 @section Group Levels
2179 All groups have a level of @dfn{subscribedness}. For instance, if a
2180 group is on level 2, it is more subscribed than a group on level 5. You
2181 can ask gnus to just list groups on a given level or lower
2182 (@pxref{Listing Groups}), or to just check for new articles in groups on
2183 a given level or lower (@pxref{Scanning New Messages}).
2185 Remember: The higher the level of the group, the less important it is.
2191 @findex gnus-group-set-current-level
2192 Set the level of the current group. If a numeric prefix is given, the
2193 next @var{n} groups will have their levels set. The user will be
2194 prompted for a level.
2197 @vindex gnus-level-killed
2198 @vindex gnus-level-zombie
2199 @vindex gnus-level-unsubscribed
2200 @vindex gnus-level-subscribed
2201 Gnus considers groups from levels 1 to
2202 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
2203 @code{gnus-level-subscribed} (exclusive) and
2204 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
2205 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
2206 (default 8) and @code{gnus-level-killed} to be killed (completely dead)
2207 (default 9). Gnus treats subscribed and unsubscribed groups exactly the
2208 same, but zombie and killed groups have no information on what articles
2209 you have read, etc, stored. This distinction between dead and living
2210 groups isn't done because it is nice or clever, it is done purely for
2211 reasons of efficiency.
2213 It is recommended that you keep all your mail groups (if any) on quite
2214 low levels (e.g. 1 or 2).
2216 Maybe the following description of the default behavior of Gnus helps to
2217 understand what these levels are all about. By default, Gnus shows you
2218 subscribed nonempty groups, but by hitting @kbd{L} you can have it show
2219 empty subscribed groups and unsubscribed groups, too. Type @kbd{l} to
2220 go back to showing nonempty subscribed groups again. Thus, unsubscribed
2221 groups are hidden, in a way.
2223 Zombie and killed groups are similar to unsubscribed groups in that they
2224 are hidden by default. But they are different from subscribed and
2225 unsubscribed groups in that Gnus doesn't ask the news server for
2226 information (number of messages, number of unread messages) on zombie
2227 and killed groups. Normally, you use @kbd{C-k} to kill the groups you
2228 aren't interested in. If most groups are killed, Gnus is faster.
2230 Why does Gnus distinguish between zombie and killed groups? Well, when
2231 a new group arrives on the server, Gnus by default makes it a zombie
2232 group. This means that you are normally not bothered with new groups,
2233 but you can type @kbd{A z} to get a list of all new groups. Subscribe
2234 the ones you like and kill the ones you don't want. (@kbd{A k} shows a
2235 list of killed groups.)
2237 If you want to play with the level variables, you should show some care.
2238 Set them once, and don't touch them ever again. Better yet, don't touch
2239 them at all unless you know exactly what you're doing.
2241 @vindex gnus-level-default-unsubscribed
2242 @vindex gnus-level-default-subscribed
2243 Two closely related variables are @code{gnus-level-default-subscribed}
2244 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
2245 which are the levels that new groups will be put on if they are
2246 (un)subscribed. These two variables should, of course, be inside the
2247 relevant valid ranges.
2249 @vindex gnus-keep-same-level
2250 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
2251 will only move to groups of the same level (or lower). In
2252 particular, going from the last article in one group to the next group
2253 will go to the next group of the same level (or lower). This might be
2254 handy if you want to read the most important groups before you read the
2257 If this variable is @code{best}, Gnus will make the next newsgroup the
2258 one with the best level.
2260 @vindex gnus-group-default-list-level
2261 All groups with a level less than or equal to
2262 @code{gnus-group-default-list-level} will be listed in the group buffer
2265 @vindex gnus-group-list-inactive-groups
2266 If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
2267 groups will be listed along with the unread groups. This variable is
2268 @code{t} by default. If it is @code{nil}, inactive groups won't be
2271 @vindex gnus-group-use-permanent-levels
2272 If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you
2273 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
2274 use this level as the ``work'' level.
2276 @vindex gnus-activate-level
2277 Gnus will normally just activate (i. e., query the server about) groups
2278 on level @code{gnus-activate-level} or less. If you don't want to
2279 activate unsubscribed groups, for instance, you might set this variable
2280 to 5. The default is 6.
2284 @section Group Score
2289 You would normally keep important groups on high levels, but that scheme
2290 is somewhat restrictive. Don't you wish you could have Gnus sort the
2291 group buffer according to how often you read groups, perhaps? Within
2294 This is what @dfn{group score} is for. You can have Gnus assign a score
2295 to each group through the mechanism described below. You can then sort
2296 the group buffer based on this score. Alternatively, you can sort on
2297 score and then level. (Taken together, the level and the score is
2298 called the @dfn{rank} of the group. A group that is on level 4 and has
2299 a score of 1 has a higher rank than a group on level 5 that has a score
2300 of 300. (The level is the most significant part and the score is the
2301 least significant part.))
2303 @findex gnus-summary-bubble-group
2304 If you want groups you read often to get higher scores than groups you
2305 read seldom you can add the @code{gnus-summary-bubble-group} function to
2306 the @code{gnus-summary-exit-hook} hook. This will result (after
2307 sorting) in a bubbling sort of action. If you want to see that in
2308 action after each summary exit, you can add
2309 @code{gnus-group-sort-groups-by-rank} or
2310 @code{gnus-group-sort-groups-by-score} to the same hook, but that will
2311 slow things down somewhat.
2314 @node Marking Groups
2315 @section Marking Groups
2316 @cindex marking groups
2318 If you want to perform some command on several groups, and they appear
2319 subsequently in the group buffer, you would normally just give a
2320 numerical prefix to the command. Most group commands will then do your
2321 bidding on those groups.
2323 However, if the groups are not in sequential order, you can still
2324 perform a command on several groups. You simply mark the groups first
2325 with the process mark and then execute the command.
2333 @findex gnus-group-mark-group
2334 Set the mark on the current group (@code{gnus-group-mark-group}).
2340 @findex gnus-group-unmark-group
2341 Remove the mark from the current group
2342 (@code{gnus-group-unmark-group}).
2346 @findex gnus-group-unmark-all-groups
2347 Remove the mark from all groups (@code{gnus-group-unmark-all-groups}).
2351 @findex gnus-group-mark-region
2352 Mark all groups between point and mark (@code{gnus-group-mark-region}).
2356 @findex gnus-group-mark-buffer
2357 Mark all groups in the buffer (@code{gnus-group-mark-buffer}).
2361 @findex gnus-group-mark-regexp
2362 Mark all groups that match some regular expression
2363 (@code{gnus-group-mark-regexp}).
2366 Also @pxref{Process/Prefix}.
2368 @findex gnus-group-universal-argument
2369 If you want to execute some command on all groups that have been marked
2370 with the process mark, you can use the @kbd{M-&}
2371 (@code{gnus-group-universal-argument}) command. It will prompt you for
2372 the command to be executed.
2375 @node Foreign Groups
2376 @section Foreign Groups
2377 @cindex foreign groups
2379 Below are some group mode commands for making and editing general foreign
2380 groups, as well as commands to ease the creation of a few
2381 special-purpose groups. All these commands insert the newly created
2382 groups under point---@code{gnus-subscribe-newsgroup-method} is not
2389 @findex gnus-group-make-group
2390 @cindex making groups
2391 Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
2392 for a name, a method and possibly an @dfn{address}. For an easier way
2393 to subscribe to @sc{nntp} groups, @pxref{Browse Foreign Server}.
2397 @findex gnus-group-rename-group
2398 @cindex renaming groups
2399 Rename the current group to something else
2400 (@code{gnus-group-rename-group}). This is valid only on some
2401 groups---mail groups mostly. This command might very well be quite slow
2407 @findex gnus-group-customize
2408 Customize the group parameters (@code{gnus-group-customize}).
2412 @findex gnus-group-edit-group-method
2413 @cindex renaming groups
2414 Enter a buffer where you can edit the select method of the current
2415 group (@code{gnus-group-edit-group-method}).
2419 @findex gnus-group-edit-group-parameters
2420 Enter a buffer where you can edit the group parameters
2421 (@code{gnus-group-edit-group-parameters}).
2425 @findex gnus-group-edit-group
2426 Enter a buffer where you can edit the group info
2427 (@code{gnus-group-edit-group}).
2431 @findex gnus-group-make-directory-group
2433 Make a directory group (@pxref{Directory Groups}). You will be prompted
2434 for a directory name (@code{gnus-group-make-directory-group}).
2439 @findex gnus-group-make-help-group
2440 Make the gnus help group (@code{gnus-group-make-help-group}).
2444 @cindex (ding) archive
2445 @cindex archive group
2446 @findex gnus-group-make-archive-group
2447 @vindex gnus-group-archive-directory
2448 @vindex gnus-group-recent-archive-directory
2449 Make a gnus archive group (@code{gnus-group-make-archive-group}). By
2450 default a group pointing to the most recent articles will be created
2451 (@code{gnus-group-recent-archive-directory}), but given a prefix, a full
2452 group will be created from @code{gnus-group-archive-directory}.
2456 @findex gnus-group-make-kiboze-group
2458 Make a kiboze group. You will be prompted for a name, for a regexp to
2459 match groups to be ``included'' in the kiboze group, and a series of
2460 strings to match on headers (@code{gnus-group-make-kiboze-group}).
2461 @xref{Kibozed Groups}.
2465 @findex gnus-group-enter-directory
2467 Read an arbitrary directory as if it were a newsgroup with the
2468 @code{nneething} backend (@code{gnus-group-enter-directory}).
2469 @xref{Anything Groups}.
2473 @findex gnus-group-make-doc-group
2474 @cindex ClariNet Briefs
2476 Make a group based on some file or other
2477 (@code{gnus-group-make-doc-group}). If you give a prefix to this
2478 command, you will be prompted for a file name and a file type.
2479 Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
2480 @code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs},
2481 @code{rfc934}, @code{rfc822-forward}, @code{nsmail} and @code{forward}.
2482 If you run this command without a prefix, Gnus will guess at the file
2483 type. @xref{Document Groups}.
2487 @vindex gnus-useful-groups
2488 @findex gnus-group-make-useful-group
2489 Create one of the groups mentioned in @code{gnus-useful-groups}
2490 (@code{gnus-group-make-useful-group}).
2494 @findex gnus-group-make-web-group
2499 Make an ephemeral group based on a web search
2500 (@code{gnus-group-make-web-group}). If you give a prefix to this
2501 command, make a solid group instead. You will be prompted for the
2502 search engine type and the search string. Valid search engine types
2503 include @code{dejanews}, @code{altavista} and @code{reference}.
2504 @xref{Web Searches}.
2506 If you use the @code{dejanews} search engine, you can limit the search
2507 to a particular group by using a match string like
2508 @samp{~g alt.sysadmin.recovery shaving}.
2511 @kindex G DEL (Group)
2512 @findex gnus-group-delete-group
2513 This function will delete the current group
2514 (@code{gnus-group-delete-group}). If given a prefix, this function will
2515 actually delete all the articles in the group, and forcibly remove the
2516 group itself from the face of the Earth. Use a prefix only if you are
2517 absolutely sure of what you are doing. This command can't be used on
2518 read-only groups (like @code{nntp} group), though.
2522 @findex gnus-group-make-empty-virtual
2523 Make a new, fresh, empty @code{nnvirtual} group
2524 (@code{gnus-group-make-empty-virtual}). @xref{Virtual Groups}.
2528 @findex gnus-group-add-to-virtual
2529 Add the current group to an @code{nnvirtual} group
2530 (@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
2533 @xref{Select Methods}, for more information on the various select
2536 @vindex gnus-activate-foreign-newsgroups
2537 If @code{gnus-activate-foreign-newsgroups} is a positive number,
2538 gnus will check all foreign groups with this level or lower at startup.
2539 This might take quite a while, especially if you subscribe to lots of
2540 groups from different @sc{nntp} servers. Also @pxref{Group Levels};
2541 @code{gnus-activate-level} also affects activation of foreign
2545 @node Group Parameters
2546 @section Group Parameters
2547 @cindex group parameters
2549 The group parameters store information local to a particular group.
2550 Here's an example group parameter list:
2553 ((to-address . "ding@@gnus.org")
2557 We see that each element consists of a "dotted pair"---the thing before
2558 the dot is the key, while the thing after the dot is the value. All the
2559 parameters have this form @emph{except} local variable specs, which are
2560 not dotted pairs, but proper lists.
2562 Some parameters have correspondant customizable variables, each of which
2563 is an alist of regexps and values.
2565 The following group parameters can be used:
2570 Address used by when doing followups and new posts.
2573 (to-address . "some@@where.com")
2576 This is primarily useful in mail groups that represent closed mailing
2577 lists---mailing lists where it's expected that everybody that writes to
2578 the mailing list is subscribed to it. Since using this parameter
2579 ensures that the mail only goes to the mailing list itself, it means
2580 that members won't receive two copies of your followups.
2582 Using @code{to-address} will actually work whether the group is foreign
2583 or not. Let's say there's a group on the server that is called
2584 @samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten
2585 the articles from a mail-to-news gateway. Posting directly to this
2586 group is therefore impossible---you have to send mail to the mailing
2587 list address instead.
2589 See also @code{gnus-parameter-to-address-alist}.
2593 Address used when doing @kbd{a} in that group.
2596 (to-list . "some@@where.com")
2599 It is totally ignored
2600 when doing a followup---except that if it is present in a news group,
2601 you'll get mail group semantics when doing @kbd{f}.
2603 If you do an @kbd{a} command in a mail group and you have neither a
2604 @code{to-list} group parameter nor a @code{to-address} group parameter,
2605 then a @code{to-list} group parameter will be added automatically upon
2606 sending the message if @code{gnus-add-to-list} is set to @code{t}.
2607 @vindex gnus-add-to-list
2609 If you do an @kbd{a} command in a mail group and you don't have a
2610 @code{to-list} group parameter, one will be added automatically upon
2611 sending the message.
2613 If this variable is set, @code{gnus-mailing-list-mode} is turned on when
2614 entering summary buffer.
2616 See also @code{gnus-parameter-to-list-alist}.
2620 If the group parameter list has the element @code{(visible . t)},
2621 that group will always be visible in the Group buffer, regardless
2622 of whether it has any unread articles.
2624 @item broken-reply-to
2625 @cindex broken-reply-to
2626 Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To}
2627 headers in this group are to be ignored. This can be useful if you're
2628 reading a mailing list group where the listserv has inserted
2629 @code{Reply-To} headers that point back to the listserv itself. This is
2630 broken behavior. So there!
2634 Elements like @code{(to-group . "some.group.name")} means that all
2635 posts in that group will be sent to @code{some.group.name}.
2639 If you have @code{(newsgroup . t)} in the group parameter list, gnus
2640 will treat all responses as if they were responses to news articles.
2641 This can be useful if you have a mail group that's really a mirror of a
2646 If @code{(gcc-self . t)} is present in the group parameter list, newly
2647 composed messages will be @code{Gcc}'d to the current group. If
2648 @code{(gcc-self . none)} is present, no @code{Gcc:} header will be
2649 generated, if @code{(gcc-self . "string")} is present, this string will
2650 be inserted literally as a @code{gcc} header. This parameter takes
2651 precedence over any default @code{Gcc} rules as described later
2652 (@pxref{Archived Messages}).
2656 If the group parameter has an element that looks like @code{(auto-expire
2657 . t)}, all articles read will be marked as expirable. For an
2658 alternative approach, @pxref{Expiring Mail}.
2660 See also @code{gnus-auto-expirable-newsgroups}.
2663 @cindex total-expire
2664 If the group parameter has an element that looks like
2665 @code{(total-expire . t)}, all read articles will be put through the
2666 expiry process, even if they are not marked as expirable. Use with
2667 caution. Unread, ticked and dormant articles are not eligible for
2670 See also @code{gnus-total-expirable-newsgroups}.
2674 @vindex nnmail-expiry-wait-function
2675 If the group parameter has an element that looks like @code{(expiry-wait
2676 . 10)}, this value will override any @code{nnmail-expiry-wait} and
2677 @code{nnmail-expiry-wait-function} when expiring expirable messages.
2678 The value can either be a number of days (not necessarily an integer) or
2679 the symbols @code{never} or @code{immediate}.
2682 @cindex score file group parameter
2683 Elements that look like @code{(score-file . "file")} will make
2684 @file{file} into the current score file for the group in question. All
2685 interactive score entries will be put into this file.
2688 @cindex adapt file group parameter
2689 Elements that look like @code{(adapt-file . "file")} will make
2690 @file{file} into the current adaptive file for the group in question.
2691 All adaptive score entries will be put into this file.
2694 When unsubscribing from a mailing list you should never send the
2695 unsubscription notice to the mailing list itself. Instead, you'd send
2696 messages to the administrative address. This parameter allows you to
2697 put the admin address somewhere convenient.
2700 Elements that look like @code{(display . MODE)} say which articles to
2701 display on entering the group. Valid values are:
2705 Display all articles, both read and unread.
2708 Display the default visible articles, which normally includes unread and
2713 Elements that look like @code{(comment . "This is a comment")}
2714 are arbitrary comments on the group. They are currently ignored by
2715 gnus, but provide a place for you to store information on particular
2719 Elements that look like @code{(charset . iso-8859-1)} will make
2720 @code{iso-8859-1} the default charset; that is, the charset that will be
2721 used for all articles that do not specify a charset.
2723 See also @code{gnus-group-charset-alist}.
2725 @item ignored-charsets
2726 Elements that look like @code{(ignored-charsets x-known iso-8859-1)}
2727 will make @code{iso-8859-1} and @code{x-unknown} ignored; that is, the
2728 default charset will be used for decoding articles.
2730 See also @code{gnus-group-ignored-charsets-alist}.
2733 You can store additional posting style information for this group only
2734 here (@pxref{Posting Styles}). The format is that of an entry in the
2735 @code{gnus-posting-styles} alist, except that there's no regexp matching
2736 the group name (of course). Style elements in this group parameter will
2737 take precedence over the ones found in @code{gnus-posting-styles}.
2739 For instance, if you want a funky name and signature in this group only,
2740 instead of hacking @code{gnus-posting-styles}, you could put something
2741 like this in the group parameters:
2746 (signature "Funky Signature"))
2751 If it is set, the value is used as the method for posting message
2752 instead of @code{gnus-post-method}.
2755 An item like @code{(banner . "regex")} causes any part of an article
2756 that matches the regular expression "regex" to be stripped. Instead of
2757 "regex", you can also use the symbol @code{signature} which strips the
2758 last signature or any of the elements of the alist
2759 @code{gnus-article-banner-alist}.
2761 @item (@var{variable} @var{form})
2762 You can use the group parameters to set variables local to the group you
2763 are entering. If you want to turn threading off in @samp{news.answers},
2764 you could put @code{(gnus-show-threads nil)} in the group parameters of
2765 that group. @code{gnus-show-threads} will be made into a local variable
2766 in the summary buffer you enter, and the form @code{nil} will be
2767 @code{eval}ed there.
2769 This can also be used as a group-specific hook function, if you'd like.
2770 If you want to hear a beep when you enter a group, you could put
2771 something like @code{(dummy-variable (ding))} in the parameters of that
2772 group. @code{dummy-variable} will be set to the result of the
2773 @code{(ding)} form, but who cares?
2777 Use the @kbd{G p} or the @kbd{G c} command to edit group parameters of a
2778 group. (@kbd{G p} presents you with a Lisp-based interface, @kbd{G c}
2779 presents you with a Customize-like interface. The latter helps avoid
2780 silly Lisp errors.) You might also be interested in reading about topic
2781 parameters (@pxref{Topic Parameters}).
2783 Group parameters can be set in @code{gnus-parameters} too. But some
2784 variables, such as @code{visible}, have no effect. For example,
2787 (setq gnus-parameters
2788 '(("mail\\..*" (gnus-show-threads nil)
2789 (gnus-use-scoring nil)
2790 (gnus-summary-line-format
2791 "%U%R%z%I%(%[%d:%ub%-20,20f%]%) %s\n")
2794 ("mail\\.me" (gnus-use-scoring t))
2795 ("list\\..*" (total-expire . t)
2796 (broken-reply-to . t)))
2799 @node Listing Groups
2800 @section Listing Groups
2801 @cindex group listing
2803 These commands all list various slices of the groups available.
2811 @findex gnus-group-list-groups
2812 List all groups that have unread articles
2813 (@code{gnus-group-list-groups}). If the numeric prefix is used, this
2814 command will list only groups of level ARG and lower. By default, it
2815 only lists groups of level five (i. e.,
2816 @code{gnus-group-default-list-level}) or lower (i.e., just subscribed
2823 @findex gnus-group-list-all-groups
2824 List all groups, whether they have unread articles or not
2825 (@code{gnus-group-list-all-groups}). If the numeric prefix is used,
2826 this command will list only groups of level ARG and lower. By default,
2827 it lists groups of level seven or lower (i.e., just subscribed and
2828 unsubscribed groups).
2832 @findex gnus-group-list-level
2833 List all unread groups on a specific level
2834 (@code{gnus-group-list-level}). If given a prefix, also list the groups
2835 with no unread articles.
2839 @findex gnus-group-list-killed
2840 List all killed groups (@code{gnus-group-list-killed}). If given a
2841 prefix argument, really list all groups that are available, but aren't
2842 currently (un)subscribed. This could entail reading the active file
2847 @findex gnus-group-list-zombies
2848 List all zombie groups (@code{gnus-group-list-zombies}).
2852 @findex gnus-group-list-matching
2853 List all unread, subscribed groups with names that match a regexp
2854 (@code{gnus-group-list-matching}).
2858 @findex gnus-group-list-all-matching
2859 List groups that match a regexp (@code{gnus-group-list-all-matching}).
2863 @findex gnus-group-list-active
2864 List absolutely all groups in the active file(s) of the
2865 server(s) you are connected to (@code{gnus-group-list-active}). This
2866 might very well take quite a while. It might actually be a better idea
2867 to do a @kbd{A M} to list all matching, and just give @samp{.} as the
2868 thing to match on. Also note that this command may list groups that
2869 don't exist (yet)---these will be listed as if they were killed groups.
2870 Take the output with some grains of salt.
2874 @findex gnus-group-apropos
2875 List all groups that have names that match a regexp
2876 (@code{gnus-group-apropos}).
2880 @findex gnus-group-description-apropos
2881 List all groups that have names or descriptions that match a regexp
2882 (@code{gnus-group-description-apropos}).
2886 @findex gnus-group-list-cached
2887 List all groups with cached articles (@code{gnus-group-list-cached}).
2891 @findex gnus-group-list-dormant
2892 List all groups with dormant articles (@code{gnus-group-list-dormant}).
2896 @findex gnus-group-list-limit
2897 List groups limited within the current selection
2898 (@code{gnus-group-list-limit}).
2902 @findex gnus-group-list-flush
2903 Flush groups from the current selection (@code{gnus-group-list-flush}).
2907 @findex gnus-group-list-plus
2908 List groups plus the current selection (@code{gnus-group-list-plus}).
2912 @vindex gnus-permanently-visible-groups
2913 @cindex visible group parameter
2914 Groups that match the @code{gnus-permanently-visible-groups} regexp will
2915 always be shown, whether they have unread articles or not. You can also
2916 add the @code{visible} element to the group parameters in question to
2917 get the same effect.
2919 @vindex gnus-list-groups-with-ticked-articles
2920 Groups that have just ticked articles in it are normally listed in the
2921 group buffer. If @code{gnus-list-groups-with-ticked-articles} is
2922 @code{nil}, these groups will be treated just like totally empty
2923 groups. It is @code{t} by default.
2926 @node Sorting Groups
2927 @section Sorting Groups
2928 @cindex sorting groups
2930 @kindex C-c C-s (Group)
2931 @findex gnus-group-sort-groups
2932 @vindex gnus-group-sort-function
2933 The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the
2934 group buffer according to the function(s) given by the
2935 @code{gnus-group-sort-function} variable. Available sorting functions
2940 @item gnus-group-sort-by-alphabet
2941 @findex gnus-group-sort-by-alphabet
2942 Sort the group names alphabetically. This is the default.
2944 @item gnus-group-sort-by-real-name
2945 @findex gnus-group-sort-by-real-name
2946 Sort the group alphabetically on the real (unprefixed) group names.
2948 @item gnus-group-sort-by-level
2949 @findex gnus-group-sort-by-level
2950 Sort by group level.
2952 @item gnus-group-sort-by-score
2953 @findex gnus-group-sort-by-score
2954 Sort by group score. @xref{Group Score}.
2956 @item gnus-group-sort-by-rank
2957 @findex gnus-group-sort-by-rank
2958 Sort by group score and then the group level. The level and the score
2959 are, when taken together, the group's @dfn{rank}. @xref{Group Score}.
2961 @item gnus-group-sort-by-unread
2962 @findex gnus-group-sort-by-unread
2963 Sort by number of unread articles.
2965 @item gnus-group-sort-by-method
2966 @findex gnus-group-sort-by-method
2967 Sort alphabetically on the select method.
2969 @item gnus-group-sort-by-server
2970 @findex gnus-group-sort-by-server
2971 Sort alphabetically on the Gnus server name.
2976 @code{gnus-group-sort-function} can also be a list of sorting
2977 functions. In that case, the most significant sort key function must be
2981 There are also a number of commands for sorting directly according to
2982 some sorting criteria:
2986 @kindex G S a (Group)
2987 @findex gnus-group-sort-groups-by-alphabet
2988 Sort the group buffer alphabetically by group name
2989 (@code{gnus-group-sort-groups-by-alphabet}).
2992 @kindex G S u (Group)
2993 @findex gnus-group-sort-groups-by-unread
2994 Sort the group buffer by the number of unread articles
2995 (@code{gnus-group-sort-groups-by-unread}).
2998 @kindex G S l (Group)
2999 @findex gnus-group-sort-groups-by-level
3000 Sort the group buffer by group level
3001 (@code{gnus-group-sort-groups-by-level}).
3004 @kindex G S v (Group)
3005 @findex gnus-group-sort-groups-by-score
3006 Sort the group buffer by group score
3007 (@code{gnus-group-sort-groups-by-score}). @xref{Group Score}.
3010 @kindex G S r (Group)
3011 @findex gnus-group-sort-groups-by-rank
3012 Sort the group buffer by group rank
3013 (@code{gnus-group-sort-groups-by-rank}). @xref{Group Score}.
3016 @kindex G S m (Group)
3017 @findex gnus-group-sort-groups-by-method
3018 Sort the group buffer alphabetically by backend name
3019 (@code{gnus-group-sort-groups-by-method}).
3023 All the commands below obey the process/prefix convention
3024 (@pxref{Process/Prefix}).
3026 When given a symbolic prefix (@pxref{Symbolic Prefixes}), all these
3027 commands will sort in reverse order.
3029 You can also sort a subset of the groups:
3033 @kindex G P a (Group)
3034 @findex gnus-group-sort-selected-groups-by-alphabet
3035 Sort the groups alphabetically by group name
3036 (@code{gnus-group-sort-selected-groups-by-alphabet}).
3039 @kindex G P u (Group)
3040 @findex gnus-group-sort-selected-groups-by-unread
3041 Sort the groups by the number of unread articles
3042 (@code{gnus-group-sort-selected-groups-by-unread}).
3045 @kindex G P l (Group)
3046 @findex gnus-group-sort-selected-groups-by-level
3047 Sort the groups by group level
3048 (@code{gnus-group-sort-selected-groups-by-level}).
3051 @kindex G P v (Group)
3052 @findex gnus-group-sort-selected-groups-by-score
3053 Sort the groups by group score
3054 (@code{gnus-group-sort-selected-groups-by-score}). @xref{Group Score}.
3057 @kindex G P r (Group)
3058 @findex gnus-group-sort-selected-groups-by-rank
3059 Sort the groups by group rank
3060 (@code{gnus-group-sort-selected-groups-by-rank}). @xref{Group Score}.
3063 @kindex G P m (Group)
3064 @findex gnus-group-sort-selected-groups-by-method
3065 Sort the groups alphabetically by backend name
3066 (@code{gnus-group-sort-selected-groups-by-method}).
3070 And finally, note that you can use @kbd{C-k} and @kbd{C-y} to manually
3074 @node Group Maintenance
3075 @section Group Maintenance
3076 @cindex bogus groups
3081 @findex gnus-group-check-bogus-groups
3082 Find bogus groups and delete them
3083 (@code{gnus-group-check-bogus-groups}).
3087 @findex gnus-group-find-new-groups
3088 Find new groups and process them (@code{gnus-group-find-new-groups}).
3089 With 1 @kbd{C-u}, use the @code{ask-server} method to query the server
3090 for new groups. With 2 @kbd{C-u}'s, use most complete method possible
3091 to query the server for new groups, and subscribe the new groups as
3095 @kindex C-c C-x (Group)
3096 @findex gnus-group-expire-articles
3097 Run all expirable articles in the current group through the expiry
3098 process (if any) (@code{gnus-group-expire-articles}). That is, delete
3099 all expirable articles in the group that have been around for a while.
3100 (@pxref{Expiring Mail}).
3103 @kindex C-c M-C-x (Group)
3104 @findex gnus-group-expire-all-groups
3105 Run all expirable articles in all groups through the expiry process
3106 (@code{gnus-group-expire-all-groups}).
3111 @node Browse Foreign Server
3112 @section Browse Foreign Server
3113 @cindex foreign servers
3114 @cindex browsing servers
3119 @findex gnus-group-browse-foreign-server
3120 You will be queried for a select method and a server name. Gnus will
3121 then attempt to contact this server and let you browse the groups there
3122 (@code{gnus-group-browse-foreign-server}).
3125 @findex gnus-browse-mode
3126 A new buffer with a list of available groups will appear. This buffer
3127 will use the @code{gnus-browse-mode}. This buffer looks a bit (well,
3128 a lot) like a normal group buffer.
3130 Here's a list of keystrokes available in the browse mode:
3135 @findex gnus-group-next-group
3136 Go to the next group (@code{gnus-group-next-group}).
3140 @findex gnus-group-prev-group
3141 Go to the previous group (@code{gnus-group-prev-group}).
3144 @kindex SPACE (Browse)
3145 @findex gnus-browse-read-group
3146 Enter the current group and display the first article
3147 (@code{gnus-browse-read-group}).
3150 @kindex RET (Browse)
3151 @findex gnus-browse-select-group
3152 Enter the current group (@code{gnus-browse-select-group}).
3156 @findex gnus-browse-unsubscribe-current-group
3157 Unsubscribe to the current group, or, as will be the case here,
3158 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
3164 @findex gnus-browse-exit
3165 Exit browse mode (@code{gnus-browse-exit}).
3169 @findex gnus-browse-describe-briefly
3170 Describe browse mode briefly (well, there's not much to describe, is
3171 there) (@code{gnus-browse-describe-briefly}).
3176 @section Exiting gnus
3177 @cindex exiting gnus
3179 Yes, gnus is ex(c)iting.
3184 @findex gnus-group-suspend
3185 Suspend gnus (@code{gnus-group-suspend}). This doesn't really exit gnus,
3186 but it kills all buffers except the Group buffer. I'm not sure why this
3187 is a gain, but then who am I to judge?
3191 @findex gnus-group-exit
3192 @c @icon{gnus-group-exit}
3193 Quit gnus (@code{gnus-group-exit}).
3197 @findex gnus-group-quit
3198 Quit gnus without saving the @file{.newsrc} files (@code{gnus-group-quit}).
3199 The dribble file will be saved, though (@pxref{Auto Save}).
3202 @vindex gnus-exit-gnus-hook
3203 @vindex gnus-suspend-gnus-hook
3204 @code{gnus-suspend-gnus-hook} is called when you suspend gnus and
3205 @code{gnus-exit-gnus-hook} is called when you quit gnus, while
3206 @code{gnus-after-exiting-gnus-hook} is called as the final item when
3211 If you wish to completely unload gnus and all its adherents, you can use
3212 the @code{gnus-unload} command. This command is also very handy when
3213 trying to customize meta-variables.
3218 Miss Lisa Cannifax, while sitting in English class, felt her feet go
3219 numbly heavy and herself fall into a hazy trance as the boy sitting
3220 behind her drew repeated lines with his pencil across the back of her
3226 @section Group Topics
3229 If you read lots and lots of groups, it might be convenient to group
3230 them hierarchically according to topics. You put your Emacs groups over
3231 here, your sex groups over there, and the rest (what, two groups or so?)
3232 you put in some misc section that you never bother with anyway. You can
3233 even group the Emacs sex groups as a sub-topic to either the Emacs
3234 groups or the sex groups---or both! Go wild!
3238 \gnusfigure{Group Topics}{400}{
3239 \put(75,50){\epsfig{figure=tmp/group-topic.ps,height=9cm}}
3250 2: alt.religion.emacs
3253 0: comp.talk.emacs.recovery
3255 8: comp.binaries.fractals
3256 13: comp.sources.unix
3259 @findex gnus-topic-mode
3261 To get this @emph{fab} functionality you simply turn on (ooh!) the
3262 @code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
3263 is a toggling command.)
3265 Go ahead, just try it. I'll still be here when you get back. La de
3266 dum... Nice tune, that... la la la... What, you're back? Yes, and now
3267 press @kbd{l}. There. All your groups are now listed under
3268 @samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
3271 If you want this permanently enabled, you should add that minor mode to
3272 the hook for the group mode:
3275 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
3279 * Topic Variables:: How to customize the topics the Lisp Way.
3280 * Topic Commands:: Interactive E-Z commands.
3281 * Topic Sorting:: Sorting each topic individually.
3282 * Topic Topology:: A map of the world.
3283 * Topic Parameters:: Parameters that apply to all groups in a topic.
3287 @node Topic Variables
3288 @subsection Topic Variables
3289 @cindex topic variables
3291 Now, if you select a topic, it will fold/unfold that topic, which is
3292 really neat, I think.
3294 @vindex gnus-topic-line-format
3295 The topic lines themselves are created according to the
3296 @code{gnus-topic-line-format} variable (@pxref{Formatting Variables}).
3309 Number of groups in the topic.
3311 Number of unread articles in the topic.
3313 Number of unread articles in the topic and all its subtopics.
3316 @vindex gnus-topic-indent-level
3317 Each sub-topic (and the groups in the sub-topics) will be indented with
3318 @code{gnus-topic-indent-level} times the topic level number of spaces.
3321 @vindex gnus-topic-mode-hook
3322 @code{gnus-topic-mode-hook} is called in topic minor mode buffers.
3324 @vindex gnus-topic-display-empty-topics
3325 The @code{gnus-topic-display-empty-topics} says whether to display even
3326 topics that have no unread articles in them. The default is @code{t}.
3329 @node Topic Commands
3330 @subsection Topic Commands
3331 @cindex topic commands
3333 When the topic minor mode is turned on, a new @kbd{T} submap will be
3334 available. In addition, a few of the standard keys change their
3335 definitions slightly.
3341 @findex gnus-topic-create-topic
3342 Prompt for a new topic name and create it
3343 (@code{gnus-topic-create-topic}).
3347 @findex gnus-topic-move-group
3348 Move the current group to some other topic
3349 (@code{gnus-topic-move-group}). This command uses the process/prefix
3350 convention (@pxref{Process/Prefix}).
3354 @findex gnus-topic-jump-to-topic
3355 Go to a topic (@code{gnus-topic-jump-to-topic}).
3359 @findex gnus-topic-copy-group
3360 Copy the current group to some other topic
3361 (@code{gnus-topic-copy-group}). This command uses the process/prefix
3362 convention (@pxref{Process/Prefix}).
3366 @findex gnus-topic-hide-topic
3367 Hide the current topic (@code{gnus-topic-hide-topic}). If given
3368 a prefix, hide the topic permanently.
3372 @findex gnus-topic-show-topic
3373 Show the current topic (@code{gnus-topic-show-topic}). If given
3374 a prefix, show the topic permanently.
3378 @findex gnus-topic-remove-group
3379 Remove a group from the current topic (@code{gnus-topic-remove-group}).
3380 This command is mainly useful if you have the same group in several
3381 topics and wish to remove it from one of the topics. You may also
3382 remove a group from all topics, but in that case, Gnus will add it to
3383 the root topic the next time you start Gnus. In fact, all new groups
3384 (which, naturally, don't belong to any topic) will show up in the root
3387 This command uses the process/prefix convention
3388 (@pxref{Process/Prefix}).
3392 @findex gnus-topic-move-matching
3393 Move all groups that match some regular expression to a topic
3394 (@code{gnus-topic-move-matching}).
3398 @findex gnus-topic-copy-matching
3399 Copy all groups that match some regular expression to a topic
3400 (@code{gnus-topic-copy-matching}).
3404 @findex gnus-topic-toggle-display-empty-topics
3405 Toggle hiding empty topics
3406 (@code{gnus-topic-toggle-display-empty-topics}).
3410 @findex gnus-topic-mark-topic
3411 Mark all groups in the current topic with the process mark
3412 (@code{gnus-topic-mark-topic}).
3415 @kindex T M-# (Topic)
3416 @findex gnus-topic-unmark-topic
3417 Remove the process mark from all groups in the current topic
3418 (@code{gnus-topic-unmark-topic}).
3422 @kindex T TAB (Topic)
3424 @findex gnus-topic-indent
3425 ``Indent'' the current topic so that it becomes a sub-topic of the
3426 previous topic (@code{gnus-topic-indent}). If given a prefix,
3427 ``un-indent'' the topic instead.
3430 @kindex M-TAB (Topic)
3431 @findex gnus-topic-unindent
3432 ``Un-indent'' the current topic so that it becomes a sub-topic of the
3433 parent of its current parent (@code{gnus-topic-unindent}).
3437 @findex gnus-topic-select-group
3439 Either select a group or fold a topic (@code{gnus-topic-select-group}).
3440 When you perform this command on a group, you'll enter the group, as
3441 usual. When done on a topic line, the topic will be folded (if it was
3442 visible) or unfolded (if it was folded already). So it's basically a
3443 toggling command on topics. In addition, if you give a numerical
3444 prefix, group on that level (and lower) will be displayed.
3447 @kindex C-c C-x (Topic)
3448 @findex gnus-topic-expire-articles
3449 Run all expirable articles in the current group or topic through the
3450 expiry process (if any)
3451 (@code{gnus-topic-expire-articles}). (@pxref{Expiring Mail}).
3455 @findex gnus-topic-kill-group
3456 Kill a group or topic (@code{gnus-topic-kill-group}). All groups in the
3457 topic will be removed along with the topic.
3461 @findex gnus-topic-yank-group
3462 Yank the previously killed group or topic
3463 (@code{gnus-topic-yank-group}). Note that all topics will be yanked
3468 @findex gnus-topic-rename
3469 Rename a topic (@code{gnus-topic-rename}).
3472 @kindex T DEL (Topic)
3473 @findex gnus-topic-delete
3474 Delete an empty topic (@code{gnus-topic-delete}).
3478 @findex gnus-topic-list-active
3479 List all groups that gnus knows about in a topics-ified way
3480 (@code{gnus-topic-list-active}).
3484 @findex gnus-topic-edit-parameters
3485 @cindex group parameters
3486 @cindex topic parameters
3488 Edit the topic parameters (@code{gnus-topic-edit-parameters}).
3489 @xref{Topic Parameters}.
3495 @subsection Topic Sorting
3496 @cindex topic sorting
3498 You can sort the groups in each topic individually with the following
3504 @kindex T S a (Topic)
3505 @findex gnus-topic-sort-groups-by-alphabet
3506 Sort the current topic alphabetically by group name
3507 (@code{gnus-topic-sort-groups-by-alphabet}).
3510 @kindex T S u (Topic)
3511 @findex gnus-topic-sort-groups-by-unread
3512 Sort the current topic by the number of unread articles
3513 (@code{gnus-topic-sort-groups-by-unread}).
3516 @kindex T S l (Topic)
3517 @findex gnus-topic-sort-groups-by-level
3518 Sort the current topic by group level
3519 (@code{gnus-topic-sort-groups-by-level}).
3522 @kindex T S v (Topic)
3523 @findex gnus-topic-sort-groups-by-score
3524 Sort the current topic by group score
3525 (@code{gnus-topic-sort-groups-by-score}). @xref{Group Score}.
3528 @kindex T S r (Topic)
3529 @findex gnus-topic-sort-groups-by-rank
3530 Sort the current topic by group rank
3531 (@code{gnus-topic-sort-groups-by-rank}). @xref{Group Score}.
3534 @kindex T S m (Topic)
3535 @findex gnus-topic-sort-groups-by-method
3536 Sort the current topic alphabetically by backend name
3537 (@code{gnus-topic-sort-groups-by-method}).
3541 @xref{Sorting Groups}, for more information about group sorting.
3544 @node Topic Topology
3545 @subsection Topic Topology
3546 @cindex topic topology
3549 So, let's have a look at an example group buffer:
3555 2: alt.religion.emacs
3558 0: comp.talk.emacs.recovery
3560 8: comp.binaries.fractals
3561 13: comp.sources.unix
3564 So, here we have one top-level topic (@samp{Gnus}), two topics under
3565 that, and one sub-topic under one of the sub-topics. (There is always
3566 just one (1) top-level topic). This topology can be expressed as
3571 (("Emacs -- I wuw it!" visible)
3572 (("Naughty Emacs" visible)))
3576 @vindex gnus-topic-topology
3577 This is in fact how the variable @code{gnus-topic-topology} would look
3578 for the display above. That variable is saved in the @file{.newsrc.eld}
3579 file, and shouldn't be messed with manually---unless you really want
3580 to. Since this variable is read from the @file{.newsrc.eld} file,
3581 setting it in any other startup files will have no effect.
3583 This topology shows what topics are sub-topics of what topics (right),
3584 and which topics are visible. Two settings are currently
3585 allowed---@code{visible} and @code{invisible}.
3588 @node Topic Parameters
3589 @subsection Topic Parameters
3590 @cindex topic parameters
3592 All groups in a topic will inherit group parameters from the parent (and
3593 ancestor) topic parameters. All valid group parameters are valid topic
3594 parameters (@pxref{Group Parameters}).
3596 In addition, the following parameters are only valid as topic
3601 When subscribing new groups by topic (@pxref{Subscription Methods}), the
3602 @code{subscribe} topic parameter says what groups go in what topic. Its
3603 value should be a regexp to match the groups that should go in that
3608 Group parameters (of course) override topic parameters, and topic
3609 parameters in sub-topics override topic parameters in super-topics. You
3610 know. Normal inheritance rules. (@dfn{Rules} is here a noun, not a
3611 verb, although you may feel free to disagree with me here.)
3617 2: alt.religion.emacs
3621 0: comp.talk.emacs.recovery
3623 8: comp.binaries.fractals
3624 13: comp.sources.unix
3628 The @samp{Emacs} topic has the topic parameter @code{(score-file
3629 . "emacs.SCORE")}; the @samp{Relief} topic has the topic parameter
3630 @code{(score-file . "relief.SCORE")}; and the @samp{Misc} topic has the
3631 topic parameter @code{(score-file . "emacs.SCORE")}. In addition,
3632 @* @samp{alt.religion.emacs} has the group parameter @code{(score-file
3633 . "religion.SCORE")}.
3635 Now, when you enter @samp{alt.sex.emacs} in the @samp{Relief} topic, you
3636 will get the @file{relief.SCORE} home score file. If you enter the same
3637 group in the @samp{Emacs} topic, you'll get the @file{emacs.SCORE} home
3638 score file. If you enter the group @samp{alt.religion.emacs}, you'll
3639 get the @file{religion.SCORE} home score file.
3641 This seems rather simple and self-evident, doesn't it? Well, yes. But
3642 there are some problems, especially with the @code{total-expiry}
3643 parameter. Say you have a mail group in two topics; one with
3644 @code{total-expiry} and one without. What happens when you do @kbd{M-x
3645 gnus-expire-all-expirable-groups}? Gnus has no way of telling which one
3646 of these topics you mean to expire articles from, so anything may
3647 happen. In fact, I hereby declare that it is @dfn{undefined} what
3648 happens. You just have to be careful if you do stuff like that.
3651 @node Misc Group Stuff
3652 @section Misc Group Stuff
3655 * Scanning New Messages:: Asking gnus to see whether new messages have arrived.
3656 * Group Information:: Information and help on groups and gnus.
3657 * Group Timestamp:: Making gnus keep track of when you last read a group.
3658 * File Commands:: Reading and writing the gnus files.
3665 @findex gnus-group-enter-server-mode
3666 Enter the server buffer (@code{gnus-group-enter-server-mode}).
3667 @xref{Server Buffer}.
3671 @findex gnus-group-post-news
3672 Post an article to a group (@code{gnus-group-post-news}). If given a
3673 prefix, the current group name will be used as the default.
3677 @findex gnus-group-mail
3678 Mail a message somewhere (@code{gnus-group-mail}).
3682 Variables for the group buffer:
3686 @item gnus-group-mode-hook
3687 @vindex gnus-group-mode-hook
3688 is called after the group buffer has been
3691 @item gnus-group-prepare-hook
3692 @vindex gnus-group-prepare-hook
3693 is called after the group buffer is
3694 generated. It may be used to modify the buffer in some strange,
3697 @item gnus-group-prepared-hook
3698 @vindex gnus-group-prepare-hook
3699 is called as the very last thing after the group buffer has been
3700 generated. It may be used to move point around, for instance.
3702 @item gnus-permanently-visible-groups
3703 @vindex gnus-permanently-visible-groups
3704 Groups matching this regexp will always be listed in the group buffer,
3705 whether they are empty or not.
3707 @item gnus-group-name-charset-method-alist
3708 @vindex gnus-group-name-charset-method-alist
3709 An alist of method and the charset for group names. It is used to show
3710 non-ASCII group names.
3714 (setq gnus-group-name-charset-method-alist
3715 '(((nntp "news.com.cn") . cn-gb-2312)))
3718 @item gnus-group-name-charset-group-alist
3719 @vindex gnus-group-name-charset-group-alist
3720 An alist of regexp of group name and the charset for group names.
3721 It is used to show non-ASCII group names.
3725 (setq gnus-group-name-charset-group-alist
3726 '(("\\.com\\.cn:" . cn-gb-2312)))
3731 @node Scanning New Messages
3732 @subsection Scanning New Messages
3733 @cindex new messages
3734 @cindex scanning new news
3740 @findex gnus-group-get-new-news
3741 @c @icon{gnus-group-get-new-news}
3742 Check the server(s) for new articles. If the numerical prefix is used,
3743 this command will check only groups of level @var{arg} and lower
3744 (@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
3745 command will force a total re-reading of the active file(s) from the
3750 @findex gnus-group-get-new-news-this-group
3751 @vindex gnus-goto-next-group-when-activating
3752 @c @icon{gnus-group-get-new-news-this-group}
3753 Check whether new articles have arrived in the current group
3754 (@code{gnus-group-get-new-news-this-group}).
3755 @code{gnus-goto-next-group-when-activating} says whether this command is
3756 to move point to the next group or not. It is @code{t} by default.
3758 @findex gnus-activate-all-groups
3759 @cindex activating groups
3761 @kindex C-c M-g (Group)
3762 Activate absolutely all groups (@code{gnus-activate-all-groups}).
3767 @findex gnus-group-restart
3768 Restart gnus (@code{gnus-group-restart}). This saves the @file{.newsrc}
3769 file(s), closes the connection to all servers, clears up all run-time
3770 gnus variables, and then starts gnus all over again.
3774 @vindex gnus-get-new-news-hook
3775 @code{gnus-get-new-news-hook} is run just before checking for new news.
3777 @vindex gnus-after-getting-new-news-hook
3778 @code{gnus-after-getting-new-news-hook} is run after checking for new
3782 @node Group Information
3783 @subsection Group Information
3784 @cindex group information
3785 @cindex information on groups
3792 @findex gnus-group-fetch-faq
3793 @vindex gnus-group-faq-directory
3796 Try to fetch the FAQ for the current group
3797 (@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
3798 @code{gnus-group-faq-directory}, which is usually a directory on a
3799 remote machine. This variable can also be a list of directories. In
3800 that case, giving a prefix to this command will allow you to choose
3801 between the various sites. @code{ange-ftp} (or @code{efs}) will be used
3802 for fetching the file.
3804 If fetching from the first site is unsuccessful, gnus will attempt to go
3805 through @code{gnus-group-faq-directory} and try to open them one by one.
3809 @c @icon{gnus-group-describe-group}
3811 @kindex C-c C-d (Group)
3812 @cindex describing groups
3813 @cindex group description
3814 @findex gnus-group-describe-group
3815 Describe the current group (@code{gnus-group-describe-group}). If given
3816 a prefix, force Gnus to re-read the description from the server.
3820 @findex gnus-group-describe-all-groups
3821 Describe all groups (@code{gnus-group-describe-all-groups}). If given a
3822 prefix, force gnus to re-read the description file from the server.
3829 @findex gnus-version
3830 Display current gnus version numbers (@code{gnus-version}).
3834 @findex gnus-group-describe-briefly
3835 Give a very short help message (@code{gnus-group-describe-briefly}).
3838 @kindex C-c C-i (Group)
3841 @findex gnus-info-find-node
3842 Go to the gnus info node (@code{gnus-info-find-node}).
3846 @node Group Timestamp
3847 @subsection Group Timestamp
3849 @cindex group timestamps
3851 It can be convenient to let gnus keep track of when you last read a
3852 group. To set the ball rolling, you should add
3853 @code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}:
3856 (add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp)
3859 After doing this, each time you enter a group, it'll be recorded.
3861 This information can be displayed in various ways---the easiest is to
3862 use the @samp{%d} spec in the group line format:
3865 (setq gnus-group-line-format
3866 "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n")
3869 This will result in lines looking like:
3872 * 0: mail.ding 19961002T012943
3873 0: custom 19961002T012713
3876 As you can see, the date is displayed in compact ISO 8601 format. This
3877 may be a bit too much, so to just display the date, you could say
3881 (setq gnus-group-line-format
3882 "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n")
3887 @subsection File Commands
3888 @cindex file commands
3894 @findex gnus-group-read-init-file
3895 @vindex gnus-init-file
3896 @cindex reading init file
3897 Re-read the init file (@code{gnus-init-file}, which defaults to
3898 @file{~/.gnus}) (@code{gnus-group-read-init-file}).
3902 @findex gnus-group-save-newsrc
3903 @cindex saving .newsrc
3904 Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
3905 (@code{gnus-group-save-newsrc}). If given a prefix, force saving the
3906 file(s) whether Gnus thinks it is necessary or not.
3909 @c @kindex Z (Group)
3910 @c @findex gnus-group-clear-dribble
3911 @c Clear the dribble buffer (@code{gnus-group-clear-dribble}).
3916 @node Summary Buffer
3917 @chapter Summary Buffer
3918 @cindex summary buffer
3920 A line for each article is displayed in the summary buffer. You can
3921 move around, read articles, post articles and reply to articles.
3923 The most common way to a summary buffer is to select a group from the
3924 group buffer (@pxref{Selecting a Group}).
3926 You can have as many summary buffers open as you wish.
3929 * Summary Buffer Format:: Deciding how the summary buffer is to look.
3930 * Summary Maneuvering:: Moving around the summary buffer.
3931 * Choosing Articles:: Reading articles.
3932 * Paging the Article:: Scrolling the current article.
3933 * Reply Followup and Post:: Posting articles.
3934 * Marking Articles:: Marking articles as read, expirable, etc.
3935 * Limiting:: You can limit the summary buffer.
3936 * Threading:: How threads are made.
3937 * Sorting the Summary Buffer:: How articles and threads are sorted.
3938 * Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
3939 * Article Caching:: You may store articles in a cache.
3940 * Persistent Articles:: Making articles expiry-resistant.
3941 * Article Backlog:: Having already read articles hang around.
3942 * Saving Articles:: Ways of customizing article saving.
3943 * Decoding Articles:: Gnus can treat series of (uu)encoded articles.
3944 * Article Treatment:: The article buffer can be mangled at will.
3945 * MIME Commands:: Doing MIMEy things with the articles.
3946 * Charsets:: Character set issues.
3947 * Article Commands:: Doing various things with the article buffer.
3948 * Summary Sorting:: Sorting the summary buffer in various ways.
3949 * Finding the Parent:: No child support? Get the parent.
3950 * Alternative Approaches:: Reading using non-default summaries.
3951 * Tree Display:: A more visual display of threads.
3952 * Mail Group Commands:: Some commands can only be used in mail groups.
3953 * Various Summary Stuff:: What didn't fit anywhere else.
3954 * Exiting the Summary Buffer:: Returning to the Group buffer,
3955 or reselecting the current group.
3956 * Crosspost Handling:: How crossposted articles are dealt with.
3957 * Duplicate Suppression:: An alternative when crosspost handling fails.
3958 * Security:: Decrypt and Verify.
3959 * Mailing List:: Mailing list minor mode.
3963 @node Summary Buffer Format
3964 @section Summary Buffer Format
3965 @cindex summary buffer format
3969 \gnusfigure{The Summary Buffer}{180}{
3970 \put(0,0){\epsfig{figure=tmp/summary.ps,width=7.5cm}}
3971 \put(445,0){\makebox(0,0)[br]{\epsfig{figure=tmp/summary-article.ps,width=7.5cm}}}
3977 * Summary Buffer Lines:: You can specify how summary lines should look.
3978 * To From Newsgroups:: How to not display your own name.
3979 * Summary Buffer Mode Line:: You can say how the mode line should look.
3980 * Summary Highlighting:: Making the summary buffer all pretty and nice.
3983 @findex mail-extract-address-components
3984 @findex gnus-extract-address-components
3985 @vindex gnus-extract-address-components
3986 Gnus will use the value of the @code{gnus-extract-address-components}
3987 variable as a function for getting the name and address parts of a
3988 @code{From} header. Three pre-defined functions exist:
3989 @code{gnus-extract-address-components}, which is the default, quite
3990 fast, and too simplistic solution;
3991 @code{mail-extract-address-components}, which works nicely, but is
3992 slower; and @code{std11-extract-address-components}, which works very
3993 nicely, but is slower. The default function will return the wrong
3994 answer in 5% of the cases. If this is unacceptable to you, use the
3995 other function instead:
3998 (setq gnus-extract-address-components
3999 'mail-extract-address-components)
4002 @vindex gnus-summary-same-subject
4003 @code{gnus-summary-same-subject} is a string indicating that the current
4004 article has the same subject as the previous. This string will be used
4005 with those specs that require it. The default is @code{""}.
4008 @node Summary Buffer Lines
4009 @subsection Summary Buffer Lines
4011 @vindex gnus-summary-line-format
4012 You can change the format of the lines in the summary buffer by changing
4013 the @code{gnus-summary-line-format} variable. It works along the same
4014 lines as a normal @code{format} string, with some extensions
4015 (@pxref{Formatting Variables}).
4017 There should always be a colon on the line; the cursor always moves to
4018 the colon after performing an operation. (Of course, Gnus wouldn't be
4019 Gnus if it wasn't possible to change this. Just write a new function
4020 @code{gnus-goto-colon} which does whatever you like with the cursor.)
4022 The default string is @samp{%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n}.
4024 The following format specification characters are understood:
4030 Subject string. List identifiers stripped,
4031 @code{gnus-list-identifies}. @xref{Article Hiding}.
4033 Subject if the article is the root of the thread or the previous article
4034 had a different subject, @code{gnus-summary-same-subject} otherwise.
4035 (@code{gnus-summary-same-subject} defaults to @code{""}.)
4037 Full @code{From} header.
4039 The name (from the @code{From} header).
4041 The name, code @code{To} header or the @code{Newsgroups} header
4042 (@pxref{To From Newsgroups}).
4044 The name (from the @code{From} header). This differs from the @code{n}
4045 spec in that it uses the function designated by the
4046 @code{gnus-extract-address-components} variable, which is slower, but
4047 may be more thorough.
4049 The address (from the @code{From} header). This works the same way as
4052 Number of lines in the article.
4054 Number of characters in the article. This specifier is not supported in some
4055 methods (like nnfolder).
4057 Indentation based on thread level (@pxref{Customizing Threading}).
4059 A complex trn-style thread tree, showing response-connecting trace lines.
4061 Nothing if the article is a root and lots of spaces if it isn't (it
4062 pushes everything after it off the screen).
4064 Opening bracket, which is normally @samp{[}, but can also be @samp{<}
4065 for adopted articles (@pxref{Customizing Threading}).
4067 Closing bracket, which is normally @samp{]}, but can also be @samp{>}
4068 for adopted articles.
4070 One space for each thread level.
4072 Twenty minus thread level spaces.
4077 This misleadingly named specifier is the @dfn{secondary mark}. This
4078 mark will say whether the article has been replied to, has been cached,
4082 Score as a number (@pxref{Scoring}).
4084 @vindex gnus-summary-zcore-fuzz
4085 Zcore, @samp{+} if above the default level and @samp{-} if below the
4086 default level. If the difference between
4087 @code{gnus-summary-default-score} and the score is less than
4088 @code{gnus-summary-zcore-fuzz}, this spec will not be used.
4096 The @code{Date} in @code{DD-MMM} format.
4098 The @code{Date} in @var{YYYYMMDD}@code{T}@var{HHMMSS} format.
4104 Number of articles in the current sub-thread. Using this spec will slow
4105 down summary buffer generation somewhat.
4107 An @samp{=} (@code{gnus-not-empty-thread-mark}) will be displayed if the
4108 article has any children.
4114 User defined specifier. The next character in the format string should
4115 be a letter. Gnus will call the function
4116 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
4117 following @samp{%u}. The function will be passed the current header as
4118 argument. The function should return a string, which will be inserted
4119 into the summary just like information from any other summary specifier.
4122 The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
4123 have to be handled with care. For reasons of efficiency, gnus will
4124 compute what column these characters will end up in, and ``hard-code''
4125 that. This means that it is invalid to have these specs after a
4126 variable-length spec. Well, you might not be arrested, but your summary
4127 buffer will look strange, which is bad enough.
4129 The smart choice is to have these specs as far to the left as possible.
4130 (Isn't that the case with everything, though? But I digress.)
4132 This restriction may disappear in later versions of gnus.
4135 @node To From Newsgroups
4136 @subsection To From Newsgroups
4140 In some groups (particularly in archive groups), the @code{From} header
4141 isn't very interesting, since all the articles there are written by
4142 you. To display the information in the @code{To} or @code{Newsgroups}
4143 headers instead, you need to decide three things: What information to
4144 gather; where to display it; and when to display it.
4148 @vindex gnus-extra-headers
4149 The reading of extra header information is controlled by the
4150 @code{gnus-extra-headers}. This is a list of header symbols. For
4154 (setq gnus-extra-headers
4155 '(To Newsgroups X-Newsreader))
4158 This will result in Gnus trying to obtain these three headers, and
4159 storing it in header structures for later easy retrieval.
4162 @findex gnus-extra-header
4163 The value of these extra headers can be accessed via the
4164 @code{gnus-extra-header} function. Here's a format line spec that will
4165 access the @code{X-Newsreader} header:
4168 "%~(form (gnus-extra-header 'X-Newsreader))@@"
4172 @vindex gnus-ignored-from-addresses
4173 The @code{gnus-ignored-from-addresses} variable says when the @samp{%f}
4174 summary line spec returns the @code{To}, @code{Newsreader} or
4175 @code{From} header. If this regexp matches the contents of the
4176 @code{From} header, the value of the @code{To} or @code{Newsreader}
4177 headers are used instead.
4181 @vindex nnmail-extra-headers
4182 A related variable is @code{nnmail-extra-headers}, which controls when
4183 to include extra headers when generating overview (@sc{nov}) files. If
4184 you have old overview files, you should regenerate them after changing
4187 @vindex gnus-summary-line-format
4188 You also have to instruct Gnus to display the data by changing the
4189 @code{%n} spec to the @code{%f} spec in the
4190 @code{gnus-summary-line-format} variable.
4192 In summary, you'd typically put something like the following in
4196 (setq gnus-extra-headers
4198 (setq nnmail-extra-headers gnus-extra-headers)
4199 (setq gnus-summary-line-format
4200 "%U%R%z%I%(%[%4L: %-20,20f%]%) %s\n")
4201 (setq gnus-ignored-from-addresses
4205 Now, this is mostly useful for mail groups, where you have control over
4206 the @sc{nov} files that are created. However, if you can persuade your
4213 to the end of her @file{overview.fmt} file, then you can use that just
4214 as you would the extra headers from the mail groups.
4217 @node Summary Buffer Mode Line
4218 @subsection Summary Buffer Mode Line
4220 @vindex gnus-summary-mode-line-format
4221 You can also change the format of the summary mode bar (@pxref{Mode Line
4222 Formatting}). Set @code{gnus-summary-mode-line-format} to whatever you
4223 like. The default is @samp{Gnus: %%b [%A] %Z}.
4225 Here are the elements you can play with:
4231 Unprefixed group name.
4233 Current article number.
4235 Current article score.
4239 Number of unread articles in this group.
4241 Number of unread articles in this group that aren't displayed in the
4244 A string with the number of unread and unselected articles represented
4245 either as @samp{<%U(+%e) more>} if there are both unread and unselected
4246 articles, and just as @samp{<%U more>} if there are just unread articles
4247 and no unselected ones.
4249 Shortish group name. For instance, @samp{rec.arts.anime} will be
4250 shortened to @samp{r.a.anime}.
4252 Subject of the current article.
4254 User-defined spec (@pxref{User-Defined Specs}).
4256 Name of the current score file (@pxref{Scoring}).
4258 Number of dormant articles (@pxref{Unread Articles}).
4260 Number of ticked articles (@pxref{Unread Articles}).
4262 Number of articles that have been marked as read in this session.
4264 Number of articles expunged by the score files.
4268 @node Summary Highlighting
4269 @subsection Summary Highlighting
4273 @item gnus-visual-mark-article-hook
4274 @vindex gnus-visual-mark-article-hook
4275 This hook is run after selecting an article. It is meant to be used for
4276 highlighting the article in some way. It is not run if
4277 @code{gnus-visual} is @code{nil}.
4279 @item gnus-summary-update-hook
4280 @vindex gnus-summary-update-hook
4281 This hook is called when a summary line is changed. It is not run if
4282 @code{gnus-visual} is @code{nil}.
4284 @item gnus-summary-selected-face
4285 @vindex gnus-summary-selected-face
4286 This is the face (or @dfn{font} as some people call it) used to
4287 highlight the current article in the summary buffer.
4289 @item gnus-summary-highlight
4290 @vindex gnus-summary-highlight
4291 Summary lines are highlighted according to this variable, which is a
4292 list where the elements are of the format @code{(@var{form}
4293 . @var{face})}. If you would, for instance, like ticked articles to be
4294 italic and high-scored articles to be bold, you could set this variable
4297 (((eq mark gnus-ticked-mark) . italic)
4298 ((> score default) . bold))
4300 As you may have guessed, if @var{form} returns a non-@code{nil} value,
4301 @var{face} will be applied to the line.
4305 @node Summary Maneuvering
4306 @section Summary Maneuvering
4307 @cindex summary movement
4309 All the straight movement commands understand the numeric prefix and
4310 behave pretty much as you'd expect.
4312 None of these commands select articles.
4317 @kindex M-n (Summary)
4318 @kindex G M-n (Summary)
4319 @findex gnus-summary-next-unread-subject
4320 Go to the next summary line of an unread article
4321 (@code{gnus-summary-next-unread-subject}).
4325 @kindex M-p (Summary)
4326 @kindex G M-p (Summary)
4327 @findex gnus-summary-prev-unread-subject
4328 Go to the previous summary line of an unread article
4329 (@code{gnus-summary-prev-unread-subject}).
4332 @kindex G g (Summary)
4333 @findex gnus-summary-goto-subject
4334 Ask for an article number and then go to the summary line of that article
4335 without displaying the article (@code{gnus-summary-goto-subject}).
4338 If gnus asks you to press a key to confirm going to the next group, you
4339 can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
4340 buffer, searching for the next group to read without actually returning
4341 to the group buffer.
4343 Variables related to summary movement:
4347 @vindex gnus-auto-select-next
4348 @item gnus-auto-select-next
4349 If you issue one of the movement commands (like @kbd{n}) and there are
4350 no more unread articles after the current one, gnus will offer to go to
4351 the next group. If this variable is @code{t} and the next group is
4352 empty, gnus will exit summary mode and return to the group buffer. If
4353 this variable is neither @code{t} nor @code{nil}, gnus will select the
4354 next group, no matter whether it has any unread articles or not. As a
4355 special case, if this variable is @code{quietly}, gnus will select the
4356 next group without asking for confirmation. If this variable is
4357 @code{almost-quietly}, the same will happen only if you are located on
4358 the last article in the group. Finally, if this variable is
4359 @code{slightly-quietly}, the @kbd{Z n} command will go to the next group
4360 without confirmation. Also @pxref{Group Levels}.
4362 @item gnus-auto-select-same
4363 @vindex gnus-auto-select-same
4364 If non-@code{nil}, all the movement commands will try to go to the next
4365 article with the same subject as the current. (@dfn{Same} here might
4366 mean @dfn{roughly equal}. See @code{gnus-summary-gather-subject-limit}
4367 for details (@pxref{Customizing Threading}).) If there are no more
4368 articles with the same subject, go to the first unread article.
4370 This variable is not particularly useful if you use a threaded display.
4372 @item gnus-summary-check-current
4373 @vindex gnus-summary-check-current
4374 If non-@code{nil}, all the ``unread'' movement commands will not proceed
4375 to the next (or previous) article if the current article is unread.
4376 Instead, they will choose the current article.
4378 @item gnus-auto-center-summary
4379 @vindex gnus-auto-center-summary
4380 If non-@code{nil}, gnus will keep the point in the summary buffer
4381 centered at all times. This makes things quite tidy, but if you have a
4382 slow network connection, or simply do not like this un-Emacsism, you can
4383 set this variable to @code{nil} to get the normal Emacs scrolling
4384 action. This will also inhibit horizontal re-centering of the summary
4385 buffer, which might make it more inconvenient to read extremely long
4388 This variable can also be a number. In that case, center the window at
4389 the given number of lines from the top.
4394 @node Choosing Articles
4395 @section Choosing Articles
4396 @cindex selecting articles
4399 * Choosing Commands:: Commands for choosing articles.
4400 * Choosing Variables:: Variables that influence these commands.
4404 @node Choosing Commands
4405 @subsection Choosing Commands
4407 None of the following movement commands understand the numeric prefix,
4408 and they all select and display an article.
4410 If you want to fetch new articles or redisplay the group, see
4411 @ref{Exiting the Summary Buffer}.
4415 @kindex SPACE (Summary)
4416 @findex gnus-summary-next-page
4417 Select the current article, or, if that one's read already, the next
4418 unread article (@code{gnus-summary-next-page}).
4423 @kindex G n (Summary)
4424 @findex gnus-summary-next-unread-article
4425 @c @icon{gnus-summary-next-unread}
4426 Go to next unread article (@code{gnus-summary-next-unread-article}).
4431 @findex gnus-summary-prev-unread-article
4432 @c @icon{gnus-summary-prev-unread}
4433 Go to previous unread article (@code{gnus-summary-prev-unread-article}).
4438 @kindex G N (Summary)
4439 @findex gnus-summary-next-article
4440 Go to the next article (@code{gnus-summary-next-article}).
4445 @kindex G P (Summary)
4446 @findex gnus-summary-prev-article
4447 Go to the previous article (@code{gnus-summary-prev-article}).
4450 @kindex G C-n (Summary)
4451 @findex gnus-summary-next-same-subject
4452 Go to the next article with the same subject
4453 (@code{gnus-summary-next-same-subject}).
4456 @kindex G C-p (Summary)
4457 @findex gnus-summary-prev-same-subject
4458 Go to the previous article with the same subject
4459 (@code{gnus-summary-prev-same-subject}).
4463 @kindex G f (Summary)
4465 @findex gnus-summary-first-unread-article
4466 Go to the first unread article
4467 (@code{gnus-summary-first-unread-article}).
4471 @kindex G b (Summary)
4473 @findex gnus-summary-best-unread-article
4474 Go to the article with the highest score
4475 (@code{gnus-summary-best-unread-article}).
4480 @kindex G l (Summary)
4481 @findex gnus-summary-goto-last-article
4482 Go to the previous article read (@code{gnus-summary-goto-last-article}).
4485 @kindex G o (Summary)
4486 @findex gnus-summary-pop-article
4488 @cindex article history
4489 Pop an article off the summary history and go to this article
4490 (@code{gnus-summary-pop-article}). This command differs from the
4491 command above in that you can pop as many previous articles off the
4492 history as you like, while @kbd{l} toggles the two last read articles.
4493 For a somewhat related issue (if you use these commands a lot),
4494 @pxref{Article Backlog}.
4499 @kindex G j (Summary)
4500 @findex gnus-summary-goto-article
4501 Ask for an article number or @code{Message-ID}, and then go to that
4502 article (@code{gnus-summary-goto-article}).
4507 @node Choosing Variables
4508 @subsection Choosing Variables
4510 Some variables relevant for moving and selecting articles:
4513 @item gnus-auto-extend-newsgroup
4514 @vindex gnus-auto-extend-newsgroup
4515 All the movement commands will try to go to the previous (or next)
4516 article, even if that article isn't displayed in the Summary buffer if
4517 this variable is non-@code{nil}. Gnus will then fetch the article from
4518 the server and display it in the article buffer.
4520 @item gnus-select-article-hook
4521 @vindex gnus-select-article-hook
4522 This hook is called whenever an article is selected. By default it
4523 exposes any threads hidden under the selected article.
4525 @item gnus-mark-article-hook
4526 @vindex gnus-mark-article-hook
4527 @findex gnus-summary-mark-unread-as-read
4528 @findex gnus-summary-mark-read-and-unread-as-read
4529 @findex gnus-unread-mark
4530 This hook is called whenever an article is selected. It is intended to
4531 be used for marking articles as read. The default value is
4532 @code{gnus-summary-mark-read-and-unread-as-read}, and will change the
4533 mark of almost any article you read to @code{gnus-unread-mark}. The
4534 only articles not affected by this function are ticked, dormant, and
4535 expirable articles. If you'd instead like to just have unread articles
4536 marked as read, you can use @code{gnus-summary-mark-unread-as-read}
4537 instead. It will leave marks like @code{gnus-low-score-mark},
4538 @code{gnus-del-mark} (and so on) alone.
4543 @node Paging the Article
4544 @section Scrolling the Article
4545 @cindex article scrolling
4550 @kindex SPACE (Summary)
4551 @findex gnus-summary-next-page
4552 Pressing @kbd{SPACE} will scroll the current article forward one page,
4553 or, if you have come to the end of the current article, will choose the
4554 next article (@code{gnus-summary-next-page}).
4557 @kindex DEL (Summary)
4558 @findex gnus-summary-prev-page
4559 Scroll the current article back one page (@code{gnus-summary-prev-page}).
4562 @kindex RET (Summary)
4563 @findex gnus-summary-scroll-up
4564 Scroll the current article one line forward
4565 (@code{gnus-summary-scroll-up}).
4568 @kindex M-RET (Summary)
4569 @findex gnus-summary-scroll-down
4570 Scroll the current article one line backward
4571 (@code{gnus-summary-scroll-down}).
4575 @kindex A g (Summary)
4577 @findex gnus-summary-show-article
4578 @vindex gnus-summary-show-article-charset-alist
4579 (Re)fetch the current article (@code{gnus-summary-show-article}). If
4580 given a prefix, fetch the current article, but don't run any of the
4581 article treatment functions. This will give you a ``raw'' article, just
4582 the way it came from the server.
4584 If given a numerical prefix, you can do semi-manual charset stuff.
4585 @kbd{C-u 0 g cn-gb-2312 RET} will decode the message as if it were
4586 encoded in the @code{cn-gb-2312} charset. If you have
4589 (setq gnus-summary-show-article-charset-alist
4594 then you can say @kbd{C-u 1 g} to get the same effect.
4599 @kindex A < (Summary)
4600 @findex gnus-summary-beginning-of-article
4601 Scroll to the beginning of the article
4602 (@code{gnus-summary-beginning-of-article}).
4607 @kindex A > (Summary)
4608 @findex gnus-summary-end-of-article
4609 Scroll to the end of the article (@code{gnus-summary-end-of-article}).
4613 @kindex A s (Summary)
4615 @findex gnus-summary-isearch-article
4616 Perform an isearch in the article buffer
4617 (@code{gnus-summary-isearch-article}).
4621 @findex gnus-summary-select-article-buffer
4622 Select the article buffer (@code{gnus-summary-select-article-buffer}).
4627 @node Reply Followup and Post
4628 @section Reply, Followup and Post
4631 * Summary Mail Commands:: Sending mail.
4632 * Summary Post Commands:: Sending news.
4633 * Summary Message Commands:: Other Message-related commands.
4634 * Canceling and Superseding:: ``Whoops, I shouldn't have called him that.''
4638 @node Summary Mail Commands
4639 @subsection Summary Mail Commands
4641 @cindex composing mail
4643 Commands for composing a mail message:
4649 @kindex S r (Summary)
4651 @findex gnus-summary-reply
4652 @c @icon{gnus-summary-mail-reply}
4653 @c @icon{gnus-summary-reply}
4654 Mail a reply to the author of the current article
4655 (@code{gnus-summary-reply}).
4660 @kindex S R (Summary)
4661 @findex gnus-summary-reply-with-original
4662 @c @icon{gnus-summary-reply-with-original}
4663 Mail a reply to the author of the current article and include the
4664 original message (@code{gnus-summary-reply-with-original}). This
4665 command uses the process/prefix convention.
4668 @kindex S w (Summary)
4669 @findex gnus-summary-wide-reply
4670 Mail a wide reply to the author of the current article
4671 (@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that
4672 goes out to all people listed in the @code{To}, @code{From} (or
4673 @code{Reply-to}) and @code{Cc} headers.
4676 @kindex S W (Summary)
4677 @findex gnus-summary-wide-reply-with-original
4678 Mail a wide reply to the current article and include the original
4679 message (@code{gnus-summary-wide-reply-with-original}). This command uses
4680 the process/prefix convention.
4683 @kindex S v (Summary)
4684 @findex gnus-summary-very-wide-reply
4685 Mail a very wide reply to the author of the current article
4686 (@code{gnus-summary-wide-reply}). A @dfn{very wide reply} is a reply
4687 that goes out to all people listed in the @code{To}, @code{From} (or
4688 @code{Reply-to}) and @code{Cc} headers in all the process/prefixed
4689 articles. This command uses the process/prefix convention.
4692 @kindex S W (Summary)
4693 @findex gnus-summary-wide-reply-with-original
4694 Mail a very wide reply to the current article and include the original
4695 message (@code{gnus-summary-wide-reply-with-original}). This command uses
4696 the process/prefix convention.
4700 @kindex S o m (Summary)
4701 @kindex C-c C-f (Summary)
4702 @findex gnus-summary-mail-forward
4703 @c @icon{gnus-summary-mail-forward}
4704 Forward the current article to some other person
4705 (@code{gnus-summary-mail-forward}). If given a prefix, include the full
4706 headers of the forwarded article.
4711 @kindex S m (Summary)
4712 @findex gnus-summary-mail-other-window
4713 @c @icon{gnus-summary-mail-originate}
4714 Send a mail to some other person
4715 (@code{gnus-summary-mail-other-window}).
4718 @kindex S D b (Summary)
4719 @findex gnus-summary-resend-bounced-mail
4720 @cindex bouncing mail
4721 If you have sent a mail, but the mail was bounced back to you for some
4722 reason (wrong address, transient failure), you can use this command to
4723 resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
4724 will be popped into a mail buffer where you can edit the headers before
4725 sending the mail off again. If you give a prefix to this command, and
4726 the bounced mail is a reply to some other mail, gnus will try to fetch
4727 that mail and display it for easy perusal of its headers. This might
4728 very well fail, though.
4731 @kindex S D r (Summary)
4732 @findex gnus-summary-resend-message
4733 Not to be confused with the previous command,
4734 @code{gnus-summary-resend-message} will prompt you for an address to
4735 send the current message off to, and then send it to that place. The
4736 headers of the message won't be altered---but lots of headers that say
4737 @code{Resent-To}, @code{Resent-From} and so on will be added. This
4738 means that you actually send a mail to someone that has a @code{To}
4739 header that (probably) points to yourself. This will confuse people.
4740 So, natcherly you'll only do that if you're really eVIl.
4742 This command is mainly used if you have several accounts and want to
4743 ship a mail to a different account of yours. (If you're both
4744 @code{root} and @code{postmaster} and get a mail for @code{postmaster}
4745 to the @code{root} account, you may want to resend it to
4746 @code{postmaster}. Ordnung muß sein!
4748 This command understands the process/prefix convention
4749 (@pxref{Process/Prefix}).
4752 @kindex S O m (Summary)
4753 @findex gnus-summary-digest-mail-forward
4754 Digest the current series (@pxref{Decoding Articles}) and forward the
4755 result using mail (@code{gnus-summary-digest-mail-forward}). This
4756 command uses the process/prefix convention (@pxref{Process/Prefix}).
4759 @kindex S M-c (Summary)
4760 @findex gnus-summary-mail-crosspost-complaint
4761 @cindex crossposting
4762 @cindex excessive crossposting
4763 Send a complaint about excessive crossposting to the author of the
4764 current article (@code{gnus-summary-mail-crosspost-complaint}).
4766 @findex gnus-crosspost-complaint
4767 This command is provided as a way to fight back against the current
4768 crossposting pandemic that's sweeping Usenet. It will compose a reply
4769 using the @code{gnus-crosspost-complaint} variable as a preamble. This
4770 command understands the process/prefix convention
4771 (@pxref{Process/Prefix}) and will prompt you before sending each mail.
4775 Also @pxref{(message)Header Commands} for more information.
4778 @node Summary Post Commands
4779 @subsection Summary Post Commands
4781 @cindex composing news
4783 Commands for posting a news article:
4789 @kindex S p (Summary)
4790 @findex gnus-summary-post-news
4791 @c @icon{gnus-summary-post-news}
4792 Post an article to the current group
4793 (@code{gnus-summary-post-news}).
4798 @kindex S f (Summary)
4799 @findex gnus-summary-followup
4800 @c @icon{gnus-summary-followup}
4801 Post a followup to the current article (@code{gnus-summary-followup}).
4805 @kindex S F (Summary)
4807 @c @icon{gnus-summary-followup-with-original}
4808 @findex gnus-summary-followup-with-original
4809 Post a followup to the current article and include the original message
4810 (@code{gnus-summary-followup-with-original}). This command uses the
4811 process/prefix convention.
4814 @kindex S n (Summary)
4815 @findex gnus-summary-followup-to-mail
4816 Post a followup to the current article via news, even if you got the
4817 message through mail (@code{gnus-summary-followup-to-mail}).
4820 @kindex S N (Summary)
4821 @findex gnus-summary-followup-to-mail-with-original
4822 Post a followup to the current article via news, even if you got the
4823 message through mail and include the original message
4824 (@code{gnus-summary-followup-to-mail-with-original}). This command uses
4825 the process/prefix convention.
4828 @kindex S o p (Summary)
4829 @findex gnus-summary-post-forward
4830 Forward the current article to a newsgroup
4831 (@code{gnus-summary-post-forward}). If given a prefix, include the full
4832 headers of the forwarded article.
4835 @kindex S O p (Summary)
4836 @findex gnus-summary-digest-post-forward
4838 @cindex making digests
4839 Digest the current series and forward the result to a newsgroup
4840 (@code{gnus-summary-digest-post-forward}). This command uses the
4841 process/prefix convention.
4844 @kindex S u (Summary)
4845 @findex gnus-uu-post-news
4846 @c @icon{gnus-uu-post-news}
4847 Uuencode a file, split it into parts, and post it as a series
4848 (@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}).
4851 Also @pxref{(message)Header Commands} for more information.
4854 @node Summary Message Commands
4855 @subsection Summary Message Commands
4859 @kindex S y (Summary)
4860 @findex gnus-summary-yank-message
4861 Yank the current article into an already existing Message composition
4862 buffer (@code{gnus-summary-yank-message}). This command prompts for
4863 what message buffer you want to yank into, and understands the
4864 process/prefix convention (@pxref{Process/Prefix}).
4869 @node Canceling and Superseding
4870 @subsection Canceling Articles
4871 @cindex canceling articles
4872 @cindex superseding articles
4874 Have you ever written something, and then decided that you really,
4875 really, really wish you hadn't posted that?
4877 Well, you can't cancel mail, but you can cancel posts.
4879 @findex gnus-summary-cancel-article
4881 @c @icon{gnus-summary-cancel-article}
4882 Find the article you wish to cancel (you can only cancel your own
4883 articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
4884 c} (@code{gnus-summary-cancel-article}). Your article will be
4885 canceled---machines all over the world will be deleting your article.
4886 This command uses the process/prefix convention (@pxref{Process/Prefix}).
4888 Be aware, however, that not all sites honor cancels, so your article may
4889 live on here and there, while most sites will delete the article in
4892 Gnus will use the ``current'' select method when canceling. If you
4893 want to use the standard posting method, use the @samp{a} symbolic
4894 prefix (@pxref{Symbolic Prefixes}).
4896 If you discover that you have made some mistakes and want to do some
4897 corrections, you can post a @dfn{superseding} article that will replace
4898 your original article.
4900 @findex gnus-summary-supersede-article
4902 Go to the original article and press @kbd{S s}
4903 (@code{gnus-summary-supersede-article}). You will be put in a buffer
4904 where you can edit the article all you want before sending it off the
4907 The same goes for superseding as for canceling, only more so: Some
4908 sites do not honor superseding. On those sites, it will appear that you
4909 have posted almost the same article twice.
4911 If you have just posted the article, and change your mind right away,
4912 there is a trick you can use to cancel/supersede the article without
4913 waiting for the article to appear on your site first. You simply return
4914 to the post buffer (which is called @code{*sent ...*}). There you will
4915 find the article you just posted, with all the headers intact. Change
4916 the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes}
4917 header by substituting one of those words for the word
4918 @code{Message-ID}. Then just press @kbd{C-c C-c} to send the article as
4919 you would do normally. The previous article will be
4920 canceled/superseded.
4922 Just remember, kids: There is no 'c' in 'supersede'.
4925 @node Marking Articles
4926 @section Marking Articles
4927 @cindex article marking
4928 @cindex article ticking
4931 There are several marks you can set on an article.
4933 You have marks that decide the @dfn{readedness} (whoo, neato-keano
4934 neologism ohoy!) of the article. Alphabetic marks generally mean
4935 @dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
4937 In addition, you also have marks that do not affect readedness.
4940 * Unread Articles:: Marks for unread articles.
4941 * Read Articles:: Marks for read articles.
4942 * Other Marks:: Marks that do not affect readedness.
4946 There's a plethora of commands for manipulating these marks:
4950 * Setting Marks:: How to set and remove marks.
4951 * Generic Marking Commands:: How to customize the marking.
4952 * Setting Process Marks:: How to mark articles for later processing.
4956 @node Unread Articles
4957 @subsection Unread Articles
4959 The following marks mark articles as (kinda) unread, in one form or
4964 @vindex gnus-ticked-mark
4965 Marked as ticked (@code{gnus-ticked-mark}).
4967 @dfn{Ticked articles} are articles that will remain visible always. If
4968 you see an article that you find interesting, or you want to put off
4969 reading it, or replying to it, until sometime later, you'd typically
4970 tick it. However, articles can be expired (from news servers by the
4971 news server software, Gnus itself never expires ticked messages), so if
4972 you want to keep an article forever, you'll have to make it persistent
4973 (@pxref{Persistent Articles}).
4976 @vindex gnus-dormant-mark
4977 Marked as dormant (@code{gnus-dormant-mark}).
4979 @dfn{Dormant articles} will only appear in the summary buffer if there
4980 are followups to it. If you want to see them even if they don't have
4981 followups, you can use the @kbd{/ D} command (@pxref{Limiting}).
4982 Otherwise (except for the visibility issue), they are just like ticked
4986 @vindex gnus-unread-mark
4987 Marked as unread (@code{gnus-unread-mark}).
4989 @dfn{Unread articles} are articles that haven't been read at all yet.
4994 @subsection Read Articles
4995 @cindex expirable mark
4997 All the following marks mark articles as read.
5002 @vindex gnus-del-mark
5003 These are articles that the user has marked as read with the @kbd{d}
5004 command manually, more or less (@code{gnus-del-mark}).
5007 @vindex gnus-read-mark
5008 Articles that have actually been read (@code{gnus-read-mark}).
5011 @vindex gnus-ancient-mark
5012 Articles that were marked as read in previous sessions and are now
5013 @dfn{old} (@code{gnus-ancient-mark}).
5016 @vindex gnus-killed-mark
5017 Marked as killed (@code{gnus-killed-mark}).
5020 @vindex gnus-kill-file-mark
5021 Marked as killed by kill files (@code{gnus-kill-file-mark}).
5024 @vindex gnus-low-score-mark
5025 Marked as read by having too low a score (@code{gnus-low-score-mark}).
5028 @vindex gnus-catchup-mark
5029 Marked as read by a catchup (@code{gnus-catchup-mark}).
5032 @vindex gnus-canceled-mark
5033 Canceled article (@code{gnus-canceled-mark})
5036 @vindex gnus-souped-mark
5037 @sc{soup}ed article (@code{gnus-souped-mark}). @xref{SOUP}.
5040 @vindex gnus-sparse-mark
5041 Sparsely reffed article (@code{gnus-sparse-mark}). @xref{Customizing
5045 @vindex gnus-duplicate-mark
5046 Article marked as read by duplicate suppression
5047 (@code{gnus-duplicate-mark}). @xref{Duplicate Suppression}.
5051 All these marks just mean that the article is marked as read, really.
5052 They are interpreted differently when doing adaptive scoring, though.
5054 One more special mark, though:
5058 @vindex gnus-expirable-mark
5059 Marked as expirable (@code{gnus-expirable-mark}).
5061 Marking articles as @dfn{expirable} (or have them marked as such
5062 automatically) doesn't make much sense in normal groups---a user doesn't
5063 control expiring of news articles, but in mail groups, for instance,
5064 articles marked as @dfn{expirable} can be deleted by gnus at
5070 @subsection Other Marks
5071 @cindex process mark
5074 There are some marks that have nothing to do with whether the article is
5080 You can set a bookmark in the current article. Say you are reading a
5081 long thesis on cats' urinary tracts, and have to go home for dinner
5082 before you've finished reading the thesis. You can then set a bookmark
5083 in the article, and gnus will jump to this bookmark the next time it
5084 encounters the article. @xref{Setting Marks}.
5087 @vindex gnus-replied-mark
5088 All articles that you have replied to or made a followup to (i.e., have
5089 answered) will be marked with an @samp{A} in the second column
5090 (@code{gnus-replied-mark}).
5092 @vindex gnus-forwarded-mark
5093 All articles that you have forwarded will be marked with an @samp{O} in
5094 the second column (@code{gnus-forwarded-mark}).
5097 @vindex gnus-cached-mark
5098 Articles stored in the article cache will be marked with an @samp{*} in
5099 the second column (@code{gnus-cached-mark}). @xref{Article Caching}.
5102 @vindex gnus-saved-mark
5103 Articles ``saved'' (in some manner or other; not necessarily
5104 religiously) are marked with an @samp{S} in the second column
5105 (@code{gnus-saved-mark}).
5108 @vindex gnus-not-empty-thread-mark
5109 @vindex gnus-empty-thread-mark
5110 If the @samp{%e} spec is used, the presence of threads or not will be
5111 marked with @code{gnus-not-empty-thread-mark} and
5112 @code{gnus-empty-thread-mark} in the third column, respectively.
5115 @vindex gnus-process-mark
5116 Finally we have the @dfn{process mark} (@code{gnus-process-mark}). A
5117 variety of commands react to the presence of the process mark. For
5118 instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
5119 all articles that have been marked with the process mark. Articles
5120 marked with the process mark have a @samp{#} in the second column.
5124 You might have noticed that most of these ``non-readedness'' marks
5125 appear in the second column by default. So if you have a cached, saved,
5126 replied article that you have process-marked, what will that look like?
5128 Nothing much. The precedence rules go as follows: process -> cache ->
5129 replied -> saved. So if the article is in the cache and is replied,
5130 you'll only see the cache mark and not the replied mark.
5134 @subsection Setting Marks
5135 @cindex setting marks
5137 All the marking commands understand the numeric prefix.
5142 @kindex M c (Summary)
5143 @kindex M-u (Summary)
5144 @findex gnus-summary-clear-mark-forward
5145 @cindex mark as unread
5146 Clear all readedness-marks from the current article
5147 (@code{gnus-summary-clear-mark-forward}). In other words, mark the
5153 @kindex M t (Summary)
5154 @findex gnus-summary-tick-article-forward
5155 Tick the current article (@code{gnus-summary-tick-article-forward}).
5156 @xref{Article Caching}.
5161 @kindex M ? (Summary)
5162 @findex gnus-summary-mark-as-dormant
5163 Mark the current article as dormant
5164 (@code{gnus-summary-mark-as-dormant}). @xref{Article Caching}.
5168 @kindex M d (Summary)
5170 @findex gnus-summary-mark-as-read-forward
5171 Mark the current article as read
5172 (@code{gnus-summary-mark-as-read-forward}).
5176 @findex gnus-summary-mark-as-read-backward
5177 Mark the current article as read and move point to the previous line
5178 (@code{gnus-summary-mark-as-read-backward}).
5183 @kindex M k (Summary)
5184 @findex gnus-summary-kill-same-subject-and-select
5185 Mark all articles that have the same subject as the current one as read,
5186 and then select the next unread article
5187 (@code{gnus-summary-kill-same-subject-and-select}).
5191 @kindex M K (Summary)
5192 @kindex C-k (Summary)
5193 @findex gnus-summary-kill-same-subject
5194 Mark all articles that have the same subject as the current one as read
5195 (@code{gnus-summary-kill-same-subject}).
5198 @kindex M C (Summary)
5199 @findex gnus-summary-catchup
5200 @c @icon{gnus-summary-catchup}
5201 Mark all unread articles as read (@code{gnus-summary-catchup}).
5204 @kindex M C-c (Summary)
5205 @findex gnus-summary-catchup-all
5206 Mark all articles in the group as read---even the ticked and dormant
5207 articles (@code{gnus-summary-catchup-all}).
5210 @kindex M H (Summary)
5211 @findex gnus-summary-catchup-to-here
5212 Catchup the current group to point (before the point)
5213 (@code{gnus-summary-catchup-to-here}).
5216 @kindex M h (Summary)
5217 @findex gnus-summary-catchup-from-here
5218 Catchup the current group from point (after the point)
5219 (@code{gnus-summary-catchup-from-here}).
5222 @kindex C-w (Summary)
5223 @findex gnus-summary-mark-region-as-read
5224 Mark all articles between point and mark as read
5225 (@code{gnus-summary-mark-region-as-read}).
5228 @kindex M V k (Summary)
5229 @findex gnus-summary-kill-below
5230 Kill all articles with scores below the default score (or below the
5231 numeric prefix) (@code{gnus-summary-kill-below}).
5235 @kindex M e (Summary)
5237 @findex gnus-summary-mark-as-expirable
5238 Mark the current article as expirable
5239 (@code{gnus-summary-mark-as-expirable}).
5242 @kindex M b (Summary)
5243 @findex gnus-summary-set-bookmark
5244 Set a bookmark in the current article
5245 (@code{gnus-summary-set-bookmark}).
5248 @kindex M B (Summary)
5249 @findex gnus-summary-remove-bookmark
5250 Remove the bookmark from the current article
5251 (@code{gnus-summary-remove-bookmark}).
5254 @kindex M V c (Summary)
5255 @findex gnus-summary-clear-above
5256 Clear all marks from articles with scores over the default score (or
5257 over the numeric prefix) (@code{gnus-summary-clear-above}).
5260 @kindex M V u (Summary)
5261 @findex gnus-summary-tick-above
5262 Tick all articles with scores over the default score (or over the
5263 numeric prefix) (@code{gnus-summary-tick-above}).
5266 @kindex M V m (Summary)
5267 @findex gnus-summary-mark-above
5268 Prompt for a mark, and mark all articles with scores over the default
5269 score (or over the numeric prefix) with this mark
5270 (@code{gnus-summary-clear-above}).
5273 @vindex gnus-summary-goto-unread
5274 The @code{gnus-summary-goto-unread} variable controls what action should
5275 be taken after setting a mark. If non-@code{nil}, point will move to
5276 the next/previous unread article. If @code{nil}, point will just move
5277 one line up or down. As a special case, if this variable is
5278 @code{never}, all the marking commands as well as other commands (like
5279 @kbd{SPACE}) will move to the next article, whether it is unread or not.
5280 The default is @code{t}.
5283 @node Generic Marking Commands
5284 @subsection Generic Marking Commands
5286 Some people would like the command that ticks an article (@kbd{!}) go to
5287 the next article. Others would like it to go to the next unread
5288 article. Yet others would like it to stay on the current article. And
5289 even though I haven't heard of anybody wanting it to go to the
5290 previous (unread) article, I'm sure there are people that want that as
5293 Multiply these five behaviors with five different marking commands, and
5294 you get a potentially complex set of variable to control what each
5297 To sidestep that mess, Gnus provides commands that do all these
5298 different things. They can be found on the @kbd{M M} map in the summary
5299 buffer. Type @kbd{M M C-h} to see them all---there are too many of them
5300 to list in this manual.
5302 While you can use these commands directly, most users would prefer
5303 altering the summary mode keymap. For instance, if you would like the
5304 @kbd{!} command to go to the next article instead of the next unread
5305 article, you could say something like:
5308 (add-hook 'gnus-summary-mode-hook 'my-alter-summary-map)
5309 (defun my-alter-summary-map ()
5310 (local-set-key "!" 'gnus-summary-put-mark-as-ticked-next))
5316 (defun my-alter-summary-map ()
5317 (local-set-key "!" "MM!n"))
5321 @node Setting Process Marks
5322 @subsection Setting Process Marks
5323 @cindex setting process marks
5330 @kindex M P p (Summary)
5331 @findex gnus-summary-mark-as-processable
5332 Mark the current article with the process mark
5333 (@code{gnus-summary-mark-as-processable}).
5334 @findex gnus-summary-unmark-as-processable
5338 @kindex M P u (Summary)
5339 @kindex M-# (Summary)
5340 Remove the process mark, if any, from the current article
5341 (@code{gnus-summary-unmark-as-processable}).
5344 @kindex M P U (Summary)
5345 @findex gnus-summary-unmark-all-processable
5346 Remove the process mark from all articles
5347 (@code{gnus-summary-unmark-all-processable}).
5350 @kindex M P i (Summary)
5351 @findex gnus-uu-invert-processable
5352 Invert the list of process marked articles
5353 (@code{gnus-uu-invert-processable}).
5356 @kindex M P R (Summary)
5357 @findex gnus-uu-mark-by-regexp
5358 Mark articles that have a @code{Subject} header that matches a regular
5359 expression (@code{gnus-uu-mark-by-regexp}).
5362 @kindex M P G (Summary)
5363 @findex gnus-uu-unmark-by-regexp
5364 Unmark articles that have a @code{Subject} header that matches a regular
5365 expression (@code{gnus-uu-unmark-by-regexp}).
5368 @kindex M P r (Summary)
5369 @findex gnus-uu-mark-region
5370 Mark articles in region (@code{gnus-uu-mark-region}).
5373 @kindex M P t (Summary)
5374 @findex gnus-uu-mark-thread
5375 Mark all articles in the current (sub)thread
5376 (@code{gnus-uu-mark-thread}).
5379 @kindex M P T (Summary)
5380 @findex gnus-uu-unmark-thread
5381 Unmark all articles in the current (sub)thread
5382 (@code{gnus-uu-unmark-thread}).
5385 @kindex M P v (Summary)
5386 @findex gnus-uu-mark-over
5387 Mark all articles that have a score above the prefix argument
5388 (@code{gnus-uu-mark-over}).
5391 @kindex M P s (Summary)
5392 @findex gnus-uu-mark-series
5393 Mark all articles in the current series (@code{gnus-uu-mark-series}).
5396 @kindex M P S (Summary)
5397 @findex gnus-uu-mark-sparse
5398 Mark all series that have already had some articles marked
5399 (@code{gnus-uu-mark-sparse}).
5402 @kindex M P a (Summary)
5403 @findex gnus-uu-mark-all
5404 Mark all articles in series order (@code{gnus-uu-mark-series}).
5407 @kindex M P b (Summary)
5408 @findex gnus-uu-mark-buffer
5409 Mark all articles in the buffer in the order they appear
5410 (@code{gnus-uu-mark-buffer}).
5413 @kindex M P k (Summary)
5414 @findex gnus-summary-kill-process-mark
5415 Push the current process mark set onto the stack and unmark all articles
5416 (@code{gnus-summary-kill-process-mark}).
5419 @kindex M P y (Summary)
5420 @findex gnus-summary-yank-process-mark
5421 Pop the previous process mark set from the stack and restore it
5422 (@code{gnus-summary-yank-process-mark}).
5425 @kindex M P w (Summary)
5426 @findex gnus-summary-save-process-mark
5427 Push the current process mark set onto the stack
5428 (@code{gnus-summary-save-process-mark}).
5432 Also see the @kbd{&} command in @pxref{Searching for Articles} for how to
5433 set process marks based on article body contents.
5440 It can be convenient to limit the summary buffer to just show some
5441 subset of the articles currently in the group. The effect most limit
5442 commands have is to remove a few (or many) articles from the summary
5445 All limiting commands work on subsets of the articles already fetched
5446 from the servers. None of these commands query the server for
5447 additional articles.
5453 @kindex / / (Summary)
5454 @findex gnus-summary-limit-to-subject
5455 Limit the summary buffer to articles that match some subject
5456 (@code{gnus-summary-limit-to-subject}).
5459 @kindex / a (Summary)
5460 @findex gnus-summary-limit-to-author
5461 Limit the summary buffer to articles that match some author
5462 (@code{gnus-summary-limit-to-author}).
5465 @kindex / x (Summary)
5466 @findex gnus-summary-limit-to-extra
5467 Limit the summary buffer to articles that match one of the ``extra''
5468 headers (@pxref{To From Newsgroups})
5469 (@code{gnus-summary-limit-to-extra}).
5473 @kindex / u (Summary)
5475 @findex gnus-summary-limit-to-unread
5476 Limit the summary buffer to articles not marked as read
5477 (@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
5478 buffer to articles strictly unread. This means that ticked and
5479 dormant articles will also be excluded.
5482 @kindex / m (Summary)
5483 @findex gnus-summary-limit-to-marks
5484 Ask for a mark and then limit to all articles that have been marked
5485 with that mark (@code{gnus-summary-limit-to-marks}).
5488 @kindex / t (Summary)
5489 @findex gnus-summary-limit-to-age
5490 Ask for a number and then limit the summary buffer to articles older than (or equal to) that number of days
5491 (@code{gnus-summary-limit-to-age}). If given a prefix, limit to
5492 articles younger than that number of days.
5495 @kindex / n (Summary)
5496 @findex gnus-summary-limit-to-articles
5497 Limit the summary buffer to the current article
5498 (@code{gnus-summary-limit-to-articles}). Uses the process/prefix
5499 convention (@pxref{Process/Prefix}).
5502 @kindex / w (Summary)
5503 @findex gnus-summary-pop-limit
5504 Pop the previous limit off the stack and restore it
5505 (@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
5509 @kindex / v (Summary)
5510 @findex gnus-summary-limit-to-score
5511 Limit the summary buffer to articles that have a score at or above some
5512 score (@code{gnus-summary-limit-to-score}).
5516 @kindex M S (Summary)
5517 @kindex / E (Summary)
5518 @findex gnus-summary-limit-include-expunged
5519 Include all expunged articles in the limit
5520 (@code{gnus-summary-limit-include-expunged}).
5523 @kindex / D (Summary)
5524 @findex gnus-summary-limit-include-dormant
5525 Include all dormant articles in the limit
5526 (@code{gnus-summary-limit-include-dormant}).
5529 @kindex / * (Summary)
5530 @findex gnus-summary-limit-include-cached
5531 Include all cached articles in the limit
5532 (@code{gnus-summary-limit-include-cached}).
5535 @kindex / d (Summary)
5536 @findex gnus-summary-limit-exclude-dormant
5537 Exclude all dormant articles from the limit
5538 (@code{gnus-summary-limit-exclude-dormant}).
5541 @kindex / M (Summary)
5542 @findex gnus-summary-limit-exclude-marks
5543 Exclude all marked articles (@code{gnus-summary-limit-exclude-marks}).
5546 @kindex / T (Summary)
5547 @findex gnus-summary-limit-include-thread
5548 Include all the articles in the current thread in the limit.
5551 @kindex / c (Summary)
5552 @findex gnus-summary-limit-exclude-childless-dormant
5553 Exclude all dormant articles that have no children from the limit
5554 (@code{gnus-summary-limit-exclude-childless-dormant}).
5557 @kindex / C (Summary)
5558 @findex gnus-summary-limit-mark-excluded-as-read
5559 Mark all excluded unread articles as read
5560 (@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix,
5561 also mark excluded ticked and dormant articles as read.
5569 @cindex article threading
5571 Gnus threads articles by default. @dfn{To thread} is to put responses
5572 to articles directly after the articles they respond to---in a
5573 hierarchical fashion.
5575 Threading is done by looking at the @code{References} headers of the
5576 articles. In a perfect world, this would be enough to build pretty
5577 trees, but unfortunately, the @code{References} header is often broken
5578 or simply missing. Weird news propagation exacerbates the problem,
5579 so one has to employ other heuristics to get pleasing results. A
5580 plethora of approaches exists, as detailed in horrible detail in
5581 @pxref{Customizing Threading}.
5583 First, a quick overview of the concepts:
5587 The top-most article in a thread; the first article in the thread.
5590 A tree-like article structure.
5593 A small(er) section of this tree-like structure.
5596 Threads often lose their roots due to article expiry, or due to the root
5597 already having been read in a previous session, and not displayed in the
5598 summary buffer. We then typically have many sub-threads that really
5599 belong to one thread, but are without connecting roots. These are
5600 called loose threads.
5602 @item thread gathering
5603 An attempt to gather loose threads into bigger threads.
5605 @item sparse threads
5606 A thread where the missing articles have been ``guessed'' at, and are
5607 displayed as empty lines in the summary buffer.
5613 * Customizing Threading:: Variables you can change to affect the threading.
5614 * Thread Commands:: Thread based commands in the summary buffer.
5618 @node Customizing Threading
5619 @subsection Customizing Threading
5620 @cindex customizing threading
5623 * Loose Threads:: How gnus gathers loose threads into bigger threads.
5624 * Filling In Threads:: Making the threads displayed look fuller.
5625 * More Threading:: Even more variables for fiddling with threads.
5626 * Low-Level Threading:: You thought it was over... but you were wrong!
5631 @subsubsection Loose Threads
5634 @cindex loose threads
5637 @item gnus-summary-make-false-root
5638 @vindex gnus-summary-make-false-root
5639 If non-@code{nil}, gnus will gather all loose subtrees into one big tree
5640 and create a dummy root at the top. (Wait a minute. Root at the top?
5641 Yup.) Loose subtrees occur when the real root has expired, or you've
5642 read or killed the root in a previous session.
5644 When there is no real root of a thread, gnus will have to fudge
5645 something. This variable says what fudging method gnus should use.
5646 There are four possible values:
5650 \gnusfigure{The Summary Buffer}{390}{
5651 \put(0,0){\epsfig{figure=tmp/summary-adopt.ps,width=7.5cm}}
5652 \put(445,0){\makebox(0,0)[br]{\epsfig{figure=tmp/summary-empty.ps,width=7.5cm}}}
5653 \put(0,400){\makebox(0,0)[tl]{\epsfig{figure=tmp/summary-none.ps,width=7.5cm}}}
5654 \put(445,400){\makebox(0,0)[tr]{\epsfig{figure=tmp/summary-dummy.ps,width=7.5cm}}}
5659 @cindex adopting articles
5664 Gnus will make the first of the orphaned articles the parent. This
5665 parent will adopt all the other articles. The adopted articles will be
5666 marked as such by pointy brackets (@samp{<>}) instead of the standard
5667 square brackets (@samp{[]}). This is the default method.
5670 @vindex gnus-summary-dummy-line-format
5671 Gnus will create a dummy summary line that will pretend to be the
5672 parent. This dummy line does not correspond to any real article, so
5673 selecting it will just select the first real article after the dummy
5674 article. @code{gnus-summary-dummy-line-format} is used to specify the
5675 format of the dummy roots. It accepts only one format spec: @samp{S},
5676 which is the subject of the article. @xref{Formatting Variables}.
5679 Gnus won't actually make any article the parent, but simply leave the
5680 subject field of all orphans except the first empty. (Actually, it will
5681 use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
5685 Don't make any article parent at all. Just gather the threads and
5686 display them after one another.
5689 Don't gather loose threads.
5692 @item gnus-summary-gather-subject-limit
5693 @vindex gnus-summary-gather-subject-limit
5694 Loose threads are gathered by comparing subjects of articles. If this
5695 variable is @code{nil}, gnus requires an exact match between the
5696 subjects of the loose threads before gathering them into one big
5697 super-thread. This might be too strict a requirement, what with the
5698 presence of stupid newsreaders that chop off long subject lines. If
5699 you think so, set this variable to, say, 20 to require that only the
5700 first 20 characters of the subjects have to match. If you set this
5701 variable to a really low number, you'll find that gnus will gather
5702 everything in sight into one thread, which isn't very helpful.
5704 @cindex fuzzy article gathering
5705 If you set this variable to the special value @code{fuzzy}, gnus will
5706 use a fuzzy string comparison algorithm on the subjects (@pxref{Fuzzy
5709 @item gnus-simplify-subject-fuzzy-regexp
5710 @vindex gnus-simplify-subject-fuzzy-regexp
5711 This can either be a regular expression or list of regular expressions
5712 that match strings that will be removed from subjects if fuzzy subject
5713 simplification is used.
5715 @item gnus-simplify-ignored-prefixes
5716 @vindex gnus-simplify-ignored-prefixes
5717 If you set @code{gnus-summary-gather-subject-limit} to something as low
5718 as 10, you might consider setting this variable to something sensible:
5720 @c Written by Michael Ernst <mernst@cs.rice.edu>
5722 (setq gnus-simplify-ignored-prefixes
5728 "wanted" "followup" "summary\\( of\\)?"
5729 "help" "query" "problem" "question"
5730 "answer" "reference" "announce"
5731 "How can I" "How to" "Comparison of"
5736 (mapconcat 'identity
5737 '("for" "for reference" "with" "about")
5739 "\\)?\\]?:?[ \t]*"))
5742 All words that match this regexp will be removed before comparing two
5745 @item gnus-simplify-subject-functions
5746 @vindex gnus-simplify-subject-functions
5747 If non-@code{nil}, this variable overrides
5748 @code{gnus-summary-gather-subject-limit}. This variable should be a
5749 list of functions to apply to the @code{Subject} string iteratively to
5750 arrive at the simplified version of the string.
5752 Useful functions to put in this list include:
5755 @item gnus-simplify-subject-re
5756 @findex gnus-simplify-subject-re
5757 Strip the leading @samp{Re:}.
5759 @item gnus-simplify-subject-fuzzy
5760 @findex gnus-simplify-subject-fuzzy
5763 @item gnus-simplify-whitespace
5764 @findex gnus-simplify-whitespace
5765 Remove excessive whitespace.
5768 You may also write your own functions, of course.
5771 @item gnus-summary-gather-exclude-subject
5772 @vindex gnus-summary-gather-exclude-subject
5773 Since loose thread gathering is done on subjects only, that might lead
5774 to many false hits, especially with certain common subjects like
5775 @samp{} and @samp{(none)}. To make the situation slightly better,
5776 you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
5777 what subjects should be excluded from the gathering process.@*
5778 The default is @samp{^ *$\\|^(none)$}.
5780 @item gnus-summary-thread-gathering-function
5781 @vindex gnus-summary-thread-gathering-function
5782 Gnus gathers threads by looking at @code{Subject} headers. This means
5783 that totally unrelated articles may end up in the same ``thread'', which
5784 is confusing. An alternate approach is to look at all the
5785 @code{Message-ID}s in all the @code{References} headers to find matches.
5786 This will ensure that no gathered threads ever include unrelated
5787 articles, but it also means that people who have posted with broken
5788 newsreaders won't be gathered properly. The choice is yours---plague or
5792 @item gnus-gather-threads-by-subject
5793 @findex gnus-gather-threads-by-subject
5794 This function is the default gathering function and looks at
5795 @code{Subject}s exclusively.
5797 @item gnus-gather-threads-by-references
5798 @findex gnus-gather-threads-by-references
5799 This function looks at @code{References} headers exclusively.
5802 If you want to test gathering by @code{References}, you could say
5806 (setq gnus-summary-thread-gathering-function
5807 'gnus-gather-threads-by-references)
5813 @node Filling In Threads
5814 @subsubsection Filling In Threads
5817 @item gnus-fetch-old-headers
5818 @vindex gnus-fetch-old-headers
5819 If non-@code{nil}, gnus will attempt to build old threads by fetching
5820 more old headers---headers to articles marked as read. If you
5821 would like to display as few summary lines as possible, but still
5822 connect as many loose threads as possible, you should set this variable
5823 to @code{some} or a number. If you set it to a number, no more than
5824 that number of extra old headers will be fetched. In either case,
5825 fetching old headers only works if the backend you are using carries
5826 overview files---this would normally be @code{nntp}, @code{nnspool} and
5827 @code{nnml}. Also remember that if the root of the thread has been
5828 expired by the server, there's not much gnus can do about that.
5830 This variable can also be set to @code{invisible}. This won't have any
5831 visible effects, but is useful if you use the @kbd{A T} command a lot
5832 (@pxref{Finding the Parent}).
5834 @item gnus-build-sparse-threads
5835 @vindex gnus-build-sparse-threads
5836 Fetching old headers can be slow. A low-rent similar effect can be
5837 gotten by setting this variable to @code{some}. Gnus will then look at
5838 the complete @code{References} headers of all articles and try to string
5839 together articles that belong in the same thread. This will leave
5840 @dfn{gaps} in the threading display where gnus guesses that an article
5841 is missing from the thread. (These gaps appear like normal summary
5842 lines. If you select a gap, gnus will try to fetch the article in
5843 question.) If this variable is @code{t}, gnus will display all these
5844 ``gaps'' without regard for whether they are useful for completing the
5845 thread or not. Finally, if this variable is @code{more}, gnus won't cut
5846 off sparse leaf nodes that don't lead anywhere. This variable is
5847 @code{nil} by default.
5849 @item gnus-read-all-available-headers
5850 @vindex gnus-read-all-available-headers
5851 This is a rather obscure variable that few will find useful. It's
5852 intended for those non-news newsgroups where the backend has to fetch
5853 quite a lot to present the summary buffer, and where it's impossible to
5854 go back to parents of articles. This is mostly the case in the
5855 web-based groups, like the @code{nnultimate} groups.
5857 If you don't use those, then it's safe to leave this as the default
5858 @code{nil}. If you want to use this variable, it should be a regexp
5859 that matches the group name, or @code{t} for all groups.
5864 @node More Threading
5865 @subsubsection More Threading
5868 @item gnus-show-threads
5869 @vindex gnus-show-threads
5870 If this variable is @code{nil}, no threading will be done, and all of
5871 the rest of the variables here will have no effect. Turning threading
5872 off will speed group selection up a bit, but it is sure to make reading
5873 slower and more awkward.
5875 @item gnus-thread-hide-subtree
5876 @vindex gnus-thread-hide-subtree
5877 If non-@code{nil}, all threads will be hidden when the summary buffer is
5880 @item gnus-thread-expunge-below
5881 @vindex gnus-thread-expunge-below
5882 All threads that have a total score (as defined by
5883 @code{gnus-thread-score-function}) less than this number will be
5884 expunged. This variable is @code{nil} by default, which means that no
5885 threads are expunged.
5887 @item gnus-thread-hide-killed
5888 @vindex gnus-thread-hide-killed
5889 if you kill a thread and this variable is non-@code{nil}, the subtree
5892 @item gnus-thread-ignore-subject
5893 @vindex gnus-thread-ignore-subject
5894 Sometimes somebody changes the subject in the middle of a thread. If
5895 this variable is non-@code{nil}, which is the default, the subject
5896 change is ignored. If it is @code{nil}, a change in the subject will
5897 result in a new thread.
5899 @item gnus-thread-indent-level
5900 @vindex gnus-thread-indent-level
5901 This is a number that says how much each sub-thread should be indented.
5904 @item gnus-sort-gathered-threads-function
5905 @vindex gnus-sort-gathered-threads-function
5906 Sometimes, particularly with mailing lists, the order in which mails
5907 arrive locally is not necessarily the same as the order in which they
5908 arrived on the mailing list. Consequently, when sorting sub-threads
5909 using the default @code{gnus-thread-sort-by-number}, responses can end
5910 up appearing before the article to which they are responding to.
5911 Setting this variable to an alternate value
5912 (e.g. @code{gnus-thread-sort-by-date}), in a group's parameters or in an
5913 appropriate hook (e.g. @code{gnus-summary-generate-hook}) can produce a
5914 more logical sub-thread ordering in such instances.
5919 @node Low-Level Threading
5920 @subsubsection Low-Level Threading
5924 @item gnus-parse-headers-hook
5925 @vindex gnus-parse-headers-hook
5926 Hook run before parsing any headers. The default value is
5927 @code{(gnus-set-summary-default-charset)}, which sets up local value of
5928 @code{default-mime-charset} in summary buffer based on variable
5929 @code{gnus-newsgroup-default-charset-alist}.
5931 @item gnus-alter-header-function
5932 @vindex gnus-alter-header-function
5933 If non-@code{nil}, this function will be called to allow alteration of
5934 article header structures. The function is called with one parameter,
5935 the article header vector, which it may alter in any way. For instance,
5936 if you have a mail-to-news gateway which alters the @code{Message-ID}s
5937 in systematic ways (by adding prefixes and such), you can use this
5938 variable to un-scramble the @code{Message-ID}s so that they are more
5939 meaningful. Here's one example:
5942 (setq gnus-alter-header-function 'my-alter-message-id)
5944 (defun my-alter-message-id (header)
5945 (let ((id (mail-header-id header)))
5947 "\\(<[^<>@@]*\\)\\.?cygnus\\..*@@\\([^<>@@]*>\\)" id)
5949 (concat (match-string 1 id) "@@" (match-string 2 id))
5956 @node Thread Commands
5957 @subsection Thread Commands
5958 @cindex thread commands
5964 @kindex T k (Summary)
5965 @kindex M-C-k (Summary)
5966 @findex gnus-summary-kill-thread
5967 Mark all articles in the current (sub-)thread as read
5968 (@code{gnus-summary-kill-thread}). If the prefix argument is positive,
5969 remove all marks instead. If the prefix argument is negative, tick
5974 @kindex T l (Summary)
5975 @kindex M-C-l (Summary)
5976 @findex gnus-summary-lower-thread
5977 Lower the score of the current (sub-)thread
5978 (@code{gnus-summary-lower-thread}).
5981 @kindex T i (Summary)
5982 @findex gnus-summary-raise-thread
5983 Increase the score of the current (sub-)thread
5984 (@code{gnus-summary-raise-thread}).
5987 @kindex T # (Summary)
5988 @findex gnus-uu-mark-thread
5989 Set the process mark on the current (sub-)thread
5990 (@code{gnus-uu-mark-thread}).
5993 @kindex T M-# (Summary)
5994 @findex gnus-uu-unmark-thread
5995 Remove the process mark from the current (sub-)thread
5996 (@code{gnus-uu-unmark-thread}).
5999 @kindex T T (Summary)
6000 @findex gnus-summary-toggle-threads
6001 Toggle threading (@code{gnus-summary-toggle-threads}).
6004 @kindex T s (Summary)
6005 @findex gnus-summary-show-thread
6006 Expose the (sub-)thread hidden under the current article, if any
6007 (@code{gnus-summary-show-thread}).
6010 @kindex T h (Summary)
6011 @findex gnus-summary-hide-thread
6012 Hide the current (sub-)thread (@code{gnus-summary-hide-thread}).
6015 @kindex T S (Summary)
6016 @findex gnus-summary-show-all-threads
6017 Expose all hidden threads (@code{gnus-summary-show-all-threads}).
6020 @kindex T H (Summary)
6021 @findex gnus-summary-hide-all-threads
6022 Hide all threads (@code{gnus-summary-hide-all-threads}).
6025 @kindex T t (Summary)
6026 @findex gnus-summary-rethread-current
6027 Re-thread the current article's thread
6028 (@code{gnus-summary-rethread-current}). This works even when the
6029 summary buffer is otherwise unthreaded.
6032 @kindex T ^ (Summary)
6033 @findex gnus-summary-reparent-thread
6034 Make the current article the child of the marked (or previous) article
6035 (@code{gnus-summary-reparent-thread}).
6039 The following commands are thread movement commands. They all
6040 understand the numeric prefix.
6045 @kindex T n (Summary)
6047 @kindex M-C-n (Summary)
6049 @kindex M-down (Summary)
6050 @findex gnus-summary-next-thread
6051 Go to the next thread (@code{gnus-summary-next-thread}).
6054 @kindex T p (Summary)
6056 @kindex M-C-p (Summary)
6058 @kindex M-up (Summary)
6059 @findex gnus-summary-prev-thread
6060 Go to the previous thread (@code{gnus-summary-prev-thread}).
6063 @kindex T d (Summary)
6064 @findex gnus-summary-down-thread
6065 Descend the thread (@code{gnus-summary-down-thread}).
6068 @kindex T u (Summary)
6069 @findex gnus-summary-up-thread
6070 Ascend the thread (@code{gnus-summary-up-thread}).
6073 @kindex T o (Summary)
6074 @findex gnus-summary-top-thread
6075 Go to the top of the thread (@code{gnus-summary-top-thread}).
6078 @vindex gnus-thread-operation-ignore-subject
6079 If you ignore subject while threading, you'll naturally end up with
6080 threads that have several different subjects in them. If you then issue
6081 a command like `T k' (@code{gnus-summary-kill-thread}) you might not
6082 wish to kill the entire thread, but just those parts of the thread that
6083 have the same subject as the current article. If you like this idea,
6084 you can fiddle with @code{gnus-thread-operation-ignore-subject}. If it
6085 is non-@code{nil} (which it is by default), subjects will be ignored
6086 when doing thread commands. If this variable is @code{nil}, articles in
6087 the same thread with different subjects will not be included in the
6088 operation in question. If this variable is @code{fuzzy}, only articles
6089 that have subjects fuzzily equal will be included (@pxref{Fuzzy
6093 @node Sorting the Summary Buffer
6094 @section Sorting the Summary Buffer
6096 @findex gnus-thread-sort-by-total-score
6097 @findex gnus-thread-sort-by-date
6098 @findex gnus-thread-sort-by-score
6099 @findex gnus-thread-sort-by-subject
6100 @findex gnus-thread-sort-by-author
6101 @findex gnus-thread-sort-by-number
6102 @vindex gnus-thread-sort-functions
6103 If you are using a threaded summary display, you can sort the threads by
6104 setting @code{gnus-thread-sort-functions}, which can be either a single
6105 function, a list of functions, or a list containing functions and
6106 @code{(not some-function)} elements.
6108 By default, sorting is done on article numbers. Ready-made sorting
6109 predicate functions include @code{gnus-thread-sort-by-number},
6110 @code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
6111 @code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
6112 @code{gnus-thread-sort-by-total-score}.
6114 Each function takes two threads and returns non-@code{nil} if the first
6115 thread should be sorted before the other. Note that sorting really is
6116 normally done by looking only at the roots of each thread.
6118 If you use more than one function, the primary sort key should be the
6119 last function in the list. You should probably always include
6120 @code{gnus-thread-sort-by-number} in the list of sorting
6121 functions---preferably first. This will ensure that threads that are
6122 equal with respect to the other sort criteria will be displayed in
6123 ascending article order.
6125 If you would like to sort by reverse score, then by subject, and finally
6126 by number, you could do something like:
6129 (setq gnus-thread-sort-functions
6130 '(gnus-thread-sort-by-number
6131 gnus-thread-sort-by-subject
6132 (not gnus-thread-sort-by-total-score)))
6135 The threads that have highest score will be displayed first in the
6136 summary buffer. When threads have the same score, they will be sorted
6137 alphabetically. The threads that have the same score and the same
6138 subject will be sorted by number, which is (normally) the sequence in
6139 which the articles arrived.
6141 If you want to sort by score and then reverse arrival order, you could
6145 (setq gnus-thread-sort-functions
6147 (not (gnus-thread-sort-by-number t1 t2)))
6148 gnus-thread-sort-by-score))
6151 @vindex gnus-thread-score-function
6152 The function in the @code{gnus-thread-score-function} variable (default
6153 @code{+}) is used for calculating the total score of a thread. Useful
6154 functions might be @code{max}, @code{min}, or squared means, or whatever
6157 @findex gnus-article-sort-functions
6158 @findex gnus-article-sort-by-date
6159 @findex gnus-article-sort-by-score
6160 @findex gnus-article-sort-by-subject
6161 @findex gnus-article-sort-by-author
6162 @findex gnus-article-sort-by-number
6163 If you are using an unthreaded display for some strange reason or other,
6164 you have to fiddle with the @code{gnus-article-sort-functions} variable.
6165 It is very similar to the @code{gnus-thread-sort-functions}, except that
6166 it uses slightly different functions for article comparison. Available
6167 sorting predicate functions are @code{gnus-article-sort-by-number},
6168 @code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
6169 @code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
6171 If you want to sort an unthreaded summary display by subject, you could
6175 (setq gnus-article-sort-functions
6176 '(gnus-article-sort-by-number
6177 gnus-article-sort-by-subject))
6182 @node Asynchronous Fetching
6183 @section Asynchronous Article Fetching
6184 @cindex asynchronous article fetching
6185 @cindex article pre-fetch
6188 If you read your news from an @sc{nntp} server that's far away, the
6189 network latencies may make reading articles a chore. You have to wait
6190 for a while after pressing @kbd{n} to go to the next article before the
6191 article appears. Why can't gnus just go ahead and fetch the article
6192 while you are reading the previous one? Why not, indeed.
6194 First, some caveats. There are some pitfalls to using asynchronous
6195 article fetching, especially the way gnus does it.
6197 Let's say you are reading article 1, which is short, and article 2 is
6198 quite long, and you are not interested in reading that. Gnus does not
6199 know this, so it goes ahead and fetches article 2. You decide to read
6200 article 3, but since gnus is in the process of fetching article 2, the
6201 connection is blocked.
6203 To avoid these situations, gnus will open two (count 'em two)
6204 connections to the server. Some people may think this isn't a very nice
6205 thing to do, but I don't see any real alternatives. Setting up that
6206 extra connection takes some time, so gnus startup will be slower.
6208 Gnus will fetch more articles than you will read. This will mean that
6209 the link between your machine and the @sc{nntp} server will become more
6210 loaded than if you didn't use article pre-fetch. The server itself will
6211 also become more loaded---both with the extra article requests, and the
6214 Ok, so now you know that you shouldn't really use this thing... unless
6217 @vindex gnus-asynchronous
6218 Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
6219 happen automatically.
6221 @vindex gnus-use-article-prefetch
6222 You can control how many articles are to be pre-fetched by setting
6223 @code{gnus-use-article-prefetch}. This is 30 by default, which means
6224 that when you read an article in the group, the backend will pre-fetch
6225 the next 30 articles. If this variable is @code{t}, the backend will
6226 pre-fetch all the articles it can without bound. If it is
6227 @code{nil}, no pre-fetching will be done.
6229 @vindex gnus-async-prefetch-article-p
6230 @findex gnus-async-read-p
6231 There are probably some articles that you don't want to pre-fetch---read
6232 articles, for instance. The @code{gnus-async-prefetch-article-p} variable controls whether an article is to be pre-fetched. This function should
6233 return non-@code{nil} when the article in question is to be
6234 pre-fetched. The default is @code{gnus-async-read-p}, which returns
6235 @code{nil} on read articles. The function is called with an article
6236 data structure as the only parameter.
6238 If, for instance, you wish to pre-fetch only unread articles shorter than 100 lines, you could say something like:
6241 (defun my-async-short-unread-p (data)
6242 "Return non-nil for short, unread articles."
6243 (and (gnus-data-unread-p data)
6244 (< (mail-header-lines (gnus-data-header data))
6247 (setq gnus-async-prefetch-article-p 'my-async-short-unread-p)
6250 These functions will be called many, many times, so they should
6251 preferably be short and sweet to avoid slowing down gnus too much.
6252 It's probably a good idea to byte-compile things like this.
6254 @vindex gnus-prefetched-article-deletion-strategy
6255 Articles have to be removed from the asynch buffer sooner or later. The
6256 @code{gnus-prefetched-article-deletion-strategy} says when to remove
6257 articles. This is a list that may contain the following elements:
6261 Remove articles when they are read.
6264 Remove articles when exiting the group.
6267 The default value is @code{(read exit)}.
6269 @c @vindex gnus-use-header-prefetch
6270 @c If @code{gnus-use-header-prefetch} is non-@code{nil}, prefetch articles
6271 @c from the next group.
6274 @node Article Caching
6275 @section Article Caching
6276 @cindex article caching
6279 If you have an @emph{extremely} slow @sc{nntp} connection, you may
6280 consider turning article caching on. Each article will then be stored
6281 locally under your home directory. As you may surmise, this could
6282 potentially use @emph{huge} amounts of disk space, as well as eat up all
6283 your inodes so fast it will make your head swim. In vodka.
6285 Used carefully, though, it could be just an easier way to save articles.
6287 @vindex gnus-use-long-file-name
6288 @vindex gnus-cache-directory
6289 @vindex gnus-use-cache
6290 To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
6291 all articles ticked or marked as dormant will then be copied
6292 over to your local cache (@code{gnus-cache-directory}). Whether this
6293 cache is flat or hierarchical is controlled by the
6294 @code{gnus-use-long-file-name} variable, as usual.
6296 When re-selecting a ticked or dormant article, it will be fetched from the
6297 cache instead of from the server. As articles in your cache will never
6298 expire, this might serve as a method of saving articles while still
6299 keeping them where they belong. Just mark all articles you want to save
6300 as dormant, and don't worry.
6302 When an article is marked as read, is it removed from the cache.
6304 @vindex gnus-cache-remove-articles
6305 @vindex gnus-cache-enter-articles
6306 The entering/removal of articles from the cache is controlled by the
6307 @code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
6308 variables. Both are lists of symbols. The first is @code{(ticked
6309 dormant)} by default, meaning that ticked and dormant articles will be
6310 put in the cache. The latter is @code{(read)} by default, meaning that
6311 articles marked as read are removed from the cache. Possibly
6312 symbols in these two lists are @code{ticked}, @code{dormant},
6313 @code{unread} and @code{read}.
6315 @findex gnus-jog-cache
6316 So where does the massive article-fetching and storing come into the
6317 picture? The @code{gnus-jog-cache} command will go through all
6318 subscribed newsgroups, request all unread articles, score them, and
6319 store them in the cache. You should only ever, ever ever ever, use this
6320 command if 1) your connection to the @sc{nntp} server is really, really,
6321 really slow and 2) you have a really, really, really huge disk.
6322 Seriously. One way to cut down on the number of articles downloaded is
6323 to score unwanted articles down and have them marked as read. They will
6324 not then be downloaded by this command.
6326 @vindex gnus-uncacheable-groups
6327 @vindex gnus-cacheable-groups
6328 It is likely that you do not want caching on all groups. For instance,
6329 if your @code{nnml} mail is located under your home directory, it makes no
6330 sense to cache it somewhere else under your home directory. Unless you
6331 feel that it's neat to use twice as much space.
6333 To limit the caching, you could set @code{gnus-cacheable-groups} to a
6334 regexp of groups to cache, @samp{^nntp} for instance, or set the
6335 @code{gnus-uncacheable-groups} regexp to @samp{^nnml}, for instance.
6336 Both variables are @code{nil} by default. If a group matches both
6337 variables, the group is not cached.
6339 @findex gnus-cache-generate-nov-databases
6340 @findex gnus-cache-generate-active
6341 @vindex gnus-cache-active-file
6342 The cache stores information on what articles it contains in its active
6343 file (@code{gnus-cache-active-file}). If this file (or any other parts
6344 of the cache) becomes all messed up for some reason or other, gnus
6345 offers two functions that will try to set things right. @kbd{M-x
6346 gnus-cache-generate-nov-databases} will (re)build all the @sc{nov}
6347 files, and @kbd{gnus-cache-generate-active} will (re)generate the active
6351 @node Persistent Articles
6352 @section Persistent Articles
6353 @cindex persistent articles
6355 Closely related to article caching, we have @dfn{persistent articles}.
6356 In fact, it's just a different way of looking at caching, and much more
6357 useful in my opinion.
6359 Say you're reading a newsgroup, and you happen on to some valuable gem
6360 that you want to keep and treasure forever. You'd normally just save it
6361 (using one of the many saving commands) in some file. The problem with
6362 that is that it's just, well, yucky. Ideally you'd prefer just having
6363 the article remain in the group where you found it forever; untouched by
6364 the expiry going on at the news server.
6366 This is what a @dfn{persistent article} is---an article that just won't
6367 be deleted. It's implemented using the normal cache functions, but
6368 you use two explicit commands for managing persistent articles:
6374 @findex gnus-cache-enter-article
6375 Make the current article persistent (@code{gnus-cache-enter-article}).
6378 @kindex M-* (Summary)
6379 @findex gnus-cache-remove-article
6380 Remove the current article from the persistent articles
6381 (@code{gnus-cache-remove-article}). This will normally delete the
6385 Both these commands understand the process/prefix convention.
6387 To avoid having all ticked articles (and stuff) entered into the cache,
6388 you should set @code{gnus-use-cache} to @code{passive} if you're just
6389 interested in persistent articles:
6392 (setq gnus-use-cache 'passive)
6396 @node Article Backlog
6397 @section Article Backlog
6399 @cindex article backlog
6401 If you have a slow connection, but the idea of using caching seems
6402 unappealing to you (and it is, really), you can help the situation some
6403 by switching on the @dfn{backlog}. This is where gnus will buffer
6404 already read articles so that it doesn't have to re-fetch articles
6405 you've already read. This only helps if you are in the habit of
6406 re-selecting articles you've recently read, of course. If you never do
6407 that, turning the backlog on will slow gnus down a little bit, and
6408 increase memory usage some.
6410 @vindex gnus-keep-backlog
6411 If you set @code{gnus-keep-backlog} to a number @var{n}, gnus will store
6412 at most @var{n} old articles in a buffer for later re-fetching. If this
6413 variable is non-@code{nil} and is not a number, gnus will store
6414 @emph{all} read articles, which means that your Emacs will grow without
6415 bound before exploding and taking your machine down with you. I put
6416 that in there just to keep y'all on your toes.
6418 This variable is @code{nil} by default.
6421 @node Saving Articles
6422 @section Saving Articles
6423 @cindex saving articles
6425 Gnus can save articles in a number of ways. Below is the documentation
6426 for saving articles in a fairly straight-forward fashion (i.e., little
6427 processing of the article is done before it is saved). For a different
6428 approach (uudecoding, unsharing) you should use @code{gnus-uu}
6429 (@pxref{Decoding Articles}).
6431 @vindex gnus-save-all-headers
6432 If @code{gnus-save-all-headers} is non-@code{nil}, gnus will not delete
6433 unwanted headers before saving the article.
6435 @vindex gnus-saved-headers
6436 If the preceding variable is @code{nil}, all headers that match the
6437 @code{gnus-saved-headers} regexp will be kept, while the rest will be
6438 deleted before saving.
6444 @kindex O o (Summary)
6446 @findex gnus-summary-save-article
6447 @c @icon{gnus-summary-save-article}
6448 Save the current article using the default article saver
6449 (@code{gnus-summary-save-article}).
6452 @kindex O m (Summary)
6453 @findex gnus-summary-save-article-mail
6454 Save the current article in mail format
6455 (@code{gnus-summary-save-article-mail}).
6458 @kindex O r (Summary)
6459 @findex gnus-summary-save-article-rmail
6460 Save the current article in rmail format
6461 (@code{gnus-summary-save-article-rmail}).
6464 @kindex O f (Summary)
6465 @findex gnus-summary-save-article-file
6466 @c @icon{gnus-summary-save-article-file}
6467 Save the current article in plain file format
6468 (@code{gnus-summary-save-article-file}).
6471 @kindex O F (Summary)
6472 @findex gnus-summary-write-article-file
6473 Write the current article in plain file format, overwriting any previous
6474 file contents (@code{gnus-summary-write-article-file}).
6477 @kindex O b (Summary)
6478 @findex gnus-summary-save-article-body-file
6479 Save the current article body in plain file format
6480 (@code{gnus-summary-save-article-body-file}).
6483 @kindex O h (Summary)
6484 @findex gnus-summary-save-article-folder
6485 Save the current article in mh folder format
6486 (@code{gnus-summary-save-article-folder}).
6489 @kindex O v (Summary)
6490 @findex gnus-summary-save-article-vm
6491 Save the current article in a VM folder
6492 (@code{gnus-summary-save-article-vm}).
6496 @kindex O p (Summary)
6498 @findex gnus-summary-pipe-output
6499 Save the current article in a pipe. Uhm, like, what I mean is---Pipe
6500 the current article to a process (@code{gnus-summary-pipe-output}).
6503 @vindex gnus-prompt-before-saving
6504 All these commands use the process/prefix convention
6505 (@pxref{Process/Prefix}). If you save bunches of articles using these
6506 functions, you might get tired of being prompted for files to save each
6507 and every article in. The prompting action is controlled by
6508 the @code{gnus-prompt-before-saving} variable, which is @code{always} by
6509 default, giving you that excessive prompting action you know and
6510 loathe. If you set this variable to @code{t} instead, you'll be prompted
6511 just once for each series of articles you save. If you like to really
6512 have Gnus do all your thinking for you, you can even set this variable
6513 to @code{nil}, which means that you will never be prompted for files to
6514 save articles in. Gnus will simply save all the articles in the default
6518 @vindex gnus-default-article-saver
6519 You can customize the @code{gnus-default-article-saver} variable to make
6520 gnus do what you want it to. You can use any of the six ready-made
6521 functions below, or you can create your own.
6525 @item gnus-summary-save-in-rmail
6526 @findex gnus-summary-save-in-rmail
6527 @vindex gnus-rmail-save-name
6528 @findex gnus-plain-save-name
6529 This is the default format, @dfn{babyl}. Uses the function in the
6530 @code{gnus-rmail-save-name} variable to get a file name to save the
6531 article in. The default is @code{gnus-plain-save-name}.
6533 @item gnus-summary-save-in-mail
6534 @findex gnus-summary-save-in-mail
6535 @vindex gnus-mail-save-name
6536 Save in a Unix mail (mbox) file. Uses the function in the
6537 @code{gnus-mail-save-name} variable to get a file name to save the
6538 article in. The default is @code{gnus-plain-save-name}.
6540 @item gnus-summary-save-in-file
6541 @findex gnus-summary-save-in-file
6542 @vindex gnus-file-save-name
6543 @findex gnus-numeric-save-name
6544 Append the article straight to an ordinary file. Uses the function in
6545 the @code{gnus-file-save-name} variable to get a file name to save the
6546 article in. The default is @code{gnus-numeric-save-name}.
6548 @item gnus-summary-save-body-in-file
6549 @findex gnus-summary-save-body-in-file
6550 Append the article body to an ordinary file. Uses the function in the
6551 @code{gnus-file-save-name} variable to get a file name to save the
6552 article in. The default is @code{gnus-numeric-save-name}.
6554 @item gnus-summary-save-in-folder
6555 @findex gnus-summary-save-in-folder
6556 @findex gnus-folder-save-name
6557 @findex gnus-Folder-save-name
6558 @vindex gnus-folder-save-name
6561 Save the article to an MH folder using @code{rcvstore} from the MH
6562 library. Uses the function in the @code{gnus-folder-save-name} variable
6563 to get a file name to save the article in. The default is
6564 @code{gnus-folder-save-name}, but you can also use
6565 @code{gnus-Folder-save-name}, which creates capitalized names.
6567 @item gnus-summary-save-in-vm
6568 @findex gnus-summary-save-in-vm
6569 Save the article in a VM folder. You have to have the VM mail
6570 reader to use this setting.
6573 @vindex gnus-article-save-directory
6574 All of these functions, except for the last one, will save the article
6575 in the @code{gnus-article-save-directory}, which is initialized from the
6576 @code{SAVEDIR} environment variable. This is @file{~/News/} by
6579 As you can see above, the functions use different functions to find a
6580 suitable name of a file to save the article in. Below is a list of
6581 available functions that generate names:
6585 @item gnus-Numeric-save-name
6586 @findex gnus-Numeric-save-name
6587 File names like @file{~/News/Alt.andrea-dworkin/45}.
6589 @item gnus-numeric-save-name
6590 @findex gnus-numeric-save-name
6591 File names like @file{~/News/alt.andrea-dworkin/45}.
6593 @item gnus-Plain-save-name
6594 @findex gnus-Plain-save-name
6595 File names like @file{~/News/Alt.andrea-dworkin}.
6597 @item gnus-plain-save-name
6598 @findex gnus-plain-save-name
6599 File names like @file{~/News/alt.andrea-dworkin}.
6601 @item gnus-sender-save-name
6602 @findex gnus-sender-save-name
6603 File names like @file{~/News/larsi}.
6606 @vindex gnus-split-methods
6607 You can have gnus suggest where to save articles by plonking a regexp into
6608 the @code{gnus-split-methods} alist. For instance, if you would like to
6609 save articles related to gnus in the file @file{gnus-stuff}, and articles
6610 related to VM in @code{vm-stuff}, you could set this variable to something
6614 (("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
6615 ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
6616 (my-choosing-function "../other-dir/my-stuff")
6617 ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
6620 We see that this is a list where each element is a list that has two
6621 elements---the @dfn{match} and the @dfn{file}. The match can either be
6622 a string (in which case it is used as a regexp to match on the article
6623 head); it can be a symbol (which will be called as a function with the
6624 group name as a parameter); or it can be a list (which will be
6625 @code{eval}ed). If any of these actions have a non-@code{nil} result,
6626 the @dfn{file} will be used as a default prompt. In addition, the
6627 result of the operation itself will be used if the function or form
6628 called returns a string or a list of strings.
6630 You basically end up with a list of file names that might be used when
6631 saving the current article. (All ``matches'' will be used.) You will
6632 then be prompted for what you really want to use as a name, with file
6633 name completion over the results from applying this variable.
6635 This variable is @code{((gnus-article-archive-name))} by default, which
6636 means that gnus will look at the articles it saves for an
6637 @code{Archive-name} line and use that as a suggestion for the file
6640 Here's an example function to clean up file names somewhat. If you have
6641 lots of mail groups called things like
6642 @samp{nnml:mail.whatever}, you may want to chop off the beginning of
6643 these group names before creating the file name to save to. The
6644 following will do just that:
6647 (defun my-save-name (group)
6648 (when (string-match "^nnml:mail." group)
6649 (substring group (match-end 0))))
6651 (setq gnus-split-methods
6652 '((gnus-article-archive-name)
6657 @vindex gnus-use-long-file-name
6658 Finally, you have the @code{gnus-use-long-file-name} variable. If it is
6659 @code{nil}, all the preceding functions will replace all periods
6660 (@samp{.}) in the group names with slashes (@samp{/})---which means that
6661 the functions will generate hierarchies of directories instead of having
6662 all the files in the top level directory
6663 (@file{~/News/alt/andrea-dworkin} instead of
6664 @file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
6665 on most systems. However, for historical reasons, this is @code{nil} on
6666 Xenix and usg-unix-v machines by default.
6668 This function also affects kill and score file names. If this variable
6669 is a list, and the list contains the element @code{not-score}, long file
6670 names will not be used for score files, if it contains the element
6671 @code{not-save}, long file names will not be used for saving, and if it
6672 contains the element @code{not-kill}, long file names will not be used
6675 If you'd like to save articles in a hierarchy that looks something like
6679 (setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
6680 (setq gnus-default-article-saver
6681 'gnus-summary-save-in-file) ; no encoding
6684 Then just save with @kbd{o}. You'd then read this hierarchy with
6685 ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
6686 the top level directory as the argument (@file{~/News/}). Then just walk
6687 around to the groups/directories with @code{nneething}.
6690 @node Decoding Articles
6691 @section Decoding Articles
6692 @cindex decoding articles
6694 Sometime users post articles (or series of articles) that have been
6695 encoded in some way or other. Gnus can decode them for you.
6698 * Uuencoded Articles:: Uudecode articles.
6699 * Shell Archives:: Unshar articles.
6700 * PostScript Files:: Split PostScript.
6701 * Other Files:: Plain save and binhex.
6702 * Decoding Variables:: Variables for a happy decoding.
6703 * Viewing Files:: You want to look at the result of the decoding?
6707 @cindex article series
6708 All these functions use the process/prefix convention
6709 (@pxref{Process/Prefix}) for finding out what articles to work on, with
6710 the extension that a ``single article'' means ``a single series''. Gnus
6711 can find out by itself what articles belong to a series, decode all the
6712 articles and unpack/view/save the resulting file(s).
6714 Gnus guesses what articles are in the series according to the following
6715 simplish rule: The subjects must be (nearly) identical, except for the
6716 last two numbers of the line. (Spaces are largely ignored, however.)
6718 For example: If you choose a subject called @samp{cat.gif (2/3)}, gnus
6719 will find all the articles that match the regexp @samp{^cat.gif
6720 ([0-9]+/[0-9]+).*$}.
6722 Subjects that are non-standard, like @samp{cat.gif (2/3) Part 6 of a
6723 series}, will not be properly recognized by any of the automatic viewing
6724 commands, and you have to mark the articles manually with @kbd{#}.
6727 @node Uuencoded Articles
6728 @subsection Uuencoded Articles
6730 @cindex uuencoded articles
6735 @kindex X u (Summary)
6736 @findex gnus-uu-decode-uu
6737 @c @icon{gnus-uu-decode-uu}
6738 Uudecodes the current series (@code{gnus-uu-decode-uu}).
6741 @kindex X U (Summary)
6742 @findex gnus-uu-decode-uu-and-save
6743 Uudecodes and saves the current series
6744 (@code{gnus-uu-decode-uu-and-save}).
6747 @kindex X v u (Summary)
6748 @findex gnus-uu-decode-uu-view
6749 Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
6752 @kindex X v U (Summary)
6753 @findex gnus-uu-decode-uu-and-save-view
6754 Uudecodes, views and saves the current series
6755 (@code{gnus-uu-decode-uu-and-save-view}).
6759 Remember that these all react to the presence of articles marked with
6760 the process mark. If, for instance, you'd like to decode and save an
6761 entire newsgroup, you'd typically do @kbd{M P a}
6762 (@code{gnus-uu-mark-all}) and then @kbd{X U}
6763 (@code{gnus-uu-decode-uu-and-save}).
6765 All this is very much different from how @code{gnus-uu} worked with
6766 @sc{gnus 4.1}, where you had explicit keystrokes for everything under
6767 the sun. This version of @code{gnus-uu} generally assumes that you mark
6768 articles in some way (@pxref{Setting Process Marks}) and then press
6771 @vindex gnus-uu-notify-files
6772 Note: When trying to decode articles that have names matching
6773 @code{gnus-uu-notify-files}, which is hard-coded to
6774 @samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
6775 automatically post an article on @samp{comp.unix.wizards} saying that
6776 you have just viewed the file in question. This feature can't be turned
6780 @node Shell Archives
6781 @subsection Shell Archives
6783 @cindex shell archives
6784 @cindex shared articles
6786 Shell archives (``shar files'') used to be a popular way to distribute
6787 sources, but it isn't used all that much today. In any case, we have
6788 some commands to deal with these:
6793 @kindex X s (Summary)
6794 @findex gnus-uu-decode-unshar
6795 Unshars the current series (@code{gnus-uu-decode-unshar}).
6798 @kindex X S (Summary)
6799 @findex gnus-uu-decode-unshar-and-save
6800 Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
6803 @kindex X v s (Summary)
6804 @findex gnus-uu-decode-unshar-view
6805 Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
6808 @kindex X v S (Summary)
6809 @findex gnus-uu-decode-unshar-and-save-view
6810 Unshars, views and saves the current series
6811 (@code{gnus-uu-decode-unshar-and-save-view}).
6815 @node PostScript Files
6816 @subsection PostScript Files
6822 @kindex X p (Summary)
6823 @findex gnus-uu-decode-postscript
6824 Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
6827 @kindex X P (Summary)
6828 @findex gnus-uu-decode-postscript-and-save
6829 Unpack and save the current PostScript series
6830 (@code{gnus-uu-decode-postscript-and-save}).
6833 @kindex X v p (Summary)
6834 @findex gnus-uu-decode-postscript-view
6835 View the current PostScript series
6836 (@code{gnus-uu-decode-postscript-view}).
6839 @kindex X v P (Summary)
6840 @findex gnus-uu-decode-postscript-and-save-view
6841 View and save the current PostScript series
6842 (@code{gnus-uu-decode-postscript-and-save-view}).
6847 @subsection Other Files
6851 @kindex X o (Summary)
6852 @findex gnus-uu-decode-save
6853 Save the current series
6854 (@code{gnus-uu-decode-save}).
6857 @kindex X b (Summary)
6858 @findex gnus-uu-decode-binhex
6859 Unbinhex the current series (@code{gnus-uu-decode-binhex}). This
6860 doesn't really work yet.
6864 @node Decoding Variables
6865 @subsection Decoding Variables
6867 Adjective, not verb.
6870 * Rule Variables:: Variables that say how a file is to be viewed.
6871 * Other Decode Variables:: Other decode variables.
6872 * Uuencoding and Posting:: Variables for customizing uuencoding.
6876 @node Rule Variables
6877 @subsubsection Rule Variables
6878 @cindex rule variables
6880 Gnus uses @dfn{rule variables} to decide how to view a file. All these
6881 variables are of the form
6884 (list '(regexp1 command2)
6891 @item gnus-uu-user-view-rules
6892 @vindex gnus-uu-user-view-rules
6894 This variable is consulted first when viewing files. If you wish to use,
6895 for instance, @code{sox} to convert an @samp{.au} sound file, you could
6898 (setq gnus-uu-user-view-rules
6899 (list '("\\\\.au$" "sox %s -t .aiff > /dev/audio")))
6902 @item gnus-uu-user-view-rules-end
6903 @vindex gnus-uu-user-view-rules-end
6904 This variable is consulted if gnus couldn't make any matches from the
6905 user and default view rules.
6907 @item gnus-uu-user-archive-rules
6908 @vindex gnus-uu-user-archive-rules
6909 This variable can be used to say what commands should be used to unpack
6914 @node Other Decode Variables
6915 @subsubsection Other Decode Variables
6918 @vindex gnus-uu-grabbed-file-functions
6920 @item gnus-uu-grabbed-file-functions
6921 All functions in this list will be called right after each file has been
6922 successfully decoded---so that you can move or view files right away,
6923 and don't have to wait for all files to be decoded before you can do
6924 anything. Ready-made functions you can put in this list are:
6928 @item gnus-uu-grab-view
6929 @findex gnus-uu-grab-view
6932 @item gnus-uu-grab-move
6933 @findex gnus-uu-grab-move
6934 Move the file (if you're using a saving function.)
6937 @item gnus-uu-be-dangerous
6938 @vindex gnus-uu-be-dangerous
6939 Specifies what to do if unusual situations arise during decoding. If
6940 @code{nil}, be as conservative as possible. If @code{t}, ignore things
6941 that didn't work, and overwrite existing files. Otherwise, ask each
6944 @item gnus-uu-ignore-files-by-name
6945 @vindex gnus-uu-ignore-files-by-name
6946 Files with name matching this regular expression won't be viewed.
6948 @item gnus-uu-ignore-files-by-type
6949 @vindex gnus-uu-ignore-files-by-type
6950 Files with a @sc{mime} type matching this variable won't be viewed.
6951 Note that Gnus tries to guess what type the file is based on the name.
6952 @code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
6955 @item gnus-uu-tmp-dir
6956 @vindex gnus-uu-tmp-dir
6957 Where @code{gnus-uu} does its work.
6959 @item gnus-uu-do-not-unpack-archives
6960 @vindex gnus-uu-do-not-unpack-archives
6961 Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
6962 looking for files to display.
6964 @item gnus-uu-view-and-save
6965 @vindex gnus-uu-view-and-save
6966 Non-@code{nil} means that the user will always be asked to save a file
6969 @item gnus-uu-ignore-default-view-rules
6970 @vindex gnus-uu-ignore-default-view-rules
6971 Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
6974 @item gnus-uu-ignore-default-archive-rules
6975 @vindex gnus-uu-ignore-default-archive-rules
6976 Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
6979 @item gnus-uu-kill-carriage-return
6980 @vindex gnus-uu-kill-carriage-return
6981 Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
6984 @item gnus-uu-unmark-articles-not-decoded
6985 @vindex gnus-uu-unmark-articles-not-decoded
6986 Non-@code{nil} means that @code{gnus-uu} will mark unsuccessfully
6987 decoded articles as unread.
6989 @item gnus-uu-correct-stripped-uucode
6990 @vindex gnus-uu-correct-stripped-uucode
6991 Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
6992 uuencoded files that have had trailing spaces deleted.
6994 @item gnus-uu-pre-uudecode-hook
6995 @vindex gnus-uu-pre-uudecode-hook
6996 Hook run before sending a message to @code{uudecode}.
6998 @item gnus-uu-view-with-metamail
6999 @vindex gnus-uu-view-with-metamail
7001 Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
7002 commands defined by the rule variables and just fudge a @sc{mime}
7003 content type based on the file name. The result will be fed to
7004 @code{metamail} for viewing.
7006 @item gnus-uu-save-in-digest
7007 @vindex gnus-uu-save-in-digest
7008 Non-@code{nil} means that @code{gnus-uu}, when asked to save without
7009 decoding, will save in digests. If this variable is @code{nil},
7010 @code{gnus-uu} will just save everything in a file without any
7011 embellishments. The digesting almost conforms to RFC 1153---no easy way
7012 to specify any meaningful volume and issue numbers were found, so I
7013 simply dropped them.
7018 @node Uuencoding and Posting
7019 @subsubsection Uuencoding and Posting
7023 @item gnus-uu-post-include-before-composing
7024 @vindex gnus-uu-post-include-before-composing
7025 Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
7026 before you compose the article. If this variable is @code{t}, you can
7027 either include an encoded file with @kbd{C-c C-i} or have one included
7028 for you when you post the article.
7030 @item gnus-uu-post-length
7031 @vindex gnus-uu-post-length
7032 Maximum length of an article. The encoded file will be split into how
7033 many articles it takes to post the entire file.
7035 @item gnus-uu-post-threaded
7036 @vindex gnus-uu-post-threaded
7037 Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
7038 thread. This may not be smart, as no other decoder I have seen is able
7039 to follow threads when collecting uuencoded articles. (Well, I have
7040 seen one package that does that---@code{gnus-uu}, but somehow, I don't
7041 think that counts...) Default is @code{nil}.
7043 @item gnus-uu-post-separate-description
7044 @vindex gnus-uu-post-separate-description
7045 Non-@code{nil} means that the description will be posted in a separate
7046 article. The first article will typically be numbered (0/x). If this
7047 variable is @code{nil}, the description the user enters will be included
7048 at the beginning of the first article, which will be numbered (1/x).
7049 Default is @code{t}.
7055 @subsection Viewing Files
7056 @cindex viewing files
7057 @cindex pseudo-articles
7059 After decoding, if the file is some sort of archive, gnus will attempt
7060 to unpack the archive and see if any of the files in the archive can be
7061 viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
7062 containing the files @file{pic1.jpg} and @file{pic2.gif}, gnus will
7063 uncompress and de-tar the main file, and then view the two pictures.
7064 This unpacking process is recursive, so if the archive contains archives
7065 of archives, it'll all be unpacked.
7067 Finally, gnus will normally insert a @dfn{pseudo-article} for each
7068 extracted file into the summary buffer. If you go to these
7069 ``articles'', you will be prompted for a command to run (usually Gnus
7070 will make a suggestion), and then the command will be run.
7072 @vindex gnus-view-pseudo-asynchronously
7073 If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
7074 until the viewing is done before proceeding.
7076 @vindex gnus-view-pseudos
7077 If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
7078 the pseudo-articles into the summary buffer, but view them
7079 immediately. If this variable is @code{not-confirm}, the user won't even
7080 be asked for a confirmation before viewing is done.
7082 @vindex gnus-view-pseudos-separately
7083 If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
7084 pseudo-article will be created for each file to be viewed. If
7085 @code{nil}, all files that use the same viewing command will be given as
7086 a list of parameters to that command.
7088 @vindex gnus-insert-pseudo-articles
7089 If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert
7090 pseudo-articles when decoding. It is @code{t} by default.
7092 So; there you are, reading your @emph{pseudo-articles} in your
7093 @emph{virtual newsgroup} from the @emph{virtual server}; and you think:
7094 Why isn't anything real anymore? How did we get here?
7097 @node Article Treatment
7098 @section Article Treatment
7100 Reading through this huge manual, you may have quite forgotten that the
7101 object of newsreaders is to actually, like, read what people have
7102 written. Reading articles. Unfortunately, people are quite bad at
7103 writing, so there are tons of functions and variables to make reading
7104 these articles easier.
7107 * Article Highlighting:: You want to make the article look like fruit salad.
7108 * Article Fontisizing:: Making emphasized text look nice.
7109 * Article Hiding:: You also want to make certain info go away.
7110 * Article Washing:: Lots of way-neat functions to make life better.
7111 * Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
7112 * Article Date:: Grumble, UT!
7113 * Article Signature:: What is a signature?
7114 * Article Miscellania:: Various other stuff.
7118 @node Article Highlighting
7119 @subsection Article Highlighting
7120 @cindex highlighting
7122 Not only do you want your article buffer to look like fruit salad, but
7123 you want it to look like technicolor fruit salad.
7128 @kindex W H a (Summary)
7129 @findex gnus-article-highlight
7130 @findex gnus-article-maybe-highlight
7131 Do much highlighting of the current article
7132 (@code{gnus-article-highlight}). This function highlights header, cited
7133 text, the signature, and adds buttons to the body and the head.
7136 @kindex W H h (Summary)
7137 @findex gnus-article-highlight-headers
7138 @vindex gnus-header-face-alist
7139 Highlight the headers (@code{gnus-article-highlight-headers}). The
7140 highlighting will be done according to the @code{gnus-header-face-alist}
7141 variable, which is a list where each element has the form
7142 @code{(@var{regexp} @var{name} @var{content})}.
7143 @var{regexp} is a regular expression for matching the
7144 header, @var{name} is the face used for highlighting the header name
7145 (@pxref{Faces and Fonts}) and @var{content} is the face for highlighting
7146 the header value. The first match made will be used. Note that
7147 @var{regexp} shouldn't have @samp{^} prepended---Gnus will add one.
7150 @kindex W H c (Summary)
7151 @findex gnus-article-highlight-citation
7152 Highlight cited text (@code{gnus-article-highlight-citation}).
7154 Some variables to customize the citation highlights:
7157 @vindex gnus-cite-parse-max-size
7159 @item gnus-cite-parse-max-size
7160 If the article size if bigger than this variable (which is 25000 by
7161 default), no citation highlighting will be performed.
7163 @item gnus-cite-max-prefix
7164 @vindex gnus-cite-max-prefix
7165 Maximum possible length for a citation prefix (default 20).
7167 @item gnus-cite-face-list
7168 @vindex gnus-cite-face-list
7169 List of faces used for highlighting citations (@pxref{Faces and Fonts}).
7170 When there are citations from multiple articles in the same message,
7171 gnus will try to give each citation from each article its own face.
7172 This should make it easier to see who wrote what.
7174 @item gnus-supercite-regexp
7175 @vindex gnus-supercite-regexp
7176 Regexp matching normal Supercite attribution lines.
7178 @item gnus-supercite-secondary-regexp
7179 @vindex gnus-supercite-secondary-regexp
7180 Regexp matching mangled Supercite attribution lines.
7182 @item gnus-cite-minimum-match-count
7183 @vindex gnus-cite-minimum-match-count
7184 Minimum number of identical prefixes we have to see before we believe
7185 that it's a citation.
7187 @item gnus-cite-attribution-prefix
7188 @vindex gnus-cite-attribution-prefix
7189 Regexp matching the beginning of an attribution line.
7191 @item gnus-cite-attribution-suffix
7192 @vindex gnus-cite-attribution-suffix
7193 Regexp matching the end of an attribution line.
7195 @item gnus-cite-attribution-face
7196 @vindex gnus-cite-attribution-face
7197 Face used for attribution lines. It is merged with the face for the
7198 cited text belonging to the attribution.
7204 @kindex W H s (Summary)
7205 @vindex gnus-signature-separator
7206 @vindex gnus-signature-face
7207 @findex gnus-article-highlight-signature
7208 Highlight the signature (@code{gnus-article-highlight-signature}).
7209 Everything after @code{gnus-signature-separator} (@pxref{Article
7210 Signature}) in an article will be considered a signature and will be
7211 highlighted with @code{gnus-signature-face}, which is @code{italic} by
7216 @xref{Customizing Articles}, for how to highlight articles automatically.
7219 @node Article Fontisizing
7220 @subsection Article Fontisizing
7222 @cindex article emphasis
7224 @findex gnus-article-emphasize
7225 @kindex W e (Summary)
7226 People commonly add emphasis to words in news articles by writing things
7227 like @samp{_this_} or @samp{*this*} or @samp{/this/}. Gnus can make
7228 this look nicer by running the article through the @kbd{W e}
7229 (@code{gnus-article-emphasize}) command.
7231 @vindex gnus-emphasis-alist
7232 How the emphasis is computed is controlled by the
7233 @code{gnus-emphasis-alist} variable. This is an alist where the first
7234 element is a regular expression to be matched. The second is a number
7235 that says what regular expression grouping is used to find the entire
7236 emphasized word. The third is a number that says what regexp grouping
7237 should be displayed and highlighted. (The text between these two
7238 groupings will be hidden.) The fourth is the face used for
7242 (setq gnus-emphasis-alist
7243 '(("_\\(\\w+\\)_" 0 1 gnus-emphasis-underline)
7244 ("\\*\\(\\w+\\)\\*" 0 1 gnus-emphasis-bold)))
7253 @vindex gnus-emphasis-underline
7254 @vindex gnus-emphasis-bold
7255 @vindex gnus-emphasis-italic
7256 @vindex gnus-emphasis-underline-bold
7257 @vindex gnus-emphasis-underline-italic
7258 @vindex gnus-emphasis-bold-italic
7259 @vindex gnus-emphasis-underline-bold-italic
7260 By default, there are seven rules, and they use the following faces:
7261 @code{gnus-emphasis-bold}, @code{gnus-emphasis-italic},
7262 @code{gnus-emphasis-underline}, @code{gnus-emphasis-bold-italic},
7263 @code{gnus-emphasis-underline-italic},
7264 @code{gnus-emphasis-underline-bold}, and
7265 @code{gnus-emphasis-underline-bold-italic}.
7267 If you want to change these faces, you can either use @kbd{M-x
7268 customize}, or you can use @code{copy-face}. For instance, if you want
7269 to make @code{gnus-emphasis-italic} use a red face instead, you could
7273 (copy-face 'red 'gnus-emphasis-italic)
7276 @vindex gnus-group-highlight-words-alist
7278 If you want to highlight arbitrary words, you can use the
7279 @code{gnus-group-highlight-words-alist} variable, which uses the same
7280 syntax as @code{gnus-emphasis-alist}. The @code{highlight-words} group
7281 parameter (@pxref{Group Parameters}) can also be used.
7283 @xref{Customizing Articles}, for how to fontize articles automatically.
7286 @node Article Hiding
7287 @subsection Article Hiding
7288 @cindex article hiding
7290 Or rather, hiding certain things in each article. There usually is much
7291 too much cruft in most articles.
7296 @kindex W W a (Summary)
7297 @findex gnus-article-hide
7298 Do quite a lot of hiding on the article buffer
7299 (@kbd{gnus-article-hide}). In particular, this function will hide
7300 headers, PGP, cited text and the signature.
7303 @kindex W W h (Summary)
7304 @findex gnus-article-toggle-headers
7305 Toggle hiding of headers (@code{gnus-article-toggle-headers}). @xref{Hiding
7309 @kindex W W b (Summary)
7310 @findex gnus-article-hide-boring-headers
7311 Hide headers that aren't particularly interesting
7312 (@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}.
7315 @kindex W W s (Summary)
7316 @findex gnus-article-hide-signature
7317 Hide signature (@code{gnus-article-hide-signature}). @xref{Article
7321 @kindex W W l (Summary)
7322 @findex gnus-article-hide-list-identifiers
7323 @vindex gnus-list-identifiers
7324 Strip list identifiers specified in @code{gnus-list-identifiers}. These
7325 are strings some mailing list servers add to the beginning of all
7326 @code{Subject} headers---for example, @samp{[zebra 4711]}. Any leading
7327 @samp{Re: } is skipped before stripping. @code{gnus-list-identifiers}
7328 may not contain @code{\\(..\\)}.
7332 @item gnus-list-identifiers
7333 @vindex gnus-list-identifiers
7334 A regular expression that matches list identifiers to be removed from
7335 subject. This can also be a list of regular expressions.
7340 @kindex W W p (Summary)
7341 @findex gnus-article-hide-pgp
7342 @vindex gnus-article-hide-pgp-hook
7343 Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}). The
7344 @code{gnus-article-hide-pgp-hook} hook will be run after a @sc{pgp}
7345 signature has been hidden. For example, to automatically verify
7346 articles that have signatures in them do:
7348 ;;; Hide pgp cruft if any.
7350 (setq gnus-treat-strip-pgp t)
7352 ;;; After hiding pgp, verify the message;
7353 ;;; only happens if pgp signature is found.
7355 (add-hook 'gnus-article-hide-pgp-hook
7358 (set-buffer gnus-original-article-buffer)
7363 @kindex W W P (Summary)
7364 @findex gnus-article-hide-pem
7365 Hide @sc{pem} (privacy enhanced messages) cruft
7366 (@code{gnus-article-hide-pem}).
7369 @kindex W W B (Summary)
7370 @findex gnus-article-strip-banner
7373 @cindex stripping advertisements
7374 @cindex advertisements
7375 Strip the banner specified by the @code{banner} group parameter
7376 (@code{gnus-article-strip-banner}). This is mainly used to hide those
7377 annoying banners and/or signatures that some mailing lists and moderated
7378 groups adds to all the messages. The way to use this function is to add
7379 the @code{banner} group parameter (@pxref{Group Parameters}) to the
7380 group you want banners stripped from. The parameter either be a string,
7381 which will be interpreted as a regular expression matching text to be
7382 removed, or the symbol @code{signature}, meaning that the (last)
7383 signature should be removed, or other symbol, meaning that the
7384 corresponding regular expression in @code{gnus-article-banner-alist} is
7388 @kindex W W c (Summary)
7389 @findex gnus-article-hide-citation
7390 Hide citation (@code{gnus-article-hide-citation}). Some variables for
7391 customizing the hiding:
7395 @item gnus-cited-opened-text-button-line-format
7396 @itemx gnus-cited-closed-text-button-line-format
7397 @vindex gnus-cited-closed-text-button-line-format
7398 @vindex gnus-cited-opened-text-button-line-format
7399 Gnus adds buttons to show where the cited text has been hidden, and to
7400 allow toggle hiding the text. The format of the variable is specified
7401 by these format-like variable (@pxref{Formatting Variables}). These
7406 Starting point of the hidden text.
7408 Ending point of the hidden text.
7410 Number of characters in the hidden region.
7412 Number of lines of hidden text.
7415 @item gnus-cited-lines-visible
7416 @vindex gnus-cited-lines-visible
7417 The number of lines at the beginning of the cited text to leave
7418 shown. This can also be a cons cell with the number of lines at the top
7419 and bottom of the text, respectively, to remain visible.
7424 @kindex W W C-c (Summary)
7425 @findex gnus-article-hide-citation-maybe
7427 Hide citation (@code{gnus-article-hide-citation-maybe}) depending on the
7428 following two variables:
7431 @item gnus-cite-hide-percentage
7432 @vindex gnus-cite-hide-percentage
7433 If the cited text is of a bigger percentage than this variable (default
7434 50), hide the cited text.
7436 @item gnus-cite-hide-absolute
7437 @vindex gnus-cite-hide-absolute
7438 The cited text must have at least this length (default 10) before it
7443 @kindex W W C (Summary)
7444 @findex gnus-article-hide-citation-in-followups
7445 Hide cited text in articles that aren't roots
7446 (@code{gnus-article-hide-citation-in-followups}). This isn't very
7447 useful as an interactive command, but might be a handy function to stick
7448 have happen automatically (@pxref{Customizing Articles}).
7452 All these ``hiding'' commands are toggles, but if you give a negative
7453 prefix to these commands, they will show what they have previously
7454 hidden. If you give a positive prefix, they will always hide.
7456 Also @pxref{Article Highlighting} for further variables for
7457 citation customization.
7459 @xref{Customizing Articles}, for how to hide article elements
7463 @node Article Washing
7464 @subsection Article Washing
7466 @cindex article washing
7468 We call this ``article washing'' for a really good reason. Namely, the
7469 @kbd{A} key was taken, so we had to use the @kbd{W} key instead.
7471 @dfn{Washing} is defined by us as ``changing something from something to
7472 something else'', but normally results in something looking better.
7475 @xref{Customizing Articles}, if you want to change how Gnus displays
7476 articles by default.
7481 This is not really washing, it's sort of the opposite of washing. If
7482 you type this, you see the article exactly as it exists on disk or on
7486 @kindex W l (Summary)
7487 @findex gnus-summary-stop-page-breaking
7488 Remove page breaks from the current article
7489 (@code{gnus-summary-stop-page-breaking}). @xref{Misc Article}, for page
7493 @kindex W r (Summary)
7494 @findex gnus-summary-caesar-message
7495 @c @icon{gnus-summary-caesar-message}
7496 Do a Caesar rotate (rot13) on the article buffer
7497 (@code{gnus-summary-caesar-message}).
7498 Unreadable articles that tell you to read them with Caesar rotate or rot13.
7499 (Typically offensive jokes and such.)
7501 It's commonly called ``rot13'' because each letter is rotated 13
7502 positions in the alphabet, e. g. @samp{B} (letter #2) -> @samp{O} (letter
7503 #15). It is sometimes referred to as ``Caesar rotate'' because Caesar
7504 is rumored to have employed this form of, uh, somewhat weak encryption.
7508 @kindex W t (Summary)
7510 @findex gnus-article-toggle-headers
7511 Toggle whether to display all headers in the article buffer
7512 (@code{gnus-article-toggle-headers}).
7515 @kindex W v (Summary)
7516 @findex gnus-summary-verbose-header
7517 Toggle whether to display all headers in the article buffer permanently
7518 (@code{gnus-summary-verbose-header}).
7521 @kindex W m (Summary)
7522 @findex gnus-summary-toggle-mime
7523 Toggle whether to run the article through @sc{mime} before displaying
7524 (@code{gnus-summary-toggle-mime}).
7527 @kindex W o (Summary)
7528 @findex gnus-article-treat-overstrike
7529 Treat overstrike (@code{gnus-article-treat-overstrike}).
7532 @kindex W d (Summary)
7533 @findex gnus-article-treat-dumbquotes
7534 @vindex gnus-article-dumbquotes-map
7536 @cindex M****s*** sm*rtq**t*s
7538 Treat M****s*** sm*rtq**t*s according to
7539 @code{gnus-article-dumbquotes-map}
7540 (@code{gnus-article-treat-dumbquotes}). Note that this function guesses
7541 whether a character is a sm*rtq**t* or not, so it should only be used
7544 Sm*rtq**t*s are M****s***'s unilateral extension to the character map in
7545 an attempt to provide more quoting characters. If you see something
7546 like @code{\222} or @code{\264} where you're expecting some kind of
7547 apostrophe or quotation mark, then try this wash.
7550 @kindex W w (Summary)
7551 @findex gnus-article-fill-cited-article
7552 Do word wrap (@code{gnus-article-fill-cited-article}).
7554 You can give the command a numerical prefix to specify the width to use
7558 @kindex W Q (Summary)
7559 @findex gnus-article-fill-long-lines
7560 Fill long lines (@code{gnus-article-fill-long-lines}).
7563 @kindex W C (Summary)
7564 @findex gnus-article-capitalize-sentences
7565 Capitalize the first word in each sentence
7566 (@code{gnus-article-capitalize-sentences}).
7569 @kindex W c (Summary)
7570 @findex gnus-article-remove-cr
7571 Translate CRLF pairs (i. e., @samp{^M}s on the end of the lines) into LF
7572 (this takes care of DOS line endings), and then translate any remaining
7573 CRs into LF (this takes care of Mac line endings)
7574 (@code{gnus-article-remove-cr}).
7577 @kindex W 6 (Summary)
7578 @findex gnus-article-de-base64-unreadable
7579 Treat base64 (@code{gnus-article-de-base64-unreadable}).
7580 Base64 is one common @sc{mime} encoding employed when sending non-ASCII
7581 (i. e., 8-bit) articles. Note that the this is usually done
7582 automatically by Gnus if the message in question has a
7583 @code{Content-Transfer-Encoding} header that says that this encoding has
7585 If a prefix is given, a charset will be asked for.
7588 @kindex W Z (Summary)
7589 @findex gnus-article-decode-HZ
7590 Treat HZ or HZP (@code{gnus-article-decode-HZ}). HZ (or HZP) is one
7591 common encoding employed when sending Chinese articles. It typically
7592 makes strings look like @samp{~@{<:Ky2;S@{#,NpJ)l6HK!#~@}}.
7595 @kindex W h (Summary)
7596 @findex gnus-article-wash-html
7597 Treat HTML (@code{gnus-article-wash-html}).
7598 Note that the this is usually done automatically by Gnus if the message
7599 in question has a @code{Content-Type} header that says that this type
7601 If a prefix is given, a charset will be asked for.
7604 @kindex W f (Summary)
7606 @findex gnus-article-display-x-face
7607 @findex gnus-article-x-face-command
7608 @vindex gnus-article-x-face-command
7609 @vindex gnus-article-x-face-too-ugly
7616 Look for and display any X-Face headers
7617 (@code{gnus-article-display-x-face}). The command executed by this
7618 function is given by the @code{gnus-article-x-face-command} variable.
7619 If this variable is a string, this string will be executed in a
7620 sub-shell. If it is a function, this function will be called with the
7621 face as the argument. If the @code{gnus-article-x-face-too-ugly} (which
7622 is a regexp) matches the @code{From} header, the face will not be shown.
7623 The default action under Emacs is to fork off the @code{display}
7624 program@footnote{@code{display} is from the ImageMagick package. For the
7625 @code{uncompface} and @code{icontopbm} programs look for a package
7626 like `compface' or `faces-xface' on a GNU/Linux system.}
7627 to view the face. Under XEmacs or Emacs 21+ with suitable image
7628 support, the default action is to display the face before the
7629 @code{From} header. (It's nicer if XEmacs has been compiled with X-Face
7630 support---that will make display somewhat faster. If there's no native
7631 X-Face support, Gnus will try to convert the @code{X-Face} header using
7632 external programs from the @code{pbmplus} package and
7633 friends.@footnote{On a GNU/Linux system look for packages with names
7634 like @code{netpbm} or @code{libgr-progs}.}) If you
7635 want to have this function in the display hook, it should probably come
7639 @kindex W b (Summary)
7640 @findex gnus-article-add-buttons
7641 Add clickable buttons to the article (@code{gnus-article-add-buttons}).
7642 @xref{Article Buttons}.
7645 @kindex W B (Summary)
7646 @findex gnus-article-add-buttons-to-head
7647 Add clickable buttons to the article headers
7648 (@code{gnus-article-add-buttons-to-head}).
7651 @kindex W p (Summary)
7652 @findex gnus-article-verify-x-pgp-sig
7653 Verify a signed control message (@code{gnus-article-verify-x-pgp-sig}).
7654 Control messages such as @code{newgroup} and @code{checkgroups} are
7655 usually signed by the hierarchy maintainer. You need to add the PGP
7656 public key of the maintainer to your keyring to verify the
7657 message.@footnote{PGP keys for many hierarchies are available at
7658 @uref{ftp://ftp.isc.org/pub/pgpcontrol/README.html}}
7661 @kindex W W H (Summary)
7662 @findex gnus-article-strip-headers-from-body
7663 Strip headers like the @code{X-No-Archive} header from the beginning of
7664 article bodies (@code{gnus-article-strip-headers-from-body}).
7667 @kindex W E l (Summary)
7668 @findex gnus-article-strip-leading-blank-lines
7669 Remove all blank lines from the beginning of the article
7670 (@code{gnus-article-strip-leading-blank-lines}).
7673 @kindex W E m (Summary)
7674 @findex gnus-article-strip-multiple-blank-lines
7675 Replace all blank lines with empty lines and then all multiple empty
7676 lines with a single empty line.
7677 (@code{gnus-article-strip-multiple-blank-lines}).
7680 @kindex W E t (Summary)
7681 @findex gnus-article-remove-trailing-blank-lines
7682 Remove all blank lines at the end of the article
7683 (@code{gnus-article-remove-trailing-blank-lines}).
7686 @kindex W E a (Summary)
7687 @findex gnus-article-strip-blank-lines
7688 Do all the three commands above
7689 (@code{gnus-article-strip-blank-lines}).
7692 @kindex W E A (Summary)
7693 @findex gnus-article-strip-all-blank-lines
7694 Remove all blank lines
7695 (@code{gnus-article-strip-all-blank-lines}).
7698 @kindex W E s (Summary)
7699 @findex gnus-article-strip-leading-space
7700 Remove all white space from the beginning of all lines of the article
7701 body (@code{gnus-article-strip-leading-space}).
7704 @kindex W E e (Summary)
7705 @findex gnus-article-strip-trailing-space
7706 Remove all white space from the end of all lines of the article
7707 body (@code{gnus-article-strip-trailing-space}).
7711 @xref{Customizing Articles}, for how to wash articles automatically.
7714 @node Article Buttons
7715 @subsection Article Buttons
7718 People often include references to other stuff in articles, and it would
7719 be nice if Gnus could just fetch whatever it is that people talk about
7720 with the minimum of fuzz when you hit @kbd{RET} or use the middle mouse
7721 button on these references.
7723 Gnus adds @dfn{buttons} to certain standard references by default:
7724 Well-formed URLs, mail addresses and Message-IDs. This is controlled by
7725 two variables, one that handles article bodies and one that handles
7730 @item gnus-button-alist
7731 @vindex gnus-button-alist
7732 This is an alist where each entry has this form:
7735 (REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
7741 All text that match this regular expression will be considered an
7742 external reference. Here's a typical regexp that matches embedded URLs:
7743 @samp{<URL:\\([^\n\r>]*\\)>}.
7746 Gnus has to know which parts of the matches is to be highlighted. This
7747 is a number that says what sub-expression of the regexp is to be
7748 highlighted. If you want it all highlighted, you use 0 here.
7751 This form will be @code{eval}ed, and if the result is non-@code{nil},
7752 this is considered a match. This is useful if you want extra sifting to
7753 avoid false matches.
7756 This function will be called when you click on this button.
7759 As with @var{button-par}, this is a sub-expression number, but this one
7760 says which part of the match is to be sent as data to @var{function}.
7764 So the full entry for buttonizing URLs is then
7767 ("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
7770 @item gnus-header-button-alist
7771 @vindex gnus-header-button-alist
7772 This is just like the other alist, except that it is applied to the
7773 article head only, and that each entry has an additional element that is
7774 used to say what headers to apply the buttonize coding to:
7777 (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
7780 @var{header} is a regular expression.
7782 @item gnus-button-url-regexp
7783 @vindex gnus-button-url-regexp
7784 A regular expression that matches embedded URLs. It is used in the
7785 default values of the variables above.
7787 @item gnus-article-button-face
7788 @vindex gnus-article-button-face
7789 Face used on buttons.
7791 @item gnus-article-mouse-face
7792 @vindex gnus-article-mouse-face
7793 Face used when the mouse cursor is over a button.
7797 @xref{Customizing Articles}, for how to buttonize articles automatically.
7801 @subsection Article Date
7803 The date is most likely generated in some obscure timezone you've never
7804 heard of, so it's quite nice to be able to find out what the time was
7805 when the article was sent.
7810 @kindex W T u (Summary)
7811 @findex gnus-article-date-ut
7812 Display the date in UT (aka. GMT, aka ZULU)
7813 (@code{gnus-article-date-ut}).
7816 @kindex W T i (Summary)
7817 @findex gnus-article-date-iso8601
7819 Display the date in international format, aka. ISO 8601
7820 (@code{gnus-article-date-iso8601}).
7823 @kindex W T l (Summary)
7824 @findex gnus-article-date-local
7825 Display the date in the local timezone (@code{gnus-article-date-local}).
7828 @kindex W T p (Summary)
7829 @findex gnus-article-date-english
7830 Display the date in a format that's easily pronounceable in English
7831 (@code{gnus-article-date-english}).
7834 @kindex W T s (Summary)
7835 @vindex gnus-article-time-format
7836 @findex gnus-article-date-user
7837 @findex format-time-string
7838 Display the date using a user-defined format
7839 (@code{gnus-article-date-user}). The format is specified by the
7840 @code{gnus-article-time-format} variable, and is a string that's passed
7841 to @code{format-time-string}. See the documentation of that variable
7842 for a list of possible format specs.
7845 @kindex W T e (Summary)
7846 @findex gnus-article-date-lapsed
7847 @findex gnus-start-date-timer
7848 @findex gnus-stop-date-timer
7849 Say how much time has elapsed between the article was posted and now
7850 (@code{gnus-article-date-lapsed}). It looks something like:
7853 X-Sent: 6 weeks, 4 days, 1 hour, 3 minutes, 8 seconds ago
7856 The value of @code{gnus-article-date-lapsed-new-header} determines
7857 whether this header will just be added below the old Date one, or will
7860 An advantage of using Gnus to read mail is that it converts simple bugs
7861 into wonderful absurdities.
7863 If you want to have this line updated continually, you can put
7866 (gnus-start-date-timer)
7869 in your @file{.gnus.el} file, or you can run it off of some hook. If
7870 you want to stop the timer, you can use the @code{gnus-stop-date-timer}
7874 @kindex W T o (Summary)
7875 @findex gnus-article-date-original
7876 Display the original date (@code{gnus-article-date-original}). This can
7877 be useful if you normally use some other conversion function and are
7878 worried that it might be doing something totally wrong. Say, claiming
7879 that the article was posted in 1854. Although something like that is
7880 @emph{totally} impossible. Don't you trust me? *titter*
7884 @xref{Customizing Articles}, for how to display the date in your
7885 preferred format automatically.
7888 @node Article Signature
7889 @subsection Article Signature
7891 @cindex article signature
7893 @vindex gnus-signature-separator
7894 Each article is divided into two parts---the head and the body. The
7895 body can be divided into a signature part and a text part. The variable
7896 that says what is to be considered a signature is
7897 @code{gnus-signature-separator}. This is normally the standard
7898 @samp{^-- $} as mandated by son-of-RFC 1036. However, many people use
7899 non-standard signature separators, so this variable can also be a list
7900 of regular expressions to be tested, one by one. (Searches are done
7901 from the end of the body towards the beginning.) One likely value is:
7904 (setq gnus-signature-separator
7905 '("^-- $" ; The standard
7906 "^-- *$" ; A common mangling
7907 "^-------*$" ; Many people just use a looong
7908 ; line of dashes. Shame!
7909 "^ *--------*$" ; Double-shame!
7910 "^________*$" ; Underscores are also popular
7911 "^========*$")) ; Pervert!
7914 The more permissive you are, the more likely it is that you'll get false
7917 @vindex gnus-signature-limit
7918 @code{gnus-signature-limit} provides a limit to what is considered a
7919 signature when displaying articles.
7923 If it is an integer, no signature may be longer (in characters) than
7926 If it is a floating point number, no signature may be longer (in lines)
7929 If it is a function, the function will be called without any parameters,
7930 and if it returns @code{nil}, there is no signature in the buffer.
7932 If it is a string, it will be used as a regexp. If it matches, the text
7933 in question is not a signature.
7936 This variable can also be a list where the elements may be of the types
7937 listed above. Here's an example:
7940 (setq gnus-signature-limit
7941 '(200.0 "^---*Forwarded article"))
7944 This means that if there are more than 200 lines after the signature
7945 separator, or the text after the signature separator is matched by
7946 the regular expression @samp{^---*Forwarded article}, then it isn't a
7947 signature after all.
7950 @node Article Miscellania
7951 @subsection Article Miscellania
7955 @kindex A t (Summary)
7956 @findex gnus-article-babel
7957 Translate the article from one language to another
7958 (@code{gnus-article-babel}).
7964 @section @sc{mime} Commands
7965 @cindex MIME decoding
7967 @cindex viewing attachments
7969 The following commands all understand the numerical prefix. For
7970 instance, @kbd{3 b} means ``view the third @sc{mime} part''.
7976 @kindex K v (Summary)
7977 View the @sc{mime} part.
7980 @kindex K o (Summary)
7981 Save the @sc{mime} part.
7984 @kindex K c (Summary)
7985 Copy the @sc{mime} part.
7988 @kindex K e (Summary)
7989 View the @sc{mime} part externally.
7992 @kindex K i (Summary)
7993 View the @sc{mime} part internally.
7996 @kindex K | (Summary)
7997 Pipe the @sc{mime} part to an external command.
8000 The rest of these @sc{mime} commands do not use the numerical prefix in
8005 @kindex K b (Summary)
8006 Make all the @sc{mime} parts have buttons in front of them. This is
8007 mostly useful if you wish to save (or perform other actions) on inlined
8011 @kindex K m (Summary)
8012 @findex gnus-summary-repair-multipart
8013 Some multipart messages are transmitted with missing or faulty headers.
8014 This command will attempt to ``repair'' these messages so that they can
8015 be viewed in a more pleasant manner
8016 (@code{gnus-summary-repair-multipart}).
8019 @kindex X m (Summary)
8020 @findex gnus-summary-save-parts
8021 Save all parts matching a @sc{mime} type to a directory
8022 (@code{gnus-summary-save-parts}). Understands the process/prefix
8023 convention (@pxref{Process/Prefix}).
8026 @kindex M-t (Summary)
8027 @findex gnus-summary-display-buttonized
8028 Toggle the buttonized display of the article buffer
8029 (@code{gnus-summary-toggle-display-buttonized}).
8032 @kindex W M w (Summary)
8033 Decode RFC 2047-encoded words in the article headers
8034 (@code{gnus-article-decode-mime-words}).
8037 @kindex W M c (Summary)
8038 Decode encoded article bodies as well as charsets
8039 (@code{gnus-article-decode-charset}).
8041 This command looks in the @code{Content-Type} header to determine the
8042 charset. If there is no such header in the article, you can give it a
8043 prefix, which will prompt for the charset to decode as. In regional
8044 groups where people post using some common encoding (but do not include
8045 MIME headers), you can set the @code{charset} group/topic parameter to
8046 the required charset (@pxref{Group Parameters}).
8049 @kindex W M v (Summary)
8050 View all the @sc{mime} parts in the current article
8051 (@code{gnus-mime-view-all-parts}).
8058 @item gnus-ignored-mime-types
8059 @vindex gnus-ignored-mime-types
8060 This is a list of regexps. @sc{mime} types that match a regexp from
8061 this list will be completely ignored by Gnus. The default value is
8064 To have all Vcards be ignored, you'd say something like this:
8067 (setq gnus-ignored-mime-types
8071 @item gnus-unbuttonized-mime-types
8072 @vindex gnus-unbuttonized-mime-types
8073 This is a list of regexps. @sc{mime} types that match a regexp from
8074 this list won't have @sc{mime} buttons inserted unless they aren't
8075 displayed. The default value is @code{(".*/.*")}.
8077 @item gnus-article-mime-part-function
8078 @vindex gnus-article-mime-part-function
8079 For each @sc{mime} part, this function will be called with the @sc{mime}
8080 handle as the parameter. The function is meant to be used to allow
8081 users to gather information from the article (e. g., add Vcard info to
8082 the bbdb database) or to do actions based on parts (e. g., automatically
8083 save all jpegs into some directory).
8085 Here's an example function the does the latter:
8088 (defun my-save-all-jpeg-parts (handle)
8089 (when (equal (car (mm-handle-type handle)) "image/jpeg")
8091 (insert (mm-get-part handle))
8092 (write-region (point-min) (point-max)
8093 (read-file-name "Save jpeg to: ")))))
8094 (setq gnus-article-mime-part-function
8095 'my-save-all-jpeg-parts)
8098 @vindex gnus-mime-multipart-functions
8099 @item gnus-mime-multipart-functions
8100 Alist of @sc{mime} multipart types and functions to handle them.
8102 @vindex mm-file-name-rewrite-functions
8103 @item mm-file-name-rewrite-functions
8104 List of functions used for rewriting file names of @sc{mime} parts.
8105 Each function takes a file name as input and returns a file name.
8107 Ready-made functions include@*
8108 @code{mm-file-name-delete-whitespace},
8109 @code{mm-file-name-trim-whitespace},
8110 @code{mm-file-name-collapse-whitespace}, and
8111 @code{mm-file-name-replace-whitespace}. The later uses the value of
8112 the variable @code{mm-file-name-replace-whitespace} to replace each
8113 whitespace character in a file name with that string; default value
8114 is @code{"_"} (a single underscore).
8115 @findex mm-file-name-delete-whitespace
8116 @findex mm-file-name-trim-whitespace
8117 @findex mm-file-name-collapse-whitespace
8118 @findex mm-file-name-replace-whitespace
8119 @vindex mm-file-name-replace-whitespace
8121 The standard functions @code{capitalize}, @code{downcase},
8122 @code{upcase}, and @code{upcase-initials} may be useful, too.
8124 Everybody knows that whitespace characters in file names are evil,
8125 except those who don't know. If you receive lots of attachments from
8126 such unenlightened users, you can make live easier by adding
8129 (setq mm-file-name-rewrite-functions
8130 '(mm-file-name-trim-whitespace
8131 mm-file-name-collapse-whitespace
8132 mm-file-name-replace-whitespace))
8136 to your @file{.gnus} file.
8145 People use different charsets, and we have @sc{mime} to let us know what
8146 charsets they use. Or rather, we wish we had. Many people use
8147 newsreaders and mailers that do not understand or use @sc{mime}, and
8148 just send out messages without saying what character sets they use. To
8149 help a bit with this, some local news hierarchies have policies that say
8150 what character set is the default. For instance, the @samp{fj}
8151 hierarchy uses @code{iso-2022-jp-2}.
8153 @vindex gnus-group-charset-alist
8154 This knowledge is encoded in the @code{gnus-group-charset-alist}
8155 variable, which is an alist of regexps (use the first item to match full
8156 group names) and default charsets to be used when reading these groups.
8158 In addition, some people do use soi-disant @sc{mime}-aware agents that
8159 aren't. These blithely mark messages as being in @code{iso-8859-1} even
8160 if they really are in @code{koi-8}. To help here, the
8161 @code{gnus-newsgroup-ignored-charsets} variable can be used. The
8162 charsets that are listed here will be ignored. The variable can be set
8163 on a group-by-group basis using the group parameters (@pxref{Group
8164 Parameters}). The default value is @code{(unknown-8bit)}, which is
8165 something some agents insist on having in there.
8167 @vindex gnus-group-posting-charset-alist
8168 When posting, @code{gnus-group-posting-charset-alist} is used to
8169 determine which charsets should not be encoded using the @sc{mime}
8170 encodings. For instance, some hierarchies discourage using
8171 quoted-printable header encoding.
8173 This variable is an alist of regexps and permitted unencoded charsets
8174 for posting. Each element of the alist has the form @code{(}@var{test
8175 header body-list}@code{)}, where:
8179 is either a regular expression matching the newsgroup header or a
8182 is the charset which may be left unencoded in the header (@code{nil}
8183 means encode all charsets),
8185 is a list of charsets which may be encoded using 8bit content-transfer
8186 encoding in the body, or one of the special values @code{nil} (always
8187 encode using quoted-printable) or @code{t} (always use 8bit).
8194 @cindex coding system aliases
8195 @cindex preferred charset
8197 Other charset tricks that may be useful, although not Gnus-specific:
8199 If there are several @sc{mime} charsets that encode the same Emacs
8200 charset, you can choose what charset to use by saying the following:
8203 (put-charset-property 'cyrillic-iso8859-5
8204 'preferred-coding-system 'koi8-r)
8207 This means that Russian will be encoded using @code{koi8-r} instead of
8208 the default @code{iso-8859-5} @sc{mime} charset.
8210 If you want to read messages in @code{koi8-u}, you can cheat and say
8213 (define-coding-system-alias 'koi8-u 'koi8-r)
8216 This will almost do the right thing.
8218 And finally, to read charsets like @code{windows-1251}, you can say
8222 (codepage-setup 1251)
8223 (define-coding-system-alias 'windows-1251 'cp1251)
8227 @node Article Commands
8228 @section Article Commands
8235 @kindex A P (Summary)
8236 @vindex gnus-ps-print-hook
8237 @findex gnus-summary-print-article
8238 Generate and print a PostScript image of the article buffer
8239 (@code{gnus-summary-print-article}). @code{gnus-ps-print-hook} will be
8240 run just before printing the buffer.
8245 @node Summary Sorting
8246 @section Summary Sorting
8247 @cindex summary sorting
8249 You can have the summary buffer sorted in various ways, even though I
8250 can't really see why you'd want that.
8255 @kindex C-c C-s C-n (Summary)
8256 @findex gnus-summary-sort-by-number
8257 Sort by article number (@code{gnus-summary-sort-by-number}).
8260 @kindex C-c C-s C-a (Summary)
8261 @findex gnus-summary-sort-by-author
8262 Sort by author (@code{gnus-summary-sort-by-author}).
8265 @kindex C-c C-s C-s (Summary)
8266 @findex gnus-summary-sort-by-subject
8267 Sort by subject (@code{gnus-summary-sort-by-subject}).
8270 @kindex C-c C-s C-d (Summary)
8271 @findex gnus-summary-sort-by-date
8272 Sort by date (@code{gnus-summary-sort-by-date}).
8275 @kindex C-c C-s C-l (Summary)
8276 @findex gnus-summary-sort-by-lines
8277 Sort by lines (@code{gnus-summary-sort-by-lines}).
8280 @kindex C-c C-s C-c (Summary)
8281 @findex gnus-summary-sort-by-chars
8282 Sort by article length (@code{gnus-summary-sort-by-chars}).
8285 @kindex C-c C-s C-i (Summary)
8286 @findex gnus-summary-sort-by-score
8287 Sort by score (@code{gnus-summary-sort-by-score}).
8290 @kindex C-c C-s C-o (Summary)
8291 @findex gnus-summary-sort-by-original
8292 Sort using the default sorting method
8293 (@code{gnus-summary-sort-by-original}).
8296 These functions will work both when you use threading and when you don't
8297 use threading. In the latter case, all summary lines will be sorted,
8298 line by line. In the former case, sorting will be done on a
8299 root-by-root basis, which might not be what you were looking for. To
8300 toggle whether to use threading, type @kbd{T T} (@pxref{Thread
8304 @node Finding the Parent
8305 @section Finding the Parent
8306 @cindex parent articles
8307 @cindex referring articles
8312 @findex gnus-summary-refer-parent-article
8313 If you'd like to read the parent of the current article, and it is not
8314 displayed in the summary buffer, you might still be able to. That is,
8315 if the current group is fetched by @sc{nntp}, the parent hasn't expired
8316 and the @code{References} in the current article are not mangled, you
8317 can just press @kbd{^} or @kbd{A r}
8318 (@code{gnus-summary-refer-parent-article}). If everything goes well,
8319 you'll get the parent. If the parent is already displayed in the
8320 summary buffer, point will just move to this article.
8322 If given a positive numerical prefix, fetch that many articles back into
8323 the ancestry. If given a negative numerical prefix, fetch just that
8324 ancestor. So if you say @kbd{3 ^}, gnus will fetch the parent, the
8325 grandparent and the grandgrandparent of the current article. If you say
8326 @kbd{-3 ^}, gnus will only fetch the grandgrandparent of the current
8330 @findex gnus-summary-refer-references
8331 @kindex A R (Summary)
8332 Fetch all articles mentioned in the @code{References} header of the
8333 article (@code{gnus-summary-refer-references}).
8336 @findex gnus-summary-refer-thread
8337 @kindex A T (Summary)
8338 Display the full thread where the current article appears
8339 (@code{gnus-summary-refer-thread}). This command has to fetch all the
8340 headers in the current group to work, so it usually takes a while. If
8341 you do it often, you may consider setting @code{gnus-fetch-old-headers}
8342 to @code{invisible} (@pxref{Filling In Threads}). This won't have any
8343 visible effects normally, but it'll make this command work a whole lot
8344 faster. Of course, it'll make group entry somewhat slow.
8346 @vindex gnus-refer-thread-limit
8347 The @code{gnus-refer-thread-limit} variable says how many old (i. e.,
8348 articles before the first displayed in the current group) headers to
8349 fetch when doing this command. The default is 200. If @code{t}, all
8350 the available headers will be fetched. This variable can be overridden
8351 by giving the @kbd{A T} command a numerical prefix.
8354 @findex gnus-summary-refer-article
8355 @kindex M-^ (Summary)
8357 @cindex fetching by Message-ID
8358 You can also ask the @sc{nntp} server for an arbitrary article, no
8359 matter what group it belongs to. @kbd{M-^}
8360 (@code{gnus-summary-refer-article}) will ask you for a
8361 @code{Message-ID}, which is one of those long, hard-to-read thingies
8362 that look something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You
8363 have to get it all exactly right. No fuzzy searches, I'm afraid.
8366 The current select method will be used when fetching by
8367 @code{Message-ID} from non-news select method, but you can override this
8368 by giving this command a prefix.
8370 @vindex gnus-refer-article-method
8371 If the group you are reading is located on a backend that does not
8372 support fetching by @code{Message-ID} very well (like @code{nnspool}),
8373 you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
8374 would, perhaps, be best if the @sc{nntp} server you consult is the one
8375 updating the spool you are reading from, but that's not really
8378 It can also be a list of select methods, as well as the special symbol
8379 @code{current}, which means to use the current select method. If it
8380 is a list, Gnus will try all the methods in the list until it finds a
8383 Here's an example setting that will first try the current method, and
8384 then ask Deja if that fails:
8387 (setq gnus-refer-article-method
8389 (nnweb "refer" (nnweb-type dejanews))))
8392 Most of the mail backends support fetching by @code{Message-ID}, but do
8393 not do a particularly excellent job at it. That is, @code{nnmbox} and
8394 @code{nnbabyl} are able to locate articles from any groups, while
8395 @code{nnml} and @code{nnfolder} are only able to locate articles that
8396 have been posted to the current group. (Anything else would be too time
8397 consuming.) @code{nnmh} does not support this at all.
8400 @node Alternative Approaches
8401 @section Alternative Approaches
8403 Different people like to read news using different methods. This being
8404 gnus, we offer a small selection of minor modes for the summary buffers.
8407 * Pick and Read:: First mark articles and then read them.
8408 * Binary Groups:: Auto-decode all articles.
8413 @subsection Pick and Read
8414 @cindex pick and read
8416 Some newsreaders (like @code{nn} and, uhm, @code{Netnews} on VM/CMS) use
8417 a two-phased reading interface. The user first marks in a summary
8418 buffer the articles she wants to read. Then she starts reading the
8419 articles with just an article buffer displayed.
8421 @findex gnus-pick-mode
8422 @kindex M-x gnus-pick-mode
8423 Gnus provides a summary buffer minor mode that allows
8424 this---@code{gnus-pick-mode}. This basically means that a few process
8425 mark commands become one-keystroke commands to allow easy marking, and
8426 it provides one additional command for switching to the summary buffer.
8428 Here are the available keystrokes when using pick mode:
8433 @findex gnus-pick-article-or-thread
8434 Pick the article or thread on the current line
8435 (@code{gnus-pick-article-or-thread}). If the variable
8436 @code{gnus-thread-hide-subtree} is true, then this key selects the
8437 entire thread when used at the first article of the thread. Otherwise,
8438 it selects just the article. If given a numerical prefix, go to that
8439 thread or article and pick it. (The line number is normally displayed
8440 at the beginning of the summary pick lines.)
8443 @kindex SPACE (Pick)
8444 @findex gnus-pick-next-page
8445 Scroll the summary buffer up one page (@code{gnus-pick-next-page}). If
8446 at the end of the buffer, start reading the picked articles.
8450 @findex gnus-pick-unmark-article-or-thread.
8451 Unpick the thread or article
8452 (@code{gnus-pick-unmark-article-or-thread}). If the variable
8453 @code{gnus-thread-hide-subtree} is true, then this key unpicks the
8454 thread if used at the first article of the thread. Otherwise it unpicks
8455 just the article. You can give this key a numerical prefix to unpick
8456 the thread or article at that line.
8460 @findex gnus-pick-start-reading
8461 @vindex gnus-pick-display-summary
8462 Start reading the picked articles (@code{gnus-pick-start-reading}). If
8463 given a prefix, mark all unpicked articles as read first. If
8464 @code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer
8465 will still be visible when you are reading.
8469 All the normal summary mode commands are still available in the
8470 pick-mode, with the exception of @kbd{u}. However @kbd{!} is available
8471 which is mapped to the same function
8472 @code{gnus-summary-tick-article-forward}.
8474 If this sounds like a good idea to you, you could say:
8477 (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
8480 @vindex gnus-pick-mode-hook
8481 @code{gnus-pick-mode-hook} is run in pick minor mode buffers.
8483 @vindex gnus-mark-unpicked-articles-as-read
8484 If @code{gnus-mark-unpicked-articles-as-read} is non-@code{nil}, mark
8485 all unpicked articles as read. The default is @code{nil}.
8487 @vindex gnus-summary-pick-line-format
8488 The summary line format in pick mode is slightly different from the
8489 standard format. At the beginning of each line the line number is
8490 displayed. The pick mode line format is controlled by the
8491 @code{gnus-summary-pick-line-format} variable (@pxref{Formatting
8492 Variables}). It accepts the same format specs that
8493 @code{gnus-summary-line-format} does (@pxref{Summary Buffer Lines}).
8497 @subsection Binary Groups
8498 @cindex binary groups
8500 @findex gnus-binary-mode
8501 @kindex M-x gnus-binary-mode
8502 If you spend much time in binary groups, you may grow tired of hitting
8503 @kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode}
8504 is a minor mode for summary buffers that makes all ordinary Gnus article
8505 selection functions uudecode series of articles and display the result
8506 instead of just displaying the articles the normal way.
8509 @findex gnus-binary-show-article
8510 The only way, in fact, to see the actual articles is the @kbd{g}
8511 command, when you have turned on this mode
8512 (@code{gnus-binary-show-article}).
8514 @vindex gnus-binary-mode-hook
8515 @code{gnus-binary-mode-hook} is called in binary minor mode buffers.
8519 @section Tree Display
8522 @vindex gnus-use-trees
8523 If you don't like the normal gnus summary display, you might try setting
8524 @code{gnus-use-trees} to @code{t}. This will create (by default) an
8525 additional @dfn{tree buffer}. You can execute all summary mode commands
8528 There are a few variables to customize the tree display, of course:
8531 @item gnus-tree-mode-hook
8532 @vindex gnus-tree-mode-hook
8533 A hook called in all tree mode buffers.
8535 @item gnus-tree-mode-line-format
8536 @vindex gnus-tree-mode-line-format
8537 A format string for the mode bar in the tree mode buffers (@pxref{Mode
8538 Line Formatting}). The default is @samp{Gnus: %%b %S %Z}. For a list
8539 of valid specs, @pxref{Summary Buffer Mode Line}.
8541 @item gnus-selected-tree-face
8542 @vindex gnus-selected-tree-face
8543 Face used for highlighting the selected article in the tree buffer. The
8544 default is @code{modeline}.
8546 @item gnus-tree-line-format
8547 @vindex gnus-tree-line-format
8548 A format string for the tree nodes. The name is a bit of a misnomer,
8549 though---it doesn't define a line, but just the node. The default value
8550 is @samp{%(%[%3,3n%]%)}, which displays the first three characters of
8551 the name of the poster. It is vital that all nodes are of the same
8552 length, so you @emph{must} use @samp{%4,4n}-like specifiers.
8558 The name of the poster.
8560 The @code{From} header.
8562 The number of the article.
8564 The opening bracket.
8566 The closing bracket.
8571 @xref{Formatting Variables}.
8573 Variables related to the display are:
8576 @item gnus-tree-brackets
8577 @vindex gnus-tree-brackets
8578 This is used for differentiating between ``real'' articles and
8579 ``sparse'' articles. The format is @code{((@var{real-open} . @var{real-close})
8580 (@var{sparse-open} . @var{sparse-close}) (@var{dummy-open} . @var{dummy-close}))}, and the
8581 default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}) (?< . ?>))}.
8583 @item gnus-tree-parent-child-edges
8584 @vindex gnus-tree-parent-child-edges
8585 This is a list that contains the characters used for connecting parent
8586 nodes to their children. The default is @code{(?- ?\\ ?|)}.
8590 @item gnus-tree-minimize-window
8591 @vindex gnus-tree-minimize-window
8592 If this variable is non-@code{nil}, gnus will try to keep the tree
8593 buffer as small as possible to allow more room for the other gnus
8594 windows. If this variable is a number, the tree buffer will never be
8595 higher than that number. The default is @code{t}. Note that if you
8596 have several windows displayed side-by-side in a frame and the tree
8597 buffer is one of these, minimizing the tree window will also resize all
8598 other windows displayed next to it.
8600 @item gnus-generate-tree-function
8601 @vindex gnus-generate-tree-function
8602 @findex gnus-generate-horizontal-tree
8603 @findex gnus-generate-vertical-tree
8604 The function that actually generates the thread tree. Two predefined
8605 functions are available: @code{gnus-generate-horizontal-tree} and
8606 @code{gnus-generate-vertical-tree} (which is the default).
8610 Here's an example from a horizontal tree buffer:
8613 @{***@}-(***)-[odd]-[Gun]
8623 Here's the same thread displayed in a vertical tree buffer:
8627 |--------------------------\-----\-----\
8628 (***) [Bjo] [Gun] [Gun]
8630 [odd] [Jan] [odd] (***) [Jor]
8632 [Gun] [Eri] [Eri] [odd]
8637 If you're using horizontal trees, it might be nice to display the trees
8638 side-by-side with the summary buffer. You could add something like the
8639 following to your @file{.gnus.el} file:
8642 (setq gnus-use-trees t
8643 gnus-generate-tree-function 'gnus-generate-horizontal-tree
8644 gnus-tree-minimize-window nil)
8645 (gnus-add-configuration
8649 (summary 0.75 point)
8654 @xref{Windows Configuration}.
8657 @node Mail Group Commands
8658 @section Mail Group Commands
8659 @cindex mail group commands
8661 Some commands only make sense in mail groups. If these commands are
8662 invalid in the current group, they will raise a hell and let you know.
8664 All these commands (except the expiry and edit commands) use the
8665 process/prefix convention (@pxref{Process/Prefix}).
8670 @kindex B e (Summary)
8671 @findex gnus-summary-expire-articles
8672 Run all expirable articles in the current group through the expiry
8673 process (@code{gnus-summary-expire-articles}). That is, delete all
8674 expirable articles in the group that have been around for a while.
8675 (@pxref{Expiring Mail}).
8678 @kindex B M-C-e (Summary)
8679 @findex gnus-summary-expire-articles-now
8680 Delete all the expirable articles in the group
8681 (@code{gnus-summary-expire-articles-now}). This means that @strong{all}
8682 articles eligible for expiry in the current group will
8683 disappear forever into that big @file{/dev/null} in the sky.
8686 @kindex B DEL (Summary)
8687 @findex gnus-summary-delete-article
8688 @c @icon{gnus-summary-mail-delete}
8689 Delete the mail article. This is ``delete'' as in ``delete it from your
8690 disk forever and ever, never to return again.'' Use with caution.
8691 (@code{gnus-summary-delete-article}).
8694 @kindex B m (Summary)
8696 @findex gnus-summary-move-article
8697 @vindex gnus-preserve-marks
8698 Move the article from one mail group to another
8699 (@code{gnus-summary-move-article}). Marks will be preserved if
8700 @var{gnus-preserve-marks} is non-@code{nil} (which is the default).
8703 @kindex B c (Summary)
8705 @findex gnus-summary-copy-article
8706 @c @icon{gnus-summary-mail-copy}
8707 Copy the article from one group (mail group or not) to a mail group
8708 (@code{gnus-summary-copy-article}). Marks will be preserved if
8709 @var{gnus-preserve-marks} is non-@code{nil} (which is the default).
8712 @kindex B B (Summary)
8713 @cindex crosspost mail
8714 @findex gnus-summary-crosspost-article
8715 Crosspost the current article to some other group
8716 (@code{gnus-summary-crosspost-article}). This will create a new copy of
8717 the article in the other group, and the Xref headers of the article will
8718 be properly updated.
8721 @kindex B i (Summary)
8722 @findex gnus-summary-import-article
8723 Import an arbitrary file into the current mail newsgroup
8724 (@code{gnus-summary-import-article}). You will be prompted for a file
8725 name, a @code{From} header and a @code{Subject} header.
8728 @kindex B r (Summary)
8729 @findex gnus-summary-respool-article
8730 Respool the mail article (@code{gnus-summary-respool-article}).
8731 @code{gnus-summary-respool-default-method} will be used as the default
8732 select method when respooling. This variable is @code{nil} by default,
8733 which means that the current group select method will be used instead.
8734 Marks will be preserved if @var{gnus-preserve-marks} is non-@code{nil}
8735 (which is the default).
8739 @kindex B w (Summary)
8741 @findex gnus-summary-edit-article
8742 @kindex C-c C-c (Article)
8743 Edit the current article (@code{gnus-summary-edit-article}). To finish
8744 editing and make the changes permanent, type @kbd{C-c C-c}
8745 (@kbd{gnus-summary-edit-article-done}). If you give a prefix to the
8746 @kbd{C-c C-c} command, gnus won't re-highlight the article.
8749 @kindex B q (Summary)
8750 @findex gnus-summary-respool-query
8751 If you want to re-spool an article, you might be curious as to what group
8752 the article will end up in before you do the re-spooling. This command
8753 will tell you (@code{gnus-summary-respool-query}).
8756 @kindex B t (Summary)
8757 @findex gnus-summary-respool-trace
8758 Similarly, this command will display all fancy splitting patterns used
8759 when repooling, if any (@code{gnus-summary-respool-trace}).
8762 @kindex B p (Summary)
8763 @findex gnus-summary-article-posted-p
8764 Some people have a tendency to send you "courtesy" copies when they
8765 follow up to articles you have posted. These usually have a
8766 @code{Newsgroups} header in them, but not always. This command
8767 (@code{gnus-summary-article-posted-p}) will try to fetch the current
8768 article from your news server (or rather, from
8769 @code{gnus-refer-article-method} or @code{gnus-select-method}) and will
8770 report back whether it found the article or not. Even if it says that
8771 it didn't find the article, it may have been posted anyway---mail
8772 propagation is much faster than news propagation, and the news copy may
8773 just not have arrived yet.
8777 @vindex gnus-move-split-methods
8778 @cindex moving articles
8779 If you move (or copy) articles regularly, you might wish to have gnus
8780 suggest where to put the articles. @code{gnus-move-split-methods} is a
8781 variable that uses the same syntax as @code{gnus-split-methods}
8782 (@pxref{Saving Articles}). You may customize that variable to create
8783 suggestions you find reasonable. (Note that
8784 @code{gnus-move-split-methods} uses group names where
8785 @code{gnus-split-methods} uses file names.)
8788 (setq gnus-move-split-methods
8789 '(("^From:.*Lars Magne" "nnml:junk")
8790 ("^Subject:.*gnus" "nnfolder:important")
8791 (".*" "nnml:misc")))
8795 @node Various Summary Stuff
8796 @section Various Summary Stuff
8799 * Summary Group Information:: Information oriented commands.
8800 * Searching for Articles:: Multiple article commands.
8801 * Summary Generation Commands:: (Re)generating the summary buffer.
8802 * Really Various Summary Commands:: Those pesky non-conformant commands.
8806 @vindex gnus-summary-mode-hook
8807 @item gnus-summary-mode-hook
8808 This hook is called when creating a summary mode buffer.
8810 @vindex gnus-summary-generate-hook
8811 @item gnus-summary-generate-hook
8812 This is called as the last thing before doing the threading and the
8813 generation of the summary buffer. It's quite convenient for customizing
8814 the threading variables based on what data the newsgroup has. This hook
8815 is called from the summary buffer after most summary buffer variables
8818 @vindex gnus-summary-prepare-hook
8819 @item gnus-summary-prepare-hook
8820 It is called after the summary buffer has been generated. You might use
8821 it to, for instance, highlight lines or modify the look of the buffer in
8822 some other ungodly manner. I don't care.
8824 @vindex gnus-summary-prepared-hook
8825 @item gnus-summary-prepared-hook
8826 A hook called as the very last thing after the summary buffer has been
8829 @vindex gnus-summary-ignore-duplicates
8830 @item gnus-summary-ignore-duplicates
8831 When gnus discovers two articles that have the same @code{Message-ID},
8832 it has to do something drastic. No articles are allowed to have the
8833 same @code{Message-ID}, but this may happen when reading mail from some
8834 sources. Gnus allows you to customize what happens with this variable.
8835 If it is @code{nil} (which is the default), gnus will rename the
8836 @code{Message-ID} (for display purposes only) and display the article as
8837 any other article. If this variable is @code{t}, it won't display the
8838 article---it'll be as if it never existed.
8840 @vindex gnus-alter-articles-to-read-function
8841 @item gnus-alter-articles-to-read-function
8842 This function, which takes two parameters (the group name and the list
8843 of articles to be selected), is called to allow the user to alter the
8844 list of articles to be selected.
8846 For instance, the following function adds the list of cached articles to
8847 the list in one particular group:
8850 (defun my-add-cached-articles (group articles)
8851 (if (string= group "some.group")
8852 (append gnus-newsgroup-cached articles)
8859 @node Summary Group Information
8860 @subsection Summary Group Information
8865 @kindex H f (Summary)
8866 @findex gnus-summary-fetch-faq
8867 @vindex gnus-group-faq-directory
8868 Try to fetch the FAQ (list of frequently asked questions) for the
8869 current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
8870 FAQ from @code{gnus-group-faq-directory}, which is usually a directory
8871 on a remote machine. This variable can also be a list of directories.
8872 In that case, giving a prefix to this command will allow you to choose
8873 between the various sites. @code{ange-ftp} or @code{efs} will probably
8874 be used for fetching the file.
8877 @kindex H d (Summary)
8878 @findex gnus-summary-describe-group
8879 Give a brief description of the current group
8880 (@code{gnus-summary-describe-group}). If given a prefix, force
8881 rereading the description from the server.
8884 @kindex H h (Summary)
8885 @findex gnus-summary-describe-briefly
8886 Give an extremely brief description of the most important summary
8887 keystrokes (@code{gnus-summary-describe-briefly}).
8890 @kindex H i (Summary)
8891 @findex gnus-info-find-node
8892 Go to the gnus info node (@code{gnus-info-find-node}).
8896 @node Searching for Articles
8897 @subsection Searching for Articles
8902 @kindex M-s (Summary)
8903 @findex gnus-summary-search-article-forward
8904 Search through all subsequent (raw) articles for a regexp
8905 (@code{gnus-summary-search-article-forward}).
8908 @kindex M-r (Summary)
8909 @findex gnus-summary-search-article-backward
8910 Search through all previous (raw) articles for a regexp
8911 (@code{gnus-summary-search-article-backward}).
8915 @findex gnus-summary-execute-command
8916 This command will prompt you for a header, a regular expression to match
8917 on this field, and a command to be executed if the match is made
8918 (@code{gnus-summary-execute-command}). If the header is an empty
8919 string, the match is done on the entire article. If given a prefix,
8920 search backward instead.
8922 For instance, @kbd{& RET some.*string #} will put the process mark on
8923 all articles that have heads or bodies that match @samp{some.*string}.
8926 @kindex M-& (Summary)
8927 @findex gnus-summary-universal-argument
8928 Perform any operation on all articles that have been marked with
8929 the process mark (@code{gnus-summary-universal-argument}).
8932 @node Summary Generation Commands
8933 @subsection Summary Generation Commands
8938 @kindex Y g (Summary)
8939 @findex gnus-summary-prepare
8940 Regenerate the current summary buffer (@code{gnus-summary-prepare}).
8943 @kindex Y c (Summary)
8944 @findex gnus-summary-insert-cached-articles
8945 Pull all cached articles (for the current group) into the summary buffer
8946 (@code{gnus-summary-insert-cached-articles}).
8951 @node Really Various Summary Commands
8952 @subsection Really Various Summary Commands
8958 @kindex C-d (Summary)
8959 @kindex A D (Summary)
8960 @findex gnus-summary-enter-digest-group
8961 If the current article is a collection of other articles (for instance,
8962 a digest), you might use this command to enter a group based on the that
8963 article (@code{gnus-summary-enter-digest-group}). Gnus will try to
8964 guess what article type is currently displayed unless you give a prefix
8965 to this command, which forces a ``digest'' interpretation. Basically,
8966 whenever you see a message that is a collection of other messages of
8967 some format, you @kbd{C-d} and read these messages in a more convenient
8971 @kindex M-C-d (Summary)
8972 @findex gnus-summary-read-document
8973 This command is very similar to the one above, but lets you gather
8974 several documents into one biiig group
8975 (@code{gnus-summary-read-document}). It does this by opening several
8976 @code{nndoc} groups for each document, and then opening an
8977 @code{nnvirtual} group on top of these @code{nndoc} groups. This
8978 command understands the process/prefix convention
8979 (@pxref{Process/Prefix}).
8982 @kindex C-t (Summary)
8983 @findex gnus-summary-toggle-truncation
8984 Toggle truncation of summary lines
8985 (@code{gnus-summary-toggle-truncation}). This will probably confuse the
8986 line centering function in the summary buffer, so it's not a good idea
8987 to have truncation switched off while reading articles.
8991 @findex gnus-summary-expand-window
8992 Expand the summary buffer window (@code{gnus-summary-expand-window}).
8993 If given a prefix, force an @code{article} window configuration.
8996 @kindex M-C-e (Summary)
8997 @findex gnus-summary-edit-parameters
8998 Edit the group parameters (@pxref{Group Parameters}) of the current
8999 group (@code{gnus-summary-edit-parameters}).
9002 @kindex M-C-a (Summary)
9003 @findex gnus-summary-customize-parameters
9004 Customize the group parameters (@pxref{Group Parameters}) of the current
9005 group (@code{gnus-summary-customize-parameters}).
9010 @node Exiting the Summary Buffer
9011 @section Exiting the Summary Buffer
9012 @cindex summary exit
9013 @cindex exiting groups
9015 Exiting from the summary buffer will normally update all info on the
9016 group and return you to the group buffer.
9022 @kindex Z Z (Summary)
9024 @findex gnus-summary-exit
9025 @vindex gnus-summary-exit-hook
9026 @vindex gnus-summary-prepare-exit-hook
9027 @c @icon{gnus-summary-exit}
9028 Exit the current group and update all information on the group
9029 (@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
9030 called before doing much of the exiting, which calls
9031 @code{gnus-summary-expire-articles} by default.
9032 @code{gnus-summary-exit-hook} is called after finishing the exit
9033 process. @code{gnus-group-no-more-groups-hook} is run when returning to
9034 group mode having no more (unread) groups.
9038 @kindex Z E (Summary)
9040 @findex gnus-summary-exit-no-update
9041 Exit the current group without updating any information on the group
9042 (@code{gnus-summary-exit-no-update}).
9046 @kindex Z c (Summary)
9048 @findex gnus-summary-catchup-and-exit
9049 @c @icon{gnus-summary-catchup-and-exit}
9050 Mark all unticked articles in the group as read and then exit
9051 (@code{gnus-summary-catchup-and-exit}).
9054 @kindex Z C (Summary)
9055 @findex gnus-summary-catchup-all-and-exit
9056 Mark all articles, even the ticked ones, as read and then exit
9057 (@code{gnus-summary-catchup-all-and-exit}).
9060 @kindex Z n (Summary)
9061 @findex gnus-summary-catchup-and-goto-next-group
9062 Mark all articles as read and go to the next group
9063 (@code{gnus-summary-catchup-and-goto-next-group}).
9066 @kindex Z R (Summary)
9067 @findex gnus-summary-reselect-current-group
9068 Exit this group, and then enter it again
9069 (@code{gnus-summary-reselect-current-group}). If given a prefix, select
9070 all articles, both read and unread.
9074 @kindex Z G (Summary)
9075 @kindex M-g (Summary)
9076 @findex gnus-summary-rescan-group
9077 @c @icon{gnus-summary-mail-get}
9078 Exit the group, check for new articles in the group, and select the
9079 group (@code{gnus-summary-rescan-group}). If given a prefix, select all
9080 articles, both read and unread.
9083 @kindex Z N (Summary)
9084 @findex gnus-summary-next-group
9085 Exit the group and go to the next group
9086 (@code{gnus-summary-next-group}).
9089 @kindex Z P (Summary)
9090 @findex gnus-summary-prev-group
9091 Exit the group and go to the previous group
9092 (@code{gnus-summary-prev-group}).
9095 @kindex Z s (Summary)
9096 @findex gnus-summary-save-newsrc
9097 Save the current number of read/marked articles in the dribble buffer
9098 and then save the dribble buffer (@code{gnus-summary-save-newsrc}). If
9099 given a prefix, also save the @file{.newsrc} file(s). Using this
9100 command will make exit without updating (the @kbd{Q} command) worthless.
9103 @vindex gnus-exit-group-hook
9104 @code{gnus-exit-group-hook} is called when you exit the current group
9105 with an ``updating'' exit. For instance @kbd{Q}
9106 (@code{gnus-summary-exit-no-update}) does not call this hook.
9108 @findex gnus-summary-wake-up-the-dead
9109 @findex gnus-dead-summary-mode
9110 @vindex gnus-kill-summary-on-exit
9111 If you're in the habit of exiting groups, and then changing your mind
9112 about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}.
9113 If you do that, gnus won't kill the summary buffer when you exit it.
9114 (Quelle surprise!) Instead it will change the name of the buffer to
9115 something like @samp{*Dead Summary ... *} and install a minor mode
9116 called @code{gnus-dead-summary-mode}. Now, if you switch back to this
9117 buffer, you'll find that all keys are mapped to a function called
9118 @code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead
9119 summary buffer will result in a live, normal summary buffer.
9121 There will never be more than one dead summary buffer at any one time.
9123 @vindex gnus-use-cross-reference
9124 The data on the current group will be updated (which articles you have
9125 read, which articles you have replied to, etc.) when you exit the
9126 summary buffer. If the @code{gnus-use-cross-reference} variable is
9127 @code{t} (which is the default), articles that are cross-referenced to
9128 this group and are marked as read, will also be marked as read in the
9129 other subscribed groups they were cross-posted to. If this variable is
9130 neither @code{nil} nor @code{t}, the article will be marked as read in
9131 both subscribed and unsubscribed groups (@pxref{Crosspost Handling}).
9134 @node Crosspost Handling
9135 @section Crosspost Handling
9139 Marking cross-posted articles as read ensures that you'll never have to
9140 read the same article more than once. Unless, of course, somebody has
9141 posted it to several groups separately. Posting the same article to
9142 several groups (not cross-posting) is called @dfn{spamming}, and you are
9143 by law required to send nasty-grams to anyone who perpetrates such a
9144 heinous crime. You may want to try NoCeM handling to filter out spam
9147 Remember: Cross-posting is kinda ok, but posting the same article
9148 separately to several groups is not. Massive cross-posting (aka.
9149 @dfn{velveeta}) is to be avoided at all costs, and you can even use the
9150 @code{gnus-summary-mail-crosspost-complaint} command to complain about
9151 excessive crossposting (@pxref{Summary Mail Commands}).
9153 @cindex cross-posting
9156 One thing that may cause Gnus to not do the cross-posting thing
9157 correctly is if you use an @sc{nntp} server that supports @sc{xover}
9158 (which is very nice, because it speeds things up considerably) which
9159 does not include the @code{Xref} header in its @sc{nov} lines. This is
9160 Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
9161 even with @sc{xover} by registering the @code{Xref} lines of all
9162 articles you actually read, but if you kill the articles, or just mark
9163 them as read without reading them, Gnus will not get a chance to snoop
9164 the @code{Xref} lines out of these articles, and will be unable to use
9165 the cross reference mechanism.
9167 @cindex LIST overview.fmt
9168 @cindex overview.fmt
9169 To check whether your @sc{nntp} server includes the @code{Xref} header
9170 in its overview files, try @samp{telnet your.nntp.server nntp},
9171 @samp{MODE READER} on @code{inn} servers, and then say @samp{LIST
9172 overview.fmt}. This may not work, but if it does, and the last line you
9173 get does not read @samp{Xref:full}, then you should shout and whine at
9174 your news admin until she includes the @code{Xref} header in the
9177 @vindex gnus-nov-is-evil
9178 If you want Gnus to get the @code{Xref}s right all the time, you have to
9179 set @code{gnus-nov-is-evil} to @code{t}, which slows things down
9184 For an alternative approach, @pxref{Duplicate Suppression}.
9187 @node Duplicate Suppression
9188 @section Duplicate Suppression
9190 By default, gnus tries to make sure that you don't have to read the same
9191 article more than once by utilizing the crossposting mechanism
9192 (@pxref{Crosspost Handling}). However, that simple and efficient
9193 approach may not work satisfactory for some users for various
9198 The @sc{nntp} server may fail to generate the @code{Xref} header. This
9199 is evil and not very common.
9202 The @sc{nntp} server may fail to include the @code{Xref} header in the
9203 @file{.overview} data bases. This is evil and all too common, alas.
9206 You may be reading the same group (or several related groups) from
9207 different @sc{nntp} servers.
9210 You may be getting mail that duplicates articles posted to groups.
9213 I'm sure there are other situations where @code{Xref} handling fails as
9214 well, but these four are the most common situations.
9216 If, and only if, @code{Xref} handling fails for you, then you may
9217 consider switching on @dfn{duplicate suppression}. If you do so, Gnus
9218 will remember the @code{Message-ID}s of all articles you have read or
9219 otherwise marked as read, and then, as if by magic, mark them as read
9220 all subsequent times you see them---in @emph{all} groups. Using this
9221 mechanism is quite likely to be somewhat inefficient, but not overly
9222 so. It's certainly preferable to reading the same articles more than
9225 Duplicate suppression is not a very subtle instrument. It's more like a
9226 sledge hammer than anything else. It works in a very simple
9227 fashion---if you have marked an article as read, it adds this Message-ID
9228 to a cache. The next time it sees this Message-ID, it will mark the
9229 article as read with the @samp{M} mark. It doesn't care what group it
9233 @item gnus-suppress-duplicates
9234 @vindex gnus-suppress-duplicates
9235 If non-@code{nil}, suppress duplicates.
9237 @item gnus-save-duplicate-list
9238 @vindex gnus-save-duplicate-list
9239 If non-@code{nil}, save the list of duplicates to a file. This will
9240 make startup and shutdown take longer, so the default is @code{nil}.
9241 However, this means that only duplicate articles read in a single gnus
9242 session are suppressed.
9244 @item gnus-duplicate-list-length
9245 @vindex gnus-duplicate-list-length
9246 This variable says how many @code{Message-ID}s to keep in the duplicate
9247 suppression list. The default is 10000.
9249 @item gnus-duplicate-file
9250 @vindex gnus-duplicate-file
9251 The name of the file to store the duplicate suppression list in. The
9252 default is @file{~/News/suppression}.
9255 If you have a tendency to stop and start gnus often, setting
9256 @code{gnus-save-duplicate-list} to @code{t} is probably a good idea. If
9257 you leave gnus running for weeks on end, you may have it @code{nil}. On
9258 the other hand, saving the list makes startup and shutdown much slower,
9259 so that means that if you stop and start gnus often, you should set
9260 @code{gnus-save-duplicate-list} to @code{nil}. Uhm. I'll leave this up
9261 to you to figure out, I think.
9266 Gnus is able to verify PGP or S/MIME signed messages or decrypt PGP
9271 To verify or decrypt PGP messages, you have to install mailcrypt or
9277 @item mm-verify-option
9278 @vindex mm-verify-option
9279 Option of verifying signed parts. @code{never}, not verify;
9280 @code{always}, always verify; @code{known}, only verify known
9281 protocols. Otherwise, ask user.
9283 @item mm-decrypt-option
9284 @vindex mm-decrypt-option
9285 Option of decrypting encrypted parts. @code{never}, no decryption;
9286 @code{always}, always decrypt @code{known}, only decrypt known
9287 protocols. Otherwise, ask user.
9292 @section Mailing List
9294 Gnus understands some mailing list fields of RFC 2369.
9299 @kindex C-c C-n h (Summary)
9300 @findex gnus-mailing-list-help
9301 Send a message to fetch mailing list help, if List-Help field exists.
9304 @kindex C-c C-n s (Summary)
9305 @findex gnus-mailing-list-subscribe
9306 Send a message to subscribe the mailing list, if List-Subscribe field exists.
9309 @kindex C-c C-n u (Summary)
9310 @findex gnus-mailing-list-unsubscribe
9311 Send a message to unsubscribe the mailing list, if List-Unsubscribe
9315 @kindex C-c C-n p (Summary)
9316 @findex gnus-mailing-list-post
9317 Post to the mailing list, if List-Post field exists.
9320 @kindex C-c C-n o (Summary)
9321 @findex gnus-mailing-list-owner
9322 Send a message to the mailing list owner, if List-Owner field exists.
9325 @kindex C-c C-n a (Summary)
9326 @findex gnus-mailing-list-owner
9327 Browse the mailing list archive, if List-Archive field exists.
9331 @node Article Buffer
9332 @chapter Article Buffer
9333 @cindex article buffer
9335 The articles are displayed in the article buffer, of which there is only
9336 one. All the summary buffers share the same article buffer unless you
9337 tell gnus otherwise.
9340 * Hiding Headers:: Deciding what headers should be displayed.
9341 * Using MIME:: Pushing articles through @sc{mime} before reading them.
9342 * Customizing Articles:: Tailoring the look of the articles.
9343 * Article Keymap:: Keystrokes available in the article buffer.
9344 * Misc Article:: Other stuff.
9348 @node Hiding Headers
9349 @section Hiding Headers
9350 @cindex hiding headers
9351 @cindex deleting headers
9353 The top section of each article is the @dfn{head}. (The rest is the
9354 @dfn{body}, but you may have guessed that already.)
9356 @vindex gnus-show-all-headers
9357 There is a lot of useful information in the head: the name of the person
9358 who wrote the article, the date it was written and the subject of the
9359 article. That's well and nice, but there's also lots of information
9360 most people do not want to see---what systems the article has passed
9361 through before reaching you, the @code{Message-ID}, the
9362 @code{References}, etc. ad nauseum---and you'll probably want to get rid
9363 of some of those lines. If you want to keep all those lines in the
9364 article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
9366 Gnus provides you with two variables for sifting headers:
9370 @item gnus-visible-headers
9371 @vindex gnus-visible-headers
9372 If this variable is non-@code{nil}, it should be a regular expression
9373 that says what headers you wish to keep in the article buffer. All
9374 headers that do not match this variable will be hidden.
9376 For instance, if you only want to see the name of the person who wrote
9377 the article and the subject, you'd say:
9380 (setq gnus-visible-headers "^From:\\|^Subject:")
9383 This variable can also be a list of regexps to match headers to
9386 @item gnus-ignored-headers
9387 @vindex gnus-ignored-headers
9388 This variable is the reverse of @code{gnus-visible-headers}. If this
9389 variable is set (and @code{gnus-visible-headers} is @code{nil}), it
9390 should be a regular expression that matches all lines that you want to
9391 hide. All lines that do not match this variable will remain visible.
9393 For instance, if you just want to get rid of the @code{References} field
9394 and the @code{Xref} field, you might say:
9397 (setq gnus-ignored-headers "^References:\\|^Xref:")
9400 This variable can also be a list of regexps to match headers to
9403 Note that if @code{gnus-visible-headers} is non-@code{nil}, this
9404 variable will have no effect.
9408 @vindex gnus-sorted-header-list
9409 Gnus can also sort the headers for you. (It does this by default.) You
9410 can control the sorting by setting the @code{gnus-sorted-header-list}
9411 variable. It is a list of regular expressions that says in what order
9412 the headers are to be displayed.
9414 For instance, if you want the name of the author of the article first,
9415 and then the subject, you might say something like:
9418 (setq gnus-sorted-header-list '("^From:" "^Subject:"))
9421 Any headers that are to remain visible, but are not listed in this
9422 variable, will be displayed in random order after all the headers listed in this variable.
9424 @findex gnus-article-hide-boring-headers
9425 @vindex gnus-boring-article-headers
9426 You can hide further boring headers by setting
9427 @code{gnus-treat-hide-boring-headers} to @code{head}. What this function
9428 does depends on the @code{gnus-boring-article-headers} variable. It's a
9429 list, but this list doesn't actually contain header names. Instead is
9430 lists various @dfn{boring conditions} that Gnus can check and remove
9433 These conditions are:
9436 Remove all empty headers.
9438 Remove the @code{Followup-To} header if it is identical to the
9439 @code{Newsgroups} header.
9441 Remove the @code{Reply-To} header if it lists the same address as the
9444 Remove the @code{Newsgroups} header if it only contains the current group
9447 Remove the @code{To} header if it only contains the address identical to
9448 the current groups's @code{to-address} parameter.
9450 Remove the @code{Date} header if the article is less than three days
9453 Remove the @code{To} header if it is very long.
9455 Remove all @code{To} headers if there are more than one.
9458 To include these three elements, you could say something like;
9461 (setq gnus-boring-article-headers
9462 '(empty followup-to reply-to))
9465 This is also the default value for this variable.
9469 @section Using @sc{mime}
9472 Mime is a standard for waving your hands through the air, aimlessly,
9473 while people stand around yawning.
9475 @sc{mime}, however, is a standard for encoding your articles, aimlessly,
9476 while all newsreaders die of fear.
9478 @sc{mime} may specify what character set the article uses, the encoding
9479 of the characters, and it also makes it possible to embed pictures and
9480 other naughty stuff in innocent-looking articles.
9482 @vindex gnus-show-mime
9483 @vindex gnus-article-display-method-for-mime
9484 @vindex gnus-strict-mime
9485 @findex gnus-article-display-mime-message
9486 Gnus handles @sc{mime} by pushing the articles through
9487 @code{gnus-article-display-method-for-mime}, which is
9488 @code{gnus-article-display-mime-message} by default. This function
9489 calls the SEMI MIME-View program to actually do the work. For more
9490 information on SEMI MIME-View, see its manual page (however it is not
9491 existed yet, sorry).
9493 Set @code{gnus-show-mime} to @code{t} if you want to use
9494 @sc{mime} all the time. However, if @code{gnus-strict-mime} is
9495 non-@code{nil}, the @sc{mime} method will only be used if there are
9496 @sc{mime} headers in the article. If you have @code{gnus-show-mime}
9497 set, then you'll see some unfortunate display glitches in the article
9498 buffer. These can't be avoided.
9500 In GNUS or Gnus, it might be best to just use the toggling functions
9501 from the summary buffer to avoid getting nasty surprises. (For instance,
9502 you enter the group @samp{alt.sing-a-long} and, before you know it,
9503 @sc{mime} has decoded the sound file in the article and some horrible
9504 sing-a-long song comes screaming out your speakers, and you can't find
9505 the volume button, because there isn't one, and people are starting to
9506 look at you, and you try to stop the program, but you can't, and you
9507 can't find the program to control the volume, and everybody else in the
9508 room suddenly decides to look at you disdainfully, and you'll feel
9511 Any similarity to real events and people is purely coincidental. Ahem.
9513 To avoid such kind of situation, gnus stops to use
9514 @code{metamail-buffer}. So now, you can set @code{gnus-show-mime} to
9515 non-@code{nil} every-time, then you can push button in the article
9516 buffer when there are nobody else.
9518 Also see @pxref{MIME Commands}.
9521 @node Customizing Articles
9522 @section Customizing Articles
9523 @cindex article customization
9525 A slew of functions for customizing how the articles are to look like
9526 exist. You can call these functions interactively, or you can have them
9527 called automatically when you select the articles.
9529 To have them called automatically, you should set the corresponding
9530 ``treatment'' variable. For instance, to have headers hidden, you'd set
9531 @code{gnus-treat-hide-headers}. Below is a list of variables that can
9532 be set, but first we discuss the values these variables can have.
9534 Note: Some values, while valid, make little sense. Check the list below
9535 for sensible values.
9539 @code{nil}: Don't do this treatment.
9542 @code{t}: Do this treatment on all body parts.
9545 @code{head}: Do the treatment on the headers.
9548 @code{last}: Do this treatment on the last part.
9551 An integer: Do this treatment on all body parts that have a length less
9555 A list of strings: Do this treatment on all body parts that are in
9556 articles that are read in groups that have names that match one of the
9557 regexps in the list.
9560 A list where the first element is not a string:
9562 The list is evaluated recursively. The first element of the list is a
9563 predicate. The following predicates are recognized: @code{or},
9564 @code{and}, @code{not} and @code{typep}. Here's an example:
9568 (typep "text/x-vcard"))
9572 @code{mime}: Do this treatment if the value of @code{gnus-show-mime}' is
9577 You may have noticed that the word @dfn{part} is used here. This refers
9578 to the fact that some messages are @sc{mime} multipart articles that may
9579 be divided into several parts. Articles that are not multiparts are
9580 considered to contain just a single part.
9582 @vindex gnus-article-treat-types
9583 Are the treatments applied to all sorts of multipart parts? Yes, if you
9584 want to, but by default, only @samp{text/plain} parts are given the
9585 treatment. This is controlled by the @code{gnus-article-treat-types}
9586 variable, which is a list of regular expressions that are matched to the
9587 type of the part. This variable is ignored if the value of the
9588 controlling variable is a predicate list, as described above.
9590 The following treatment options are available. The easiest way to
9591 customize this is to examine the @code{gnus-article-treat} customization
9592 group. Values in parenthesis are suggested sensible values. Others are
9593 possible but those listed are probably sufficient for most people.
9596 @item gnus-treat-highlight-signature (t, last)
9597 @item gnus-treat-buttonize (t, integer)
9598 @item gnus-treat-buttonize-head (head)
9599 @item gnus-treat-emphasize (t, head, integer)
9600 @item gnus-treat-fill-article (t, integer)
9601 @item gnus-treat-strip-cr (t, integer)
9602 @item gnus-treat-hide-headers (head)
9603 @item gnus-treat-hide-boring-headers (head)
9604 @item gnus-treat-hide-signature (t, last)
9605 @item gnus-treat-hide-citation (t, integer)
9606 @item gnus-treat-hide-citation-maybe (t, integer)
9607 @item gnus-treat-strip-pgp (t, last, integer)
9608 @item gnus-treat-x-pgp-sig (head)
9609 @item gnus-treat-strip-pem (t, last, integer)
9610 @item gnus-treat-highlight-headers (head)
9611 @item gnus-treat-highlight-citation (t, integer)
9612 @item gnus-treat-highlight-signature (t, last, integer)
9613 @item gnus-treat-date-ut (head)
9614 @item gnus-treat-date-local (head)
9615 @item gnus-treat-date-english (head)
9616 @item gnus-treat-date-lapsed (head)
9617 @item gnus-treat-date-original (head)
9618 @item gnus-treat-date-iso8601 (head)
9619 @item gnus-treat-date-user-defined (head)
9620 @item gnus-treat-strip-headers-in-body (t, integer)
9621 @item gnus-treat-strip-trailing-blank-lines (t, last, integer)
9622 @item gnus-treat-strip-leading-blank-lines (t, integer)
9623 @item gnus-treat-strip-multiple-blank-lines (t, integer)
9624 @item gnus-treat-overstrike (t, integer)
9625 @item gnus-treat-display-xface (head)
9626 @item gnus-treat-display-smileys (t, integer)
9627 @item gnus-treat-display-picons (head)
9628 @item gnus-treat-capitalize-sentences (t, integer)
9629 @item gnus-treat-fill-long-lines (t, integer)
9630 @item gnus-treat-play-sounds
9631 @item gnus-treat-translate
9632 @item gnus-treat-decode-article-as-default-mime-charset
9635 @vindex gnus-part-display-hook
9636 You can, of course, write your own functions to be called from
9637 @code{gnus-part-display-hook}. The functions are called narrowed to the
9638 part, and you can do anything you like, pretty much. There is no
9639 information that you have to keep in the buffer---you can change
9643 @node Article Keymap
9644 @section Article Keymap
9646 Most of the keystrokes in the summary buffer can also be used in the
9647 article buffer. They should behave as if you typed them in the summary
9648 buffer, which means that you don't actually have to have a summary
9649 buffer displayed while reading. You can do it all from the article
9652 A few additional keystrokes are available:
9657 @kindex SPACE (Article)
9658 @findex gnus-article-next-page
9659 Scroll forwards one page (@code{gnus-article-next-page}).
9662 @kindex DEL (Article)
9663 @findex gnus-article-prev-page
9664 Scroll backwards one page (@code{gnus-article-prev-page}).
9667 @kindex C-c ^ (Article)
9668 @findex gnus-article-refer-article
9669 If point is in the neighborhood of a @code{Message-ID} and you press
9670 @kbd{C-c ^}, Gnus will try to get that article from the server
9671 (@code{gnus-article-refer-article}).
9674 @kindex C-c C-m (Article)
9675 @findex gnus-article-mail
9676 Send a reply to the address near point (@code{gnus-article-mail}). If
9677 given a prefix, include the mail.
9681 @findex gnus-article-show-summary
9682 Reconfigure the buffers so that the summary buffer becomes visible
9683 (@code{gnus-article-show-summary}).
9687 @findex gnus-article-describe-briefly
9688 Give a very brief description of the available keystrokes
9689 (@code{gnus-article-describe-briefly}).
9692 @kindex TAB (Article)
9693 @findex gnus-article-next-button
9694 Go to the next button, if any (@code{gnus-article-next-button}). This
9695 only makes sense if you have buttonizing turned on.
9698 @kindex M-TAB (Article)
9699 @findex gnus-article-prev-button
9700 Go to the previous button, if any (@code{gnus-article-prev-button}).
9706 @section Misc Article
9710 @item gnus-single-article-buffer
9711 @vindex gnus-single-article-buffer
9712 If non-@code{nil}, use the same article buffer for all the groups.
9713 (This is the default.) If @code{nil}, each group will have its own
9716 @vindex gnus-article-decode-hook
9717 @item gnus-article-decode-hook
9719 Hook used to decode @sc{mime} articles. The default value is
9720 @code{(article-decode-charset article-decode-encoded-words)}
9722 @vindex gnus-article-prepare-hook
9723 @item gnus-article-prepare-hook
9724 This hook is called right after the article has been inserted into the
9725 article buffer. It is mainly intended for functions that do something
9726 depending on the contents; it should probably not be used for changing
9727 the contents of the article buffer.
9729 @item gnus-article-mode-hook
9730 @vindex gnus-article-mode-hook
9731 Hook called in article mode buffers.
9733 @item gnus-article-mode-syntax-table
9734 @vindex gnus-article-mode-syntax-table
9735 Syntax table used in article buffers. It is initialized from
9736 @code{text-mode-syntax-table}.
9738 @vindex gnus-article-mode-line-format
9739 @item gnus-article-mode-line-format
9740 This variable is a format string along the same lines as
9741 @code{gnus-summary-mode-line-format} (@pxref{Mode Line Formatting}). It
9742 accepts the same format specifications as that variable, with two
9747 The @dfn{wash status} of the article. This is a short string with one
9748 character for each possible article wash operation that may have been
9751 The number of @sc{mime} parts in the article.
9754 @vindex gnus-break-pages
9756 @item gnus-break-pages
9757 Controls whether @dfn{page breaking} is to take place. If this variable
9758 is non-@code{nil}, the articles will be divided into pages whenever a
9759 page delimiter appears in the article. If this variable is @code{nil},
9760 paging will not be done.
9762 @item gnus-page-delimiter
9763 @vindex gnus-page-delimiter
9764 This is the delimiter mentioned above. By default, it is @samp{^L}
9769 @node Composing Messages
9770 @chapter Composing Messages
9771 @cindex composing messages
9774 @cindex sending mail
9780 @kindex C-c C-c (Post)
9781 All commands for posting and mailing will put you in a message buffer
9782 where you can edit the article all you like, before you send the
9783 article by pressing @kbd{C-c C-c}. @xref{Top, , Top, message, The
9784 Message Manual}. Where the message will be posted/mailed to depends
9785 on your setup (@pxref{Posting Server}).
9788 * Mail:: Mailing and replying.
9789 * Posting Server:: What server should you post via?
9790 * Mail and Post:: Mailing and posting at the same time.
9791 * Archived Messages:: Where gnus stores the messages you've sent.
9792 * Posting Styles:: An easier way to specify who you are.
9793 * Drafts:: Postponing messages and rejected messages.
9794 * Rejected Articles:: What happens if the server doesn't like your article?
9795 * Using GPG:: How to use GPG and MML to sign and encrypt messages
9798 Also see @pxref{Canceling and Superseding} for information on how to
9799 remove articles you shouldn't have posted.
9805 Variables for customizing outgoing mail:
9808 @item gnus-uu-digest-headers
9809 @vindex gnus-uu-digest-headers
9810 List of regexps to match headers included in digested messages. The
9811 headers will be included in the sequence they are matched.
9813 @item gnus-add-to-list
9814 @vindex gnus-add-to-list
9815 If non-@code{nil}, add a @code{to-list} group parameter to mail groups
9816 that have none when you do a @kbd{a}.
9821 @node Posting Server
9822 @section Posting Server
9824 When you press those magical @kbd{C-c C-c} keys to ship off your latest
9825 (extremely intelligent, of course) article, where does it go?
9827 Thank you for asking. I hate you.
9829 @vindex gnus-post-method
9831 It can be quite complicated. Normally, Gnus will post using the same
9832 select method as you're reading from (which might be convenient if
9833 you're reading lots of groups from different private servers).
9834 However. If the server you're reading from doesn't allow posting,
9835 just reading, you probably want to use some other server to post your
9836 (extremely intelligent and fabulously interesting) articles. You can
9837 then set the @code{gnus-post-method} to some other method:
9840 (setq gnus-post-method '(nnspool ""))
9843 Now, if you've done this, and then this server rejects your article, or
9844 this server is down, what do you do then? To override this variable you
9845 can use a non-zero prefix to the @kbd{C-c C-c} command to force using
9846 the ``current'' server, to get back the default behavior, for posting.
9848 If you give a zero prefix (i.e., @kbd{C-u 0 C-c C-c}) to that command,
9849 gnus will prompt you for what method to use for posting.
9851 You can also set @code{gnus-post-method} to a list of select methods.
9852 If that's the case, gnus will always prompt you for what method to use
9855 Finally, if you want to always post using the native select method,
9856 you can set this variable to @code{nil}.
9860 @section Mail and Post
9862 Here's a list of variables relevant to both mailing and
9866 @item gnus-mailing-list-groups
9867 @findex gnus-mailing-list-groups
9868 @cindex mailing lists
9870 If your news server offers groups that are really mailing lists
9871 gatewayed to the @sc{nntp} server, you can read those groups without
9872 problems, but you can't post/followup to them without some difficulty.
9873 One solution is to add a @code{to-address} to the group parameters
9874 (@pxref{Group Parameters}). An easier thing to do is set the
9875 @code{gnus-mailing-list-groups} to a regexp that matches the groups that
9876 really are mailing lists. Then, at least, followups to the mailing
9877 lists will work most of the time. Posting to these groups (@kbd{a}) is
9878 still a pain, though.
9882 You may want to do spell-checking on messages that you send out. Or, if
9883 you don't want to spell-check by hand, you could add automatic
9884 spell-checking via the @code{ispell} package:
9887 @findex ispell-message
9889 (add-hook 'message-send-hook 'ispell-message)
9892 If you want to change the @code{ispell} dictionary based on what group
9893 you're in, you could say something like the following:
9896 (add-hook 'gnus-select-group-hook
9900 "^de\\." (gnus-group-real-name gnus-newsgroup-name))
9901 (ispell-change-dictionary "deutsch"))
9903 (ispell-change-dictionary "english")))))
9906 Modify to suit your needs.
9909 @node Archived Messages
9910 @section Archived Messages
9911 @cindex archived messages
9912 @cindex sent messages
9914 Gnus provides a few different methods for storing the mail and news you
9915 send. The default method is to use the @dfn{archive virtual server} to
9916 store the messages. If you want to disable this completely, the
9917 @code{gnus-message-archive-group} variable should be @code{nil}, which
9920 @vindex gnus-message-archive-method
9921 @code{gnus-message-archive-method} says what virtual server gnus is to
9922 use to store sent messages. The default is:
9926 (nnfolder-directory "~/Mail/archive")
9927 (nnfolder-active-file "~/Mail/archive/active")
9928 (nnfolder-get-new-mail nil)
9929 (nnfolder-inhibit-expiry t))
9932 You can, however, use any mail select method (@code{nnml},
9933 @code{nnmbox}, etc.). @code{nnfolder} is a quite likable select method
9934 for doing this sort of thing, though. If you don't like the default
9935 directory chosen, you could say something like:
9938 (setq gnus-message-archive-method
9939 '(nnfolder "archive"
9940 (nnfolder-inhibit-expiry t)
9941 (nnfolder-active-file "~/News/sent-mail/active")
9942 (nnfolder-directory "~/News/sent-mail/")))
9945 @vindex gnus-message-archive-group
9947 Gnus will insert @code{Gcc} headers in all outgoing messages that point
9948 to one or more group(s) on that server. Which group to use is
9949 determined by the @code{gnus-message-archive-group} variable.
9951 This variable can be used to do the following:
9955 Messages will be saved in that group.
9957 Note that you can include a select method in the group name, then the
9958 message will not be stored in the select method given by
9959 @code{gnus-message-archive-method}, but in the select method specified
9960 by the group name, instead. Suppose @code{gnus-message-archive-method}
9961 has the default value shown above. Then setting
9962 @code{gnus-message-archive-group} to @code{"foo"} means that outgoing
9963 messages are stored in @samp{nnfolder+archive:foo}, but if you use the
9964 value @code{"nnml:foo"}, then outgoing messages will be stored in
9966 @item a list of strings
9967 Messages will be saved in all those groups.
9968 @item an alist of regexps, functions and forms
9969 When a key ``matches'', the result is used.
9971 No message archiving will take place. This is the default.
9976 Just saving to a single group called @samp{MisK}:
9978 (setq gnus-message-archive-group "MisK")
9981 Saving to two groups, @samp{MisK} and @samp{safe}:
9983 (setq gnus-message-archive-group '("MisK" "safe"))
9986 Save to different groups based on what group you are in:
9988 (setq gnus-message-archive-group
9989 '(("^alt" "sent-to-alt")
9990 ("mail" "sent-to-mail")
9991 (".*" "sent-to-misc")))
9996 (setq gnus-message-archive-group
9997 '((if (message-news-p)
10002 How about storing all news messages in one file, but storing all mail
10003 messages in one file per month:
10006 (setq gnus-message-archive-group
10007 '((if (message-news-p)
10009 (concat "mail." (format-time-string "%Y-%m")))))
10012 (XEmacs 19.13 doesn't have @code{format-time-string}, so you'll have to
10013 use a different value for @code{gnus-message-archive-group} there.)
10015 Now, when you send a message off, it will be stored in the appropriate
10016 group. (If you want to disable storing for just one particular message,
10017 you can just remove the @code{Gcc} header that has been inserted.) The
10018 archive group will appear in the group buffer the next time you start
10019 gnus, or the next time you press @kbd{F} in the group buffer. You can
10020 enter it and read the articles in it just like you'd read any other
10021 group. If the group gets really big and annoying, you can simply rename
10022 if (using @kbd{G r} in the group buffer) to something
10023 nice---@samp{misc-mail-september-1995}, or whatever. New messages will
10024 continue to be stored in the old (now empty) group.
10026 That's the default method of archiving sent messages. Gnus offers a
10027 different way for the people who don't like the default method. In that
10028 case you should set @code{gnus-message-archive-group} to @code{nil};
10029 this will disable archiving.
10032 @item gnus-outgoing-message-group
10033 @vindex gnus-outgoing-message-group
10034 All outgoing messages will be put in this group. If you want to store
10035 all your outgoing mail and articles in the group @samp{nnml:archive},
10036 you set this variable to that value. This variable can also be a list of
10039 If you want to have greater control over what group to put each
10040 message in, you can set this variable to a function that checks the
10041 current newsgroup name and then returns a suitable group name (or list
10044 This variable can be used instead of @code{gnus-message-archive-group},
10045 but the latter is the preferred method.
10047 @item gnus-inews-mark-gcc-as-read
10048 @vindex gnus-inews-mark-gcc-as-read
10049 If non-@code{nil}, automatically mark @code{Gcc} articles as read.
10054 @node Posting Styles
10055 @section Posting Styles
10056 @cindex posting styles
10059 All them variables, they make my head swim.
10061 So what if you want a different @code{Organization} and signature based
10062 on what groups you post to? And you post both from your home machine
10063 and your work machine, and you want different @code{From} lines, and so
10066 @vindex gnus-posting-styles
10067 One way to do stuff like that is to write clever hooks that change the
10068 variables you need to have changed. That's a bit boring, so somebody
10069 came up with the bright idea of letting the user specify these things in
10070 a handy alist. Here's an example of a @code{gnus-posting-styles}
10075 (signature "Peace and happiness")
10076 (organization "What me?"))
10078 (signature "Death to everybody"))
10079 ("comp.emacs.i-love-it"
10080 (organization "Emacs is it")))
10083 As you might surmise from this example, this alist consists of several
10084 @dfn{styles}. Each style will be applicable if the first element
10085 ``matches'', in some form or other. The entire alist will be iterated
10086 over, from the beginning towards the end, and each match will be
10087 applied, which means that attributes in later styles that match override
10088 the same attributes in earlier matching styles. So
10089 @samp{comp.programming.literate} will have the @samp{Death to everybody}
10090 signature and the @samp{What me?} @code{Organization} header.
10092 The first element in each style is called the @code{match}. If it's a
10093 string, then Gnus will try to regexp match it against the group name.
10094 If it is the symbol @code{header}, then Gnus will look for header (the
10095 next element in the match) in the original article , and compare that to
10096 the last regexp in the match. If it's a function symbol, that function
10097 will be called with no arguments. If it's a variable symbol, then the
10098 variable will be referenced. If it's a list, then that list will be
10099 @code{eval}ed. In any case, if this returns a non-@code{nil} value,
10100 then the style is said to @dfn{match}.
10102 Each style may contain a arbitrary amount of @dfn{attributes}. Each
10103 attribute consists of a @code{(@var{name} @var{value})} pair. The
10104 attribute name can be one of @code{signature}, @code{signature-file},
10105 @code{organization}, @code{address}, @code{name} or @code{body}. The
10106 attribute name can also be a string. In that case, this will be used as
10107 a header name, and the value will be inserted in the headers of the
10108 article; if the value is @code{nil}, the header name will be removed.
10109 If the attribute name is @code{eval}, the form is evaluated, and the
10110 result is thrown away.
10112 The attribute value can be a string (used verbatim), a function with
10113 zero arguments (the return value will be used), a variable (its value
10114 will be used) or a list (it will be @code{eval}ed and the return value
10115 will be used). The functions and sexps are called/@code{eval}ed in the
10116 message buffer that is being set up. The headers of the current article
10117 are available through the @code{message-reply-headers} variable.
10119 If you wish to check whether the message you are about to compose is
10120 meant to be a news article or a mail message, you can check the values
10121 of the @code{message-news-p} and @code{message-mail-p} functions.
10123 @findex message-mail-p
10124 @findex message-news-p
10126 So here's a new example:
10129 (setq gnus-posting-styles
10131 (signature-file "~/.signature")
10133 ("X-Home-Page" (getenv "WWW_HOME"))
10134 (organization "People's Front Against MWM"))
10136 (signature my-funny-signature-randomizer))
10137 ((equal (system-name) "gnarly")
10138 (signature my-quote-randomizer))
10140 (signature my-news-signature))
10141 (header "to" "larsi.*org"
10142 (Organization "Somewhere, Inc."))
10143 ((posting-from-work-p)
10144 (signature-file "~/.work-signature")
10145 (address "user@@bar.foo")
10146 (body "You are fired.\n\nSincerely, your boss.")
10147 (organization "Important Work, Inc"))
10149 (From (save-excursion
10150 (set-buffer gnus-article-buffer)
10151 (message-fetch-field "to"))))
10153 (signature-file "~/.mail-signature"))))
10156 The @samp{nnml:.*} rule means that you use the @code{To} address as the
10157 @code{From} address in all your outgoing replies, which might be handy
10158 if you fill many roles.
10165 If you are writing a message (mail or news) and suddenly remember that
10166 you have a steak in the oven (or some pesto in the food processor, you
10167 craaazy vegetarians), you'll probably wish there was a method to save
10168 the message you are writing so that you can continue editing it some
10169 other day, and send it when you feel its finished.
10171 Well, don't worry about it. Whenever you start composing a message of
10172 some sort using the gnus mail and post commands, the buffer you get will
10173 automatically associate to an article in a special @dfn{draft} group.
10174 If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
10175 article will be saved there. (Auto-save files also go to the draft
10179 @vindex nndraft-directory
10180 The draft group is a special group (which is implemented as an
10181 @code{nndraft} group, if you absolutely have to know) called
10182 @samp{nndraft:drafts}. The variable @code{nndraft-directory} says where
10183 @code{nndraft} is to store its files. What makes this group special is
10184 that you can't tick any articles in it or mark any articles as
10185 read---all articles in the group are permanently unread.
10187 If the group doesn't exist, it will be created and you'll be subscribed
10188 to it. The only way to make it disappear from the Group buffer is to
10191 @c @findex gnus-dissociate-buffer-from-draft
10192 @c @kindex C-c M-d (Mail)
10193 @c @kindex C-c M-d (Post)
10194 @c @findex gnus-associate-buffer-with-draft
10195 @c @kindex C-c C-d (Mail)
10196 @c @kindex C-c C-d (Post)
10197 @c If you're writing some super-secret message that you later want to
10198 @c encode with PGP before sending, you may wish to turn the auto-saving
10199 @c (and association with the draft group) off. You never know who might be
10200 @c interested in reading all your extremely valuable and terribly horrible
10201 @c and interesting secrets. The @kbd{C-c M-d}
10202 @c (@code{gnus-dissociate-buffer-from-draft}) command does that for you.
10203 @c If you change your mind and want to turn the auto-saving back on again,
10204 @c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that.
10206 @c @vindex gnus-use-draft
10207 @c To leave association with the draft group off by default, set
10208 @c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default.
10210 @findex gnus-draft-edit-message
10211 @kindex D e (Draft)
10212 When you want to continue editing the article, you simply enter the
10213 draft group and push @kbd{D e} (@code{gnus-draft-edit-message}) to do
10214 that. You will be placed in a buffer where you left off.
10216 Rejected articles will also be put in this draft group (@pxref{Rejected
10219 @findex gnus-draft-send-all-messages
10220 @findex gnus-draft-send-message
10221 If you have lots of rejected messages you want to post (or mail) without
10222 doing further editing, you can use the @kbd{D s} command
10223 (@code{gnus-draft-send-message}). This command understands the
10224 process/prefix convention (@pxref{Process/Prefix}). The @kbd{D S}
10225 command (@code{gnus-draft-send-all-messages}) will ship off all messages
10228 If you have some messages that you wish not to send, you can use the
10229 @kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message
10230 as unsendable. This is a toggling command.
10233 @node Rejected Articles
10234 @section Rejected Articles
10235 @cindex rejected articles
10237 Sometimes a news server will reject an article. Perhaps the server
10238 doesn't like your face. Perhaps it just feels miserable. Perhaps
10239 @emph{there be demons}. Perhaps you have included too much cited text.
10240 Perhaps the disk is full. Perhaps the server is down.
10242 These situations are, of course, totally beyond the control of gnus.
10243 (Gnus, of course, loves the way you look, always feels great, has angels
10244 fluttering around inside of it, doesn't care about how much cited text
10245 you include, never runs full and never goes down.) So gnus saves these
10246 articles until some later time when the server feels better.
10248 The rejected articles will automatically be put in a special draft group
10249 (@pxref{Drafts}). When the server comes back up again, you'd then
10250 typically enter that group and send all the articles off.
10256 Gnus has an ALPHA support to GPG that's provided by @file{gpg.el}. See
10257 @code{mm-verify-option} and @code{mm-decrypt-option} to enable Gnus to
10258 verify or decrypt messages accordingly.
10260 To use this correctly with GPG, you'll need the following lisp code in your
10261 @file{~/.emacs} or @file{~/.gnus}:
10265 (setq mml2015-use 'gpg)
10266 (setq gpg-temp-directory (expand-file-name "~/.gnupg/tmp"))
10269 The @code{gpg-temp-directory} need to point to a directory with permissions set
10270 to 700, for your own safety.
10272 If you want to benefit of PGP2.6 compatibility, you might create a script named
10273 @file{gpg-2comp} with these instructions:
10277 exec gpg --rfc1991 "$@@"
10280 If you don't want to use such compatibility, you can add the following line to
10281 your @file{~/.emacs} or @file{~/.gnus}:
10284 (setq gpg-command-default-alist (quote ((gpg . "gpg") (gpg-2comp . "gpg"))))
10287 To sign or encrypt your message you may choose to use the MML Security
10288 menu or @kbd{C-c C-m s p} to sign your message using PGP/MIME, @kbd{C-c
10289 C-m s s} to sign your message using S/MIME. There's also @kbd{C-c C-m c
10290 p} to encrypt your message with PGP/MIME and @kbd{C-c C-m c s} to
10291 encrypt using S/MIME.
10293 Gnus will ask for your passphrase and then it will send your message, if
10294 you've typed it correctly.
10296 @node Select Methods
10297 @chapter Select Methods
10298 @cindex foreign groups
10299 @cindex select methods
10301 A @dfn{foreign group} is a group not read by the usual (or
10302 default) means. It could be, for instance, a group from a different
10303 @sc{nntp} server, it could be a virtual group, or it could be your own
10304 personal mail group.
10306 A foreign group (or any group, really) is specified by a @dfn{name} and
10307 a @dfn{select method}. To take the latter first, a select method is a
10308 list where the first element says what backend to use (e.g. @code{nntp},
10309 @code{nnspool}, @code{nnml}) and the second element is the @dfn{server
10310 name}. There may be additional elements in the select method, where the
10311 value may have special meaning for the backend in question.
10313 One could say that a select method defines a @dfn{virtual server}---so
10314 we do just that (@pxref{Server Buffer}).
10316 The @dfn{name} of the group is the name the backend will recognize the
10319 For instance, the group @samp{soc.motss} on the @sc{nntp} server
10320 @samp{some.where.edu} will have the name @samp{soc.motss} and select
10321 method @code{(nntp "some.where.edu")}. Gnus will call this group
10322 @samp{nntp+some.where.edu:soc.motss}, even though the @code{nntp}
10323 backend just knows this group as @samp{soc.motss}.
10325 The different methods all have their peculiarities, of course.
10328 * Server Buffer:: Making and editing virtual servers.
10329 * Getting News:: Reading USENET news with Gnus.
10330 * Getting Mail:: Reading your personal mail with Gnus.
10331 * Browsing the Web:: Getting messages from a plethora of Web sources.
10332 * Other Sources:: Reading directories, files, SOUP packets.
10333 * Combined Groups:: Combining groups into one group.
10334 * Gnus Unplugged:: Reading news and mail offline.
10338 @node Server Buffer
10339 @section Server Buffer
10341 Traditionally, a @dfn{server} is a machine or a piece of software that
10342 one connects to, and then requests information from. Gnus does not
10343 connect directly to any real servers, but does all transactions through
10344 one backend or other. But that's just putting one layer more between
10345 the actual media and Gnus, so we might just as well say that each
10346 backend represents a virtual server.
10348 For instance, the @code{nntp} backend may be used to connect to several
10349 different actual @sc{nntp} servers, or, perhaps, to many different ports
10350 on the same actual @sc{nntp} server. You tell Gnus which backend to
10351 use, and what parameters to set by specifying a @dfn{select method}.
10353 These select method specifications can sometimes become quite
10354 complicated---say, for instance, that you want to read from the
10355 @sc{nntp} server @samp{news.funet.fi} on port number 13, which
10356 hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
10357 Anyway, if you had to specify that for each group that used this
10358 server, that would be too much work, so Gnus offers a way of naming
10359 select methods, which is what you do in the server buffer.
10361 To enter the server buffer, use the @kbd{^}
10362 (@code{gnus-group-enter-server-mode}) command in the group buffer.
10365 * Server Buffer Format:: You can customize the look of this buffer.
10366 * Server Commands:: Commands to manipulate servers.
10367 * Example Methods:: Examples server specifications.
10368 * Creating a Virtual Server:: An example session.
10369 * Server Variables:: Which variables to set.
10370 * Servers and Methods:: You can use server names as select methods.
10371 * Unavailable Servers:: Some servers you try to contact may be down.
10374 @vindex gnus-server-mode-hook
10375 @code{gnus-server-mode-hook} is run when creating the server buffer.
10378 @node Server Buffer Format
10379 @subsection Server Buffer Format
10380 @cindex server buffer format
10382 @vindex gnus-server-line-format
10383 You can change the look of the server buffer lines by changing the
10384 @code{gnus-server-line-format} variable. This is a @code{format}-like
10385 variable, with some simple extensions:
10390 How the news is fetched---the backend name.
10393 The name of this server.
10396 Where the news is to be fetched from---the address.
10399 The opened/closed/denied status of the server.
10402 @vindex gnus-server-mode-line-format
10403 The mode line can also be customized by using the
10404 @code{gnus-server-mode-line-format} variable (@pxref{Mode Line
10405 Formatting}). The following specs are understood:
10415 Also @pxref{Formatting Variables}.
10418 @node Server Commands
10419 @subsection Server Commands
10420 @cindex server commands
10426 @findex gnus-server-add-server
10427 Add a new server (@code{gnus-server-add-server}).
10431 @findex gnus-server-edit-server
10432 Edit a server (@code{gnus-server-edit-server}).
10435 @kindex SPACE (Server)
10436 @findex gnus-server-read-server
10437 Browse the current server (@code{gnus-server-read-server}).
10441 @findex gnus-server-exit
10442 Return to the group buffer (@code{gnus-server-exit}).
10446 @findex gnus-server-kill-server
10447 Kill the current server (@code{gnus-server-kill-server}).
10451 @findex gnus-server-yank-server
10452 Yank the previously killed server (@code{gnus-server-yank-server}).
10456 @findex gnus-server-copy-server
10457 Copy the current server (@code{gnus-server-copy-server}).
10461 @findex gnus-server-list-servers
10462 List all servers (@code{gnus-server-list-servers}).
10466 @findex gnus-server-scan-server
10467 Request that the server scan its sources for new articles
10468 (@code{gnus-server-scan-server}). This is mainly sensible with mail
10473 @findex gnus-server-regenerate-server
10474 Request that the server regenerate all its data structures
10475 (@code{gnus-server-regenerate-server}). This can be useful if you have
10476 a mail backend that has gotten out of sync.
10481 @node Example Methods
10482 @subsection Example Methods
10484 Most select methods are pretty simple and self-explanatory:
10487 (nntp "news.funet.fi")
10490 Reading directly from the spool is even simpler:
10496 As you can see, the first element in a select method is the name of the
10497 backend, and the second is the @dfn{address}, or @dfn{name}, if you
10500 After these two elements, there may be an arbitrary number of
10501 @code{(@var{variable} @var{form})} pairs.
10503 To go back to the first example---imagine that you want to read from
10504 port 15 on that machine. This is what the select method should
10508 (nntp "news.funet.fi" (nntp-port-number 15))
10511 You should read the documentation to each backend to find out what
10512 variables are relevant, but here's an @code{nnmh} example:
10514 @code{nnmh} is a mail backend that reads a spool-like structure. Say
10515 you have two structures that you wish to access: One is your private
10516 mail spool, and the other is a public one. Here's the possible spec for
10520 (nnmh "private" (nnmh-directory "~/private/mail/"))
10523 (This server is then called @samp{private}, but you may have guessed
10526 Here's the method for a public spool:
10530 (nnmh-directory "/usr/information/spool/")
10531 (nnmh-get-new-mail nil))
10537 If you are behind a firewall and only have access to the @sc{nntp}
10538 server from the firewall machine, you can instruct Gnus to @code{rlogin}
10539 on the firewall machine and telnet from there to the @sc{nntp} server.
10540 Doing this can be rather fiddly, but your virtual server definition
10541 should probably look something like this:
10545 (nntp-open-connection-function nntp-open-via-rlogin-and-telnet)
10546 (nntp-via-address "the.firewall.machine")
10547 (nntp-address "the.real.nntp.host")
10548 (nntp-end-of-line "\n"))
10551 If you want to use the wonderful @code{ssh} program to provide a
10552 compressed connection over the modem line, you could add the following
10553 configuration to the example above:
10556 (nntp-via-rlogin-command "ssh")
10559 If you're behind a firewall, but have direct access to the outside world
10560 through a wrapper command like "runsocks", you could open a socksified
10561 telnet connection to the news server as follows:
10565 (nntp-pre-command "runsocks")
10566 (nntp-open-connection-function nntp-open-via-telnet)
10567 (nntp-address "the.news.server")
10568 (nntp-end-of-line "\n"))
10571 This means that you have to have set up @code{ssh-agent} correctly to
10572 provide automatic authorization, of course. And to get a compressed
10573 connection, you have to have the @samp{Compression} option in the
10574 @code{ssh} @file{config} file.
10577 @node Creating a Virtual Server
10578 @subsection Creating a Virtual Server
10580 If you're saving lots of articles in the cache by using persistent
10581 articles, you may want to create a virtual server to read the cache.
10583 First you need to add a new server. The @kbd{a} command does that. It
10584 would probably be best to use @code{nnspool} to read the cache. You
10585 could also use @code{nnml} or @code{nnmh}, though.
10587 Type @kbd{a nnspool RET cache RET}.
10589 You should now have a brand new @code{nnspool} virtual server called
10590 @samp{cache}. You now need to edit it to have the right definitions.
10591 Type @kbd{e} to edit the server. You'll be entered into a buffer that
10592 will contain the following:
10602 (nnspool-spool-directory "~/News/cache/")
10603 (nnspool-nov-directory "~/News/cache/")
10604 (nnspool-active-file "~/News/cache/active"))
10607 Type @kbd{C-c C-c} to return to the server buffer. If you now press
10608 @kbd{RET} over this virtual server, you should be entered into a browse
10609 buffer, and you should be able to enter any of the groups displayed.
10612 @node Server Variables
10613 @subsection Server Variables
10615 One sticky point when defining variables (both on backends and in Emacs
10616 in general) is that some variables are typically initialized from other
10617 variables when the definition of the variables is being loaded. If you
10618 change the "base" variable after the variables have been loaded, you
10619 won't change the "derived" variables.
10621 This typically affects directory and file variables. For instance,
10622 @code{nnml-directory} is @file{~/Mail/} by default, and all @code{nnml}
10623 directory variables are initialized from that variable, so
10624 @code{nnml-active-file} will be @file{~/Mail/active}. If you define a
10625 new virtual @code{nnml} server, it will @emph{not} suffice to set just
10626 @code{nnml-directory}---you have to explicitly set all the file
10627 variables to be what you want them to be. For a complete list of
10628 variables for each backend, see each backend's section later in this
10629 manual, but here's an example @code{nnml} definition:
10633 (nnml-directory "~/my-mail/")
10634 (nnml-active-file "~/my-mail/active")
10635 (nnml-newsgroups-file "~/my-mail/newsgroups"))
10639 @node Servers and Methods
10640 @subsection Servers and Methods
10642 Wherever you would normally use a select method
10643 (e.g. @code{gnus-secondary-select-method}, in the group select method,
10644 when browsing a foreign server) you can use a virtual server name
10645 instead. This could potentially save lots of typing. And it's nice all
10649 @node Unavailable Servers
10650 @subsection Unavailable Servers
10652 If a server seems to be unreachable, Gnus will mark that server as
10653 @code{denied}. That means that any subsequent attempt to make contact
10654 with that server will just be ignored. ``It can't be opened,'' Gnus
10655 will tell you, without making the least effort to see whether that is
10656 actually the case or not.
10658 That might seem quite naughty, but it does make sense most of the time.
10659 Let's say you have 10 groups subscribed to on server
10660 @samp{nephelococcygia.com}. This server is located somewhere quite far
10661 away from you and the machine is quite slow, so it takes 1 minute just
10662 to find out that it refuses connection to you today. If Gnus were to
10663 attempt to do that 10 times, you'd be quite annoyed, so Gnus won't
10664 attempt to do that. Once it has gotten a single ``connection refused'',
10665 it will regard that server as ``down''.
10667 So, what happens if the machine was only feeling unwell temporarily?
10668 How do you test to see whether the machine has come up again?
10670 You jump to the server buffer (@pxref{Server Buffer}) and poke it
10671 with the following commands:
10677 @findex gnus-server-open-server
10678 Try to establish connection to the server on the current line
10679 (@code{gnus-server-open-server}).
10683 @findex gnus-server-close-server
10684 Close the connection (if any) to the server
10685 (@code{gnus-server-close-server}).
10689 @findex gnus-server-deny-server
10690 Mark the current server as unreachable
10691 (@code{gnus-server-deny-server}).
10694 @kindex M-o (Server)
10695 @findex gnus-server-open-all-servers
10696 Open the connections to all servers in the buffer
10697 (@code{gnus-server-open-all-servers}).
10700 @kindex M-c (Server)
10701 @findex gnus-server-close-all-servers
10702 Close the connections to all servers in the buffer
10703 (@code{gnus-server-close-all-servers}).
10707 @findex gnus-server-remove-denials
10708 Remove all marks to whether Gnus was denied connection from any servers
10709 (@code{gnus-server-remove-denials}).
10715 @section Getting News
10716 @cindex reading news
10717 @cindex news backends
10719 A newsreader is normally used for reading news. Gnus currently provides
10720 only two methods of getting news---it can read from an @sc{nntp} server,
10721 or it can read from a local spool.
10724 * NNTP:: Reading news from an @sc{nntp} server.
10725 * News Spool:: Reading news from the local spool.
10730 @subsection @sc{nntp}
10733 Subscribing to a foreign group from an @sc{nntp} server is rather easy.
10734 You just specify @code{nntp} as method and the address of the @sc{nntp}
10735 server as the, uhm, address.
10737 If the @sc{nntp} server is located at a non-standard port, setting the
10738 third element of the select method to this port number should allow you
10739 to connect to the right port. You'll have to edit the group info for
10740 that (@pxref{Foreign Groups}).
10742 The name of the foreign group can be the same as a native group. In
10743 fact, you can subscribe to the same group from as many different servers
10744 you feel like. There will be no name collisions.
10746 The following variables can be used to create a virtual @code{nntp}
10751 @item nntp-server-opened-hook
10752 @vindex nntp-server-opened-hook
10753 @cindex @sc{mode reader}
10755 @cindex authentification
10756 @cindex nntp authentification
10757 @findex nntp-send-authinfo
10758 @findex nntp-send-mode-reader
10759 is run after a connection has been made. It can be used to send
10760 commands to the @sc{nntp} server after it has been contacted. By
10761 default it sends the command @code{MODE READER} to the server with the
10762 @code{nntp-send-mode-reader} function. This function should always be
10763 present in this hook.
10765 @item nntp-authinfo-function
10766 @vindex nntp-authinfo-function
10767 @findex nntp-send-authinfo
10768 @vindex nntp-authinfo-file
10769 This function will be used to send @samp{AUTHINFO} to the @sc{nntp}
10770 server. The default function is @code{nntp-send-authinfo}, which looks
10771 through your @file{~/.authinfo} (or whatever you've set the
10772 @code{nntp-authinfo-file} variable to) for applicable entries. If none
10773 are found, it will prompt you for a login name and a password. The
10774 format of the @file{~/.authinfo} file is (almost) the same as the
10775 @code{ftp} @file{~/.netrc} file, which is defined in the @code{ftp}
10776 manual page, but here are the salient facts:
10780 The file contains one or more line, each of which define one server.
10783 Each line may contain an arbitrary number of token/value pairs.
10785 The valid tokens include @samp{machine}, @samp{login}, @samp{password},
10786 @samp{default}. In addition Gnus introduces two new tokens, not present
10787 in the original @file{.netrc}/@code{ftp} syntax, namely @samp{port} and
10788 @samp{force}. (This is the only way the @file{.authinfo} file format
10789 deviates from the @file{.netrc} file format.) @samp{port} is used to
10790 indicate what port on the server the credentials apply to and
10791 @samp{force} is explained below.
10795 Here's an example file:
10798 machine news.uio.no login larsi password geheimnis
10799 machine nntp.ifi.uio.no login larsi force yes
10802 The token/value pairs may appear in any order; @samp{machine} doesn't
10803 have to be first, for instance.
10805 In this example, both login name and password have been supplied for the
10806 former server, while the latter has only the login name listed, and the
10807 user will be prompted for the password. The latter also has the
10808 @samp{force} tag, which means that the authinfo will be sent to the
10809 @var{nntp} server upon connection; the default (i.e., when there is not
10810 @samp{force} tag) is to not send authinfo to the @var{nntp} server
10811 until the @var{nntp} server asks for it.
10813 You can also add @samp{default} lines that will apply to all servers
10814 that don't have matching @samp{machine} lines.
10820 This will force sending @samp{AUTHINFO} commands to all servers not
10821 previously mentioned.
10823 Remember to not leave the @file{~/.authinfo} file world-readable.
10825 @item nntp-server-action-alist
10826 @vindex nntp-server-action-alist
10827 This is a list of regexps to match on server types and actions to be
10828 taken when matches are made. For instance, if you want Gnus to beep
10829 every time you connect to innd, you could say something like:
10832 (setq nntp-server-action-alist
10833 '(("innd" (ding))))
10836 You probably don't want to do that, though.
10838 The default value is
10841 '(("nntpd 1\\.5\\.11t"
10842 (remove-hook 'nntp-server-opened-hook
10843 'nntp-send-mode-reader)))
10846 This ensures that Gnus doesn't send the @code{MODE READER} command to
10847 nntpd 1.5.11t, since that command chokes that server, I've been told.
10849 @item nntp-maximum-request
10850 @vindex nntp-maximum-request
10851 If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
10852 will collect headers by sending a series of @code{head} commands. To
10853 speed things up, the backend sends lots of these commands without
10854 waiting for reply, and then reads all the replies. This is controlled
10855 by the @code{nntp-maximum-request} variable, and is 400 by default. If
10856 your network is buggy, you should set this to 1.
10858 @item nntp-connection-timeout
10859 @vindex nntp-connection-timeout
10860 If you have lots of foreign @code{nntp} groups that you connect to
10861 regularly, you're sure to have problems with @sc{nntp} servers not
10862 responding properly, or being too loaded to reply within reasonable
10863 time. This is can lead to awkward problems, which can be helped
10864 somewhat by setting @code{nntp-connection-timeout}. This is an integer
10865 that says how many seconds the @code{nntp} backend should wait for a
10866 connection before giving up. If it is @code{nil}, which is the default,
10867 no timeouts are done.
10869 @c @item nntp-command-timeout
10870 @c @vindex nntp-command-timeout
10871 @c @cindex PPP connections
10872 @c @cindex dynamic IP addresses
10873 @c If you're running Gnus on a machine that has a dynamically assigned
10874 @c address, Gnus may become confused. If the address of your machine
10875 @c changes after connecting to the @sc{nntp} server, Gnus will simply sit
10876 @c waiting forever for replies from the server. To help with this
10877 @c unfortunate problem, you can set this command to a number. Gnus will
10878 @c then, if it sits waiting for a reply from the server longer than that
10879 @c number of seconds, shut down the connection, start a new one, and resend
10880 @c the command. This should hopefully be transparent to the user. A
10881 @c likely number is 30 seconds.
10883 @c @item nntp-retry-on-break
10884 @c @vindex nntp-retry-on-break
10885 @c If this variable is non-@code{nil}, you can also @kbd{C-g} if Gnus
10886 @c hangs. This will have much the same effect as the command timeout
10887 @c described above.
10889 @item nntp-server-hook
10890 @vindex nntp-server-hook
10891 This hook is run as the last step when connecting to an @sc{nntp}
10894 @item nntp-buggy-select
10895 @vindex nntp-buggy-select
10896 Set this to non-@code{nil} if your select routine is buggy.
10898 @item nntp-nov-is-evil
10899 @vindex nntp-nov-is-evil
10900 If the @sc{nntp} server does not support @sc{nov}, you could set this
10901 variable to @code{t}, but @code{nntp} usually checks automatically whether @sc{nov}
10904 @item nntp-xover-commands
10905 @vindex nntp-xover-commands
10908 List of strings used as commands to fetch @sc{nov} lines from a
10909 server. The default value of this variable is @code{("XOVER"
10913 @vindex nntp-nov-gap
10914 @code{nntp} normally sends just one big request for @sc{nov} lines to
10915 the server. The server responds with one huge list of lines. However,
10916 if you have read articles 2-5000 in the group, and only want to read
10917 article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
10918 lines that you will not need. This variable says how
10919 big a gap between two consecutive articles is allowed to be before the
10920 @code{XOVER} request is split into several request. Note that if your
10921 network is fast, setting this variable to a really small number means
10922 that fetching will probably be slower. If this variable is @code{nil},
10923 @code{nntp} will never split requests. The default is 5.
10925 @item nntp-prepare-server-hook
10926 @vindex nntp-prepare-server-hook
10927 A hook run before attempting to connect to an @sc{nntp} server.
10929 @item nntp-warn-about-losing-connection
10930 @vindex nntp-warn-about-losing-connection
10931 If this variable is non-@code{nil}, some noise will be made when a
10932 server closes connection.
10934 @item nntp-record-commands
10935 @vindex nntp-record-commands
10936 If non-@code{nil}, @code{nntp} will log all commands it sends to the
10937 @sc{nntp} server (along with a timestamp) in the @samp{*nntp-log*}
10938 buffer. This is useful if you are debugging a Gnus/@sc{nntp} connection
10939 that doesn't seem to work.
10941 @item nntp-open-connection-function
10942 @vindex nntp-open-connection-function
10943 It is possible to customize how the connection to the nntp server will
10944 be opened. If you specify an @code{nntp-open-connection-function}
10945 parameter, Gnus will use that function to establish the connection.
10946 Five pre-made functions are supplied. These functions can be grouped in
10947 two categories: direct connection functions (three pre-made), and
10948 indirect ones (two pre-made).
10950 @item nntp-list-options
10951 @vindex nntp-list-options
10952 List of newsgroup name used for a option of the LIST command to restrict
10953 the listing output to only the specified newsgroups. Each newsgroup name
10954 can be a shell-style wildcard, for instance, @dfn{fj.*}, @dfn{japan.*},
10955 etc. Fortunately, if the server can accept such a option, it will
10956 probably make gnus run faster. You may use it as a server variable as
10960 (setq gnus-select-method
10961 '(nntp "news.somewhere.edu"
10962 (nntp-list-options ("fj.*" "japan.*"))))
10965 @item nntp-options-subscribe
10966 @vindex nntp-options-subscribe
10967 Regexp matching the newsgroup names which will be subscribed
10968 unconditionally. Use @dfn{ } instead of @dfn{$} for a regexp string.
10969 It may be effective as well as @code{nntp-list-options} even though the
10970 server could not accept a shell-style wildcard as a option of the LIST
10971 command. You may use it as a server variable as follows:
10974 (setq gnus-select-method
10975 '(nntp "news.somewhere.edu"
10976 (nntp-options-subscribe "^fj\\.\\|^japan\\.")))
10979 @item nntp-options-not-subscribe
10980 @vindex nntp-options-not-subscribe
10981 Regexp matching the newsgroup names which will not be subscribed
10982 unconditionally. Use @dfn{ } instead of @dfn{$} for a regexp string.
10983 It may be effective as well as @code{nntp-list-options} even though the
10984 server could not accept a shell-style wildcard as a option of the LIST
10985 command. You may use it as a server variable as follows:
10988 (setq gnus-select-method
10989 '(nntp "news.somewhere.edu"
10990 (nntp-options-not-subscribe "\\.binaries\\.")))
10995 * Direct Functions:: Connecting directly to the server.
10996 * Indirect Functions:: Connecting indirectly to the server.
10997 * Common Variables:: Understood by several connection functions.
11001 @node Direct Functions
11002 @subsubsection Direct Functions
11003 @cindex direct connection functions
11005 These functions are called direct because they open a direct connection
11006 between your machine and the @sc{nntp} server. The behavior of these
11007 functions is also affected by commonly understood variables
11008 (@pxref{Common Variables}).
11011 @findex nntp-open-network-stream
11012 @item nntp-open-network-stream
11013 This is the default, and simply connects to some port or other on the
11016 @findex nntp-open-ssl-stream
11017 @item nntp-open-ssl-stream
11018 Opens a connection to a server over a @dfn{secure} channel. To use this
11019 you must have SSLay installed
11020 (@uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL}, and you also need
11021 @file{ssl.el} (from the W3 distribution, for instance). You then
11022 define a server as follows:
11025 ;; Type `C-c C-c' after you've finished editing.
11027 ;; "snews" is port 563 and is predefined in our /etc/services
11029 (nntp "snews.bar.com"
11030 (nntp-open-connection-function nntp-open-ssl-stream)
11031 (nntp-port-number "snews")
11032 (nntp-address "snews.bar.com"))
11035 @findex nntp-open-telnet-stream
11036 @item nntp-open-telnet-stream
11037 Opens a connection to an @sc{nntp} server by simply @samp{telnet}'ing
11038 it. You might wonder why this function exists, since we have the
11039 default @code{nntp-open-network-stream} which would do the job. (One
11040 of) the reason(s) is that if you are behind a firewall but have direct
11041 connections to the outside world thanks to a command wrapper like
11042 @code{runsocks}, you can use it like this:
11046 (nntp-pre-command "runsocks")
11047 (nntp-open-connection-function nntp-open-telnet-stream)
11048 (nntp-address "the.news.server"))
11051 With the default method, you would need to wrap your whole Emacs
11052 session, which is not a good idea.
11056 @node Indirect Functions
11057 @subsubsection Indirect Functions
11058 @cindex indirect connection functions
11060 These functions are called indirect because they connect to an
11061 intermediate host before actually connecting to the @sc{nntp} server.
11062 All of these functions and related variables are also said to belong to
11063 the "via" family of connection: they're all prefixed with "via" to make
11064 things cleaner. The behavior of these functions is also affected by
11065 commonly understood variables (@pxref{Common Variables}).
11068 @item nntp-open-via-rlogin-and-telnet
11069 @findex nntp-open-via-rlogin-and-telnet
11070 Does an @samp{rlogin} on a remote system, and then does a @samp{telnet}
11071 to the real @sc{nntp} server from there. This is useful for instance if
11072 you need to connect to a firewall machine first.
11074 @code{nntp-open-via-rlogin-and-telnet}-specific variables:
11077 @item nntp-via-rlogin-command
11078 @vindex nntp-via-rlogin-command
11079 Command used to log in on the intermediate host. The default is
11080 @samp{rsh}, but @samp{ssh} is a popular alternative.
11083 @item nntp-open-via-telnet-and-telnet
11084 @findex nntp-open-via-telnet-and-telnet
11085 Does essentially the same, but uses @samp{telnet} instead of
11086 @samp{rlogin} to connect to the intermediate host.
11088 @code{nntp-open-via-telnet-and-telnet}-specific variables:
11091 @item nntp-via-telnet-command
11092 @vindex nntp-via-telnet-command
11093 Command used to @code{telnet} the intermediate host. The default is
11096 @item nntp-via-telnet-switches
11097 @vindex nntp-via-telnet-switches
11098 List of strings to be used as the switches to the
11099 @code{nntp-via-telnet-command} command. The default is @samp{("-8")}.
11101 @item nntp-via-user-password
11102 @vindex nntp-via-user-password
11103 Password to use when logging in on the intermediate host.
11105 @item nntp-via-envuser
11106 @vindex nntp-via-envuser
11107 If non-@code{nil}, the intermediate @code{telnet} session (client and
11108 server both) will support the @code{ENVIRON} option and not prompt for
11109 login name. This works for Solaris @code{telnet}, for instance.
11111 @item nntp-via-shell-prompt
11112 @vindex nntp-via-shell-prompt
11113 Regexp matching the shell prompt on the intermediate host. The default
11114 is @samp{bash\\|\$ *\r?$\\|> *\r?}.
11121 Here are some additional variables that are understood by all the above
11126 @item nntp-via-user-name
11127 @vindex nntp-via-user-name
11128 User name to use when connecting to the intermediate host.
11130 @item nntp-via-address
11131 @vindex nntp-via-address
11132 Address of the intermediate host to connect to.
11137 @node Common Variables
11138 @subsubsection Common Variables
11140 The following variables affect the behavior of all, or several of the
11141 pre-made connection functions. When not specified, all functions are
11146 @item nntp-pre-command
11147 @vindex nntp-pre-command
11148 A command wrapper to use when connecting through a non native connection
11149 function (all except @code{nntp-open-network-stream} and
11150 @code{nntp-open-ssl-stream}. This is where you would put a @samp{SOCKS}
11151 wrapper for instance.
11154 @vindex nntp-address
11155 The address of the @sc{nntp} server.
11157 @item nntp-port-number
11158 @vindex nntp-port-number
11159 Port number to connect to the @sc{nntp} server. The default is @samp{nntp}.
11161 @item nntp-end-of-line
11162 @vindex nntp-end-of-line
11163 String to use as end-of-line marker when talking to the @sc{nntp}
11164 server. This is @samp{\r\n} by default, but should be @samp{\n} when
11165 using a non native connection function.
11167 @item nntp-telnet-command
11168 @vindex nntp-telnet-command
11169 Command to use when connecting to the @sc{nntp} server through
11170 @samp{telnet}. This is NOT for an intermediate host. This is just for
11171 the real @sc{nntp} server. The default is @samp{telnet}.
11173 @item nntp-telnet-switches
11174 @vindex nntp-telnet-switches
11175 A list of switches to pass to @code{nntp-telnet-command}. The default
11182 @subsection News Spool
11186 Subscribing to a foreign group from the local spool is extremely easy,
11187 and might be useful, for instance, to speed up reading groups that
11188 contain very big articles---@samp{alt.binaries.pictures.furniture}, for
11191 Anyway, you just specify @code{nnspool} as the method and @code{""} (or
11192 anything else) as the address.
11194 If you have access to a local spool, you should probably use that as the
11195 native select method (@pxref{Finding the News}). It is normally faster
11196 than using an @code{nntp} select method, but might not be. It depends.
11197 You just have to try to find out what's best at your site.
11201 @item nnspool-inews-program
11202 @vindex nnspool-inews-program
11203 Program used to post an article.
11205 @item nnspool-inews-switches
11206 @vindex nnspool-inews-switches
11207 Parameters given to the inews program when posting an article.
11209 @item nnspool-spool-directory
11210 @vindex nnspool-spool-directory
11211 Where @code{nnspool} looks for the articles. This is normally
11212 @file{/usr/spool/news/}.
11214 @item nnspool-nov-directory
11215 @vindex nnspool-nov-directory
11216 Where @code{nnspool} will look for @sc{nov} files. This is normally
11217 @file{/usr/spool/news/over.view/}.
11219 @item nnspool-lib-dir
11220 @vindex nnspool-lib-dir
11221 Where the news lib dir is (@file{/usr/lib/news/} by default).
11223 @item nnspool-active-file
11224 @vindex nnspool-active-file
11225 The path to the active file.
11227 @item nnspool-newsgroups-file
11228 @vindex nnspool-newsgroups-file
11229 The path to the group descriptions file.
11231 @item nnspool-history-file
11232 @vindex nnspool-history-file
11233 The path to the news history file.
11235 @item nnspool-active-times-file
11236 @vindex nnspool-active-times-file
11237 The path to the active date file.
11239 @item nnspool-nov-is-evil
11240 @vindex nnspool-nov-is-evil
11241 If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
11244 @item nnspool-sift-nov-with-sed
11245 @vindex nnspool-sift-nov-with-sed
11247 If non-@code{nil}, which is the default, use @code{sed} to get the
11248 relevant portion from the overview file. If nil, @code{nnspool} will
11249 load the entire file into a buffer and process it there.
11255 @section Getting Mail
11256 @cindex reading mail
11259 Reading mail with a newsreader---isn't that just plain WeIrD? But of
11263 * Mail in a Newsreader:: Important introductory notes.
11264 * Getting Started Reading Mail:: A simple cookbook example.
11265 * Splitting Mail:: How to create mail groups.
11266 * Mail Sources:: How to tell Gnus where to get mail from.
11267 * Mail Backend Variables:: Variables for customizing mail handling.
11268 * Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
11269 * Group Mail Splitting:: Use group customize to drive mail splitting.
11270 * Incorporating Old Mail:: What about the old mail you have?
11271 * Expiring Mail:: Getting rid of unwanted mail.
11272 * Washing Mail:: Removing gruft from the mail you get.
11273 * Duplicates:: Dealing with duplicated mail.
11274 * Not Reading Mail:: Using mail backends for reading other files.
11275 * Choosing a Mail Backend:: Gnus can read a variety of mail formats.
11279 @node Mail in a Newsreader
11280 @subsection Mail in a Newsreader
11282 If you are used to traditional mail readers, but have decided to switch
11283 to reading mail with Gnus, you may find yourself experiencing something
11284 of a culture shock.
11286 Gnus does not behave like traditional mail readers. If you want to make
11287 it behave that way, you can, but it's an uphill battle.
11289 Gnus, by default, handles all its groups using the same approach. This
11290 approach is very newsreaderly---you enter a group, see the new/unread
11291 messages, and when you read the messages, they get marked as read, and
11292 you don't see them any more. (Unless you explicitly ask for them.)
11294 In particular, you do not do anything explicitly to delete messages.
11296 Does this mean that all the messages that have been marked as read are
11297 deleted? How awful!
11299 But, no, it means that old messages are @dfn{expired} according to some
11300 scheme or other. For news messages, the expire process is controlled by
11301 the news administrator; for mail, the expire process is controlled by
11302 you. The expire process for mail is covered in depth in @pxref{Expiring
11305 What many Gnus users find, after using it a while for both news and
11306 mail, is that the transport mechanism has very little to do with how
11307 they want to treat a message.
11309 Many people subscribe to several mailing lists. These are transported
11310 via SMTP, and are therefore mail. But we might go for weeks without
11311 answering, or even reading these messages very carefully. We may not
11312 need to save them because if we should need to read one again, they are
11313 archived somewhere else.
11315 Some people have local news groups which have only a handful of readers.
11316 These are transported via @sc{nntp}, and are therefore news. But we may need
11317 to read and answer a large fraction of the messages very carefully in
11318 order to do our work. And there may not be an archive, so we may need
11319 to save the interesting messages the same way we would personal mail.
11321 The important distinction turns out to be not the transport mechanism,
11322 but other factors such as how interested we are in the subject matter,
11323 or how easy it is to retrieve the message if we need to read it again.
11325 Gnus provides many options for sorting mail into ``groups'' which behave
11326 like newsgroups, and for treating each group (whether mail or news)
11329 Some users never get comfortable using the Gnus (ahem) paradigm and wish
11330 that Gnus should grow up and be a male, er, mail reader. It is possible
11331 to whip Gnus into a more mailreaderly being, but, as said before, it's
11332 not easy. People who prefer proper mail readers should try @sc{vm}
11333 instead, which is an excellent, and proper, mail reader.
11335 I don't mean to scare anybody off, but I want to make it clear that you
11336 may be required to learn a new way of thinking about messages. After
11337 you've been subjected to The Gnus Way, you will come to love it. I can
11338 guarantee it. (At least the guy who sold me the Emacs Subliminal
11339 Brain-Washing Functions that I've put into Gnus did guarantee it. You
11340 Will Be Assimilated. You Love Gnus. You Love The Gnus Mail Way.
11344 @node Getting Started Reading Mail
11345 @subsection Getting Started Reading Mail
11347 It's quite easy to use Gnus to read your new mail. You just plonk the
11348 mail backend of your choice into @code{gnus-secondary-select-methods},
11349 and things will happen automatically.
11351 For instance, if you want to use @code{nnml} (which is a "one file per
11352 mail" backend), you could put the following in your @file{.gnus} file:
11355 (setq gnus-secondary-select-methods
11356 '((nnml "private")))
11359 Now, the next time you start Gnus, this backend will be queried for new
11360 articles, and it will move all the messages in your spool file to its
11361 directory, which is @code{~/Mail/} by default. The new group that will
11362 be created (@samp{mail.misc}) will be subscribed, and you can read it
11363 like any other group.
11365 You will probably want to split the mail into several groups, though:
11368 (setq nnmail-split-methods
11369 '(("junk" "^From:.*Lars Ingebrigtsen")
11370 ("crazy" "^Subject:.*die\\|^Organization:.*flabby")
11374 This will result in three new @code{nnml} mail groups being created:
11375 @samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the
11376 mail that doesn't fit into the first two groups will be placed in the
11379 This should be sufficient for reading mail with Gnus. You might want to
11380 give the other sections in this part of the manual a perusal, though.
11381 Especially @pxref{Choosing a Mail Backend} and @pxref{Expiring Mail}.
11384 @node Splitting Mail
11385 @subsection Splitting Mail
11386 @cindex splitting mail
11387 @cindex mail splitting
11389 @vindex nnmail-split-methods
11390 The @code{nnmail-split-methods} variable says how the incoming mail is
11391 to be split into groups.
11394 (setq nnmail-split-methods
11395 '(("mail.junk" "^From:.*Lars Ingebrigtsen")
11396 ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
11397 ("mail.other" "")))
11400 This variable is a list of lists, where the first element of each of
11401 these lists is the name of the mail group (they do not have to be called
11402 something beginning with @samp{mail}, by the way), and the second
11403 element is a regular expression used on the header of each mail to
11404 determine if it belongs in this mail group. The first string may
11405 contain @samp{\\1} forms, like the ones used by @code{replace-match} to
11406 insert sub-expressions from the matched text. For instance:
11409 ("list.\\1" "From:.* \\(.*\\)-list@@majordomo.com")
11412 The second element can also be a function. In that case, it will be
11413 called narrowed to the headers with the first element of the rule as the
11414 argument. It should return a non-@code{nil} value if it thinks that the
11415 mail belongs in that group.
11417 The last of these groups should always be a general one, and the regular
11418 expression should @emph{always} be @samp{} so that it matches any mails
11419 that haven't been matched by any of the other regexps. (These rules are
11420 processed from the beginning of the alist toward the end. The first
11421 rule to make a match will "win", unless you have crossposting enabled.
11422 In that case, all matching rules will "win".)
11424 If you like to tinker with this yourself, you can set this variable to a
11425 function of your choice. This function will be called without any
11426 arguments in a buffer narrowed to the headers of an incoming mail
11427 message. The function should return a list of group names that it
11428 thinks should carry this mail message.
11430 Note that the mail backends are free to maul the poor, innocent,
11431 incoming headers all they want to. They all add @code{Lines} headers;
11432 some add @code{X-Gnus-Group} headers; most rename the Unix mbox
11433 @code{From<SPACE>} line to something else.
11435 @vindex nnmail-crosspost
11436 The mail backends all support cross-posting. If several regexps match,
11437 the mail will be ``cross-posted'' to all those groups.
11438 @code{nnmail-crosspost} says whether to use this mechanism or not. Note
11439 that no articles are crossposted to the general (@samp{}) group.
11441 @vindex nnmail-crosspost-link-function
11444 @code{nnmh} and @code{nnml} makes crossposts by creating hard links to
11445 the crossposted articles. However, not all file systems support hard
11446 links. If that's the case for you, set
11447 @code{nnmail-crosspost-link-function} to @code{copy-file}. (This
11448 variable is @code{add-name-to-file} by default.)
11450 @kindex M-x nnmail-split-history
11451 @kindex nnmail-split-history
11452 If you wish to see where the previous mail split put the messages, you
11453 can use the @kbd{M-x nnmail-split-history} command. If you wish to see
11454 where re-spooling messages would put the messages, you can use
11455 @code{gnus-summary-respool-trace} and related commands (@pxref{Mail
11458 Gnus gives you all the opportunity you could possibly want for shooting
11459 yourself in the foot. Let's say you create a group that will contain
11460 all the mail you get from your boss. And then you accidentally
11461 unsubscribe from the group. Gnus will still put all the mail from your
11462 boss in the unsubscribed group, and so, when your boss mails you ``Have
11463 that report ready by Monday or you're fired!'', you'll never see it and,
11464 come Tuesday, you'll still believe that you're gainfully employed while
11465 you really should be out collecting empty bottles to save up for next
11466 month's rent money.
11470 @subsection Mail Sources
11472 Mail can be gotten from many different sources---the mail spool, from a
11473 POP mail server, from a procmail directory, or from a maildir, for
11477 * Mail Source Specifiers:: How to specify what a mail source is.
11478 * Mail Source Customization:: Some variables that influence things.
11479 * Fetching Mail:: Using the mail source specifiers.
11483 @node Mail Source Specifiers
11484 @subsubsection Mail Source Specifiers
11486 @cindex mail server
11489 @cindex mail source
11491 You tell Gnus how to fetch mail by setting @code{mail-sources}
11492 (@pxref{Fetching Mail}) to a @dfn{mail source specifier}.
11497 (pop :server "pop3.mailserver.com" :user "myname")
11500 As can be observed, a mail source specifier is a list where the first
11501 element is a @dfn{mail source type}, followed by an arbitrary number of
11502 @dfn{keywords}. Keywords that are not explicitly specified are given
11505 The following mail source types are available:
11509 Get mail from a single file; typically from the mail spool.
11515 The path of the file. Defaults to the value of the @code{MAIL}
11516 environment variable or @file{/usr/mail/spool/user-name}.
11519 An example file mail source:
11522 (file :path "/usr/spool/mail/user-name")
11525 Or using the default path:
11531 If the mail spool file is not located on the local machine, it's best to
11532 use POP or @sc{imap} or the like to fetch the mail. You can not use ange-ftp
11533 file names here---it has no way to lock the mail spool while moving the
11536 If it's impossible to set up a proper server, you can use ssh instead.
11540 '((file :prescript "ssh host bin/getmail >%t")))
11543 The @samp{getmail} script would look something like the following:
11547 # getmail - move mail from spool to stdout
11550 MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail
11552 rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP
11555 Alter this script to fit find the @samp{movemail} you want to use.
11559 Get mail from several files in a directory. This is typically used when
11560 you have procmail split the incoming mail into several files. Setting
11561 @code{nnmail-scan-directory-mail-source-once} to non-nil forces Gnus to
11562 scan the mail source only once. This is particularly useful if you want
11563 to scan mail groups at a specified level.
11569 The path of the directory where the files are. There is no default
11573 Only files ending with this suffix are used. The default is
11577 Only files that have this predicate return non-@code{nil} are returned.
11578 The default is @code{identity}. This is used as an additional
11579 filter---only files that have the right suffix @emph{and} satisfy this
11580 predicate are considered.
11584 Script run before/after fetching mail.
11588 An example directory mail source:
11591 (directory :path "/home/user-name/procmail-dir/"
11596 Get mail from a POP server.
11602 The name of the POP server. The default is taken from the
11603 @code{MAILHOST} environment variable.
11606 The port number of the POP server. This can be a number (eg,
11607 @samp{:port 1234}) or a string (eg, @samp{:port "pop3"}). If it is a
11608 string, it should be a service name as listed in @file{/etc/services} on
11609 Unix systems. The default is @samp{"pop3"}. On some systems you might
11610 need to specify it as @samp{"pop-3"} instead.
11613 The user name to give to the POP server. The default is the login
11617 The password to give to the POP server. If not specified, the user is
11621 The program to use to fetch mail from the POP server. This should be
11622 a @code{format}-like string. Here's an example:
11625 fetchmail %u@@%s -P %p %t
11628 The valid format specifier characters are:
11632 The name of the file the mail is to be moved to. This must always be
11633 included in this string.
11636 The name of the server.
11639 The port number of the server.
11642 The user name to use.
11645 The password to use.
11648 The values used for these specs are taken from the values you give the
11649 corresponding keywords.
11652 A script to be run before fetching the mail. The syntax is the same as
11653 the @code{:program} keyword. This can also be a function to be run.
11656 A script to be run after fetching the mail. The syntax is the same as
11657 the @code{:program} keyword. This can also be a function to be run.
11660 The function to use to fetch mail from the POP server. The function is
11661 called with one parameter---the name of the file where the mail should
11664 @item :authentication
11665 This can be either the symbol @code{password} or the symbol @code{apop}
11666 and says what authentication scheme to use. The default is
11671 If the @code{:program} and @code{:function} keywords aren't specified,
11672 @code{pop3-movemail} will be used.
11674 Here are some examples. Fetch from the default POP server, using the
11675 default user name, and default fetcher:
11681 Fetch from a named server with a named user and password:
11684 (pop :server "my.pop.server"
11685 :user "user-name" :password "secret")
11688 Use @samp{movemail} to move the mail:
11691 (pop :program "movemail po:%u %t %p")
11695 Get mail from a maildir. This is a type of mailbox that is supported by
11696 at least qmail and postfix, where each file in a special directory
11697 contains exactly one mail.
11703 The path of the directory where the mails are stored. The default is
11704 taken from the @code{MAILDIR} environment variable or
11707 The subdirectories of the Maildir. The default is
11708 @samp{("new" "cur")}.
11710 @c If you sometimes look at your mail through a pop3 daemon before fetching
11711 @c them with Gnus, you may also have to fetch your mails from the
11712 @c @code{cur} directory inside the maildir, like in the first example
11715 You can also get mails from remote hosts (because maildirs don't suffer
11716 from locking problems).
11720 Two example maildir mail sources:
11723 (maildir :path "/home/user-name/Maildir/"
11724 :subdirs ("cur" "new"))
11728 (maildir :path "/user@@remotehost.org:~/Maildir/"
11733 Get mail from a @sc{imap} server. If you don't want to use @sc{imap}
11734 as intended, as a network mail reading protocol (ie with nnimap), for
11735 some reason or other, Gnus let you treat it similar to a POP server
11736 and fetches articles from a given @sc{imap} mailbox. @xref{IMAP}, for
11743 The name of the @sc{imap} server. The default is taken from the
11744 @code{MAILHOST} environment variable.
11747 The port number of the @sc{imap} server. The default is @samp{143}, or
11748 @samp{993} for SSL connections.
11751 The user name to give to the @sc{imap} server. The default is the login
11755 The password to give to the @sc{imap} server. If not specified, the user is
11759 What stream to use for connecting to the server, this is one of the
11760 symbols in @code{imap-stream-alist}. Right now, this means
11761 @samp{kerberos4}, @samp{ssl} or the default @samp{network}.
11763 @item :authentication
11764 Which authenticator to use for authenticating to the server, this is one
11765 of the symbols in @code{imap-authenticator-alist}. Right now, this
11766 means @samp{kerberos4}, @samp{cram-md5}, @samp{anonymous} or the default
11770 When using the `shell' :stream, the contents of this variable is
11771 mapped into the `imap-shell-program' variable. This should be a
11772 @code{format}-like string (or list of strings). Here's an example:
11778 The valid format specifier characters are:
11782 The name of the server.
11785 User name from `imap-default-user'.
11788 The port number of the server.
11791 The values used for these specs are taken from the values you give the
11792 corresponding keywords.
11795 The name of the mailbox to get mail from. The default is @samp{INBOX}
11796 which normally is the mailbox which receive incoming mail.
11799 The predicate used to find articles to fetch. The default, @samp{UNSEEN
11800 UNDELETED}, is probably the best choice for most people, but if you
11801 sometimes peek in your mailbox with a @sc{imap} client and mark some
11802 articles as read (or; SEEN) you might want to set this to @samp{nil}.
11803 Then all articles in the mailbox is fetched, no matter what. For a
11804 complete list of predicates, see RFC 2060 §6.4.4.
11807 How to flag fetched articles on the server, the default @samp{\Deleted}
11808 will mark them as deleted, an alternative would be @samp{\Seen} which
11809 would simply mark them as read. These are the two most likely choices,
11810 but more flags are defined in RFC 2060 §2.3.2.
11813 If non-nil, don't remove all articles marked as deleted in the mailbox
11814 after finishing the fetch.
11818 An example @sc{imap} mail source:
11821 (imap :server "mail.mycorp.com"
11823 :fetchflag "\\Seen")
11827 Get mail from a webmail server, such as www.hotmail.com,
11828 webmail.netscape.com, www.netaddress.com, www.my-deja.com.
11830 NOTE: Now mail.yahoo.com provides POP3 service, so @sc{pop} mail source
11833 NOTE: Webmail largely depends cookies. A "one-line-cookie" patch is
11834 required for url "4.0pre.46".
11836 WARNING: Mails may lost. NO WARRANTY.
11842 The type of the webmail server. The default is @code{hotmail}. The
11843 alternatives are @code{netscape}, @code{netaddress}, @code{my-deja}.
11846 The user name to give to the webmail server. The default is the login
11850 The password to give to the webmail server. If not specified, the user is
11854 If non-nil, only fetch unread articles and don't move them to trash
11855 folder after finishing the fetch.
11859 An example webmail source:
11862 (webmail :subtype 'hotmail
11864 :password "secret")
11869 @item Common Keywords
11870 Common keywords can be used in any type of mail source.
11876 If non-nil, fetch the mail even when Gnus is unplugged. If you use
11877 directory source to get mail, you can specify it as in this example:
11881 '((directory :path "/home/pavel/.Spool/"
11886 Gnus will then fetch your mail even when you are unplugged. This is
11887 useful when you use local mail and news.
11892 @subsubsection Function Interface
11894 Some of the above keywords specify a Lisp function to be executed.
11895 For each keyword @code{:foo}, the Lisp variable @code{foo} is bound to
11896 the value of the keyword while the function is executing. For example,
11897 consider the following mail-source setting:
11900 (setq mail-sources '((pop :user "jrl"
11901 :server "pophost" :function fetchfunc)))
11904 While the function @code{fetchfunc} is executing, the symbol @code{user}
11905 is bound to @code{"jrl"}, and the symbol @code{server} is bound to
11906 @code{"pophost"}. The symbols @code{port}, @code{password},
11907 @code{program}, @code{prescript}, @code{postscript}, @code{function},
11908 and @code{authentication} are also bound (to their default values).
11910 See above for a list of keywords for each type of mail source.
11913 @node Mail Source Customization
11914 @subsubsection Mail Source Customization
11916 The following is a list of variables that influence how the mail is
11917 fetched. You would normally not need to set or change any of these
11921 @item mail-source-crash-box
11922 @vindex mail-source-crash-box
11923 File where mail will be stored while processing it. The default is
11924 @file{~/.emacs-mail-crash-box}.
11926 @item mail-source-delete-incoming
11927 @vindex mail-source-delete-incoming
11928 If non-@code{nil}, delete incoming files after handling them.
11930 @item mail-source-directory
11931 @vindex mail-source-directory
11932 Directory where files (if any) will be stored. The default is
11933 @file{~/Mail/}. At present, the only thing this is used for is to say
11934 where the incoming files will be stored if the previous variable is
11937 @item mail-source-incoming-file-prefix
11938 @vindex mail-source-incoming-file-prefix
11939 Prefix for file name for storing incoming mail. The default is
11940 @file{Incoming}, in which case files will end up with names like
11941 @file{Incoming30630D_} or @file{Incoming298602ZD}. This is really only
11942 relevant if @code{mail-source-delete-incoming} is @code{nil}.
11944 @item mail-source-default-file-modes
11945 @vindex mail-source-default-file-modes
11946 All new mail files will get this file mode. The default is 384.
11951 @node Fetching Mail
11952 @subsubsection Fetching Mail
11954 @vindex mail-sources
11955 @vindex nnmail-spool-file
11956 The way to actually tell Gnus where to get new mail from is to set
11957 @code{mail-sources} to a list of mail source specifiers
11958 (@pxref{Mail Source Specifiers}).
11960 If this variable (and the obsolescent @code{nnmail-spool-file}) is
11961 @code{nil}, the mail backends will never attempt to fetch mail by
11964 If you want to fetch mail both from your local spool as well as a POP
11965 mail server, you'd say something like:
11970 (pop :server "pop3.mail.server"
11971 :password "secret")))
11974 Or, if you don't want to use any of the keyword defaults:
11978 '((file :path "/var/spool/mail/user-name")
11979 (pop :server "pop3.mail.server"
11982 :password "secret")))
11986 When you use a mail backend, Gnus will slurp all your mail from your
11987 inbox and plonk it down in your home directory. Gnus doesn't move any
11988 mail if you're not using a mail backend---you have to do a lot of magic
11989 invocations first. At the time when you have finished drawing the
11990 pentagram, lightened the candles, and sacrificed the goat, you really
11991 shouldn't be too surprised when Gnus moves your mail.
11995 @node Mail Backend Variables
11996 @subsection Mail Backend Variables
11998 These variables are (for the most part) pertinent to all the various
12002 @vindex nnmail-read-incoming-hook
12003 @item nnmail-read-incoming-hook
12004 The mail backends all call this hook after reading new mail. You can
12005 use this hook to notify any mail watch programs, if you want to.
12007 @vindex nnmail-split-hook
12008 @item nnmail-split-hook
12009 @findex article-decode-encoded-words
12010 @findex RFC 1522 decoding
12011 @findex RFC 2047 decoding
12012 Hook run in the buffer where the mail headers of each message is kept
12013 just before the splitting based on these headers is done. The hook is
12014 free to modify the buffer contents in any way it sees fit---the buffer
12015 is discarded after the splitting has been done, and no changes performed
12016 in the buffer will show up in any files.
12017 @code{gnus-article-decode-encoded-words} is one likely function to add
12020 @vindex nnmail-pre-get-new-mail-hook
12021 @vindex nnmail-post-get-new-mail-hook
12022 @item nnmail-pre-get-new-mail-hook
12023 @itemx nnmail-post-get-new-mail-hook
12024 These are two useful hooks executed when treating new incoming
12025 mail---@code{nnmail-pre-get-new-mail-hook} (is called just before
12026 starting to handle the new mail) and
12027 @code{nnmail-post-get-new-mail-hook} (is called when the mail handling
12028 is done). Here's and example of using these two hooks to change the
12029 default file modes the new mail files get:
12032 (add-hook 'nnmail-pre-get-new-mail-hook
12033 (lambda () (set-default-file-modes 511)))
12035 (add-hook 'nnmail-post-get-new-mail-hook
12036 (lambda () (set-default-file-modes 551)))
12039 @item nnmail-use-long-file-names
12040 @vindex nnmail-use-long-file-names
12041 If non-@code{nil}, the mail backends will use long file and directory
12042 names. Groups like @samp{mail.misc} will end up in directories
12043 (assuming use of @code{nnml} backend) or files (assuming use of
12044 @code{nnfolder} backend) like @file{mail.misc}. If it is @code{nil},
12045 the same group will end up in @file{mail/misc}.
12047 @item nnmail-delete-file-function
12048 @vindex nnmail-delete-file-function
12049 @findex delete-file
12050 Function called to delete files. It is @code{delete-file} by default.
12052 @item nnmail-cache-accepted-message-ids
12053 @vindex nnmail-cache-accepted-message-ids
12054 If non-@code{nil}, put the @code{Message-ID}s of articles imported into
12055 the backend (via @code{Gcc}, for instance) into the mail duplication
12056 discovery cache. The default is @code{nil}.
12061 @node Fancy Mail Splitting
12062 @subsection Fancy Mail Splitting
12063 @cindex mail splitting
12064 @cindex fancy mail splitting
12066 @vindex nnmail-split-fancy
12067 @findex nnmail-split-fancy
12068 If the rather simple, standard method for specifying how to split mail
12069 doesn't allow you to do what you want, you can set
12070 @code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
12071 play with the @code{nnmail-split-fancy} variable.
12073 Let's look at an example value of this variable first:
12076 ;; Messages from the mailer daemon are not crossposted to any of
12077 ;; the ordinary groups. Warnings are put in a separate group
12078 ;; from real errors.
12079 (| ("from" mail (| ("subject" "warn.*" "mail.warning")
12081 ;; Non-error messages are crossposted to all relevant
12082 ;; groups, but we don't crosspost between the group for the
12083 ;; (ding) list and the group for other (ding) related mail.
12084 (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
12085 ("subject" "ding" "ding.misc"))
12086 ;; Other mailing lists...
12087 (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
12088 (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
12089 ;; Both lists below have the same suffix, so prevent
12090 ;; cross-posting to mkpkg.list of messages posted only to
12091 ;; the bugs- list, but allow cross-posting when the
12092 ;; message was really cross-posted.
12093 (any "bugs-mypackage@@somewhere" "mypkg.bugs")
12094 (any "mypackage@@somewhere\" - "bugs-mypackage" "mypkg.list")
12096 (any "larsi@@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen"))
12097 ;; Unmatched mail goes to the catch all group.
12101 This variable has the format of a @dfn{split}. A split is a (possibly)
12102 recursive structure where each split may contain other splits. Here are
12103 the five possible split syntaxes:
12108 @samp{group}: If the split is a string, that will be taken as a group
12109 name. Normal regexp match expansion will be done. See below for
12113 @code{(@var{field} @var{value} @code{[-} @var{restrict}
12114 @code{[@dots{}]}@code{]} @var{split})}: If the split is a list, the
12115 first element of which is a string, then store the message as
12116 specified by @var{split}, if header @var{field} (a regexp) contains
12117 @var{value} (also a regexp). If @var{restrict} (yet another regexp)
12118 matches some string after @var{field} and before the end of the
12119 matched @var{value}, the @var{split} is ignored. If none of the
12120 @var{restrict} clauses match, @var{split} is processed.
12123 @code{(| @var{split}@dots{})}: If the split is a list, and the first
12124 element is @code{|} (vertical bar), then process each @var{split} until
12125 one of them matches. A @var{split} is said to match if it will cause
12126 the mail message to be stored in one or more groups.
12129 @code{(& @var{split}@dots{})}: If the split is a list, and the first
12130 element is @code{&}, then process all @var{split}s in the list.
12133 @code{junk}: If the split is the symbol @code{junk}, then don't save
12134 this message. Use with extreme caution.
12137 @code{(: @var{function} @var{arg1} @var{arg2} @dots{})}: If the split is
12138 a list, and the first element is @code{:}, then the second element will
12139 be called as a function with @var{args} given as arguments. The
12140 function should return a @var{split}.
12143 For instance, the following function could be used to split based on the
12144 body of the messages:
12147 (defun split-on-body ()
12149 (set-buffer " *nnmail incoming*")
12150 (goto-char (point-min))
12151 (when (re-search-forward "Some.*string" nil t)
12155 The @samp{" *nnmail incoming*"} is narrowed to the message in question
12156 when the @code{:} function is run.
12159 @code{(! @var{func} @var{split})}: If the split is a list, and the first
12160 element is @code{!}, then SPLIT will be processed, and FUNC will be
12161 called as a function with the result of SPLIT as argument. FUNC should
12165 @code{nil}: If the split is @code{nil}, it is ignored.
12169 In these splits, @var{field} must match a complete field name.
12170 @var{value} must match a complete word according to the fundamental mode
12171 syntax table. You can use @code{.*} in the regexps to match partial
12172 field names or words. In other words, all @var{value}'s are wrapped in
12173 @samp{\<} and @samp{\>} pairs.
12175 @vindex nnmail-split-abbrev-alist
12176 @var{field} and @var{value} can also be lisp symbols, in that case they
12177 are expanded as specified by the variable
12178 @code{nnmail-split-abbrev-alist}. This is an alist of cons cells, where
12179 the @code{car} of a cell contains the key, and the @code{cdr} contains the associated
12182 @vindex nnmail-split-fancy-syntax-table
12183 @code{nnmail-split-fancy-syntax-table} is the syntax table in effect
12184 when all this splitting is performed.
12186 If you want to have Gnus create groups dynamically based on some
12187 information in the headers (i.e., do @code{replace-match}-like
12188 substitutions in the group names), you can say things like:
12191 (any "debian-\\b\\(\\w+\\)@@lists.debian.org" "mail.debian.\\1")
12194 In this example, messages sent to @samp{debian-foo@@lists.debian.org}
12195 will be filed in @samp{mail.debian.foo}.
12197 If the string contains the element @samp{\&}, then the previously
12198 matched string will be substituted. Similarly, the elements @samp{\\1}
12199 up to @samp{\\9} will be substituted with the text matched by the
12200 groupings 1 through 9.
12202 @findex nnmail-split-fancy-with-parent
12203 @code{nnmail-split-fancy-with-parent} is a function which allows you to
12204 split followups into the same groups their parents are in. Sometimes
12205 you can't make splitting rules for all your mail. For example, your
12206 boss might send you personal mail regarding different projects you are
12207 working on, and as you can't tell your boss to put a distinguishing
12208 string into the subject line, you have to resort to manually moving the
12209 messages into the right group. With this function, you only have to do
12210 it once per thread.
12212 To use this feature, you have to set @code{nnmail-treat-duplicates} to a
12213 non-nil value. And then you can include
12214 @code{nnmail-split-fancy-with-parent} using the colon feature, like so:
12216 (setq nnmail-split-fancy
12217 '(| (: nnmail-split-fancy-with-parent)
12218 ;; other splits go here
12222 This feature works as follows: when @code{nnmail-treat-duplicates} is
12223 non-nil, Gnus records the message id of every message it sees in the
12224 file specified by the variable @code{nnmail-message-id-cache-file},
12225 together with the group it is in (the group is omitted for non-mail
12226 messages). When mail splitting is invoked, the function
12227 @code{nnmail-split-fancy-with-parent} then looks at the References (and
12228 In-Reply-To) header of each message to split and searches the file
12229 specified by @code{nnmail-message-id-cache-file} for the message ids.
12230 When it has found a parent, it returns the corresponding group name
12231 unless the group name matches the regexp
12232 @code{nnmail-split-fancy-with-parent-ignore-groups}. It is recommended
12233 that you set @code{nnmail-message-id-cache-length} to a somewhat higher
12234 number than the default so that the message ids are still in the cache.
12235 (A value of 5000 appears to create a file some 300 kBytes in size.)
12236 @vindex nnmail-cache-accepted-message-ids
12237 When @code{nnmail-cache-accepted-message-ids} is non-@code{nil}, Gnus
12238 also records the message ids of moved articles, so that the followup
12239 messages goes into the new group.
12242 @node Group Mail Splitting
12243 @subsection Group Mail Splitting
12244 @cindex mail splitting
12245 @cindex group mail splitting
12247 @findex gnus-group-split
12248 If you subscribe to dozens of mailing lists but you don't want to
12249 maintain mail splitting rules manually, group mail splitting is for you.
12250 You just have to set @var{to-list} and/or @var{to-address} in group
12251 parameters or group customization and set @code{nnmail-split-methods} to
12252 @code{gnus-group-split}. This splitting function will scan all groups
12253 for those parameters and split mail accordingly, i.e., messages posted
12254 from or to the addresses specified in the parameters @var{to-list} or
12255 @var{to-address} of a mail group will be stored in that group.
12257 Sometimes, mailing lists have multiple addresses, and you may want mail
12258 splitting to recognize them all: just set the @var{extra-aliases} group
12259 parameter to the list of additional addresses and it's done. If you'd
12260 rather use a regular expression, set @var{split-regexp}.
12262 All these parameters in a group will be used to create an
12263 @code{nnmail-split-fancy} split, in which the @var{field} is @samp{any},
12264 the @var{value} is a single regular expression that matches
12265 @var{to-list}, @var{to-address}, all of @var{extra-aliases} and all
12266 matches of @var{split-regexp}, and the @var{split} is the name of the
12267 group. @var{restrict}s are also supported: just set the
12268 @var{split-exclude} parameter to a list of regular expressions.
12270 If you can't get the right split to be generated using all these
12271 parameters, or you just need something fancier, you can set the
12272 parameter @var{split-spec} to an @code{nnmail-split-fancy} split. In
12273 this case, all other aforementioned parameters will be ignored by
12274 @code{gnus-group-split}. In particular, @var{split-spec} may be set to
12275 @code{nil}, in which case the group will be ignored by
12276 @code{gnus-group-split}.
12278 @vindex gnus-group-split-default-catch-all-group
12279 @code{gnus-group-split} will do cross-posting on all groups that match,
12280 by defining a single @code{&} fancy split containing one split for each
12281 group. If a message doesn't match any split, it will be stored in the
12282 group named in @code{gnus-group-split-default-catch-all-group}, unless
12283 some group has @var{split-spec} set to @code{catch-all}, in which case
12284 that group is used as the catch-all group. Even though this variable is
12285 often used just to name a group, it may also be set to an arbitrarily
12286 complex fancy split (after all, a group name is a fancy split), and this
12287 may be useful to split mail that doesn't go to any mailing list to
12288 personal mail folders. Note that this fancy split is added as the last
12289 element of a @code{|} split list that also contains a @code{&} split
12290 with the rules extracted from group parameters.
12292 It's time for an example. Assume the following group parameters have
12297 ((to-address . "bar@@femail.com")
12298 (split-regexp . ".*@@femail\\.com"))
12300 ((to-list . "foo@@nowhere.gov")
12301 (extra-aliases "foo@@localhost" "foo-redist@@home")
12302 (split-exclude "bugs-foo" "rambling-foo")
12303 (admin-address . "foo-request@@nowhere.gov"))
12305 ((split-spec . catch-all))
12308 Setting @code{nnmail-split-methods} to @code{gnus-group-split} will
12309 behave as if @code{nnmail-split-fancy} had been selected and variable
12310 @code{nnmail-split-fancy} had been set as follows:
12313 (| (& (any "\\(bar@@femail\\.com\\|.*@@femail\\.com\\)" "mail.bar")
12314 (any "\\(foo@@nowhere\\.gov\\|foo@@localhost\\|foo-redist@@home\\)"
12315 - "bugs-foo" - "rambling-foo" "mail.foo"))
12319 @findex gnus-group-split-fancy
12320 If you'd rather not use group splitting for all your mail groups, you
12321 may use it for only some of them, by using @code{nnmail-split-fancy}
12325 (: gnus-mlsplt-fancy GROUPS NO-CROSSPOST CATCH-ALL)
12328 @var{groups} may be a regular expression or a list of group names whose
12329 parameters will be scanned to generate the output split.
12330 @var{no-crosspost} can be used to disable cross-posting; in this case, a
12331 single @code{|} split will be output. @var{catch-all} is the fallback
12332 fancy split, used like @var{gnus-group-split-default-catch-all-group}.
12333 If @var{catch-all} is @code{nil}, or if @var{split-regexp} matches the
12334 empty string in any selected group, no catch-all split will be issued.
12335 Otherwise, if some group has @var{split-spec} set to @code{catch-all},
12336 this group will override the value of the @var{catch-all} argument.
12338 @findex gnus-group-split-setup
12339 Unfortunately, scanning all groups and their parameters can be quite
12340 slow, especially considering that it has to be done for every message.
12341 But don't despair! The function @code{gnus-group-split-setup} can be
12342 used to enable @code{gnus-group-split} in a much more efficient way. It
12343 sets @code{nnmail-split-methods} to @code{nnmail-split-fancy} and sets
12344 @code{nnmail-split-fancy} to the split produced by
12345 @code{gnus-group-split-fancy}. Thus, the group parameters are only
12346 scanned once, no matter how many messages are split.
12348 @findex gnus-group-split-update
12349 However, if you change group parameters, you'd have to update
12350 @code{nnmail-split-fancy} manually. You can do it by running
12351 @code{gnus-group-split-update}. If you'd rather have it updated
12352 automatically, just tell @code{gnus-group-split-setup} to do it for
12353 you. For example, add to your @file{.gnus}:
12356 (gnus-group-split-setup AUTO-UPDATE CATCH-ALL)
12359 If @var{auto-update} is non-@code{nil}, @code{gnus-group-split-update}
12360 will be added to @code{nnmail-pre-get-new-mail-hook}, so you won't ever
12361 have to worry about updating @code{nnmail-split-fancy} again. If you
12362 don't omit @var{catch-all} (it's optional, equivalent to @code{nil}),
12363 @code{gnus-group-split-default-catch-all-group} will be set to its
12366 @vindex gnus-group-split-updated-hook
12367 Because you may want to change @code{nnmail-split-fancy} after it is set
12368 by @code{gnus-group-split-update}, this function will run
12369 @code{gnus-group-split-updated-hook} just before finishing.
12371 @node Incorporating Old Mail
12372 @subsection Incorporating Old Mail
12373 @cindex incorporating old mail
12374 @cindex import old mail
12376 Most people have lots of old mail stored in various file formats. If
12377 you have set up Gnus to read mail using one of the spiffy Gnus mail
12378 backends, you'll probably wish to have that old mail incorporated into
12381 Doing so can be quite easy.
12383 To take an example: You're reading mail using @code{nnml}
12384 (@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a
12385 satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox
12386 file filled with important, but old, mail. You want to move it into
12387 your @code{nnml} groups.
12393 Go to the group buffer.
12396 Type `G f' and give the path to the mbox file when prompted to create an
12397 @code{nndoc} group from the mbox file (@pxref{Foreign Groups}).
12400 Type `SPACE' to enter the newly created group.
12403 Type `M P b' to process-mark all articles in this group's buffer
12404 (@pxref{Setting Process Marks}).
12407 Type `B r' to respool all the process-marked articles, and answer
12408 @samp{nnml} when prompted (@pxref{Mail Group Commands}).
12411 All the mail messages in the mbox file will now also be spread out over
12412 all your @code{nnml} groups. Try entering them and check whether things
12413 have gone without a glitch. If things look ok, you may consider
12414 deleting the mbox file, but I wouldn't do that unless I was absolutely
12415 sure that all the mail has ended up where it should be.
12417 Respooling is also a handy thing to do if you're switching from one mail
12418 backend to another. Just respool all the mail in the old mail groups
12419 using the new mail backend.
12422 @node Expiring Mail
12423 @subsection Expiring Mail
12424 @cindex article expiry
12426 Traditional mail readers have a tendency to remove mail articles when
12427 you mark them as read, in some way. Gnus takes a fundamentally
12428 different approach to mail reading.
12430 Gnus basically considers mail just to be news that has been received in
12431 a rather peculiar manner. It does not think that it has the power to
12432 actually change the mail, or delete any mail messages. If you enter a
12433 mail group, and mark articles as ``read'', or kill them in some other
12434 fashion, the mail articles will still exist on the system. I repeat:
12435 Gnus will not delete your old, read mail. Unless you ask it to, of
12438 To make Gnus get rid of your unwanted mail, you have to mark the
12439 articles as @dfn{expirable}. This does not mean that the articles will
12440 disappear right away, however. In general, a mail article will be
12441 deleted from your system if, 1) it is marked as expirable, AND 2) it is
12442 more than one week old. If you do not mark an article as expirable, it
12443 will remain on your system until hell freezes over. This bears
12444 repeating one more time, with some spurious capitalizations: IF you do
12445 NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
12447 @vindex gnus-auto-expirable-newsgroups
12448 You do not have to mark articles as expirable by hand. Groups that
12449 match the regular expression @code{gnus-auto-expirable-newsgroups} will
12450 have all articles that you read marked as expirable automatically. All
12451 articles marked as expirable have an @samp{E} in the first
12452 column in the summary buffer.
12454 By default, if you have auto expiry switched on, Gnus will mark all the
12455 articles you read as expirable, no matter if they were read or unread
12456 before. To avoid having articles marked as read marked as expirable
12457 automatically, you can put something like the following in your
12460 @vindex gnus-mark-article-hook
12462 (remove-hook 'gnus-mark-article-hook
12463 'gnus-summary-mark-read-and-unread-as-read)
12464 (add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read)
12467 Note that making a group auto-expirable doesn't mean that all read
12468 articles are expired---only the articles marked as expirable
12469 will be expired. Also note that using the @kbd{d} command won't make
12470 articles expirable---only semi-automatic marking of articles as read will
12471 mark the articles as expirable in auto-expirable groups.
12473 Let's say you subscribe to a couple of mailing lists, and you want the
12474 articles you have read to disappear after a while:
12477 (setq gnus-auto-expirable-newsgroups
12478 "mail.nonsense-list\\|mail.nice-list")
12481 Another way to have auto-expiry happen is to have the element
12482 @code{auto-expire} in the group parameters of the group.
12484 If you use adaptive scoring (@pxref{Adaptive Scoring}) and
12485 auto-expiring, you'll have problems. Auto-expiring and adaptive scoring
12486 don't really mix very well.
12488 @vindex nnmail-expiry-wait
12489 The @code{nnmail-expiry-wait} variable supplies the default time an
12490 expirable article has to live. Gnus starts counting days from when the
12491 message @emph{arrived}, not from when it was sent. The default is seven
12494 Gnus also supplies a function that lets you fine-tune how long articles
12495 are to live, based on what group they are in. Let's say you want to
12496 have one month expiry period in the @samp{mail.private} group, a one day
12497 expiry period in the @samp{mail.junk} group, and a six day expiry period
12500 @vindex nnmail-expiry-wait-function
12502 (setq nnmail-expiry-wait-function
12504 (cond ((string= group "mail.private")
12506 ((string= group "mail.junk")
12508 ((string= group "important")
12514 The group names this function is fed are ``unadorned'' group
12515 names---no @samp{nnml:} prefixes and the like.
12517 The @code{nnmail-expiry-wait} variable and
12518 @code{nnmail-expiry-wait-function} function can either be a number (not
12519 necessarily an integer) or one of the symbols @code{immediate} or
12522 You can also use the @code{expiry-wait} group parameter to selectively
12523 change the expiry period (@pxref{Group Parameters}).
12525 @vindex nnmail-expiry-target
12526 The normal action taken when expiring articles is to delete them.
12527 However, in some circumstances it might make more sense to move them to
12528 other groups instead of deleting them. The variable @code{nnmail-expiry-target}
12529 (and the @code{expiry-target} group parameter) controls this. The
12530 variable supplies a default value for all groups, which can be
12531 overridden for specific groups by the group parameter.
12532 default value is @code{delete}, but this can also be a string (which
12533 should be the name of the group the message should be moved to), or a
12534 function (which will be called in a buffer narrowed to the message in
12535 question, and with the name of the group being moved from as its
12536 parameter) which should return a target -- either a group name or
12539 Here's an example for specifying a group name:
12541 (setq nnmail-expiry-target "nnml:expired")
12545 @vindex nnmail-keep-last-article
12546 If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
12547 expire the final article in a mail newsgroup. This is to make life
12548 easier for procmail users.
12550 @vindex gnus-total-expirable-newsgroups
12551 By the way: That line up there, about Gnus never expiring non-expirable
12552 articles, is a lie. If you put @code{total-expire} in the group
12553 parameters, articles will not be marked as expirable, but all read
12554 articles will be put through the expiry process. Use with extreme
12555 caution. Even more dangerous is the
12556 @code{gnus-total-expirable-newsgroups} variable. All groups that match
12557 this regexp will have all read articles put through the expiry process,
12558 which means that @emph{all} old mail articles in the groups in question
12559 will be deleted after a while. Use with extreme caution, and don't come
12560 crying to me when you discover that the regexp you used matched the
12561 wrong group and all your important mail has disappeared. Be a
12562 @emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
12565 Most people make most of their mail groups total-expirable, though.
12567 @vindex gnus-inhibit-user-auto-expire
12568 If @code{gnus-inhibit-user-auto-expire} is non-@code{nil}, user marking
12569 commands will not mark an article as expirable, even if the group has
12570 auto-expire turned on.
12574 @subsection Washing Mail
12575 @cindex mail washing
12576 @cindex list server brain damage
12577 @cindex incoming mail treatment
12579 Mailers and list servers are notorious for doing all sorts of really,
12580 really stupid things with mail. ``Hey, RFC 822 doesn't explicitly
12581 prohibit us from adding the string @code{wE aRe ElItE!!!!!1!!} to the
12582 end of all lines passing through our server, so let's do that!!!!1!''
12583 Yes, but RFC 822 wasn't designed to be read by morons. Things that were
12584 considered to be self-evident were not discussed. So. Here we are.
12586 Case in point: The German version of Microsoft Exchange adds @samp{AW:
12587 } to the subjects of replies instead of @samp{Re: }. I could pretend to
12588 be shocked and dismayed by this, but I haven't got the energy. It is to
12591 Gnus provides a plethora of functions for washing articles while
12592 displaying them, but it might be nicer to do the filtering before
12593 storing the mail to disc. For that purpose, we have three hooks and
12594 various functions that can be put in these hooks.
12597 @item nnmail-prepare-incoming-hook
12598 @vindex nnmail-prepare-incoming-hook
12599 This hook is called before doing anything with the mail and is meant for
12600 grand, sweeping gestures. It is called in a buffer that contains all
12601 the new, incoming mail. Functions to be used include:
12604 @item nnheader-ms-strip-cr
12605 @findex nnheader-ms-strip-cr
12606 Remove trailing carriage returns from each line. This is default on
12607 Emacs running on MS machines.
12611 @item nnmail-prepare-incoming-header-hook
12612 @vindex nnmail-prepare-incoming-header-hook
12613 This hook is called narrowed to each header. It can be used when
12614 cleaning up the headers. Functions that can be used include:
12617 @item nnmail-remove-leading-whitespace
12618 @findex nnmail-remove-leading-whitespace
12619 Clear leading white space that ``helpful'' listservs have added to the
12620 headers to make them look nice. Aaah.
12622 @item nnmail-remove-list-identifiers
12623 @findex nnmail-remove-list-identifiers
12624 Some list servers add an identifier---for example, @samp{(idm)}---to the
12625 beginning of all @code{Subject} headers. I'm sure that's nice for
12626 people who use stone age mail readers. This function will remove
12627 strings that match the @code{nnmail-list-identifiers} regexp, which can
12628 also be a list of regexp. @code{nnmail-list-identifiers} may not contain
12631 For instance, if you want to remove the @samp{(idm)} and the
12632 @samp{nagnagnag} identifiers:
12635 (setq nnmail-list-identifiers
12636 '("(idm)" "nagnagnag"))
12639 This can also be done non-destructively with
12640 @code{gnus-list-identifiers}, @xref{Article Hiding}.
12642 @item nnmail-remove-tabs
12643 @findex nnmail-remove-tabs
12644 Translate all @samp{TAB} characters into @samp{SPACE} characters.
12646 @item nnmail-fix-eudora-headers
12647 @findex nnmail-fix-eudora-headers
12649 Eudora produces broken @code{References} headers, but OK
12650 @code{In-Reply-To} headers. This function will get rid of the
12651 @code{References} headers.
12655 @item nnmail-prepare-incoming-message-hook
12656 @vindex nnmail-prepare-incoming-message-hook
12657 This hook is called narrowed to each message. Functions to be used
12661 @item article-de-quoted-unreadable
12662 @findex article-de-quoted-unreadable
12663 Decode Quoted Readable encoding.
12670 @subsection Duplicates
12672 @vindex nnmail-treat-duplicates
12673 @vindex nnmail-message-id-cache-length
12674 @vindex nnmail-message-id-cache-file
12675 @cindex duplicate mails
12676 If you are a member of a couple of mailing lists, you will sometimes
12677 receive two copies of the same mail. This can be quite annoying, so
12678 @code{nnmail} checks for and treats any duplicates it might find. To do
12679 this, it keeps a cache of old @code{Message-ID}s---
12680 @code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
12681 default. The approximate maximum number of @code{Message-ID}s stored
12682 there is controlled by the @code{nnmail-message-id-cache-length}
12683 variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
12684 stored.) If all this sounds scary to you, you can set
12685 @code{nnmail-treat-duplicates} to @code{warn} (which is what it is by
12686 default), and @code{nnmail} won't delete duplicate mails. Instead it
12687 will insert a warning into the head of the mail saying that it thinks
12688 that this is a duplicate of a different message.
12690 This variable can also be a function. If that's the case, the function
12691 will be called from a buffer narrowed to the message in question with
12692 the @code{Message-ID} as a parameter. The function must return either
12693 @code{nil}, @code{warn}, or @code{delete}.
12695 You can turn this feature off completely by setting the variable to
12698 If you want all the duplicate mails to be put into a special
12699 @dfn{duplicates} group, you could do that using the normal mail split
12703 (setq nnmail-split-fancy
12704 '(| ;; Messages duplicates go to a separate group.
12705 ("gnus-warning" "duplicat\\(e\\|ion\\) of message" "duplicate")
12706 ;; Message from daemons, postmaster, and the like to another.
12707 (any mail "mail.misc")
12714 (setq nnmail-split-methods
12715 '(("duplicates" "^Gnus-Warning:.*duplicate")
12720 Here's a neat feature: If you know that the recipient reads her mail
12721 with Gnus, and that she has @code{nnmail-treat-duplicates} set to
12722 @code{delete}, you can send her as many insults as you like, just by
12723 using a @code{Message-ID} of a mail that you know that she's already
12724 received. Think of all the fun! She'll never see any of it! Whee!
12727 @node Not Reading Mail
12728 @subsection Not Reading Mail
12730 If you start using any of the mail backends, they have the annoying
12731 habit of assuming that you want to read mail with them. This might not
12732 be unreasonable, but it might not be what you want.
12734 If you set @code{mail-sources} and @code{nnmail-spool-file} to
12735 @code{nil}, none of the backends will ever attempt to read incoming
12736 mail, which should help.
12738 @vindex nnbabyl-get-new-mail
12739 @vindex nnmbox-get-new-mail
12740 @vindex nnml-get-new-mail
12741 @vindex nnmh-get-new-mail
12742 @vindex nnfolder-get-new-mail
12743 This might be too much, if, for instance, you are reading mail quite
12744 happily with @code{nnml} and just want to peek at some old @sc{rmail}
12745 file you have stashed away with @code{nnbabyl}. All backends have
12746 variables called backend-@code{get-new-mail}. If you want to disable
12747 the @code{nnbabyl} mail reading, you edit the virtual server for the
12748 group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
12750 All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
12751 narrowed to the article to be saved before saving it when reading
12755 @node Choosing a Mail Backend
12756 @subsection Choosing a Mail Backend
12758 Gnus will read the mail spool when you activate a mail group. The mail
12759 file is first copied to your home directory. What happens after that
12760 depends on what format you want to store your mail in.
12762 There are five different mail backends in the standard Gnus, and more
12763 backends are available separately. The mail backend most people use
12764 (because it is the fastest and most flexible) is @code{nnml}
12765 (@pxref{Mail Spool}).
12768 * Unix Mail Box:: Using the (quite) standard Un*x mbox.
12769 * Rmail Babyl:: Emacs programs use the rmail babyl format.
12770 * Mail Spool:: Store your mail in a private spool?
12771 * MH Spool:: An mhspool-like backend.
12772 * Mail Folders:: Having one file for each group.
12773 * Comparing Mail Backends:: An in-depth looks at pros and cons.
12777 @node Unix Mail Box
12778 @subsubsection Unix Mail Box
12780 @cindex unix mail box
12782 @vindex nnmbox-active-file
12783 @vindex nnmbox-mbox-file
12784 The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
12785 mail. @code{nnmbox} will add extra headers to each mail article to say
12786 which group it belongs in.
12788 Virtual server settings:
12791 @item nnmbox-mbox-file
12792 @vindex nnmbox-mbox-file
12793 The name of the mail box in the user's home directory. Default is
12796 @item nnmbox-active-file
12797 @vindex nnmbox-active-file
12798 The name of the active file for the mail box. Default is
12799 @file{~/.mbox-active}.
12801 @item nnmbox-get-new-mail
12802 @vindex nnmbox-get-new-mail
12803 If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
12804 into groups. Default is @code{t}.
12809 @subsubsection Rmail Babyl
12813 @vindex nnbabyl-active-file
12814 @vindex nnbabyl-mbox-file
12815 The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
12816 mbox}) to store mail. @code{nnbabyl} will add extra headers to each
12817 mail article to say which group it belongs in.
12819 Virtual server settings:
12822 @item nnbabyl-mbox-file
12823 @vindex nnbabyl-mbox-file
12824 The name of the rmail mbox file. The default is @file{~/RMAIL}
12826 @item nnbabyl-active-file
12827 @vindex nnbabyl-active-file
12828 The name of the active file for the rmail box. The default is
12829 @file{~/.rmail-active}
12831 @item nnbabyl-get-new-mail
12832 @vindex nnbabyl-get-new-mail
12833 If non-@code{nil}, @code{nnbabyl} will read incoming mail. Default is
12839 @subsubsection Mail Spool
12841 @cindex mail @sc{nov} spool
12843 The @dfn{nnml} spool mail format isn't compatible with any other known
12844 format. It should be used with some caution.
12846 @vindex nnml-directory
12847 If you use this backend, Gnus will split all incoming mail into files,
12848 one file for each mail, and put the articles into the corresponding
12849 directories under the directory specified by the @code{nnml-directory}
12850 variable. The default value is @file{~/Mail/}.
12852 You do not have to create any directories beforehand; Gnus will take
12855 If you have a strict limit as to how many files you are allowed to store
12856 in your account, you should not use this backend. As each mail gets its
12857 own file, you might very well occupy thousands of inodes within a few
12858 weeks. If this is no problem for you, and it isn't a problem for you
12859 having your friendly systems administrator walking around, madly,
12860 shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should
12861 know that this is probably the fastest format to use. You do not have
12862 to trudge through a big mbox file just to read your new mail.
12864 @code{nnml} is probably the slowest backend when it comes to article
12865 splitting. It has to create lots of files, and it also generates
12866 @sc{nov} databases for the incoming mails. This makes it the fastest
12867 backend when it comes to reading mail.
12869 Virtual server settings:
12872 @item nnml-directory
12873 @vindex nnml-directory
12874 All @code{nnml} directories will be placed under this directory.
12875 The default is the value of `message-directory' (whose default value is
12878 @item nnml-active-file
12879 @vindex nnml-active-file
12880 The active file for the @code{nnml} server. The default is
12881 @file{~/Mail/active"}.
12883 @item nnml-newsgroups-file
12884 @vindex nnml-newsgroups-file
12885 The @code{nnml} group descriptions file. @xref{Newsgroups File
12886 Format}. The default is @file{~/Mail/newsgroups"}.
12888 @item nnml-get-new-mail
12889 @vindex nnml-get-new-mail
12890 If non-@code{nil}, @code{nnml} will read incoming mail. The default is
12893 @item nnml-nov-is-evil
12894 @vindex nnml-nov-is-evil
12895 If non-@code{nil}, this backend will ignore any @sc{nov} files. The
12896 default is @code{nil}
12898 @item nnml-nov-file-name
12899 @vindex nnml-nov-file-name
12900 The name of the @sc{nov} files. The default is @file{.overview}.
12902 @item nnml-prepare-save-mail-hook
12903 @vindex nnml-prepare-save-mail-hook
12904 Hook run narrowed to an article before saving.
12908 @findex nnml-generate-nov-databases
12909 If your @code{nnml} groups and @sc{nov} files get totally out of whack,
12910 you can do a complete update by typing @kbd{M-x
12911 nnml-generate-nov-databases}. This command will trawl through the
12912 entire @code{nnml} hierarchy, looking at each and every article, so it
12913 might take a while to complete. A better interface to this
12914 functionality can be found in the server buffer (@pxref{Server
12919 @subsubsection MH Spool
12921 @cindex mh-e mail spool
12923 @code{nnmh} is just like @code{nnml}, except that is doesn't generate
12924 @sc{nov} databases and it doesn't keep an active file. This makes
12925 @code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
12926 makes it easier to write procmail scripts for.
12928 Virtual server settings:
12931 @item nnmh-directory
12932 @vindex nnmh-directory
12933 All @code{nnmh} directories will be located under this directory. The
12934 default is the value of @code{message-directory} (whose default is
12937 @item nnmh-get-new-mail
12938 @vindex nnmh-get-new-mail
12939 If non-@code{nil}, @code{nnmh} will read incoming mail. The default is
12943 @vindex nnmh-be-safe
12944 If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
12945 sure that the articles in the folder are actually what Gnus thinks they
12946 are. It will check date stamps and stat everything in sight, so
12947 setting this to @code{t} will mean a serious slow-down. If you never
12948 use anything but Gnus to read the @code{nnmh} articles, you do not have
12949 to set this variable to @code{t}. The default is @code{nil}.
12954 @subsubsection Mail Folders
12956 @cindex mbox folders
12957 @cindex mail folders
12959 @code{nnfolder} is a backend for storing each mail group in a separate
12960 file. Each file is in the standard Un*x mbox format. @code{nnfolder}
12961 will add extra headers to keep track of article numbers and arrival
12964 Virtual server settings:
12967 @item nnfolder-directory
12968 @vindex nnfolder-directory
12969 All the @code{nnfolder} mail boxes will be stored under this directory.
12970 The default is the value of @code{message-directory} (whose default is
12973 @item nnfolder-active-file
12974 @vindex nnfolder-active-file
12975 The name of the active file. The default is @file{~/Mail/active}.
12977 @item nnfolder-newsgroups-file
12978 @vindex nnfolder-newsgroups-file
12979 The name of the group descriptions file. @xref{Newsgroups File
12980 Format}. The default is @file{~/Mail/newsgroups"}
12982 @item nnfolder-get-new-mail
12983 @vindex nnfolder-get-new-mail
12984 If non-@code{nil}, @code{nnfolder} will read incoming mail. The default
12987 @item nnfolder-save-buffer-hook
12988 @vindex nnfolder-save-buffer-hook
12989 @cindex backup files
12990 Hook run before saving the folders. Note that Emacs does the normal
12991 backup renaming of files even with the @code{nnfolder} buffers. If you
12992 wish to switch this off, you could say something like the following in
12993 your @file{.emacs} file:
12996 (defun turn-off-backup ()
12997 (set (make-local-variable 'backup-inhibited) t))
12999 (add-hook 'nnfolder-save-buffer-hook 'turn-off-backup)
13002 @item nnfolder-delete-mail-hook
13003 @vindex nnfolder-delete-mail-hook
13004 Hook run in a buffer narrowed to the message that is to be deleted.
13005 This function can be used to copy the message to somewhere else, or to
13006 extract some information from it before removing it.
13008 @item nnfolder-nov-is-evil
13009 @vindex nnfolder-nov-is-evil
13010 If non-@code{nil}, this backend will ignore any @sc{nov} files. The
13011 default is @code{nil}.
13016 @findex nnfolder-generate-active-file
13017 @kindex M-x nnfolder-generate-active-file
13018 If you have lots of @code{nnfolder}-like files you'd like to read with
13019 @code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
13020 command to make @code{nnfolder} aware of all likely files in
13021 @code{nnfolder-directory}. This only works if you use long file names,
13024 @node Comparing Mail Backends
13025 @subsubsection Comparing Mail Backends
13027 First, just for terminology, the @dfn{backend} is the common word for a
13028 low-level access method---a transport, if you will, by which something
13029 is acquired. The sense is that one's mail has to come from somewhere,
13030 and so selection of a suitable backend is required in order to get that
13031 mail within spitting distance of Gnus.
13033 The same concept exists for Usenet itself: Though access to articles is
13034 typically done by @sc{nntp} these days, once upon a midnight dreary, everyone
13035 in the world got at Usenet by running a reader on the machine where the
13036 articles lay (the machine which today we call an @sc{nntp} server), and
13037 access was by the reader stepping into the articles' directory spool
13038 area directly. One can still select between either the @code{nntp} or
13039 @code{nnspool} backends, to select between these methods, if one happens
13040 actually to live on the server (or can see its spool directly, anyway,
13043 The goal in selecting a mail backend is to pick one which
13044 simultaneously represents a suitable way of dealing with the original
13045 format plus leaving mail in a form that is convenient to use in the
13046 future. Here are some high and low points on each:
13051 UNIX systems have historically had a single, very common, and well-
13052 defined format. All messages arrive in a single @dfn{spool file}, and
13053 they are delineated by a line whose regular expression matches
13054 @samp{^From_}. (My notational use of @samp{_} is to indicate a space,
13055 to make it clear in this instance that this is not the RFC-specified
13056 @samp{From:} header.) Because Emacs and therefore Gnus emanate
13057 historically from the Unix environment, it is simplest if one does not
13058 mess a great deal with the original mailbox format, so if one chooses
13059 this backend, Gnus' primary activity in getting mail from the real spool
13060 area to Gnus' preferred directory is simply to copy it, with no
13061 (appreciable) format change in the process. It is the ``dumbest'' way
13062 to move mail into availability in the Gnus environment. This makes it
13063 fast to move into place, but slow to parse, when Gnus has to look at
13068 Once upon a time, there was the DEC-10 and DEC-20, running operating
13069 systems called TOPS and related things, and the usual (only?) mail
13070 reading environment was a thing called Babyl. I don't know what format
13071 was used for mail landing on the system, but Babyl had its own internal
13072 format to which mail was converted, primarily involving creating a
13073 spool-file-like entity with a scheme for inserting Babyl-specific
13074 headers and status bits above the top of each message in the file.
13075 RMAIL was Emacs' first mail reader, it was written by Richard Stallman,
13076 and Stallman came out of that TOPS/Babyl environment, so he wrote RMAIL
13077 to understand the mail files folks already had in existence. Gnus (and
13078 VM, for that matter) continue to support this format because it's
13079 perceived as having some good qualities in those mailer-specific
13080 headers/status bits stuff. RMAIL itself still exists as well, of
13081 course, and is still maintained by Stallman.
13083 Both of the above forms leave your mail in a single file on your
13084 filesystem, and they must parse that entire file each time you take a
13089 @code{nnml} is the backend which smells the most as though you were
13090 actually operating with an @code{nnspool}-accessed Usenet system. (In
13091 fact, I believe @code{nnml} actually derived from @code{nnspool} code,
13092 lo these years ago.) One's mail is taken from the original spool file,
13093 and is then cut up into individual message files, 1:1. It maintains a
13094 Usenet-style active file (analogous to what one finds in an INN- or
13095 CNews-based news system in (for instance) @file{/var/lib/news/active},
13096 or what is returned via the @samp{NNTP LIST} verb) and also creates
13097 @dfn{overview} files for efficient group entry, as has been defined for
13098 @sc{nntp} servers for some years now. It is slower in mail-splitting,
13099 due to the creation of lots of files, updates to the @code{nnml} active
13100 file, and additions to overview files on a per-message basis, but it is
13101 extremely fast on access because of what amounts to the indexing support
13102 provided by the active file and overviews.
13104 @code{nnml} costs @dfn{inodes} in a big way; that is, it soaks up the
13105 resource which defines available places in the filesystem to put new
13106 files. Sysadmins take a dim view of heavy inode occupation within
13107 tight, shared filesystems. But if you live on a personal machine where
13108 the filesystem is your own and space is not at a premium, @code{nnml}
13111 It is also problematic using this backend if you are living in a
13112 FAT16-based Windows world, since much space will be wasted on all these
13117 The Rand MH mail-reading system has been around UNIX systems for a very
13118 long time; it operates by splitting one's spool file of messages into
13119 individual files, but with little or no indexing support -- @code{nnmh}
13120 is considered to be semantically equivalent to ``@code{nnml} without
13121 active file or overviews''. This is arguably the worst choice, because
13122 one gets the slowness of individual file creation married to the
13123 slowness of access parsing when learning what's new in one's groups.
13127 Basically the effect of @code{nnfolder} is @code{nnmbox} (the first
13128 method described above) on a per-group basis. That is, @code{nnmbox}
13129 itself puts *all* one's mail in one file; @code{nnfolder} provides a
13130 little bit of optimization to this so that each of one's mail groups has
13131 a Unix mail box file. It's faster than @code{nnmbox} because each group
13132 can be parsed separately, and still provides the simple Unix mail box
13133 format requiring minimal effort in moving the mail around. In addition,
13134 it maintains an ``active'' file making it much faster for Gnus to figure
13135 out how many messages there are in each separate group.
13137 If you have groups that are expected to have a massive amount of
13138 messages, @code{nnfolder} is not the best choice, but if you receive
13139 only a moderate amount of mail, @code{nnfolder} is probably the most
13140 friendly mail backend all over.
13145 @node Browsing the Web
13146 @section Browsing the Web
13148 @cindex browsing the web
13152 Web-based discussion forums are getting more and more popular. On many
13153 subjects, the web-based forums have become the most important forums,
13154 eclipsing the importance of mailing lists and news groups. The reason
13155 is easy to understand---they are friendly to new users; you just point
13156 and click, and there's the discussion. With mailing lists, you have to
13157 go through a cumbersome subscription procedure, and most people don't
13158 even know what a news group is.
13160 The problem with this scenario is that web browsers are not very good at
13161 being newsreaders. They do not keep track of what articles you've read;
13162 they do not allow you to score on subjects you're interested in; they do
13163 not allow off-line browsing; they require you to click around and drive
13164 you mad in the end.
13166 So---if web browsers suck at reading discussion forums, why not use Gnus
13169 Gnus has been getting a bit of a collection of backends for providing
13170 interfaces to these sources.
13173 * Web Searches:: Creating groups from articles that match a string.
13174 * Slashdot:: Reading the Slashdot comments.
13175 * Ultimate:: The Ultimate Bulletin Board systems.
13176 * Web Archive:: Reading mailing list archived on web.
13177 * RSS:: Reading RDF site summary.
13178 * Customizing w3:: Doing stuff to Emacs/w3 from Gnus.
13181 All the web sources require Emacs/w3 and the url library to work.
13183 The main caveat with all these web sources is that they probably won't
13184 work for a very long time. Gleaning information from the @sc{html} data
13185 is guesswork at best, and when the layout is altered, the Gnus backend
13186 will fail. If you have reasonably new versions of these backends,
13187 though, you should be ok.
13189 One thing all these Web methods have in common is that the Web sources
13190 are often down, unavailable or just plain too slow to be fun. In those
13191 cases, it makes a lot of sense to let the Gnus Agent (@pxref{Gnus
13192 Unplugged}) handle downloading articles, and then you can read them at
13193 leisure from your local disk. No more World Wide Wait for you.
13197 @subsection Web Searches
13201 @cindex InReference
13202 @cindex Usenet searches
13203 @cindex searching the Usenet
13205 It's, like, too neat to search the Usenet for articles that match a
13206 string, but it, like, totally @emph{sucks}, like, totally, to use one of
13207 those, like, Web browsers, and you, like, have to, rilly, like, look at
13208 the commercials, so, like, with Gnus you can do @emph{rad}, rilly,
13209 searches without having to use a browser.
13211 The @code{nnweb} backend allows an easy interface to the mighty search
13212 engine. You create an @code{nnweb} group, enter a search pattern, and
13213 then enter the group and read the articles like you would any normal
13214 group. The @kbd{G w} command in the group buffer (@pxref{Foreign
13215 Groups}) will do this in an easy-to-use fashion.
13217 @code{nnweb} groups don't really lend themselves to being solid
13218 groups---they have a very fleeting idea of article numbers. In fact,
13219 each time you enter an @code{nnweb} group (not even changing the search
13220 pattern), you are likely to get the articles ordered in a different
13221 manner. Not even using duplicate suppression (@pxref{Duplicate
13222 Suppression}) will help, since @code{nnweb} doesn't even know the
13223 @code{Message-ID} of the articles before reading them using some search
13224 engines (DejaNews, for instance). The only possible way to keep track
13225 of which articles you've read is by scoring on the @code{Date}
13226 header---mark all articles posted before the last date you read the
13229 If the search engine changes its output substantially, @code{nnweb}
13230 won't be able to parse it and will fail. One could hardly fault the Web
13231 providers if they were to do this---their @emph{raison d'être} is to
13232 make money off of advertisements, not to provide services to the
13233 community. Since @code{nnweb} washes the ads off all the articles, one
13234 might think that the providers might be somewhat miffed. We'll see.
13236 You must have the @code{url} and @code{w3} package installed to be able
13237 to use @code{nnweb}.
13239 Virtual server variables:
13244 What search engine type is being used. The currently supported types
13245 are @code{dejanews}, @code{dejanewsold}, @code{altavista} and
13249 @vindex nnweb-search
13250 The search string to feed to the search engine.
13252 @item nnweb-max-hits
13253 @vindex nnweb-max-hits
13254 Advisory maximum number of hits per search to display. The default is
13257 @item nnweb-type-definition
13258 @vindex nnweb-type-definition
13259 Type-to-definition alist. This alist says what @code{nnweb} should do
13260 with the various search engine types. The following elements must be
13265 Function to decode the article and provide something that Gnus
13269 Function to create an article number to message header and URL alist.
13272 Function to send the search string to the search engine.
13275 The address the aforementioned function should send the search string
13279 Format string URL to fetch an article by @code{Message-ID}.
13286 @subsection Slashdot
13290 Slashdot (@uref{http://slashdot.org/}) is a popular news site, with
13291 lively discussion following the news articles. @code{nnslashdot} will
13292 let you read this forum in a convenient manner.
13294 The easiest way to read this source is to put something like the
13295 following in your @file{.gnus.el} file:
13298 (setq gnus-secondary-select-methods
13299 '((nnslashdot "")))
13302 This will make Gnus query the @code{nnslashdot} backend for new comments
13303 and groups. The @kbd{F} command will subscribe each new news article as
13304 a new Gnus group, and you can read the comments by entering these
13305 groups. (Note that the default subscription method is to subscribe new
13306 groups as zombies. Other methods are available (@pxref{Subscription
13309 If you want to remove an old @code{nnslashdot} group, the @kbd{G DEL}
13310 command is the most handy tool (@pxref{Foreign Groups}).
13312 When following up to @code{nnslashdot} comments (or posting new
13313 comments), some light @sc{html}izations will be performed. In
13314 particular, text quoted with @samp{> } will be quoted with
13315 @code{blockquote} instead, and signatures will have @code{br} added to
13316 the end of each line. Other than that, you can just write @sc{html}
13317 directly into the message buffer. Note that Slashdot filters out some
13320 The following variables can be altered to change its behavior:
13323 @item nnslashdot-threaded
13324 Whether @code{nnslashdot} should display threaded groups or not. The
13325 default is @code{t}. To be able to display threads, @code{nnslashdot}
13326 has to retrieve absolutely all comments in a group upon entry. If a
13327 threaded display is not required, @code{nnslashdot} will only retrieve
13328 the comments that are actually wanted by the user. Threading is nicer,
13329 but much, much slower than untreaded.
13331 @item nnslashdot-login-name
13332 @vindex nnslashdot-login-name
13333 The login name to use when posting.
13335 @item nnslashdot-password
13336 @vindex nnslashdot-password
13337 The password to use when posting.
13339 @item nnslashdot-directory
13340 @vindex nnslashdot-directory
13341 Where @code{nnslashdot} will store its files. The default is
13342 @samp{~/News/slashdot/}.
13344 @item nnslashdot-active-url
13345 @vindex nnslashdot-active-url
13346 The @sc{url} format string that will be used to fetch the information on
13347 news articles and comments. The default is
13348 @samp{http://slashdot.org/search.pl?section=&min=%d}.
13350 @item nnslashdot-comments-url
13351 @vindex nnslashdot-comments-url
13352 The @sc{url} format string that will be used to fetch comments. The
13354 @samp{http://slashdot.org/comments.pl?sid=%s&threshold=%d&commentsort=%d&mode=flat&startat=%d}.
13356 @item nnslashdot-article-url
13357 @vindex nnslashdot-article-url
13358 The @sc{url} format string that will be used to fetch the news article. The
13360 @samp{http://slashdot.org/article.pl?sid=%s&mode=nocomment}.
13362 @item nnslashdot-threshold
13363 @vindex nnslashdot-threshold
13364 The score threshold. The default is -1.
13366 @item nnslashdot-group-number
13367 @vindex nnslashdot-group-number
13368 The number of old groups, in addition to the ten latest, to keep
13369 updated. The default is 0.
13376 @subsection Ultimate
13378 @cindex Ultimate Bulletin Board
13380 The Ultimate Bulletin Board (@uref{http://www.ultimatebb.com/}) is
13381 probably the most popular Web bulletin board system used. It has a
13382 quite regular and nice interface, and it's possible to get the
13383 information Gnus needs to keep groups updated.
13385 The easiest way to get started with @code{nnultimate} is to say
13386 something like the following in the group buffer: @kbd{B nnultimate RET
13387 http://www.tcj.com/messboard/ubbcgi/ RET}. (Substitute the @sc{url}
13388 (not including @samp{Ultimate.cgi} or the like at the end) for a forum
13389 you're interested in; there's quite a list of them on the Ultimate web
13390 site.) Then subscribe to the groups you're interested in from the
13391 server buffer, and read them from the group buffer.
13393 The following @code{nnultimate} variables can be altered:
13396 @item nnultimate-directory
13397 @vindex nnultimate-directory
13398 The directory where @code{nnultimate} stores its files. The default is
13399 @samp{~/News/ultimate/}.
13404 @subsection Web Archive
13406 @cindex Web Archive
13408 Some mailing lists only have archives on Web servers, such as
13409 @uref{http://www.egroups.com/} and
13410 @uref{http://www.mail-archive.com/}. It has a quite regular and nice
13411 interface, and it's possible to get the information Gnus needs to keep
13414 The easiest way to get started with @code{nnwarchive} is to say
13415 something like the following in the group buffer: @kbd{M-x
13416 gnus-group-make-warchive-group RET an_egroup RET egroups RET
13417 www.egroups.com RET your@@email.address RET}. (Substitute the
13418 @sc{an_egroup} with the mailing list you subscribed, the
13419 @sc{your@@email.address} with your email address.), or to browse the
13420 backend by @kbd{B nnwarchive RET mail-archive RET}.
13422 The following @code{nnwarchive} variables can be altered:
13425 @item nnwarchive-directory
13426 @vindex nnwarchive-directory
13427 The directory where @code{nnwarchive} stores its files. The default is
13428 @samp{~/News/warchive/}.
13430 @item nnwarchive-login
13431 @vindex nnwarchive-login
13432 The account name on the web server.
13434 @item nnwarchive-passwd
13435 @vindex nnwarchive-passwd
13436 The password for your account on the web server.
13444 Some sites have RDF site summary (RSS)
13445 @uref{http://purl.org/rss/1.0/spec}. It has a quite regular and nice
13446 interface, and it's possible to get the information Gnus needs to keep
13449 The easiest way to get started with @code{nnrss} is to say something
13450 like the following in the group buffer: @kbd{B nnrss RET RET}, then
13453 The following @code{nnrss} variables can be altered:
13456 @item nnrss-directory
13457 @vindex nnrss-directory
13458 The directory where @code{nnrss} stores its files. The default is
13459 @samp{~/News/rss/}.
13463 The following code may be helpful, if you want to show the description in
13464 the summary buffer.
13467 (add-to-list 'nnmail-extra-headers nnrss-description-field)
13468 (setq gnus-summary-line-format "%U%R%z%I%(%[%4L: %-15,15f%]%) %s%uX\n")
13470 (defun gnus-user-format-function-X (header)
13472 (assq nnrss-description-field (mail-header-extra header))))
13473 (if descr (concat "\n\t" (cdr descr)) "")))
13476 The following code may be useful to open an nnrss url directly from the
13479 (require 'browse-url)
13481 (defun browse-nnrss-url( arg )
13483 (let ((url (assq nnrss-url-field
13486 (assq (gnus-summary-article-number)
13487 gnus-newsgroup-data))))))
13489 (browse-url (cdr url))
13490 (gnus-summary-scroll-up arg))))
13492 (eval-after-load "gnus"
13493 #'(define-key gnus-summary-mode-map
13494 (kbd "<RET>") 'browse-nnrss-url))
13495 (add-to-list 'nnmail-extra-headers nnrss-url-field)
13498 @node Customizing w3
13499 @subsection Customizing w3
13505 Gnus uses the url library to fetch web pages and Emacs/w3 to display web
13506 pages. Emacs/w3 is documented in its own manual, but there are some
13507 things that may be more relevant for Gnus users.
13509 For instance, a common question is how to make Emacs/w3 follow links
13510 using the @code{browse-url} functions (which will call some external web
13511 browser like Netscape). Here's one way:
13514 (eval-after-load "w3"
13516 (fset 'w3-fetch-orig (symbol-function 'w3-fetch))
13517 (defun w3-fetch (&optional url target)
13518 (interactive (list (w3-read-url-with-default)))
13519 (if (eq major-mode 'gnus-article-mode)
13521 (w3-fetch-orig url target)))))
13524 Put that in your @file{.emacs} file, and hitting links in w3-rendered
13525 @sc{html} in the Gnus article buffers will use @code{browse-url} to
13529 @node Other Sources
13530 @section Other Sources
13532 Gnus can do more than just read news or mail. The methods described
13533 below allow Gnus to view directories and files as if they were
13537 * Directory Groups:: You can read a directory as if it was a newsgroup.
13538 * Anything Groups:: Dired? Who needs dired?
13539 * Document Groups:: Single files can be the basis of a group.
13540 * SOUP:: Reading @sc{soup} packets ``offline''.
13541 * Mail-To-News Gateways:: Posting articles via mail-to-news gateways.
13542 * IMAP:: Using Gnus as a @sc{imap} client.
13546 @node Directory Groups
13547 @subsection Directory Groups
13549 @cindex directory groups
13551 If you have a directory that has lots of articles in separate files in
13552 it, you might treat it as a newsgroup. The files have to have numerical
13555 This might be an opportune moment to mention @code{ange-ftp} (and its
13556 successor @code{efs}), that most wonderful of all wonderful Emacs
13557 packages. When I wrote @code{nndir}, I didn't think much about it---a
13558 backend to read directories. Big deal.
13560 @code{ange-ftp} changes that picture dramatically. For instance, if you
13561 enter the @code{ange-ftp} file name
13562 @file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name,
13563 @code{ange-ftp} or @code{efs} will actually allow you to read this
13564 directory over at @samp{sina} as a newsgroup. Distributed news ahoy!
13566 @code{nndir} will use @sc{nov} files if they are present.
13568 @code{nndir} is a ``read-only'' backend---you can't delete or expire
13569 articles with this method. You can use @code{nnmh} or @code{nnml} for
13570 whatever you use @code{nndir} for, so you could switch to any of those
13571 methods if you feel the need to have a non-read-only @code{nndir}.
13574 @node Anything Groups
13575 @subsection Anything Groups
13578 From the @code{nndir} backend (which reads a single spool-like
13579 directory), it's just a hop and a skip to @code{nneething}, which
13580 pretends that any arbitrary directory is a newsgroup. Strange, but
13583 When @code{nneething} is presented with a directory, it will scan this
13584 directory and assign article numbers to each file. When you enter such
13585 a group, @code{nneething} must create ``headers'' that Gnus can use.
13586 After all, Gnus is a newsreader, in case you're forgetting.
13587 @code{nneething} does this in a two-step process. First, it snoops each
13588 file in question. If the file looks like an article (i.e., the first
13589 few lines look like headers), it will use this as the head. If this is
13590 just some arbitrary file without a head (e.g. a C source file),
13591 @code{nneething} will cobble up a header out of thin air. It will use
13592 file ownership, name and date and do whatever it can with these
13595 All this should happen automatically for you, and you will be presented
13596 with something that looks very much like a newsgroup. Totally like a
13597 newsgroup, to be precise. If you select an article, it will be displayed
13598 in the article buffer, just as usual.
13600 If you select a line that represents a directory, Gnus will pop you into
13601 a new summary buffer for this @code{nneething} group. And so on. You can
13602 traverse the entire disk this way, if you feel like, but remember that
13603 Gnus is not dired, really, and does not intend to be, either.
13605 There are two overall modes to this action---ephemeral or solid. When
13606 doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
13607 will not store information on what files you have read, and what files
13608 are new, and so on. If you create a solid @code{nneething} group the
13609 normal way with @kbd{G m}, Gnus will store a mapping table between
13610 article numbers and file names, and you can treat this group like any
13611 other groups. When you activate a solid @code{nneething} group, you will
13612 be told how many unread articles it contains, etc., etc.
13617 @item nneething-map-file-directory
13618 @vindex nneething-map-file-directory
13619 All the mapping files for solid @code{nneething} groups will be stored
13620 in this directory, which defaults to @file{~/.nneething/}.
13622 @item nneething-exclude-files
13623 @vindex nneething-exclude-files
13624 All files that match this regexp will be ignored. Nice to use to exclude
13625 auto-save files and the like, which is what it does by default.
13627 @item nneething-include-files
13628 @vindex nneething-include-files
13629 Regexp saying what files to include in the group. If this variable is
13630 non-@code{nil}, only files matching this regexp will be included.
13632 @item nneething-map-file
13633 @vindex nneething-map-file
13634 Name of the map files.
13638 @node Document Groups
13639 @subsection Document Groups
13641 @cindex documentation group
13644 @code{nndoc} is a cute little thing that will let you read a single file
13645 as a newsgroup. Several files types are supported:
13652 The babyl (rmail) mail box.
13657 The standard Unix mbox file.
13659 @cindex MMDF mail box
13661 The MMDF mail box format.
13664 Several news articles appended into a file.
13667 @cindex rnews batch files
13668 The rnews batch transport format.
13669 @cindex forwarded messages
13672 Forwarded articles.
13675 Netscape mail boxes.
13678 MIME multipart messages.
13680 @item standard-digest
13681 The standard (RFC 1153) digest format.
13684 Non-standard digest format---matches most things, but does it badly.
13687 You can also use the special ``file type'' @code{guess}, which means
13688 that @code{nndoc} will try to guess what file type it is looking at.
13689 @code{digest} means that @code{nndoc} should guess what digest type the
13692 @code{nndoc} will not try to change the file or insert any extra headers into
13693 it---it will simply, like, let you use the file as the basis for a
13694 group. And that's it.
13696 If you have some old archived articles that you want to insert into your
13697 new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
13698 that. Say you have an old @file{RMAIL} file with mail that you now want
13699 to split into your new @code{nnml} groups. You look at that file using
13700 @code{nndoc} (using the @kbd{G f} command in the group buffer
13701 (@pxref{Foreign Groups})), set the process mark on all the articles in
13702 the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r})
13703 using @code{nnml}. If all goes well, all the mail in the @file{RMAIL}
13704 file is now also stored in lots of @code{nnml} directories, and you can
13705 delete that pesky @file{RMAIL} file. If you have the guts!
13707 Virtual server variables:
13710 @item nndoc-article-type
13711 @vindex nndoc-article-type
13712 This should be one of @code{mbox}, @code{babyl}, @code{digest},
13713 @code{news}, @code{rnews}, @code{mmdf}, @code{forward}, @code{rfc934},
13714 @code{rfc822-forward}, @code{mime-parts}, @code{standard-digest},
13715 @code{slack-digest}, @code{clari-briefs}, @code{nsmail} or @code{guess}.
13717 @item nndoc-post-type
13718 @vindex nndoc-post-type
13719 This variable says whether Gnus is to consider the group a news group or
13720 a mail group. There are two valid values: @code{mail} (the default)
13725 * Document Server Internals:: How to add your own document types.
13729 @node Document Server Internals
13730 @subsubsection Document Server Internals
13732 Adding new document types to be recognized by @code{nndoc} isn't
13733 difficult. You just have to whip up a definition of what the document
13734 looks like, write a predicate function to recognize that document type,
13735 and then hook into @code{nndoc}.
13737 First, here's an example document type definition:
13741 (article-begin . "^\^A\^A\^A\^A\n")
13742 (body-end . "^\^A\^A\^A\^A\n"))
13745 The definition is simply a unique @dfn{name} followed by a series of
13746 regexp pseudo-variable settings. Below are the possible
13747 variables---don't be daunted by the number of variables; most document
13748 types can be defined with very few settings:
13751 @item first-article
13752 If present, @code{nndoc} will skip past all text until it finds
13753 something that match this regexp. All text before this will be
13756 @item article-begin
13757 This setting has to be present in all document type definitions. It
13758 says what the beginning of each article looks like.
13760 @item head-begin-function
13761 If present, this should be a function that moves point to the head of
13764 @item nndoc-head-begin
13765 If present, this should be a regexp that matches the head of the
13768 @item nndoc-head-end
13769 This should match the end of the head of the article. It defaults to
13770 @samp{^$}---the empty line.
13772 @item body-begin-function
13773 If present, this function should move point to the beginning of the body
13777 This should match the beginning of the body of the article. It defaults
13780 @item body-end-function
13781 If present, this function should move point to the end of the body of
13785 If present, this should match the end of the body of the article.
13788 If present, this should match the end of the file. All text after this
13789 regexp will be totally ignored.
13793 So, using these variables @code{nndoc} is able to dissect a document
13794 file into a series of articles, each with a head and a body. However, a
13795 few more variables are needed since not all document types are all that
13796 news-like---variables needed to transform the head or the body into
13797 something that's palatable for Gnus:
13800 @item prepare-body-function
13801 If present, this function will be called when requesting an article. It
13802 will be called with point at the start of the body, and is useful if the
13803 document has encoded some parts of its contents.
13805 @item article-transform-function
13806 If present, this function is called when requesting an article. It's
13807 meant to be used for more wide-ranging transformation of both head and
13808 body of the article.
13810 @item generate-head-function
13811 If present, this function is called to generate a head that Gnus can
13812 understand. It is called with the article number as a parameter, and is
13813 expected to generate a nice head for the article in question. It is
13814 called when requesting the headers of all articles.
13818 Let's look at the most complicated example I can come up with---standard
13823 (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+"))
13824 (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+"))
13825 (prepare-body-function . nndoc-unquote-dashes)
13826 (body-end-function . nndoc-digest-body-end)
13827 (head-end . "^ ?$")
13828 (body-begin . "^ ?\n")
13829 (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$")
13830 (subtype digest guess))
13833 We see that all text before a 70-width line of dashes is ignored; all
13834 text after a line that starts with that @samp{^End of} is also ignored;
13835 each article begins with a 30-width line of dashes; the line separating
13836 the head from the body may contain a single space; and that the body is
13837 run through @code{nndoc-unquote-dashes} before being delivered.
13839 To hook your own document definition into @code{nndoc}, use the
13840 @code{nndoc-add-type} function. It takes two parameters---the first is
13841 the definition itself and the second (optional) parameter says where in
13842 the document type definition alist to put this definition. The alist is
13843 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
13844 is of @code{mmdf} type, and so on. These type predicates should return
13845 @code{nil} if the document is not of the correct type; @code{t} if it is
13846 of the correct type; and a number if the document might be of the
13847 correct type. A high number means high probability; a low number means
13848 low probability with @samp{0} being the lowest valid number.
13856 In the PC world people often talk about ``offline'' newsreaders. These
13857 are thingies that are combined reader/news transport monstrosities.
13858 With built-in modem programs. Yecchh!
13860 Of course, us Unix Weenie types of human beans use things like
13861 @code{uucp} and, like, @code{nntpd} and set up proper news and mail
13862 transport things like Ghod intended. And then we just use normal
13865 However, it can sometimes be convenient to do something that's a bit
13866 easier on the brain if you have a very slow modem, and you're not really
13867 that interested in doing things properly.
13869 A file format called @sc{soup} has been developed for transporting news
13870 and mail from servers to home machines and back again. It can be a bit
13873 First some terminology:
13878 This is the machine that is connected to the outside world and where you
13879 get news and/or mail from.
13882 This is the machine that you want to do the actual reading and responding
13883 on. It is typically not connected to the rest of the world in any way.
13886 Something that contains messages and/or commands. There are two kinds
13890 @item message packets
13891 These are packets made at the server, and typically contain lots of
13892 messages for you to read. These are called @file{SoupoutX.tgz} by
13893 default, where @var{x} is a number.
13895 @item response packets
13896 These are packets made at the home machine, and typically contains
13897 replies that you've written. These are called @file{SoupinX.tgz} by
13898 default, where @var{x} is a number.
13908 You log in on the server and create a @sc{soup} packet. You can either
13909 use a dedicated @sc{soup} thingie (like the @code{awk} program), or you
13910 can use Gnus to create the packet with its @sc{soup} commands (@kbd{O
13911 s} and/or @kbd{G s b}; and then @kbd{G s p}) (@pxref{SOUP Commands}).
13914 You transfer the packet home. Rail, boat, car or modem will do fine.
13917 You put the packet in your home directory.
13920 You fire up Gnus on your home machine using the @code{nnsoup} backend as
13921 the native or secondary server.
13924 You read articles and mail and answer and followup to the things you
13925 want (@pxref{SOUP Replies}).
13928 You do the @kbd{G s r} command to pack these replies into a @sc{soup}
13932 You transfer this packet to the server.
13935 You use Gnus to mail this packet out with the @kbd{G s s} command.
13938 You then repeat until you die.
13942 So you basically have a bipartite system---you use @code{nnsoup} for
13943 reading and Gnus for packing/sending these @sc{soup} packets.
13946 * SOUP Commands:: Commands for creating and sending @sc{soup} packets
13947 * SOUP Groups:: A backend for reading @sc{soup} packets.
13948 * SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
13952 @node SOUP Commands
13953 @subsubsection SOUP Commands
13955 These are commands for creating and manipulating @sc{soup} packets.
13959 @kindex G s b (Group)
13960 @findex gnus-group-brew-soup
13961 Pack all unread articles in the current group
13962 (@code{gnus-group-brew-soup}). This command understands the
13963 process/prefix convention.
13966 @kindex G s w (Group)
13967 @findex gnus-soup-save-areas
13968 Save all @sc{soup} data files (@code{gnus-soup-save-areas}).
13971 @kindex G s s (Group)
13972 @findex gnus-soup-send-replies
13973 Send all replies from the replies packet
13974 (@code{gnus-soup-send-replies}).
13977 @kindex G s p (Group)
13978 @findex gnus-soup-pack-packet
13979 Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
13982 @kindex G s r (Group)
13983 @findex nnsoup-pack-replies
13984 Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
13987 @kindex O s (Summary)
13988 @findex gnus-soup-add-article
13989 This summary-mode command adds the current article to a @sc{soup} packet
13990 (@code{gnus-soup-add-article}). It understands the process/prefix
13991 convention (@pxref{Process/Prefix}).
13996 There are a few variables to customize where Gnus will put all these
14001 @item gnus-soup-directory
14002 @vindex gnus-soup-directory
14003 Directory where Gnus will save intermediate files while composing
14004 @sc{soup} packets. The default is @file{~/SoupBrew/}.
14006 @item gnus-soup-replies-directory
14007 @vindex gnus-soup-replies-directory
14008 This is what Gnus will use as a temporary directory while sending our
14009 reply packets. @file{~/SoupBrew/SoupReplies/} is the default.
14011 @item gnus-soup-prefix-file
14012 @vindex gnus-soup-prefix-file
14013 Name of the file where Gnus stores the last used prefix. The default is
14014 @samp{gnus-prefix}.
14016 @item gnus-soup-packer
14017 @vindex gnus-soup-packer
14018 A format string command for packing a @sc{soup} packet. The default is
14019 @samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}.
14021 @item gnus-soup-unpacker
14022 @vindex gnus-soup-unpacker
14023 Format string command for unpacking a @sc{soup} packet. The default is
14024 @samp{gunzip -c %s | tar xvf -}.
14026 @item gnus-soup-packet-directory
14027 @vindex gnus-soup-packet-directory
14028 Where Gnus will look for reply packets. The default is @file{~/}.
14030 @item gnus-soup-packet-regexp
14031 @vindex gnus-soup-packet-regexp
14032 Regular expression matching @sc{soup} reply packets in
14033 @code{gnus-soup-packet-directory}.
14039 @subsubsection @sc{soup} Groups
14042 @code{nnsoup} is the backend for reading @sc{soup} packets. It will
14043 read incoming packets, unpack them, and put them in a directory where
14044 you can read them at leisure.
14046 These are the variables you can use to customize its behavior:
14050 @item nnsoup-tmp-directory
14051 @vindex nnsoup-tmp-directory
14052 When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this
14053 directory. (@file{/tmp/} by default.)
14055 @item nnsoup-directory
14056 @vindex nnsoup-directory
14057 @code{nnsoup} then moves each message and index file to this directory.
14058 The default is @file{~/SOUP/}.
14060 @item nnsoup-replies-directory
14061 @vindex nnsoup-replies-directory
14062 All replies will be stored in this directory before being packed into a
14063 reply packet. The default is @file{~/SOUP/replies/"}.
14065 @item nnsoup-replies-format-type
14066 @vindex nnsoup-replies-format-type
14067 The @sc{soup} format of the replies packets. The default is @samp{?n}
14068 (rnews), and I don't think you should touch that variable. I probably
14069 shouldn't even have documented it. Drats! Too late!
14071 @item nnsoup-replies-index-type
14072 @vindex nnsoup-replies-index-type
14073 The index type of the replies packet. The default is @samp{?n}, which
14074 means ``none''. Don't fiddle with this one either!
14076 @item nnsoup-active-file
14077 @vindex nnsoup-active-file
14078 Where @code{nnsoup} stores lots of information. This is not an ``active
14079 file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
14080 this file or mess it up in any way, you're dead. The default is
14081 @file{~/SOUP/active}.
14083 @item nnsoup-packer
14084 @vindex nnsoup-packer
14085 Format string command for packing a reply @sc{soup} packet. The default
14086 is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}.
14088 @item nnsoup-unpacker
14089 @vindex nnsoup-unpacker
14090 Format string command for unpacking incoming @sc{soup} packets. The
14091 default is @samp{gunzip -c %s | tar xvf -}.
14093 @item nnsoup-packet-directory
14094 @vindex nnsoup-packet-directory
14095 Where @code{nnsoup} will look for incoming packets. The default is
14098 @item nnsoup-packet-regexp
14099 @vindex nnsoup-packet-regexp
14100 Regular expression matching incoming @sc{soup} packets. The default is
14103 @item nnsoup-always-save
14104 @vindex nnsoup-always-save
14105 If non-@code{nil}, save the replies buffer after each posted message.
14111 @subsubsection SOUP Replies
14113 Just using @code{nnsoup} won't mean that your postings and mailings end
14114 up in @sc{soup} reply packets automagically. You have to work a bit
14115 more for that to happen.
14117 @findex nnsoup-set-variables
14118 The @code{nnsoup-set-variables} command will set the appropriate
14119 variables to ensure that all your followups and replies end up in the
14122 In specific, this is what it does:
14125 (setq message-send-news-function 'nnsoup-request-post)
14126 (setq message-send-mail-function 'nnsoup-request-mail)
14129 And that's it, really. If you only want news to go into the @sc{soup}
14130 system you just use the first line. If you only want mail to be
14131 @sc{soup}ed you use the second.
14134 @node Mail-To-News Gateways
14135 @subsection Mail-To-News Gateways
14136 @cindex mail-to-news gateways
14139 If your local @code{nntp} server doesn't allow posting, for some reason
14140 or other, you can post using one of the numerous mail-to-news gateways.
14141 The @code{nngateway} backend provides the interface.
14143 Note that you can't read anything from this backend---it can only be
14149 @item nngateway-address
14150 @vindex nngateway-address
14151 This is the address of the mail-to-news gateway.
14153 @item nngateway-header-transformation
14154 @vindex nngateway-header-transformation
14155 News headers often have to be transformed in some odd way or other
14156 for the mail-to-news gateway to accept it. This variable says what
14157 transformation should be called, and defaults to
14158 @code{nngateway-simple-header-transformation}. The function is called
14159 narrowed to the headers to be transformed and with one parameter---the
14162 This default function just inserts a new @code{To} header based on the
14163 @code{Newsgroups} header and the gateway address.
14164 For instance, an article with this @code{Newsgroups} header:
14167 Newsgroups: alt.religion.emacs
14170 will get this @code{From} header inserted:
14173 To: alt-religion-emacs@@GATEWAY
14176 The following pre-defined functions exist:
14178 @findex nngateway-simple-header-transformation
14181 @item nngateway-simple-header-transformation
14182 Creates a @code{To} header that looks like
14183 @var{newsgroup}@@@code{nngateway-address}.
14185 @findex nngateway-mail2news-header-transformation
14187 @item nngateway-mail2news-header-transformation
14188 Creates a @code{To} header that looks like
14189 @code{nngateway-address}.
14194 (setq gnus-post-method
14196 "mail2news@@replay.com"
14197 (nngateway-header-transformation
14198 nngateway-mail2news-header-transformation)))
14206 So, to use this, simply say something like:
14209 (setq gnus-post-method '(nngateway "GATEWAY.ADDRESS"))
14215 @subsection @sc{imap}
14219 @sc{imap} is a network protocol for reading mail (or news, or ...),
14220 think of it as a modernized @sc{nntp}. Connecting to a @sc{imap}
14221 server is much similar to connecting to a news server, you just
14222 specify the network address of the server.
14224 @sc{imap} has two properties. First, @sc{imap} can do everything that
14225 POP can, it can hence be viewed as POP++. Secondly, @sc{imap} is a
14226 mail storage protocol, similar to @sc{nntp} being a news storage
14227 protocol. (@sc{imap} offers more features than @sc{nntp} because news
14228 is more or less read-only whereas mail is read-write.)
14230 If you want to use @sc{imap} as POP++, use an imap entry in
14231 mail-sources. With this, Gnus will fetch mails from the @sc{imap}
14232 server and store them on the local disk. This is not the usage
14233 described in this section. @xref{Mail Sources}.
14235 If you want to use @sc{imap} as a mail storage protocol, use an nnimap
14236 entry in gnus-secondary-select-methods. With this, Gnus will
14237 manipulate mails stored on the @sc{imap} server. This is the kind of
14238 usage explained in this section.
14240 A server configuration in @code{~/.gnus} with a few @sc{imap} servers
14241 might look something like this:
14244 (setq gnus-secondary-select-methods
14245 '((nnimap "simpleserver") ; no special configuration
14246 ; perhaps a ssh port forwarded server:
14248 (nnimap-address "localhost")
14249 (nnimap-server-port 1430))
14250 ; a UW server running on localhost
14252 (nnimap-server-port 143)
14253 (nnimap-address "localhost")
14254 (nnimap-list-pattern ("INBOX" "mail/*")))
14255 ; anonymous public cyrus server:
14256 (nnimap "cyrus.andrew.cmu.edu"
14257 (nnimap-authenticator anonymous)
14258 (nnimap-list-pattern "archive.*")
14259 (nnimap-stream network))
14260 ; a ssl server on a non-standard port:
14262 (nnimap-address "vic20.somewhere.com")
14263 (nnimap-server-port 9930)
14264 (nnimap-stream ssl))))
14267 The following variables can be used to create a virtual @code{nnimap}
14272 @item nnimap-address
14273 @vindex nnimap-address
14275 The address of the remote @sc{imap} server. Defaults to the virtual
14276 server name if not specified.
14278 @item nnimap-server-port
14279 @vindex nnimap-server-port
14280 Port on server to contact. Defaults to port 143, or 993 for SSL.
14282 Note that this should be a integer, example server specification:
14285 (nnimap "mail.server.com"
14286 (nnimap-server-port 4711))
14289 @item nnimap-list-pattern
14290 @vindex nnimap-list-pattern
14291 String or list of strings of mailboxes to limit available groups to.
14292 This is used when the server has very many mailboxes and you're only
14293 interested in a few -- some servers export your home directory via
14294 @sc{imap}, you'll probably want to limit the mailboxes to those in
14295 @file{~/Mail/*} then.
14297 The string can also be a cons of REFERENCE and the string as above, what
14298 REFERENCE is used for is server specific, but on the University of
14299 Washington server it's a directory that will be concatenated with the
14302 Example server specification:
14305 (nnimap "mail.server.com"
14306 (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*"
14307 ("~friend/Mail/" . "list/*"))))
14310 @item nnimap-stream
14311 @vindex nnimap-stream
14312 The type of stream used to connect to your server. By default, nnimap
14313 will detect and automatically use all of the below, with the exception
14314 of SSL. (SSL is being replaced by STARTTLS, which can be automatically
14315 detected, but it's not widely deployed yet).
14317 Example server specification:
14320 (nnimap "mail.server.com"
14321 (nnimap-stream ssl))
14324 Please note that the value of @code{nnimap-stream} is a symbol!
14328 @dfn{gssapi:} Connect with GSSAPI (usually kerberos 5). Requires the
14329 @samp{imtest} program.
14331 @dfn{kerberos4:} Connect with kerberos 4. Requires the @samp{imtest} program.
14333 @dfn{starttls:} Connect via the STARTTLS extension (similar to
14334 SSL). Requires the external library @samp{starttls.el} and program
14337 @dfn{ssl:} Connect through SSL. Requires OpenSSL (the
14338 program @samp{openssl}) or SSLeay (@samp{s_client}).
14340 @dfn{shell:} Use a shell command to start @sc{imap} connection.
14342 @dfn{network:} Plain, TCP/IP network connection.
14345 @vindex imap-kerberos4-program
14346 The @samp{imtest} program is shipped with Cyrus IMAPD. If you're
14347 using @samp{imtest} from Cyrus IMAPD < 2.0.14 (which includes version
14348 1.5.x and 1.6.x) you need to frob @code{imap-process-connection-type}
14349 to make @code{imap.el} use a pty instead of a pipe when communicating
14350 with @samp{imtest}. You will then suffer from a line length
14351 restrictions on IMAP commands, which might make Gnus seem to hang
14352 indefinitely if you have many articles in a mailbox. The variable
14353 @code{imap-kerberos4-program} contain parameters to pass to the imtest
14356 @vindex imap-ssl-program
14357 For SSL connections, the OpenSSL program is available from
14358 @uref{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay,
14359 and nnimap support it too - although the most recent versions of
14360 SSLeay, 0.9.x, are known to have serious bugs making it
14361 useless. Earlier versions, especially 0.8.x, of SSLeay are known to
14362 work. The variable @code{imap-ssl-program} contain parameters to pass
14365 @vindex imap-shell-program
14366 @vindex imap-shell-host
14367 For @sc{imap} connections using the @code{shell} stream, the variable
14368 @code{imap-shell-program} specify what program to call.
14370 @item nnimap-authenticator
14371 @vindex nnimap-authenticator
14373 The authenticator used to connect to the server. By default, nnimap
14374 will use the most secure authenticator your server is capable of.
14376 Example server specification:
14379 (nnimap "mail.server.com"
14380 (nnimap-authenticator anonymous))
14383 Please note that the value of @code{nnimap-authenticator} is a symbol!
14387 @dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Require
14388 external program @code{imtest}.
14390 @dfn{kerberos4:} Kerberos authentication. Require external program
14393 @dfn{digest-md5:} Encrypted username/password via DIGEST-MD5. Require
14394 external library @code{digest-md5.el}.
14396 @dfn{cram-md5:} Encrypted username/password via CRAM-MD5.
14398 @dfn{login:} Plain-text username/password via LOGIN.
14400 @dfn{anonymous:} Login as `anonymous', supplying your emailadress as password.
14403 @item nnimap-expunge-on-close
14405 @vindex nnimap-expunge-on-close
14406 Unlike Parmenides the @sc{imap} designers has decided that things that
14407 doesn't exist actually does exist. More specifically, @sc{imap} has
14408 this concept of marking articles @code{Deleted} which doesn't actually
14409 delete them, and this (marking them @code{Deleted}, that is) is what
14410 nnimap does when you delete a article in Gnus (with @kbd{G DEL} or
14413 Since the articles aren't really removed when we mark them with the
14414 @code{Deleted} flag we'll need a way to actually delete them. Feel like
14415 running in circles yet?
14417 Traditionally, nnimap has removed all articles marked as @code{Deleted}
14418 when closing a mailbox but this is now configurable by this server
14421 The possible options are:
14426 The default behavior, delete all articles marked as "Deleted" when
14429 Never actually delete articles. Currently there is no way of showing
14430 the articles marked for deletion in nnimap, but other @sc{imap} clients
14431 may allow you to do this. If you ever want to run the EXPUNGE command
14432 manually, @xref{Expunging mailboxes}.
14434 When closing mailboxes, nnimap will ask if you wish to expunge deleted
14439 @item nnimap-importantize-dormant
14440 @vindex nnimap-importantize-dormant
14442 If non-nil, marks dormant articles as ticked (as well), for other IMAP
14443 clients. Within Gnus, dormant articles will naturally still (only) be
14444 marked as ticked. This is to make dormant articles stand out, just
14445 like ticked articles, in other IMAP clients. (In other words, Gnus has
14446 two ``Tick'' marks and IMAP has only one.)
14448 Probably the only reason for frobing this would be if you're trying
14449 enable per-user persistant dormant flags, using something like:
14452 (setcdr (assq 'dormant nnimap-mark-to-flag-alist)
14453 (format "gnus-dormant-%s" (user-login-name)))
14454 (setcdr (assq 'dormant nnimap-mark-to-predicate-alist)
14455 (format "KEYWORD gnus-dormant-%s" (user-login-name)))
14458 In this case, you would not want the per-user dormant flag showing up
14459 as ticked for other users.
14461 @item nnimap-expunge-search-string
14463 @vindex nnimap-expunge-search-string
14465 This variable contain the IMAP search command sent to server when
14466 searching for articles eligible for expiring. The default is
14467 @code{"UID %s NOT SINCE %s"}, where the first @code{%s} is replaced by
14468 UID set and the second @code{%s} is replaced by a date.
14470 Probably the only useful value to change this to is
14471 @code{"UID %s NOT SENTSINCE %s"}, which makes nnimap use the Date: in
14472 messages instead of the internal article date. See section 6.4.4 of
14473 RFC 2060 for more information on valid strings.
14475 @item nnimap-authinfo-file
14476 @vindex nnimap-authinfo-file
14478 A file containing credentials used to log in on servers. The format is
14479 (almost) the same as the @code{ftp} @file{~/.netrc} file. See the
14480 variable @code{nntp-authinfo-file} for exact syntax; also see
14486 * Splitting in IMAP:: Splitting mail with nnimap.
14487 * Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
14488 * Expunging mailboxes:: Equivalent of a "compress mailbox" button.
14493 @node Splitting in IMAP
14494 @subsubsection Splitting in @sc{imap}
14495 @cindex splitting imap mail
14497 Splitting is something Gnus users has loved and used for years, and now
14498 the rest of the world is catching up. Yeah, dream on, not many
14499 @sc{imap} server has server side splitting and those that have splitting
14500 seem to use some non-standard protocol. This means that @sc{imap}
14501 support for Gnus has to do it's own splitting.
14505 Here are the variables of interest:
14509 @item nnimap-split-crosspost
14510 @cindex splitting, crosspost
14512 @vindex nnimap-split-crosspost
14514 If non-nil, do crossposting if several split methods match the mail. If
14515 nil, the first match in @code{nnimap-split-rule} found will be used.
14517 Nnmail equivalent: @code{nnmail-crosspost}.
14519 @item nnimap-split-inbox
14520 @cindex splitting, inbox
14522 @vindex nnimap-split-inbox
14524 A string or a list of strings that gives the name(s) of @sc{imap}
14525 mailboxes to split from. Defaults to nil, which means that splitting is
14529 (setq nnimap-split-inbox
14530 '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap"))
14533 No nnmail equivalent.
14535 @item nnimap-split-rule
14536 @cindex Splitting, rules
14537 @vindex nnimap-split-rule
14539 New mail found in @code{nnimap-split-inbox} will be split according to
14542 This variable contains a list of lists, where the first element in the
14543 sublist gives the name of the @sc{imap} mailbox to move articles
14544 matching the regexp in the second element in the sublist. Got that?
14545 Neither did I, we need examples.
14548 (setq nnimap-split-rule
14550 "^Sender: owner-nnimap@@vic20.globalcom.se")
14551 ("INBOX.junk" "^Subject:.*MAKE MONEY")
14552 ("INBOX.private" "")))
14555 This will put all articles from the nnimap mailing list into mailbox
14556 INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line
14557 into INBOX.junk and everything else in INBOX.private.
14559 The first string may contain `\\1' forms, like the ones used by
14560 replace-match to insert sub-expressions from the matched text. For
14564 ("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@@")
14567 The second element can also be a function. In that case, it will be
14568 called with the first element of the rule as the argument, in a buffer
14569 containing the headers of the article. It should return a non-nil value
14570 if it thinks that the mail belongs in that group.
14572 Nnmail users might recollect that the last regexp had to be empty to
14573 match all articles (like in the example above). This is not required in
14574 nnimap. Articles not matching any of the regexps will not be moved out
14575 of your inbox. (This might affect performance if you keep lots of
14576 unread articles in your inbox, since the splitting code would go over
14577 them every time you fetch new mail.)
14579 These rules are processed from the beginning of the alist toward the
14580 end. The first rule to make a match will "win", unless you have
14581 crossposting enabled. In that case, all matching rules will "win".
14583 This variable can also have a function as its value, the function will
14584 be called with the headers narrowed and should return a group where it
14585 thinks the article should be split to. See @code{nnimap-split-fancy}.
14587 The splitting code tries to create mailboxes if it need too.
14589 To allow for different split rules on different virtual servers, and
14590 even different split rules in different inboxes on the same server,
14591 the syntax of this variable have been extended along the lines of:
14594 (setq nnimap-split-rule
14595 '(("my1server" (".*" (("ding" "ding@@gnus.org")
14596 ("junk" "From:.*Simon")))
14597 ("my2server" ("INBOX" nnimap-split-fancy))
14598 ("my[34]server" (".*" (("private" "To:.*Simon")
14599 ("junk" my-junk-func)))))
14602 The virtual server name is in fact a regexp, so that the same rules
14603 may apply to several servers. In the example, the servers
14604 @code{my3server} and @code{my4server} both use the same rules.
14605 Similarly, the inbox string is also a regexp. The actual splitting
14606 rules are as before, either a function, or a list with group/regexp or
14607 group/function elements.
14609 Nnmail equivalent: @code{nnmail-split-methods}.
14611 @item nnimap-split-predicate
14613 @vindex nnimap-split-predicate
14615 Mail matching this predicate in @code{nnimap-split-inbox} will be
14616 split, it is a string and the default is @samp{UNSEEN UNDELETED}.
14618 This might be useful if you use another @sc{imap} client to read mail in
14619 your inbox but would like Gnus to split all articles in the inbox
14620 regardless of readedness. Then you might change this to
14623 @item nnimap-split-fancy
14624 @cindex splitting, fancy
14625 @findex nnimap-split-fancy
14626 @vindex nnimap-split-fancy
14628 It's possible to set @code{nnimap-split-rule} to
14629 @code{nnmail-split-fancy} if you want to use fancy
14630 splitting. @xref{Fancy Mail Splitting}.
14632 However, to be able to have different fancy split rules for nnmail and
14633 nnimap backends you can set @code{nnimap-split-rule} to
14634 @code{nnimap-split-fancy} and define the nnimap specific fancy split
14635 rule in @code{nnimap-split-fancy}.
14640 (setq nnimap-split-rule 'nnimap-split-fancy
14641 nnimap-split-fancy ...)
14644 Nnmail equivalent: @code{nnmail-split-fancy}.
14648 @node Editing IMAP ACLs
14649 @subsubsection Editing @sc{imap} ACLs
14650 @cindex editing imap acls
14651 @cindex Access Control Lists
14652 @cindex Editing @sc{imap} ACLs
14654 @findex gnus-group-nnimap-edit-acl
14656 ACL stands for Access Control List. ACLs are used in @sc{imap} for
14657 limiting (or enabling) other users access to your mail boxes. Not all
14658 @sc{imap} servers support this, this function will give an error if it
14661 To edit a ACL for a mailbox, type @kbd{G l}
14662 (@code{gnus-group-edit-nnimap-acl}) and you'll be presented with a ACL
14663 editing window with detailed instructions.
14665 Some possible uses:
14669 Giving "anyone" the "lrs" rights (lookup, read, keep seen/unseen flags)
14670 on your mailing list mailboxes enables other users on the same server to
14671 follow the list without subscribing to it.
14673 At least with the Cyrus server, you are required to give the user
14674 "anyone" posting ("p") capabilities to have "plussing" work (that is,
14675 mail sent to user+mailbox@@domain ending up in the @sc{imap} mailbox
14679 @node Expunging mailboxes
14680 @subsubsection Expunging mailboxes
14684 @cindex Manual expunging
14686 @findex gnus-group-nnimap-expunge
14688 If you're using the @code{never} setting of @code{nnimap-expunge-on-close},
14689 you may want the option of expunging all deleted articles in a mailbox
14690 manually. This is exactly what @kbd{G x} does.
14692 Currently there is no way of showing deleted articles, you can just
14697 @node Combined Groups
14698 @section Combined Groups
14700 Gnus allows combining a mixture of all the other group types into bigger
14704 * Virtual Groups:: Combining articles from many groups.
14705 * Kibozed Groups:: Looking through parts of the newsfeed for articles.
14709 @node Virtual Groups
14710 @subsection Virtual Groups
14712 @cindex virtual groups
14713 @cindex merging groups
14715 An @dfn{nnvirtual group} is really nothing more than a collection of
14718 For instance, if you are tired of reading many small groups, you can
14719 put them all in one big group, and then grow tired of reading one
14720 big, unwieldy group. The joys of computing!
14722 You specify @code{nnvirtual} as the method. The address should be a
14723 regexp to match component groups.
14725 All marks in the virtual group will stick to the articles in the
14726 component groups. So if you tick an article in a virtual group, the
14727 article will also be ticked in the component group from whence it came.
14728 (And vice versa---marks from the component groups will also be shown in
14729 the virtual group.)
14731 Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
14732 newsgroups into one, big, happy newsgroup:
14735 (nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
14738 The component groups can be native or foreign; everything should work
14739 smoothly, but if your computer explodes, it was probably my fault.
14741 Collecting the same group from several servers might actually be a good
14742 idea if users have set the Distribution header to limit distribution.
14743 If you would like to read @samp{soc.motss} both from a server in Japan
14744 and a server in Norway, you could use the following as the group regexp:
14747 "^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$"
14750 (Remember, though, that if you're creating the group with @kbd{G m}, you
14751 shouldn't double the backslashes, and you should leave off the quote
14752 characters at the beginning and the end of the string.)
14754 This should work kinda smoothly---all articles from both groups should
14755 end up in this one, and there should be no duplicates. Threading (and
14756 the rest) will still work as usual, but there might be problems with the
14757 sequence of articles. Sorting on date might be an option here
14758 (@pxref{Selecting a Group}).
14760 One limitation, however---all groups included in a virtual
14761 group have to be alive (i.e., subscribed or unsubscribed). Killed or
14762 zombie groups can't be component groups for @code{nnvirtual} groups.
14764 @vindex nnvirtual-always-rescan
14765 If the @code{nnvirtual-always-rescan} is non-@code{nil},
14766 @code{nnvirtual} will always scan groups for unread articles when
14767 entering a virtual group. If this variable is @code{nil} (which is the
14768 default) and you read articles in a component group after the virtual
14769 group has been activated, the read articles from the component group
14770 will show up when you enter the virtual group. You'll also see this
14771 effect if you have two virtual groups that have a component group in
14772 common. If that's the case, you should set this variable to @code{t}.
14773 Or you can just tap @code{M-g} on the virtual group every time before
14774 you enter it---it'll have much the same effect.
14776 @code{nnvirtual} can have both mail and news groups as component groups.
14777 When responding to articles in @code{nnvirtual} groups, @code{nnvirtual}
14778 has to ask the backend of the component group the article comes from
14779 whether it is a news or mail backend. However, when you do a @kbd{^},
14780 there is typically no sure way for the component backend to know this,
14781 and in that case @code{nnvirtual} tells Gnus that the article came from a
14782 not-news backend. (Just to be on the safe side.)
14784 @kbd{C-c C-t} in the message buffer will insert the @code{Newsgroups}
14785 line from the article you respond to in these cases.
14789 @node Kibozed Groups
14790 @subsection Kibozed Groups
14794 @dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of)
14795 the news feed''. @code{nnkiboze} is a backend that will do this for
14796 you. Oh joy! Now you can grind any @sc{nntp} server down to a halt
14797 with useless requests! Oh happiness!
14799 @kindex G k (Group)
14800 To create a kibozed group, use the @kbd{G k} command in the group
14803 The address field of the @code{nnkiboze} method is, as with
14804 @code{nnvirtual}, a regexp to match groups to be ``included'' in the
14805 @code{nnkiboze} group. That's where most similarities between @code{nnkiboze}
14806 and @code{nnvirtual} end.
14808 In addition to this regexp detailing component groups, an @code{nnkiboze} group
14809 must have a score file to say what articles are to be included in
14810 the group (@pxref{Scoring}).
14812 @kindex M-x nnkiboze-generate-groups
14813 @findex nnkiboze-generate-groups
14814 You must run @kbd{M-x nnkiboze-generate-groups} after creating the
14815 @code{nnkiboze} groups you want to have. This command will take time. Lots of
14816 time. Oodles and oodles of time. Gnus has to fetch the headers from
14817 all the articles in all the component groups and run them through the
14818 scoring process to determine if there are any articles in the groups
14819 that are to be part of the @code{nnkiboze} groups.
14821 Please limit the number of component groups by using restrictive
14822 regexps. Otherwise your sysadmin may become annoyed with you, and the
14823 @sc{nntp} site may throw you off and never let you back in again.
14824 Stranger things have happened.
14826 @code{nnkiboze} component groups do not have to be alive---they can be dead,
14827 and they can be foreign. No restrictions.
14829 @vindex nnkiboze-directory
14830 The generation of an @code{nnkiboze} group means writing two files in
14831 @code{nnkiboze-directory}, which is @file{~/News/} by default. One
14832 contains the @sc{nov} header lines for all the articles in the group,
14833 and the other is an additional @file{.newsrc} file to store information
14834 on what groups have been searched through to find component articles.
14836 Articles marked as read in the @code{nnkiboze} group will have
14837 their @sc{nov} lines removed from the @sc{nov} file.
14840 @node Gnus Unplugged
14841 @section Gnus Unplugged
14846 @cindex Gnus Unplugged
14848 In olden times (ca. February '88), people used to run their newsreaders
14849 on big machines with permanent connections to the net. News transport
14850 was dealt with by news servers, and all the newsreaders had to do was to
14851 read news. Believe it or not.
14853 Nowadays most people read news and mail at home, and use some sort of
14854 modem to connect to the net. To avoid running up huge phone bills, it
14855 would be nice to have a way to slurp down all the news and mail, hang up
14856 the phone, read for several hours, and then upload any responses you
14857 have to make. And then you repeat the procedure.
14859 Of course, you can use news servers for doing this as well. I've used
14860 @code{inn} together with @code{slurp}, @code{pop} and @code{sendmail}
14861 for some years, but doing that's a bore. Moving the news server
14862 functionality up to the newsreader makes sense if you're the only person
14863 reading news on a machine.
14865 Using Gnus as an ``offline'' newsreader is quite simple.
14869 First, set up Gnus as you would do if you were running it on a machine
14870 that has full connection to the net. Go ahead. I'll still be waiting
14874 Then, put the following magical incantation at the end of your
14875 @file{.gnus.el} file:
14882 That's it. Gnus is now an ``offline'' newsreader.
14884 Of course, to use it as such, you have to learn a few new commands.
14887 * Agent Basics:: How it all is supposed to work.
14888 * Agent Categories:: How to tell the Gnus Agent what to download.
14889 * Agent Commands:: New commands for all the buffers.
14890 * Agent Expiry:: How to make old articles go away.
14891 * Agent and IMAP:: How to use the Agent with IMAP.
14892 * Outgoing Messages:: What happens when you post/mail something?
14893 * Agent Variables:: Customizing is fun.
14894 * Example Setup:: An example @file{.gnus.el} file for offline people.
14895 * Batching Agents:: How to fetch news from a @code{cron} job.
14896 * Agent Caveats:: What you think it'll do and what it does.
14901 @subsection Agent Basics
14903 First, let's get some terminology out of the way.
14905 The Gnus Agent is said to be @dfn{unplugged} when you have severed the
14906 connection to the net (and notified the Agent that this is the case).
14907 When the connection to the net is up again (and Gnus knows this), the
14908 Agent is @dfn{plugged}.
14910 The @dfn{local} machine is the one you're running on, and which isn't
14911 connected to the net continuously.
14913 @dfn{Downloading} means fetching things from the net to your local
14914 machine. @dfn{Uploading} is doing the opposite.
14916 Let's take a typical Gnus session using the Agent.
14921 You start Gnus with @code{gnus-unplugged}. This brings up the Gnus
14922 Agent in a disconnected state. You can read all the news that you have
14923 already fetched while in this mode.
14926 You then decide to see whether any new news has arrived. You connect
14927 your machine to the net (using PPP or whatever), and then hit @kbd{J j}
14928 to make Gnus become @dfn{plugged} and use @kbd{g} to check for new mail
14929 as usual. To check for new mail in unplugged mode, see (@pxref{Mail
14930 Source Specifiers}).
14933 You can then read the new news immediately, or you can download the news
14934 onto your local machine. If you want to do the latter, you press @kbd{g}
14935 to check if there are any new news and then @kbd{J
14936 s} to fetch all the eligible articles in all the groups. (To let Gnus
14937 know which articles you want to download, @pxref{Agent Categories}.)
14940 After fetching the articles, you press @kbd{J j} to make Gnus become
14941 unplugged again, and you shut down the PPP thing (or whatever). And
14942 then you read the news offline.
14945 And then you go to step 2.
14948 Here are some things you should do the first time (or so) that you use
14954 Decide which servers should be covered by the Agent. If you have a mail
14955 backend, it would probably be nonsensical to have it covered by the
14956 Agent. Go to the server buffer (@kbd{^} in the group buffer) and press
14957 @kbd{J a} the server (or servers) that you wish to have covered by the
14958 Agent (@pxref{Server Agent Commands}). This will typically be only the
14959 primary select method, which is listed on the bottom in the buffer.
14962 Decide on download policy. @xref{Agent Categories}.
14969 @node Agent Categories
14970 @subsection Agent Categories
14972 One of the main reasons to integrate the news transport layer into the
14973 newsreader is to allow greater control over what articles to download.
14974 There's not much point in downloading huge amounts of articles, just to
14975 find out that you're not interested in reading any of them. It's better
14976 to be somewhat more conservative in choosing what to download, and then
14977 mark the articles for downloading manually if it should turn out that
14978 you're interested in the articles anyway.
14980 The main way to control what is to be downloaded is to create a
14981 @dfn{category} and then assign some (or all) groups to this category.
14982 Groups that do not belong in any other category belong to the
14983 @code{default} category. Gnus has its own buffer for creating and
14984 managing categories.
14987 * Category Syntax:: What a category looks like.
14988 * Category Buffer:: A buffer for maintaining categories.
14989 * Category Variables:: Customize'r'Us.
14993 @node Category Syntax
14994 @subsubsection Category Syntax
14996 A category consists of two things.
15000 A predicate which (generally) gives a rough outline of which articles
15001 are eligible for downloading; and
15004 a score rule which (generally) gives you a finer granularity when
15005 deciding what articles to download. (Note that this @dfn{download
15006 score} is not necessarily related to normal scores.)
15009 A predicate in its simplest form can be a single predicate such as
15010 @code{true} or @code{false}. These two will download every available
15011 article or nothing respectively. In the case of these two special
15012 predicates an additional score rule is superfluous.
15014 Predicates of @code{high} or @code{low} download articles in respect of
15015 their scores in relationship to @code{gnus-agent-high-score} and
15016 @code{gnus-agent-low-score} as described below.
15018 To gain even finer control of what is to be regarded eligible for
15019 download a predicate can consist of a number of predicates with logical
15020 operators sprinkled in between.
15022 Perhaps some examples are in order.
15024 Here's a simple predicate. (It's the default predicate, in fact, used
15025 for all groups that don't belong to any other category.)
15031 Quite simple, eh? This predicate is true if and only if the article is
15032 short (for some value of ``short'').
15034 Here's a more complex predicate:
15043 This means that an article should be downloaded if it has a high score,
15044 or if the score is not low and the article is not long. You get the
15047 The available logical operators are @code{or}, @code{and} and
15048 @code{not}. (If you prefer, you can use the more ``C''-ish operators
15049 @samp{|}, @code{&} and @code{!} instead.)
15051 The following predicates are pre-defined, but if none of these fit what
15052 you want to do, you can write your own.
15056 True iff the article is shorter than @code{gnus-agent-short-article}
15057 lines; default 100.
15060 True iff the article is longer than @code{gnus-agent-long-article}
15061 lines; default 200.
15064 True iff the article has a download score less than
15065 @code{gnus-agent-low-score}; default 0.
15068 True iff the article has a download score greater than
15069 @code{gnus-agent-high-score}; default 0.
15072 True iff the Gnus Agent guesses that the article is spam. The
15073 heuristics may change over time, but at present it just computes a
15074 checksum and sees whether articles match.
15083 If you want to create your own predicate function, here's what you have
15084 to know: The functions are called with no parameters, but the
15085 @code{gnus-headers} and @code{gnus-score} dynamic variables are bound to
15088 For example, you could decide that you don't want to download articles
15089 that were posted more than a certain number of days ago (e.g. posted
15090 more than @code{gnus-agent-expire-days} ago) you might write a function
15091 something along the lines of the following:
15094 (defun my-article-old-p ()
15095 "Say whether an article is old."
15096 (< (time-to-days (date-to-time (mail-header-date gnus-headers)))
15097 (- (time-to-days (current-time)) gnus-agent-expire-days)))
15100 with the predicate then defined as:
15103 (not my-article-old-p)
15106 or you could append your predicate to the predefined
15107 @code{gnus-category-predicate-alist} in your @file{~/.gnus.el} or
15108 wherever. (Note: this would have to be at a point *after*
15109 @code{gnus-agent} has been loaded via @code{(gnus-agentize)})
15112 (setq gnus-category-predicate-alist
15113 (append gnus-category-predicate-alist
15114 '((old . my-article-old-p))))
15117 and simply specify your predicate as:
15123 If/when using something like the above, be aware that there are many
15124 misconfigured systems/mailers out there and so an article's date is not
15125 always a reliable indication of when it was posted. Hell, some people
15126 just don't give a damn.
15128 The above predicates apply to *all* the groups which belong to the
15129 category. However, if you wish to have a specific predicate for an
15130 individual group within a category, or you're just too lazy to set up a
15131 new category, you can enter a group's individual predicate in it's group
15132 parameters like so:
15135 (agent-predicate . short)
15138 This is the group parameter equivalent of the agent category default.
15139 Note that when specifying a single word predicate like this, the
15140 @code{agent-predicate} specification must be in dotted pair notation.
15142 The equivalent of the longer example from above would be:
15145 (agent-predicate or high (and (not low) (not long)))
15148 The outer parenthesis required in the category specification are not
15149 entered here as, not being in dotted pair notation, the value of the
15150 predicate is assumed to be a list.
15153 Now, the syntax of the download score is the same as the syntax of
15154 normal score files, except that all elements that require actually
15155 seeing the article itself are verboten. This means that only the
15156 following headers can be scored on: @code{Subject}, @code{From},
15157 @code{Date}, @code{Message-ID}, @code{References}, @code{Chars},
15158 @code{Lines}, and @code{Xref}.
15160 As with predicates, the specification of the @code{download score rule}
15161 to use in respect of a group can be in either the category definition if
15162 it's to be applicable to all groups in therein, or a group's parameters
15163 if it's to be specific to that group.
15165 In both of these places the @code{download score rule} can take one of
15172 This has the same syntax as a normal gnus score file except only a
15173 subset of scoring keywords are available as mentioned above.
15179 Category specification
15183 ("Lars Ingebrigtsen" 1000000 nil s))
15189 Group Parameter specification
15192 (agent-score ("from"
15193 ("Lars Ingebrigtsen" 1000000 nil s))
15198 Again, note the omission of the outermost parenthesis here.
15204 These score files must *only* contain the permitted scoring keywords
15211 Category specification
15214 ("~/News/agent.SCORE")
15220 ("~/News/agent.SCORE" "~/News/agent.group.SCORE")
15224 Group Parameter specification
15227 (agent-score "~/News/agent.SCORE")
15230 Additional score files can be specified as above. Need I say anything
15235 Use @code{normal} score files
15237 If you don't want to maintain two sets of scoring rules for a group, and
15238 your desired @code{downloading} criteria for a group are the same as your
15239 @code{reading} criteria then you can tell the agent to refer to your
15240 @code{normal} score files when deciding what to download.
15242 These directives in either the category definition or a group's
15243 parameters will cause the agent to read in all the applicable score
15244 files for a group, *filtering out* those sections that do not
15245 relate to one of the permitted subset of scoring keywords.
15249 Category Specification
15256 Group Parameter specification
15259 (agent-score . file)
15264 @node Category Buffer
15265 @subsubsection Category Buffer
15267 You'd normally do all category maintenance from the category buffer.
15268 When you enter it for the first time (with the @kbd{J c} command from
15269 the group buffer), you'll only see the @code{default} category.
15271 The following commands are available in this buffer:
15275 @kindex q (Category)
15276 @findex gnus-category-exit
15277 Return to the group buffer (@code{gnus-category-exit}).
15280 @kindex k (Category)
15281 @findex gnus-category-kill
15282 Kill the current category (@code{gnus-category-kill}).
15285 @kindex c (Category)
15286 @findex gnus-category-copy
15287 Copy the current category (@code{gnus-category-copy}).
15290 @kindex a (Category)
15291 @findex gnus-category-add
15292 Add a new category (@code{gnus-category-add}).
15295 @kindex p (Category)
15296 @findex gnus-category-edit-predicate
15297 Edit the predicate of the current category
15298 (@code{gnus-category-edit-predicate}).
15301 @kindex g (Category)
15302 @findex gnus-category-edit-groups
15303 Edit the list of groups belonging to the current category
15304 (@code{gnus-category-edit-groups}).
15307 @kindex s (Category)
15308 @findex gnus-category-edit-score
15309 Edit the download score rule of the current category
15310 (@code{gnus-category-edit-score}).
15313 @kindex l (Category)
15314 @findex gnus-category-list
15315 List all the categories (@code{gnus-category-list}).
15319 @node Category Variables
15320 @subsubsection Category Variables
15323 @item gnus-category-mode-hook
15324 @vindex gnus-category-mode-hook
15325 Hook run in category buffers.
15327 @item gnus-category-line-format
15328 @vindex gnus-category-line-format
15329 Format of the lines in the category buffer (@pxref{Formatting
15330 Variables}). Valid elements are:
15334 The name of the category.
15337 The number of groups in the category.
15340 @item gnus-category-mode-line-format
15341 @vindex gnus-category-mode-line-format
15342 Format of the category mode line (@pxref{Mode Line Formatting}).
15344 @item gnus-agent-short-article
15345 @vindex gnus-agent-short-article
15346 Articles that have fewer lines than this are short. Default 100.
15348 @item gnus-agent-long-article
15349 @vindex gnus-agent-long-article
15350 Articles that have more lines than this are long. Default 200.
15352 @item gnus-agent-low-score
15353 @vindex gnus-agent-low-score
15354 Articles that have a score lower than this have a low score. Default
15357 @item gnus-agent-high-score
15358 @vindex gnus-agent-high-score
15359 Articles that have a score higher than this have a high score. Default
15365 @node Agent Commands
15366 @subsection Agent Commands
15368 All the Gnus Agent commands are on the @kbd{J} submap. The @kbd{J j}
15369 (@code{gnus-agent-toggle-plugged} command works in all modes, and
15370 toggles the plugged/unplugged state of the Gnus Agent.
15374 * Group Agent Commands::
15375 * Summary Agent Commands::
15376 * Server Agent Commands::
15379 You can run a complete batch fetch from the command line with the
15380 following incantation:
15382 @cindex gnus-agent-batch-fetch
15384 $ emacs -batch -l ~/.gnus.el -f gnus-agent-batch-fetch
15389 @node Group Agent Commands
15390 @subsubsection Group Agent Commands
15394 @kindex J u (Agent Group)
15395 @findex gnus-agent-fetch-groups
15396 Fetch all eligible articles in the current group
15397 (@code{gnus-agent-fetch-groups}).
15400 @kindex J c (Agent Group)
15401 @findex gnus-enter-category-buffer
15402 Enter the Agent category buffer (@code{gnus-enter-category-buffer}).
15405 @kindex J s (Agent Group)
15406 @findex gnus-agent-fetch-session
15407 Fetch all eligible articles in all groups
15408 (@code{gnus-agent-fetch-session}).
15411 @kindex J S (Agent Group)
15412 @findex gnus-group-send-drafts
15413 Send all sendable messages in the draft group
15414 (@code{gnus-group-send-drafts}). @xref{Drafts}.
15417 @kindex J a (Agent Group)
15418 @findex gnus-agent-add-group
15419 Add the current group to an Agent category
15420 (@code{gnus-agent-add-group}). This command understands the
15421 process/prefix convention (@pxref{Process/Prefix}).
15424 @kindex J r (Agent Group)
15425 @findex gnus-agent-remove-group
15426 Remove the current group from its category, if any
15427 (@code{gnus-agent-remove-group}). This command understands the
15428 process/prefix convention (@pxref{Process/Prefix}).
15431 @kindex J Y (Agent Group)
15432 @findex gnus-agent-synchronize-flags
15433 Synchronize flags changed while unplugged with remote server, if any.
15439 @node Summary Agent Commands
15440 @subsubsection Summary Agent Commands
15444 @kindex J # (Agent Summary)
15445 @findex gnus-agent-mark-article
15446 Mark the article for downloading (@code{gnus-agent-mark-article}).
15449 @kindex J M-# (Agent Summary)
15450 @findex gnus-agent-unmark-article
15451 Remove the downloading mark from the article
15452 (@code{gnus-agent-unmark-article}).
15455 @kindex @@ (Agent Summary)
15456 @findex gnus-agent-toggle-mark
15457 Toggle whether to download the article (@code{gnus-agent-toggle-mark}).
15460 @kindex J c (Agent Summary)
15461 @findex gnus-agent-catchup
15462 Mark all undownloaded articles as read (@code{gnus-agent-catchup}).
15467 @node Server Agent Commands
15468 @subsubsection Server Agent Commands
15472 @kindex J a (Agent Server)
15473 @findex gnus-agent-add-server
15474 Add the current server to the list of servers covered by the Gnus Agent
15475 (@code{gnus-agent-add-server}).
15478 @kindex J r (Agent Server)
15479 @findex gnus-agent-remove-server
15480 Remove the current server from the list of servers covered by the Gnus
15481 Agent (@code{gnus-agent-remove-server}).
15487 @subsection Agent Expiry
15489 @vindex gnus-agent-expire-days
15490 @findex gnus-agent-expire
15491 @kindex M-x gnus-agent-expire
15492 @cindex Agent expiry
15493 @cindex Gnus Agent expiry
15496 @code{nnagent} doesn't handle expiry. Instead, there's a special
15497 @code{gnus-agent-expire} command that will expire all read articles that
15498 are older than @code{gnus-agent-expire-days} days. It can be run
15499 whenever you feel that you're running out of space. It's not
15500 particularly fast or efficient, and it's not a particularly good idea to
15501 interrupt it (with @kbd{C-g} or anything else) once you've started it.
15503 @vindex gnus-agent-expire-all
15504 if @code{gnus-agent-expire-all} is non-@code{nil}, this command will
15505 expire all articles---unread, read, ticked and dormant. If @code{nil}
15506 (which is the default), only read articles are eligible for expiry, and
15507 unread, ticked and dormant articles will be kept indefinitely.
15510 @node Agent and IMAP
15511 @subsection Agent and IMAP
15513 The Agent work with any Gnus backend, including nnimap. However,
15514 since there are some conceptual differences between @sc{nntp} and
15515 @sc{imap}, this section (should) provide you with some information to
15516 make Gnus Agent work smoother as a @sc{imap} Disconnected Mode client.
15518 The first thing to keep in mind is that all flags (read, ticked, etc)
15519 are kept on the @sc{imap} server, rather than in @code{.newsrc} as is the
15520 case for nntp. Thus Gnus need to remember flag changes when
15521 disconnected, and synchronize these flags when you plug back in.
15523 Gnus keep track of flag changes when reading nnimap groups under the
15524 Agent by default. When you plug back in, by default Gnus will check if
15525 you have any changed any flags and ask if you wish to synchronize these
15526 with the server. This behavior is customizable with
15527 @code{gnus-agent-synchronize-flags}.
15529 @vindex gnus-agent-synchronize-flags
15530 If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will
15531 never automatically synchronize flags. If it is @code{ask}, the
15532 default, the Agent will check if you made any changes and if so ask if
15533 you wish to synchronize these when you re-connect. If it has any other
15534 value, all flags will be synchronized automatically.
15536 If you do not wish to automatically synchronize flags when you
15537 re-connect, this can be done manually with the
15538 @code{gnus-agent-synchronize-flags} command that is bound to @kbd{J Y}
15539 in the group buffer by default.
15541 Some things are currently not implemented in the Agent that you'd might
15542 expect from a disconnected @sc{imap} client, including:
15547 Copying/moving articles into nnimap groups when unplugged.
15550 Creating/deleting nnimap groups when unplugged.
15554 Technical note: the synchronization algorithm does not work by "pushing"
15555 all local flags to the server, but rather incrementally update the
15556 server view of flags by changing only those flags that were changed by
15557 the user. Thus, if you set one flag on a article, quit the group and
15558 re-select the group and remove the flag; the flag will be set and
15559 removed from the server when you "synchronize". The queued flag
15560 operations can be found in the per-server @code{flags} file in the Agent
15561 directory. It's emptied when you synchronize flags.
15564 @node Outgoing Messages
15565 @subsection Outgoing Messages
15567 When Gnus is unplugged, all outgoing messages (both mail and news) are
15568 stored in the draft groups (@pxref{Drafts}). You can view them there
15569 after posting, and edit them at will.
15571 When Gnus is plugged again, you can send the messages either from the
15572 draft group with the special commands available there, or you can use
15573 the @kbd{J S} command in the group buffer to send all the sendable
15574 messages in the draft group.
15578 @node Agent Variables
15579 @subsection Agent Variables
15582 @item gnus-agent-directory
15583 @vindex gnus-agent-directory
15584 Where the Gnus Agent will store its files. The default is
15585 @file{~/News/agent/}.
15587 @item gnus-agent-handle-level
15588 @vindex gnus-agent-handle-level
15589 Groups on levels (@pxref{Group Levels}) higher than this variable will
15590 be ignored by the Agent. The default is @code{gnus-level-subscribed},
15591 which means that only subscribed group will be considered by the Agent
15594 @item gnus-agent-plugged-hook
15595 @vindex gnus-agent-plugged-hook
15596 Hook run when connecting to the network.
15598 @item gnus-agent-unplugged-hook
15599 @vindex gnus-agent-unplugged-hook
15600 Hook run when disconnecting from the network.
15605 @node Example Setup
15606 @subsection Example Setup
15608 If you don't want to read this manual, and you have a fairly standard
15609 setup, you may be able to use something like the following as your
15610 @file{.gnus.el} file to get started.
15613 ;;; Define how Gnus is to fetch news. We do this over @sc{nntp}
15614 ;;; from your ISP's server.
15615 (setq gnus-select-method '(nntp "news.your-isp.com"))
15617 ;;; Define how Gnus is to read your mail. We read mail from
15618 ;;; your ISP's POP server.
15619 (setq mail-sources '((pop :server "pop.your-isp.com")))
15621 ;;; Say how Gnus is to store the mail. We use nnml groups.
15622 (setq gnus-secondary-select-methods '((nnml "")))
15624 ;;; Make Gnus into an offline newsreader.
15628 That should be it, basically. Put that in your @file{~/.gnus.el} file,
15629 edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x
15632 If this is the first time you've run Gnus, you will be subscribed
15633 automatically to a few default newsgroups. You'll probably want to
15634 subscribe to more groups, and to do that, you have to query the
15635 @sc{nntp} server for a complete list of groups with the @kbd{A A}
15636 command. This usually takes quite a while, but you only have to do it
15639 After reading and parsing a while, you'll be presented with a list of
15640 groups. Subscribe to the ones you want to read with the @kbd{u}
15641 command. @kbd{l} to make all the killed groups disappear after you've
15642 subscribe to all the groups you want to read. (@kbd{A k} will bring
15643 back all the killed groups.)
15645 You can now read the groups at once, or you can download the articles
15646 with the @kbd{J s} command. And then read the rest of this manual to
15647 find out which of the other gazillion things you want to customize.
15650 @node Batching Agents
15651 @subsection Batching Agents
15653 Having the Gnus Agent fetch articles (and post whatever messages you've
15654 written) is quite easy once you've gotten things set up properly. The
15655 following shell script will do everything that is necessary:
15659 emacs -batch -l ~/.emacs -f gnus-agent-batch >/dev/null
15663 @node Agent Caveats
15664 @subsection Agent Caveats
15666 The Gnus Agent doesn't seem to work like most other offline
15667 newsreaders. Here are some common questions that some imaginary people
15671 @item If I read an article while plugged, do they get entered into the
15676 @item If I read an article while plugged, and the article already exists
15677 in the Agent, will it get downloaded once more?
15683 In short, when Gnus is unplugged, it only looks into the locally stored
15684 articles; when it's plugged, it only talks to your ISP.
15691 Other people use @dfn{kill files}, but we here at Gnus Towers like
15692 scoring better than killing, so we'd rather switch than fight. They do
15693 something completely different as well, so sit up straight and pay
15696 @vindex gnus-summary-mark-below
15697 All articles have a default score (@code{gnus-summary-default-score}),
15698 which is 0 by default. This score may be raised or lowered either
15699 interactively or by score files. Articles that have a score lower than
15700 @code{gnus-summary-mark-below} are marked as read.
15702 Gnus will read any @dfn{score files} that apply to the current group
15703 before generating the summary buffer.
15705 There are several commands in the summary buffer that insert score
15706 entries based on the current article. You can, for instance, ask Gnus to
15707 lower or increase the score of all articles with a certain subject.
15709 There are two sorts of scoring entries: Permanent and temporary.
15710 Temporary score entries are self-expiring entries. Any entries that are
15711 temporary and have not been used for, say, a week, will be removed
15712 silently to help keep the sizes of the score files down.
15715 * Summary Score Commands:: Adding score entries for the current group.
15716 * Group Score Commands:: General score commands.
15717 * Score Variables:: Customize your scoring. (My, what terminology).
15718 * Score File Format:: What a score file may contain.
15719 * Score File Editing:: You can edit score files by hand as well.
15720 * Adaptive Scoring:: Big Sister Gnus knows what you read.
15721 * Home Score File:: How to say where new score entries are to go.
15722 * Followups To Yourself:: Having Gnus notice when people answer you.
15723 * Scoring Tips:: How to score effectively.
15724 * Reverse Scoring:: That problem child of old is not problem.
15725 * Global Score Files:: Earth-spanning, ear-splitting score files.
15726 * Kill Files:: They are still here, but they can be ignored.
15727 * Converting Kill Files:: Translating kill files to score files.
15728 * GroupLens:: Getting predictions on what you like to read.
15729 * Advanced Scoring:: Using logical expressions to build score rules.
15730 * Score Decays:: It can be useful to let scores wither away.
15734 @node Summary Score Commands
15735 @section Summary Score Commands
15736 @cindex score commands
15738 The score commands that alter score entries do not actually modify real
15739 score files. That would be too inefficient. Gnus maintains a cache of
15740 previously loaded score files, one of which is considered the
15741 @dfn{current score file alist}. The score commands simply insert
15742 entries into this list, and upon group exit, this list is saved.
15744 The current score file is by default the group's local score file, even
15745 if no such score file actually exists. To insert score commands into
15746 some other score file (e.g. @file{all.SCORE}), you must first make this
15747 score file the current one.
15749 General score commands that don't actually change the score file:
15754 @kindex V s (Summary)
15755 @findex gnus-summary-set-score
15756 Set the score of the current article (@code{gnus-summary-set-score}).
15759 @kindex V S (Summary)
15760 @findex gnus-summary-current-score
15761 Display the score of the current article
15762 (@code{gnus-summary-current-score}).
15765 @kindex V t (Summary)
15766 @findex gnus-score-find-trace
15767 Display all score rules that have been used on the current article
15768 (@code{gnus-score-find-trace}).
15771 @kindex V R (Summary)
15772 @findex gnus-summary-rescore
15773 Run the current summary through the scoring process
15774 (@code{gnus-summary-rescore}). This might be useful if you're playing
15775 around with your score files behind Gnus' back and want to see the
15776 effect you're having.
15779 @kindex V c (Summary)
15780 @findex gnus-score-change-score-file
15781 Make a different score file the current
15782 (@code{gnus-score-change-score-file}).
15785 @kindex V e (Summary)
15786 @findex gnus-score-edit-current-scores
15787 Edit the current score file (@code{gnus-score-edit-current-scores}).
15788 You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score
15792 @kindex V f (Summary)
15793 @findex gnus-score-edit-file
15794 Edit a score file and make this score file the current one
15795 (@code{gnus-score-edit-file}).
15798 @kindex V F (Summary)
15799 @findex gnus-score-flush-cache
15800 Flush the score cache (@code{gnus-score-flush-cache}). This is useful
15801 after editing score files.
15804 @kindex V C (Summary)
15805 @findex gnus-score-customize
15806 Customize a score file in a visually pleasing manner
15807 (@code{gnus-score-customize}).
15811 The rest of these commands modify the local score file.
15816 @kindex V m (Summary)
15817 @findex gnus-score-set-mark-below
15818 Prompt for a score, and mark all articles with a score below this as
15819 read (@code{gnus-score-set-mark-below}).
15822 @kindex V x (Summary)
15823 @findex gnus-score-set-expunge-below
15824 Prompt for a score, and add a score rule to the current score file to
15825 expunge all articles below this score
15826 (@code{gnus-score-set-expunge-below}).
15829 The keystrokes for actually making score entries follow a very regular
15830 pattern, so there's no need to list all the commands. (Hundreds of
15833 @findex gnus-summary-increase-score
15834 @findex gnus-summary-lower-score
15838 The first key is either @kbd{I} (upper case i) for increasing the score
15839 or @kbd{L} for lowering the score.
15841 The second key says what header you want to score on. The following
15842 keys are available:
15846 Score on the author name.
15849 Score on the subject line.
15852 Score on the @code{Xref} line---i.e., the cross-posting line.
15855 Score on the @code{References} line.
15861 Score on the number of lines.
15864 Score on the @code{Message-ID} header.
15867 Score on followups---this matches the author name, and adds scores to
15868 the followups to this author. (Using this key leads to the creation of
15869 @file{ADAPT} files.)
15878 Score on thread. (Using this key leads to the creation of @file{ADAPT}
15884 The third key is the match type. Which match types are valid depends on
15885 what headers you are scoring on.
15897 Substring matching.
15900 Fuzzy matching (@pxref{Fuzzy Matching}).
15929 Greater than number.
15934 The fourth and final key says whether this is a temporary (i.e., expiring)
15935 score entry, or a permanent (i.e., non-expiring) score entry, or whether
15936 it is to be done immediately, without adding to the score file.
15940 Temporary score entry.
15943 Permanent score entry.
15946 Immediately scoring.
15951 So, let's say you want to increase the score on the current author with
15952 exact matching permanently: @kbd{I a e p}. If you want to lower the
15953 score based on the subject line, using substring matching, and make a
15954 temporary score entry: @kbd{L s s t}. Pretty easy.
15956 To make things a bit more complicated, there are shortcuts. If you use
15957 a capital letter on either the second or third keys, Gnus will use
15958 defaults for the remaining one or two keystrokes. The defaults are
15959 ``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s
15960 t}, and @kbd{I a R} is the same as @kbd{I a r t}.
15962 These functions take both the numerical prefix and the symbolic prefix
15963 (@pxref{Symbolic Prefixes}). A numerical prefix says how much to lower
15964 (or increase) the score of the article. A symbolic prefix of @code{a}
15965 says to use the @file{all.SCORE} file for the command instead of the
15966 current score file.
15968 @vindex gnus-score-mimic-keymap
15969 The @code{gnus-score-mimic-keymap} says whether these commands will
15970 pretend they are keymaps or not.
15973 @node Group Score Commands
15974 @section Group Score Commands
15975 @cindex group score commands
15977 There aren't many of these as yet, I'm afraid.
15982 @kindex W f (Group)
15983 @findex gnus-score-flush-cache
15984 Gnus maintains a cache of score alists to avoid having to reload them
15985 all the time. This command will flush the cache
15986 (@code{gnus-score-flush-cache}).
15990 You can do scoring from the command line by saying something like:
15992 @findex gnus-batch-score
15993 @cindex batch scoring
15995 $ emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-batch-score
15999 @node Score Variables
16000 @section Score Variables
16001 @cindex score variables
16005 @item gnus-use-scoring
16006 @vindex gnus-use-scoring
16007 If @code{nil}, Gnus will not check for score files, and will not, in
16008 general, do any score-related work. This is @code{t} by default.
16010 @item gnus-kill-killed
16011 @vindex gnus-kill-killed
16012 If this variable is @code{nil}, Gnus will never apply score files to
16013 articles that have already been through the kill process. While this
16014 may save you lots of time, it also means that if you apply a kill file
16015 to a group, and then change the kill file and want to run it over you
16016 group again to kill more articles, it won't work. You have to set this
16017 variable to @code{t} to do that. (It is @code{t} by default.)
16019 @item gnus-kill-files-directory
16020 @vindex gnus-kill-files-directory
16021 All kill and score files will be stored in this directory, which is
16022 initialized from the @code{SAVEDIR} environment variable by default.
16023 This is @file{~/News/} by default.
16025 @item gnus-score-file-suffix
16026 @vindex gnus-score-file-suffix
16027 Suffix to add to the group name to arrive at the score file name
16028 (@samp{SCORE} by default.)
16030 @item gnus-score-uncacheable-files
16031 @vindex gnus-score-uncacheable-files
16032 @cindex score cache
16033 All score files are normally cached to avoid excessive re-loading of
16034 score files. However, if this might make your Emacs grow big and
16035 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
16036 @file{all.SCORE}, while it might be a good idea to not cache
16037 @file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
16038 variable is @samp{ADAPT$} by default, so no adaptive score files will
16041 @item gnus-save-score
16042 @vindex gnus-save-score
16043 If you have really complicated score files, and do lots of batch
16044 scoring, then you might set this variable to @code{t}. This will make
16045 Gnus save the scores into the @file{.newsrc.eld} file.
16047 If you do not set this to @code{t}, then manual scores (like those set
16048 with @kbd{V s} (@code{gnus-summary-set-score})) will not be preserved
16049 across group visits.
16051 @item gnus-score-interactive-default-score
16052 @vindex gnus-score-interactive-default-score
16053 Score used by all the interactive raise/lower commands to raise/lower
16054 score with. Default is 1000, which may seem excessive, but this is to
16055 ensure that the adaptive scoring scheme gets enough room to play with.
16056 We don't want the small changes from the adaptive scoring to overwrite
16057 manually entered data.
16059 @item gnus-summary-default-score
16060 @vindex gnus-summary-default-score
16061 Default score of an article, which is 0 by default.
16063 @item gnus-summary-expunge-below
16064 @vindex gnus-summary-expunge-below
16065 Don't display the summary lines of articles that have scores lower than
16066 this variable. This is @code{nil} by default, which means that no
16067 articles will be hidden. This variable is local to the summary buffers,
16068 and has to be set from @code{gnus-summary-mode-hook}.
16070 @item gnus-score-over-mark
16071 @vindex gnus-score-over-mark
16072 Mark (in the third column) used for articles with a score over the
16073 default. Default is @samp{+}.
16075 @item gnus-score-below-mark
16076 @vindex gnus-score-below-mark
16077 Mark (in the third column) used for articles with a score below the
16078 default. Default is @samp{-}.
16080 @item gnus-score-find-score-files-function
16081 @vindex gnus-score-find-score-files-function
16082 Function used to find score files for the current group. This function
16083 is called with the name of the group as the argument.
16085 Predefined functions available are:
16088 @item gnus-score-find-single
16089 @findex gnus-score-find-single
16090 Only apply the group's own score file.
16092 @item gnus-score-find-bnews
16093 @findex gnus-score-find-bnews
16094 Apply all score files that match, using bnews syntax. This is the
16095 default. If the current group is @samp{gnu.emacs.gnus}, for instance,
16096 @file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and
16097 @file{gnu.all.SCORE} would all apply. In short, the instances of
16098 @samp{all} in the score file names are translated into @samp{.*}, and
16099 then a regexp match is done.
16101 This means that if you have some score entries that you want to apply to
16102 all groups, then you put those entries in the @file{all.SCORE} file.
16104 The score files are applied in a semi-random order, although Gnus will
16105 try to apply the more general score files before the more specific score
16106 files. It does this by looking at the number of elements in the score
16107 file names---discarding the @samp{all} elements.
16109 @item gnus-score-find-hierarchical
16110 @findex gnus-score-find-hierarchical
16111 Apply all score files from all the parent groups. This means that you
16112 can't have score files like @file{all.SCORE}, but you can have
16113 @file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE} for each
16117 This variable can also be a list of functions. In that case, all these
16118 functions will be called with the group name as argument, and all the
16119 returned lists of score files will be applied. These functions can also
16120 return lists of score alists directly. In that case, the functions that
16121 return these non-file score alists should probably be placed before the
16122 ``real'' score file functions, to ensure that the last score file
16123 returned is the local score file. Phu.
16125 For example, to do hierarchical scoring but use a non-server-specific
16126 overall score file, you could use the value
16128 (list (lambda (group) ("all.SCORE"))
16129 'gnus-score-find-hierarchical)
16132 @item gnus-score-expiry-days
16133 @vindex gnus-score-expiry-days
16134 This variable says how many days should pass before an unused score file
16135 entry is expired. If this variable is @code{nil}, no score file entries
16136 are expired. It's 7 by default.
16138 @item gnus-update-score-entry-dates
16139 @vindex gnus-update-score-entry-dates
16140 If this variable is non-@code{nil}, matching score entries will have
16141 their dates updated. (This is how Gnus controls expiry---all
16142 non-matching entries will become too old while matching entries will
16143 stay fresh and young.) However, if you set this variable to @code{nil},
16144 even matching entries will grow old and will have to face that oh-so
16147 @item gnus-score-after-write-file-function
16148 @vindex gnus-score-after-write-file-function
16149 Function called with the name of the score file just written.
16151 @item gnus-score-thread-simplify
16152 @vindex gnus-score-thread-simplify
16153 If this variable is non-@code{nil}, article subjects will be simplified
16154 for subject scoring purposes in the same manner as with
16155 threading---according to the current value of
16156 gnus-simplify-subject-functions. If the scoring entry uses
16157 @code{substring} or @code{exact} matching, the match will also be
16158 simplified in this manner.
16163 @node Score File Format
16164 @section Score File Format
16165 @cindex score file format
16167 A score file is an @code{emacs-lisp} file that normally contains just a
16168 single form. Casual users are not expected to edit these files;
16169 everything can be changed from the summary buffer.
16171 Anyway, if you'd like to dig into it yourself, here's an example:
16175 ("Lars Ingebrigtsen" -10000)
16177 ("larsi\\|lmi" -50000 nil R))
16179 ("Ding is Badd" nil 728373))
16181 ("alt.politics" -1000 728372 s))
16186 (mark-and-expunge -10)
16190 (files "/hom/larsi/News/gnu.SCORE")
16191 (exclude-files "all.SCORE")
16192 (local (gnus-newsgroup-auto-expire t)
16193 (gnus-summary-make-false-root empty))
16197 This example demonstrates most score file elements. For a different
16198 approach, see @pxref{Advanced Scoring}.
16200 Even though this looks much like lisp code, nothing here is actually
16201 @code{eval}ed. The lisp reader is used to read this form, though, so it
16202 has to be valid syntactically, if not semantically.
16204 Six keys are supported by this alist:
16209 If the key is a string, it is the name of the header to perform the
16210 match on. Scoring can only be performed on these eight headers:
16211 @code{From}, @code{Subject}, @code{References}, @code{Message-ID},
16212 @code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to
16213 these headers, there are three strings to tell Gnus to fetch the entire
16214 article and do the match on larger parts of the article: @code{Body}
16215 will perform the match on the body of the article, @code{Head} will
16216 perform the match on the head of the article, and @code{All} will
16217 perform the match on the entire article. Note that using any of these
16218 last three keys will slow down group entry @emph{considerably}. The
16219 final ``header'' you can score on is @code{Followup}. These score
16220 entries will result in new score entries being added for all follow-ups
16221 to articles that matches these score entries.
16223 Following this key is a arbitrary number of score entries, where each
16224 score entry has one to four elements.
16228 The first element is the @dfn{match element}. On most headers this will
16229 be a string, but on the Lines and Chars headers, this must be an
16233 If the second element is present, it should be a number---the @dfn{score
16234 element}. This number should be an integer in the neginf to posinf
16235 interval. This number is added to the score of the article if the match
16236 is successful. If this element is not present, the
16237 @code{gnus-score-interactive-default-score} number will be used
16238 instead. This is 1000 by default.
16241 If the third element is present, it should be a number---the @dfn{date
16242 element}. This date says when the last time this score entry matched,
16243 which provides a mechanism for expiring the score entries. It this
16244 element is not present, the score entry is permanent. The date is
16245 represented by the number of days since December 31, 1 BCE.
16248 If the fourth element is present, it should be a symbol---the @dfn{type
16249 element}. This element specifies what function should be used to see
16250 whether this score entry matches the article. What match types that can
16251 be used depends on what header you wish to perform the match on.
16254 @item From, Subject, References, Xref, Message-ID
16255 For most header types, there are the @code{r} and @code{R} (regexp), as
16256 well as @code{s} and @code{S} (substring) types, and @code{e} and
16257 @code{E} (exact match), and @code{w} (word match) types. If this
16258 element is not present, Gnus will assume that substring matching should
16259 be used. @code{R}, @code{S}, and @code{E} differ from the others in
16260 that the matches will be done in a case-sensitive manner. All these
16261 one-letter types are really just abbreviations for the @code{regexp},
16262 @code{string}, @code{exact}, and @code{word} types, which you can use
16263 instead, if you feel like.
16266 These two headers use different match types: @code{<}, @code{>},
16267 @code{=}, @code{>=} and @code{<=}.
16269 These predicates are true if
16272 (PREDICATE HEADER MATCH)
16275 evaluates to non-@code{nil}. For instance, the advanced match
16276 @code{("lines" 4 <)} (@pxref{Advanced Scoring}) will result in the
16283 Or to put it another way: When using @code{<} on @code{Lines} with 4 as
16284 the match, we get the score added if the article has less than 4 lines.
16285 (It's easy to get confused and think it's the other way around. But
16286 it's not. I think.)
16288 When matching on @code{Lines}, be careful because some backends (like
16289 @code{nndir}) do not generate @code{Lines} header, so every article ends
16290 up being marked as having 0 lines. This can lead to strange results if
16291 you happen to lower score of the articles with few lines.
16294 For the Date header we have three kinda silly match types:
16295 @code{before}, @code{at} and @code{after}. I can't really imagine this
16296 ever being useful, but, like, it would feel kinda silly not to provide
16297 this function. Just in case. You never know. Better safe than sorry.
16298 Once burnt, twice shy. Don't judge a book by its cover. Never not have
16299 sex on a first date. (I have been told that at least one person, and I
16300 quote, ``found this function indispensable'', however.)
16304 A more useful match type is @code{regexp}. With it, you can match the
16305 date string using a regular expression. The date is normalized to
16306 ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. If
16307 you want to match all articles that have been posted on April 1st in
16308 every year, you could use @samp{....0401.........} as a match string,
16309 for instance. (Note that the date is kept in its original time zone, so
16310 this will match articles that were posted when it was April 1st where
16311 the article was posted from. Time zones are such wholesome fun for the
16314 @item Head, Body, All
16315 These three match keys use the same match types as the @code{From} (etc)
16319 This match key is somewhat special, in that it will match the
16320 @code{From} header, and affect the score of not only the matching
16321 articles, but also all followups to the matching articles. This allows
16322 you e.g. increase the score of followups to your own articles, or
16323 decrease the score of followups to the articles of some known
16324 trouble-maker. Uses the same match types as the @code{From} header
16325 uses. (Using this match key will lead to creation of @file{ADAPT}
16329 This match key works along the same lines as the @code{Followup} match
16330 key. If you say that you want to score on a (sub-)thread started by an
16331 article with a @code{Message-ID} @var{x}, then you add a @samp{thread}
16332 match. This will add a new @samp{thread} match for each article that
16333 has @var{x} in its @code{References} header. (These new @samp{thread}
16334 matches will use the @code{Message-ID}s of these matching articles.)
16335 This will ensure that you can raise/lower the score of an entire thread,
16336 even though some articles in the thread may not have complete
16337 @code{References} headers. Note that using this may lead to
16338 undeterministic scores of the articles in the thread. (Using this match
16339 key will lead to creation of @file{ADAPT} files.)
16343 @cindex Score File Atoms
16345 The value of this entry should be a number. Any articles with a score
16346 lower than this number will be marked as read.
16349 The value of this entry should be a number. Any articles with a score
16350 lower than this number will be removed from the summary buffer.
16352 @item mark-and-expunge
16353 The value of this entry should be a number. Any articles with a score
16354 lower than this number will be marked as read and removed from the
16357 @item thread-mark-and-expunge
16358 The value of this entry should be a number. All articles that belong to
16359 a thread that has a total score below this number will be marked as read
16360 and removed from the summary buffer. @code{gnus-thread-score-function}
16361 says how to compute the total score for a thread.
16364 The value of this entry should be any number of file names. These files
16365 are assumed to be score files as well, and will be loaded the same way
16368 @item exclude-files
16369 The clue of this entry should be any number of files. These files will
16370 not be loaded, even though they would normally be so, for some reason or
16374 The value of this entry will be @code{eval}el. This element will be
16375 ignored when handling global score files.
16378 Read-only score files will not be updated or saved. Global score files
16379 should feature this atom (@pxref{Global Score Files}). (Note:
16380 @dfn{Global} here really means @dfn{global}; not your personal
16381 apply-to-all-groups score files.)
16384 The value of this entry should be a number. Articles that do not have
16385 parents will get this number added to their scores. Imagine you follow
16386 some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you
16387 will only follow a few of the threads, also want to see any new threads.
16389 You can do this with the following two score file entries:
16393 (mark-and-expunge -100)
16396 When you enter the group the first time, you will only see the new
16397 threads. You then raise the score of the threads that you find
16398 interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the
16399 rest. Next time you enter the group, you will see new articles in the
16400 interesting threads, plus any new threads.
16402 I.e.---the orphan score atom is for high-volume groups where a few
16403 interesting threads which can't be found automatically by ordinary
16404 scoring rules exist.
16407 This entry controls the adaptive scoring. If it is @code{t}, the
16408 default adaptive scoring rules will be used. If it is @code{ignore}, no
16409 adaptive scoring will be performed on this group. If it is a list, this
16410 list will be used as the adaptive scoring rules. If it isn't present,
16411 or is something other than @code{t} or @code{ignore}, the default
16412 adaptive scoring rules will be used. If you want to use adaptive
16413 scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
16414 @code{t}, and insert an @code{(adapt ignore)} in the groups where you do
16415 not want adaptive scoring. If you only want adaptive scoring in a few
16416 groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
16417 insert @code{(adapt t)} in the score files of the groups where you want
16421 All adaptive score entries will go to the file named by this entry. It
16422 will also be applied when entering the group. This atom might be handy
16423 if you want to adapt on several groups at once, using the same adaptive
16424 file for a number of groups.
16427 @cindex local variables
16428 The value of this entry should be a list of @code{(VAR VALUE)} pairs.
16429 Each @var{var} will be made buffer-local to the current summary buffer,
16430 and set to the value specified. This is a convenient, if somewhat
16431 strange, way of setting variables in some groups if you don't like hooks
16432 much. Note that the @var{value} won't be evaluated.
16436 @node Score File Editing
16437 @section Score File Editing
16439 You normally enter all scoring commands from the summary buffer, but you
16440 might feel the urge to edit them by hand as well, so we've supplied you
16441 with a mode for that.
16443 It's simply a slightly customized @code{emacs-lisp} mode, with these
16444 additional commands:
16449 @kindex C-c C-c (Score)
16450 @findex gnus-score-edit-done
16451 Save the changes you have made and return to the summary buffer
16452 (@code{gnus-score-edit-done}).
16455 @kindex C-c C-d (Score)
16456 @findex gnus-score-edit-insert-date
16457 Insert the current date in numerical format
16458 (@code{gnus-score-edit-insert-date}). This is really the day number, if
16459 you were wondering.
16462 @kindex C-c C-p (Score)
16463 @findex gnus-score-pretty-print
16464 The adaptive score files are saved in an unformatted fashion. If you
16465 intend to read one of these files, you want to @dfn{pretty print} it
16466 first. This command (@code{gnus-score-pretty-print}) does that for
16471 Type @kbd{M-x gnus-score-mode} to use this mode.
16473 @vindex gnus-score-mode-hook
16474 @code{gnus-score-menu-hook} is run in score mode buffers.
16476 In the summary buffer you can use commands like @kbd{V f} and @kbd{V
16477 e} to begin editing score files.
16480 @node Adaptive Scoring
16481 @section Adaptive Scoring
16482 @cindex adaptive scoring
16484 If all this scoring is getting you down, Gnus has a way of making it all
16485 happen automatically---as if by magic. Or rather, as if by artificial
16486 stupidity, to be precise.
16488 @vindex gnus-use-adaptive-scoring
16489 When you read an article, or mark an article as read, or kill an
16490 article, you leave marks behind. On exit from the group, Gnus can sniff
16491 these marks and add score elements depending on what marks it finds.
16492 You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
16493 @code{t} or @code{(line)}. If you want score adaptively on separate
16494 words appearing in the subjects, you should set this variable to
16495 @code{(word)}. If you want to use both adaptive methods, set this
16496 variable to @code{(word line)}.
16498 @vindex gnus-default-adaptive-score-alist
16499 To give you complete control over the scoring process, you can customize
16500 the @code{gnus-default-adaptive-score-alist} variable. For instance, it
16501 might look something like this:
16504 (setq gnus-default-adaptive-score-alist
16505 '((gnus-unread-mark)
16506 (gnus-ticked-mark (from 4))
16507 (gnus-dormant-mark (from 5))
16508 (gnus-del-mark (from -4) (subject -1))
16509 (gnus-read-mark (from 4) (subject 2))
16510 (gnus-expirable-mark (from -1) (subject -1))
16511 (gnus-killed-mark (from -1) (subject -3))
16512 (gnus-kill-file-mark)
16513 (gnus-ancient-mark)
16514 (gnus-low-score-mark)
16515 (gnus-catchup-mark (from -1) (subject -1))))
16518 As you see, each element in this alist has a mark as a key (either a
16519 variable name or a ``real'' mark---a character). Following this key is
16520 a arbitrary number of header/score pairs. If there are no header/score
16521 pairs following the key, no adaptive scoring will be done on articles
16522 that have that key as the article mark. For instance, articles with
16523 @code{gnus-unread-mark} in the example above will not get adaptive score
16526 Each article can have only one mark, so just a single of these rules
16527 will be applied to each article.
16529 To take @code{gnus-del-mark} as an example---this alist says that all
16530 articles that have that mark (i.e., are marked with @samp{D}) will have a
16531 score entry added to lower based on the @code{From} header by -4, and
16532 lowered by @code{Subject} by -1. Change this to fit your prejudices.
16534 If you have marked 10 articles with the same subject with
16535 @code{gnus-del-mark}, the rule for that mark will be applied ten times.
16536 That means that that subject will get a score of ten times -1, which
16537 should be, unless I'm much mistaken, -10.
16539 If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all
16540 the read articles will be marked with the @samp{E} mark. This'll
16541 probably make adaptive scoring slightly impossible, so auto-expiring and
16542 adaptive scoring doesn't really mix very well.
16544 The headers you can score on are @code{from}, @code{subject},
16545 @code{message-id}, @code{references}, @code{xref}, @code{lines},
16546 @code{chars} and @code{date}. In addition, you can score on
16547 @code{followup}, which will create an adaptive score entry that matches
16548 on the @code{References} header using the @code{Message-ID} of the
16549 current article, thereby matching the following thread.
16551 You can also score on @code{thread}, which will try to score all
16552 articles that appear in a thread. @code{thread} matches uses a
16553 @code{Message-ID} to match on the @code{References} header of the
16554 article. If the match is made, the @code{Message-ID} of the article is
16555 added to the @code{thread} rule. (Think about it. I'd recommend two
16556 aspirins afterwards.)
16558 If you use this scheme, you should set the score file atom @code{mark}
16559 to something small---like -300, perhaps, to avoid having small random
16560 changes result in articles getting marked as read.
16562 After using adaptive scoring for a week or so, Gnus should start to
16563 become properly trained and enhance the authors you like best, and kill
16564 the authors you like least, without you having to say so explicitly.
16566 You can control what groups the adaptive scoring is to be performed on
16567 by using the score files (@pxref{Score File Format}). This will also
16568 let you use different rules in different groups.
16570 @vindex gnus-adaptive-file-suffix
16571 The adaptive score entries will be put into a file where the name is the
16572 group name with @code{gnus-adaptive-file-suffix} appended. The default
16575 @vindex gnus-score-exact-adapt-limit
16576 When doing adaptive scoring, substring or fuzzy matching would probably
16577 give you the best results in most cases. However, if the header one
16578 matches is short, the possibility for false positives is great, so if
16579 the length of the match is less than
16580 @code{gnus-score-exact-adapt-limit}, exact matching will be used. If
16581 this variable is @code{nil}, exact matching will always be used to avoid
16584 @vindex gnus-default-adaptive-word-score-alist
16585 As mentioned above, you can adapt either on individual words or entire
16586 headers. If you adapt on words, the
16587 @code{gnus-default-adaptive-word-score-alist} variable says what score
16588 each instance of a word should add given a mark.
16591 (setq gnus-default-adaptive-word-score-alist
16592 `((,gnus-read-mark . 30)
16593 (,gnus-catchup-mark . -10)
16594 (,gnus-killed-mark . -20)
16595 (,gnus-del-mark . -15)))
16598 This is the default value. If you have adaption on words enabled, every
16599 word that appears in subjects of articles marked with
16600 @code{gnus-read-mark} will result in a score rule that increase the
16601 score with 30 points.
16603 @vindex gnus-default-ignored-adaptive-words
16604 @vindex gnus-ignored-adaptive-words
16605 Words that appear in the @code{gnus-default-ignored-adaptive-words} list
16606 will be ignored. If you wish to add more words to be ignored, use the
16607 @code{gnus-ignored-adaptive-words} list instead.
16609 @vindex gnus-adaptive-word-length-limit
16610 Some may feel that short words shouldn't count when doing adaptive
16611 scoring. If so, you may set @code{gnus-adaptive-word-length-limit} to
16612 an integer. Words shorter than this number will be ignored. This
16613 variable defaults til @code{nil}.
16615 @vindex gnus-adaptive-word-syntax-table
16616 When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the
16617 syntax table in effect. It is similar to the standard syntax table, but
16618 it considers numbers to be non-word-constituent characters.
16620 @vindex gnus-adaptive-word-minimum
16621 If @code{gnus-adaptive-word-minimum} is set to a number, the adaptive
16622 word scoring process will never bring down the score of an article to
16623 below this number. The default is @code{nil}.
16625 @vindex gnus-adaptive-word-no-group-words
16626 If @code{gnus-adaptive-word-no-group-words} is set to @code{t}, gnus
16627 won't adaptively word score any of the words in the group name. Useful
16628 for groups like @samp{comp.editors.emacs}, where most of the subject
16629 lines contain the word @samp{emacs}.
16631 After using this scheme for a while, it might be nice to write a
16632 @code{gnus-psychoanalyze-user} command to go through the rules and see
16633 what words you like and what words you don't like. Or perhaps not.
16635 Note that the adaptive word scoring thing is highly experimental and is
16636 likely to change in the future. Initial impressions seem to indicate
16637 that it's totally useless as it stands. Some more work (involving more
16638 rigorous statistical methods) will have to be done to make this useful.
16641 @node Home Score File
16642 @section Home Score File
16644 The score file where new score file entries will go is called the
16645 @dfn{home score file}. This is normally (and by default) the score file
16646 for the group itself. For instance, the home score file for
16647 @samp{gnu.emacs.gnus} is @file{gnu.emacs.gnus.SCORE}.
16649 However, this may not be what you want. It is often convenient to share
16650 a common home score file among many groups---all @samp{emacs} groups
16651 could perhaps use the same home score file.
16653 @vindex gnus-home-score-file
16654 The variable that controls this is @code{gnus-home-score-file}. It can
16659 A string. Then this file will be used as the home score file for all
16663 A function. The result of this function will be used as the home score
16664 file. The function will be called with the name of the group as the
16668 A list. The elements in this list can be:
16672 @code{(@var{regexp} @var{file-name})}. If the @var{regexp} matches the
16673 group name, the @var{file-name} will be used as the home score file.
16676 A function. If the function returns non-nil, the result will be used as
16677 the home score file.
16680 A string. Use the string as the home score file.
16683 The list will be traversed from the beginning towards the end looking
16688 So, if you want to use just a single score file, you could say:
16691 (setq gnus-home-score-file
16692 "my-total-score-file.SCORE")
16695 If you want to use @file{gnu.SCORE} for all @samp{gnu} groups and
16696 @file{rec.SCORE} for all @samp{rec} groups (and so on), you can say:
16698 @findex gnus-hierarchial-home-score-file
16700 (setq gnus-home-score-file
16701 'gnus-hierarchial-home-score-file)
16704 This is a ready-made function provided for your convenience.
16705 Other functions include
16708 @item gnus-current-home-score-file
16709 @findex gnus-current-home-score-file
16710 Return the ``current'' regular score file. This will make scoring
16711 commands add entry to the ``innermost'' matching score file.
16715 If you want to have one score file for the @samp{emacs} groups and
16716 another for the @samp{comp} groups, while letting all other groups use
16717 their own home score files:
16720 (setq gnus-home-score-file
16721 ;; All groups that match the regexp "\\.emacs"
16722 '(("\\.emacs" "emacs.SCORE")
16723 ;; All the comp groups in one score file
16724 ("^comp" "comp.SCORE")))
16727 @vindex gnus-home-adapt-file
16728 @code{gnus-home-adapt-file} works exactly the same way as
16729 @code{gnus-home-score-file}, but says what the home adaptive score file
16730 is instead. All new adaptive file entries will go into the file
16731 specified by this variable, and the same syntax is allowed.
16733 In addition to using @code{gnus-home-score-file} and
16734 @code{gnus-home-adapt-file}, you can also use group parameters
16735 (@pxref{Group Parameters}) and topic parameters (@pxref{Topic
16736 Parameters}) to achieve much the same. Group and topic parameters take
16737 precedence over this variable.
16740 @node Followups To Yourself
16741 @section Followups To Yourself
16743 Gnus offers two commands for picking out the @code{Message-ID} header in
16744 the current buffer. Gnus will then add a score rule that scores using
16745 this @code{Message-ID} on the @code{References} header of other
16746 articles. This will, in effect, increase the score of all articles that
16747 respond to the article in the current buffer. Quite useful if you want
16748 to easily note when people answer what you've said.
16752 @item gnus-score-followup-article
16753 @findex gnus-score-followup-article
16754 This will add a score to articles that directly follow up your own
16757 @item gnus-score-followup-thread
16758 @findex gnus-score-followup-thread
16759 This will add a score to all articles that appear in a thread ``below''
16763 @vindex message-sent-hook
16764 These two functions are both primarily meant to be used in hooks like
16765 @code{message-sent-hook}, like this:
16767 (add-hook 'message-sent-hook 'gnus-score-followup-thread)
16771 If you look closely at your own @code{Message-ID}, you'll notice that
16772 the first two or three characters are always the same. Here's two of
16776 <x6u3u47icf.fsf@@eyesore.no>
16777 <x6sp9o7ibw.fsf@@eyesore.no>
16780 So ``my'' ident on this machine is @samp{x6}. This can be
16781 exploited---the following rule will raise the score on all followups to
16786 ("<x6[0-9a-z]+\\.fsf\\(_-_\\)?@@.*eyesore\\.no>"
16790 Whether it's the first two or first three characters that are ``yours''
16791 is system-dependent.
16795 @section Scoring Tips
16796 @cindex scoring tips
16802 @cindex scoring crossposts
16803 If you want to lower the score of crossposts, the line to match on is
16804 the @code{Xref} header.
16806 ("xref" (" talk.politics.misc:" -1000))
16809 @item Multiple crossposts
16810 If you want to lower the score of articles that have been crossposted to
16811 more than, say, 3 groups:
16814 ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+"
16818 @item Matching on the body
16819 This is generally not a very good idea---it takes a very long time.
16820 Gnus actually has to fetch each individual article from the server. But
16821 you might want to anyway, I guess. Even though there are three match
16822 keys (@code{Head}, @code{Body} and @code{All}), you should choose one
16823 and stick with it in each score file. If you use any two, each article
16824 will be fetched @emph{twice}. If you want to match a bit on the
16825 @code{Head} and a bit on the @code{Body}, just use @code{All} for all
16828 @item Marking as read
16829 You will probably want to mark articles that have scores below a certain
16830 number as read. This is most easily achieved by putting the following
16831 in your @file{all.SCORE} file:
16835 You may also consider doing something similar with @code{expunge}.
16837 @item Negated character classes
16838 If you say stuff like @code{[^abcd]*}, you may get unexpected results.
16839 That will match newlines, which might lead to, well, The Unknown. Say
16840 @code{[^abcd\n]*} instead.
16844 @node Reverse Scoring
16845 @section Reverse Scoring
16846 @cindex reverse scoring
16848 If you want to keep just articles that have @samp{Sex with Emacs} in the
16849 subject header, and expunge all other articles, you could put something
16850 like this in your score file:
16854 ("Sex with Emacs" 2))
16859 So, you raise all articles that match @samp{Sex with Emacs} and mark the
16860 rest as read, and expunge them to boot.
16863 @node Global Score Files
16864 @section Global Score Files
16865 @cindex global score files
16867 Sure, other newsreaders have ``global kill files''. These are usually
16868 nothing more than a single kill file that applies to all groups, stored
16869 in the user's home directory. Bah! Puny, weak newsreaders!
16871 What I'm talking about here are Global Score Files. Score files from
16872 all over the world, from users everywhere, uniting all nations in one
16873 big, happy score file union! Ange-score! New and untested!
16875 @vindex gnus-global-score-files
16876 All you have to do to use other people's score files is to set the
16877 @code{gnus-global-score-files} variable. One entry for each score file,
16878 or each score file directory. Gnus will decide by itself what score
16879 files are applicable to which group.
16881 To use the score file
16882 @file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and
16883 all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory,
16887 (setq gnus-global-score-files
16888 '("/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE"
16889 "/ftp@@ftp.some-where:/pub/score/"))
16892 @findex gnus-score-search-global-directories
16894 Simple, eh? Directory names must end with a @samp{/}. These
16895 directories are typically scanned only once during each Gnus session.
16896 If you feel the need to manually re-scan the remote directories, you can
16897 use the @code{gnus-score-search-global-directories} command.
16899 Note that, at present, using this option will slow down group entry
16900 somewhat. (That is---a lot.)
16902 If you want to start maintaining score files for other people to use,
16903 just put your score file up for anonymous ftp and announce it to the
16904 world. Become a retro-moderator! Participate in the retro-moderator
16905 wars sure to ensue, where retro-moderators battle it out for the
16906 sympathy of the people, luring them to use their score files on false
16907 premises! Yay! The net is saved!
16909 Here are some tips for the would-be retro-moderator, off the top of my
16915 Articles heavily crossposted are probably junk.
16917 To lower a single inappropriate article, lower by @code{Message-ID}.
16919 Particularly brilliant authors can be raised on a permanent basis.
16921 Authors that repeatedly post off-charter for the group can safely be
16922 lowered out of existence.
16924 Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
16925 articles completely.
16928 Use expiring score entries to keep the size of the file down. You
16929 should probably have a long expiry period, though, as some sites keep
16930 old articles for a long time.
16933 ... I wonder whether other newsreaders will support global score files
16934 in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
16935 Wave, xrn and 1stReader are bound to implement scoring. Should we start
16936 holding our breath yet?
16940 @section Kill Files
16943 Gnus still supports those pesky old kill files. In fact, the kill file
16944 entries can now be expiring, which is something I wrote before Daniel
16945 Quinlan thought of doing score files, so I've left the code in there.
16947 In short, kill processing is a lot slower (and I do mean @emph{a lot})
16948 than score processing, so it might be a good idea to rewrite your kill
16949 files into score files.
16951 Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
16952 forms into this file, which means that you can use kill files as some
16953 sort of primitive hook function to be run on group entry, even though
16954 that isn't a very good idea.
16956 Normal kill files look like this:
16959 (gnus-kill "From" "Lars Ingebrigtsen")
16960 (gnus-kill "Subject" "ding")
16964 This will mark every article written by me as read, and remove the
16965 marked articles from the summary buffer. Very useful, you'll agree.
16967 Other programs use a totally different kill file syntax. If Gnus
16968 encounters what looks like a @code{rn} kill file, it will take a stab at
16971 Two summary functions for editing a GNUS kill file:
16976 @kindex M-k (Summary)
16977 @findex gnus-summary-edit-local-kill
16978 Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
16981 @kindex M-K (Summary)
16982 @findex gnus-summary-edit-global-kill
16983 Edit the general kill file (@code{gnus-summary-edit-global-kill}).
16986 Two group mode functions for editing the kill files:
16991 @kindex M-k (Group)
16992 @findex gnus-group-edit-local-kill
16993 Edit this group's kill file (@code{gnus-group-edit-local-kill}).
16996 @kindex M-K (Group)
16997 @findex gnus-group-edit-global-kill
16998 Edit the general kill file (@code{gnus-group-edit-global-kill}).
17001 Kill file variables:
17004 @item gnus-kill-file-name
17005 @vindex gnus-kill-file-name
17006 A kill file for the group @samp{soc.motss} is normally called
17007 @file{soc.motss.KILL}. The suffix appended to the group name to get
17008 this file name is detailed by the @code{gnus-kill-file-name} variable.
17009 The ``global'' kill file (not in the score file sense of ``global'', of
17010 course) is just called @file{KILL}.
17012 @vindex gnus-kill-save-kill-file
17013 @item gnus-kill-save-kill-file
17014 If this variable is non-@code{nil}, Gnus will save the
17015 kill file after processing, which is necessary if you use expiring
17018 @item gnus-apply-kill-hook
17019 @vindex gnus-apply-kill-hook
17020 @findex gnus-apply-kill-file-unless-scored
17021 @findex gnus-apply-kill-file
17022 A hook called to apply kill files to a group. It is
17023 @code{(gnus-apply-kill-file)} by default. If you want to ignore the
17024 kill file if you have a score file for the same group, you can set this
17025 hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want
17026 kill files to be processed, you should set this variable to @code{nil}.
17028 @item gnus-kill-file-mode-hook
17029 @vindex gnus-kill-file-mode-hook
17030 A hook called in kill-file mode buffers.
17035 @node Converting Kill Files
17036 @section Converting Kill Files
17038 @cindex converting kill files
17040 If you have loads of old kill files, you may want to convert them into
17041 score files. If they are ``regular'', you can use
17042 the @file{gnus-kill-to-score.el} package; if not, you'll have to do it
17045 The kill to score conversion package isn't included in Gnus by default.
17046 You can fetch it from
17047 @uref{http://www.stud.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}.
17049 If your old kill files are very complex---if they contain more
17050 non-@code{gnus-kill} forms than not, you'll have to convert them by
17051 hand. Or just let them be as they are. Gnus will still use them as
17059 GroupLens is a collaborative filtering system that helps you work
17060 together with other people to find the quality news articles out of the
17061 huge volume of news articles generated every day.
17063 To accomplish this the GroupLens system combines your opinions about
17064 articles you have already read with the opinions of others who have done
17065 likewise and gives you a personalized prediction for each unread news
17066 article. Think of GroupLens as a matchmaker. GroupLens watches how you
17067 rate articles, and finds other people that rate articles the same way.
17068 Once it has found some people you agree with it tells you, in the form
17069 of a prediction, what they thought of the article. You can use this
17070 prediction to help you decide whether or not you want to read the
17074 * Using GroupLens:: How to make Gnus use GroupLens.
17075 * Rating Articles:: Letting GroupLens know how you rate articles.
17076 * Displaying Predictions:: Displaying predictions given by GroupLens.
17077 * GroupLens Variables:: Customizing GroupLens.
17081 @node Using GroupLens
17082 @subsection Using GroupLens
17084 To use GroupLens you must register a pseudonym with your local Better
17086 @uref{http://www.cs.umn.edu/Research/GroupLens/bbb.html} is the only
17087 better bit in town at the moment.
17089 Once you have registered you'll need to set a couple of variables.
17093 @item gnus-use-grouplens
17094 @vindex gnus-use-grouplens
17095 Setting this variable to a non-@code{nil} value will make Gnus hook into
17096 all the relevant GroupLens functions.
17098 @item grouplens-pseudonym
17099 @vindex grouplens-pseudonym
17100 This variable should be set to the pseudonym you got when registering
17101 with the Better Bit Bureau.
17103 @item grouplens-newsgroups
17104 @vindex grouplens-newsgroups
17105 A list of groups that you want to get GroupLens predictions for.
17109 That's the minimum of what you need to get up and running with GroupLens.
17110 Once you've registered, GroupLens will start giving you scores for
17111 articles based on the average of what other people think. But, to get
17112 the real benefit of GroupLens you need to start rating articles
17113 yourself. Then the scores GroupLens gives you will be personalized for
17114 you, based on how the people you usually agree with have already rated.
17117 @node Rating Articles
17118 @subsection Rating Articles
17120 In GroupLens, an article is rated on a scale from 1 to 5, inclusive.
17121 Where 1 means something like this article is a waste of bandwidth and 5
17122 means that the article was really good. The basic question to ask
17123 yourself is, "on a scale from 1 to 5 would I like to see more articles
17126 There are four ways to enter a rating for an article in GroupLens.
17131 @kindex r (GroupLens)
17132 @findex bbb-summary-rate-article
17133 This function will prompt you for a rating on a scale of one to five.
17136 @kindex k (GroupLens)
17137 @findex grouplens-score-thread
17138 This function will prompt you for a rating, and rate all the articles in
17139 the thread. This is really useful for some of those long running giant
17140 threads in rec.humor.
17144 The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be
17145 the score of the article you're reading.
17150 @kindex n (GroupLens)
17151 @findex grouplens-next-unread-article
17152 Rate the article and go to the next unread article.
17155 @kindex , (GroupLens)
17156 @findex grouplens-best-unread-article
17157 Rate the article and go to the next unread article with the highest score.
17161 If you want to give the current article a score of 4 and then go to the
17162 next article, just type @kbd{4 n}.
17165 @node Displaying Predictions
17166 @subsection Displaying Predictions
17168 GroupLens makes a prediction for you about how much you will like a
17169 news article. The predictions from GroupLens are on a scale from 1 to
17170 5, where 1 is the worst and 5 is the best. You can use the predictions
17171 from GroupLens in one of three ways controlled by the variable
17172 @code{gnus-grouplens-override-scoring}.
17174 @vindex gnus-grouplens-override-scoring
17175 There are three ways to display predictions in grouplens. You may
17176 choose to have the GroupLens scores contribute to, or override the
17177 regular gnus scoring mechanism. override is the default; however, some
17178 people prefer to see the Gnus scores plus the grouplens scores. To get
17179 the separate scoring behavior you need to set
17180 @code{gnus-grouplens-override-scoring} to @code{'separate}. To have the
17181 GroupLens predictions combined with the grouplens scores set it to
17182 @code{'override} and to combine the scores set
17183 @code{gnus-grouplens-override-scoring} to @code{'combine}. When you use
17184 the combine option you will also want to set the values for
17185 @code{grouplens-prediction-offset} and
17186 @code{grouplens-score-scale-factor}.
17188 @vindex grouplens-prediction-display
17189 In either case, GroupLens gives you a few choices for how you would like
17190 to see your predictions displayed. The display of predictions is
17191 controlled by the @code{grouplens-prediction-display} variable.
17193 The following are valid values for that variable.
17196 @item prediction-spot
17197 The higher the prediction, the further to the right an @samp{*} is
17200 @item confidence-interval
17201 A numeric confidence interval.
17203 @item prediction-bar
17204 The higher the prediction, the longer the bar.
17206 @item confidence-bar
17207 Numerical confidence.
17209 @item confidence-spot
17210 The spot gets bigger with more confidence.
17212 @item prediction-num
17213 Plain-old numeric value.
17215 @item confidence-plus-minus
17216 Prediction +/- confidence.
17221 @node GroupLens Variables
17222 @subsection GroupLens Variables
17226 @item gnus-summary-grouplens-line-format
17227 The summary line format used in GroupLens-enhanced summary buffers. It
17228 accepts the same specs as the normal summary line format (@pxref{Summary
17229 Buffer Lines}). The default is @samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%)
17232 @item grouplens-bbb-host
17233 Host running the bbbd server. @samp{grouplens.cs.umn.edu} is the
17236 @item grouplens-bbb-port
17237 Port of the host running the bbbd server. The default is 9000.
17239 @item grouplens-score-offset
17240 Offset the prediction by this value. In other words, subtract the
17241 prediction value by this number to arrive at the effective score. The
17244 @item grouplens-score-scale-factor
17245 This variable allows the user to magnify the effect of GroupLens scores.
17246 The scale factor is applied after the offset. The default is 1.
17251 @node Advanced Scoring
17252 @section Advanced Scoring
17254 Scoring on Subjects and From headers is nice enough, but what if you're
17255 really interested in what a person has to say only when she's talking
17256 about a particular subject? Or what if you really don't want to
17257 read what person A has to say when she's following up to person B, but
17258 want to read what she says when she's following up to person C?
17260 By using advanced scoring rules you may create arbitrarily complex
17264 * Advanced Scoring Syntax:: A definition.
17265 * Advanced Scoring Examples:: What they look like.
17266 * Advanced Scoring Tips:: Getting the most out of it.
17270 @node Advanced Scoring Syntax
17271 @subsection Advanced Scoring Syntax
17273 Ordinary scoring rules have a string as the first element in the rule.
17274 Advanced scoring rules have a list as the first element. The second
17275 element is the score to be applied if the first element evaluated to a
17276 non-@code{nil} value.
17278 These lists may consist of three logical operators, one redirection
17279 operator, and various match operators.
17286 This logical operator will evaluate each of its arguments until it finds
17287 one that evaluates to @code{false}, and then it'll stop. If all arguments
17288 evaluate to @code{true} values, then this operator will return
17293 This logical operator will evaluate each of its arguments until it finds
17294 one that evaluates to @code{true}. If no arguments are @code{true},
17295 then this operator will return @code{false}.
17300 This logical operator only takes a single argument. It returns the
17301 logical negation of the value of its argument.
17305 There is an @dfn{indirection operator} that will make its arguments
17306 apply to the ancestors of the current article being scored. For
17307 instance, @code{1-} will make score rules apply to the parent of the
17308 current article. @code{2-} will make score rules apply to the
17309 grandparent of the current article. Alternatively, you can write
17310 @code{^^}, where the number of @code{^}s (carets) says how far back into
17311 the ancestry you want to go.
17313 Finally, we have the match operators. These are the ones that do the
17314 real work. Match operators are header name strings followed by a match
17315 and a match type. A typical match operator looks like @samp{("from"
17316 "Lars Ingebrigtsen" s)}. The header names are the same as when using
17317 simple scoring, and the match types are also the same.
17320 @node Advanced Scoring Examples
17321 @subsection Advanced Scoring Examples
17323 Let's say you want to increase the score of articles written by Lars
17324 when he's talking about Gnus:
17328 ("from" "Lars Ingebrigtsen")
17329 ("subject" "Gnus"))
17335 When he writes long articles, he sometimes has something nice to say:
17339 ("from" "Lars Ingebrigtsen")
17346 However, when he responds to things written by Reig Eigil Logge, you
17347 really don't want to read what he's written:
17351 ("from" "Lars Ingebrigtsen")
17352 (1- ("from" "Reig Eigir Logge")))
17356 Everybody that follows up Redmondo when he writes about disappearing
17357 socks should have their scores raised, but only when they talk about
17358 white socks. However, when Lars talks about socks, it's usually not
17365 ("from" "redmondo@@.*no" r)
17366 ("body" "disappearing.*socks" t)))
17367 (! ("from" "Lars Ingebrigtsen"))
17368 ("body" "white.*socks"))
17372 The possibilities are endless.
17375 @node Advanced Scoring Tips
17376 @subsection Advanced Scoring Tips
17378 The @code{&} and @code{|} logical operators do short-circuit logic.
17379 That is, they stop processing their arguments when it's clear what the
17380 result of the operation will be. For instance, if one of the arguments
17381 of an @code{&} evaluates to @code{false}, there's no point in evaluating
17382 the rest of the arguments. This means that you should put slow matches
17383 (@samp{body}, @samp{header}) last and quick matches (@samp{from},
17384 @samp{subject}) first.
17386 The indirection arguments (@code{1-} and so on) will make their
17387 arguments work on previous generations of the thread. If you say
17398 Then that means "score on the from header of the grandparent of the
17399 current article". An indirection is quite fast, but it's better to say:
17405 ("subject" "Gnus")))
17412 (1- ("from" "Lars"))
17413 (1- ("subject" "Gnus")))
17418 @section Score Decays
17419 @cindex score decays
17422 You may find that your scores have a tendency to grow without
17423 bounds, especially if you're using adaptive scoring. If scores get too
17424 big, they lose all meaning---they simply max out and it's difficult to
17425 use them in any sensible way.
17427 @vindex gnus-decay-scores
17428 @findex gnus-decay-score
17429 @vindex gnus-decay-score-function
17430 Gnus provides a mechanism for decaying scores to help with this problem.
17431 When score files are loaded and @code{gnus-decay-scores} is
17432 non-@code{nil}, Gnus will run the score files through the decaying
17433 mechanism thereby lowering the scores of all non-permanent score rules.
17434 The decay itself if performed by the @code{gnus-decay-score-function}
17435 function, which is @code{gnus-decay-score} by default. Here's the
17436 definition of that function:
17439 (defun gnus-decay-score (score)
17441 This is done according to `gnus-score-decay-constant'
17442 and `gnus-score-decay-scale'."
17445 (* (if (< score 0) 1 -1)
17447 (max gnus-score-decay-constant
17449 gnus-score-decay-scale)))))))
17452 @vindex gnus-score-decay-scale
17453 @vindex gnus-score-decay-constant
17454 @code{gnus-score-decay-constant} is 3 by default and
17455 @code{gnus-score-decay-scale} is 0.05. This should cause the following:
17459 Scores between -3 and 3 will be set to 0 when this function is called.
17462 Scores with magnitudes between 3 and 60 will be shrunk by 3.
17465 Scores with magnitudes greater than 60 will be shrunk by 5% of the
17469 If you don't like this decay function, write your own. It is called
17470 with the score to be decayed as its only parameter, and it should return
17471 the new score, which should be an integer.
17473 Gnus will try to decay scores once a day. If you haven't run Gnus for
17474 four days, Gnus will decay the scores four times, for instance.
17481 * Process/Prefix:: A convention used by many treatment commands.
17482 * Interactive:: Making Gnus ask you many questions.
17483 * Symbolic Prefixes:: How to supply some Gnus functions with options.
17484 * Formatting Variables:: You can specify what buffers should look like.
17485 * Windows Configuration:: Configuring the Gnus buffer windows.
17486 * Faces and Fonts:: How to change how faces look.
17487 * Compilation:: How to speed Gnus up.
17488 * Mode Lines:: Displaying information in the mode lines.
17489 * Highlighting and Menus:: Making buffers look all nice and cozy.
17490 * Buttons:: Get tendinitis in ten easy steps!
17491 * Daemons:: Gnus can do things behind your back.
17492 * NoCeM:: How to avoid spam and other fatty foods.
17493 * Undo:: Some actions can be undone.
17494 * Moderation:: What to do if you're a moderator.
17495 * XEmacs Enhancements:: There are more pictures and stuff under XEmacs.
17496 * Fuzzy Matching:: What's the big fuzz?
17497 * Thwarting Email Spam:: A how-to on avoiding unsolicited commercial email.
17498 * Various Various:: Things that are really various.
17502 @node Process/Prefix
17503 @section Process/Prefix
17504 @cindex process/prefix convention
17506 Many functions, among them functions for moving, decoding and saving
17507 articles, use what is known as the @dfn{Process/Prefix convention}.
17509 This is a method for figuring out what articles the user wants the
17510 command to be performed on.
17514 If the numeric prefix is N, perform the operation on the next N
17515 articles, starting with the current one. If the numeric prefix is
17516 negative, perform the operation on the previous N articles, starting
17517 with the current one.
17519 @vindex transient-mark-mode
17520 If @code{transient-mark-mode} in non-@code{nil} and the region is
17521 active, all articles in the region will be worked upon.
17523 If there is no numeric prefix, but some articles are marked with the
17524 process mark, perform the operation on the articles marked with
17527 If there is neither a numeric prefix nor any articles marked with the
17528 process mark, just perform the operation on the current article.
17530 Quite simple, really, but it needs to be made clear so that surprises
17533 Commands that react to the process mark will push the current list of
17534 process marked articles onto a stack and will then clear all process
17535 marked articles. You can restore the previous configuration with the
17536 @kbd{M P y} command (@pxref{Setting Process Marks}).
17538 @vindex gnus-summary-goto-unread
17539 One thing that seems to shock & horrify lots of people is that, for
17540 instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
17541 Since each @kbd{d} (which marks the current article as read) by default
17542 goes to the next unread article after marking, this means that @kbd{3 d}
17543 will mark the next three unread articles as read, no matter what the
17544 summary buffer looks like. Set @code{gnus-summary-goto-unread} to
17545 @code{nil} for a more straightforward action.
17547 Many commands do not use the process/prefix convention. All commands
17548 that do explicitly say so in this manual. To apply the process/prefix
17549 convention to commands that do not use it, you can use the @kbd{M-&}
17550 command. For instance, to mark all the articles in the group as
17551 expirable, you could say `M P b M-& E'.
17555 @section Interactive
17556 @cindex interaction
17560 @item gnus-novice-user
17561 @vindex gnus-novice-user
17562 If this variable is non-@code{nil}, you are either a newcomer to the
17563 World of Usenet, or you are very cautious, which is a nice thing to be,
17564 really. You will be given questions of the type ``Are you sure you want
17565 to do this?'' before doing anything dangerous. This is @code{t} by
17568 @item gnus-expert-user
17569 @vindex gnus-expert-user
17570 If this variable is non-@code{nil}, you will seldom be asked any
17571 questions by Gnus. It will simply assume you know what you're doing, no
17572 matter how strange.
17574 @item gnus-interactive-catchup
17575 @vindex gnus-interactive-catchup
17576 Require confirmation before catching up a group if non-@code{nil}. It
17577 is @code{t} by default.
17579 @item gnus-interactive-exit
17580 @vindex gnus-interactive-exit
17581 Require confirmation before exiting Gnus. This variable is @code{t} by
17586 @node Symbolic Prefixes
17587 @section Symbolic Prefixes
17588 @cindex symbolic prefixes
17590 Quite a lot of Emacs commands react to the (numeric) prefix. For
17591 instance, @kbd{C-u 4 C-f} moves point four characters forward, and
17592 @kbd{C-u 9 0 0 I s s p} adds a permanent @code{Subject} substring score
17593 rule of 900 to the current article.
17595 This is all nice and well, but what if you want to give a command some
17596 additional information? Well, what most commands do is interpret the
17597 ``raw'' prefix in some special way. @kbd{C-u 0 C-x C-s} means that one
17598 doesn't want a backup file to be created when saving the current buffer,
17599 for instance. But what if you want to save without making a backup
17600 file, and you want Emacs to flash lights and play a nice tune at the
17601 same time? You can't, and you're probably perfectly happy that way.
17603 @kindex M-i (Summary)
17604 @findex gnus-symbolic-argument
17605 I'm not, so I've added a second prefix---the @dfn{symbolic prefix}. The
17606 prefix key is @kbd{M-i} (@code{gnus-symbolic-argument}), and the next
17607 character typed in is the value. You can stack as many @kbd{M-i}
17608 prefixes as you want. @kbd{M-i a M-C-u} means ``feed the @kbd{M-C-u}
17609 command the symbolic prefix @code{a}''. @kbd{M-i a M-i b M-C-u} means
17610 ``feed the @kbd{M-C-u} command the symbolic prefixes @code{a} and
17611 @code{b}''. You get the drift.
17613 Typing in symbolic prefixes to commands that don't accept them doesn't
17614 hurt, but it doesn't do any good either. Currently not many Gnus
17615 functions make use of the symbolic prefix.
17617 If you're interested in how Gnus implements this, @pxref{Extended
17621 @node Formatting Variables
17622 @section Formatting Variables
17623 @cindex formatting variables
17625 Throughout this manual you've probably noticed lots of variables called
17626 things like @code{gnus-group-line-format} and
17627 @code{gnus-summary-mode-line-format}. These control how Gnus is to
17628 output lines in the various buffers. There's quite a lot of them.
17629 Fortunately, they all use the same syntax, so there's not that much to
17632 Here's an example format spec (from the group buffer): @samp{%M%S%5y:
17633 %(%g%)\n}. We see that it is indeed extremely ugly, and that there are
17634 lots of percentages everywhere.
17637 * Formatting Basics:: A formatting variable is basically a format string.
17638 * Mode Line Formatting:: Some rules about mode line formatting variables.
17639 * Advanced Formatting:: Modifying output in various ways.
17640 * User-Defined Specs:: Having Gnus call your own functions.
17641 * Formatting Fonts:: Making the formatting look colorful and nice.
17644 Currently Gnus uses the following formatting variables:
17645 @code{gnus-group-line-format}, @code{gnus-summary-line-format},
17646 @code{gnus-server-line-format}, @code{gnus-topic-line-format},
17647 @code{gnus-group-mode-line-format},
17648 @code{gnus-summary-mode-line-format},
17649 @code{gnus-article-mode-line-format},
17650 @code{gnus-server-mode-line-format}, and
17651 @code{gnus-summary-pick-line-format}.
17653 All these format variables can also be arbitrary elisp forms. In that
17654 case, they will be @code{eval}ed to insert the required lines.
17656 @kindex M-x gnus-update-format
17657 @findex gnus-update-format
17658 Gnus includes a command to help you while creating your own format
17659 specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
17660 update the spec in question and pop you to a buffer where you can
17661 examine the resulting lisp code to be run to generate the line.
17665 @node Formatting Basics
17666 @subsection Formatting Basics
17668 Each @samp{%} element will be replaced by some string or other when the
17669 buffer in question is generated. @samp{%5y} means ``insert the @samp{y}
17670 spec, and pad with spaces to get a 5-character field''.
17672 As with normal C and Emacs Lisp formatting strings, the numerical
17673 modifier between the @samp{%} and the formatting type character will
17674 @dfn{pad} the output so that it is always at least that long.
17675 @samp{%5y} will make the field always (at least) five characters wide by
17676 padding with spaces to the left. If you say @samp{%-5y}, it will pad to
17679 You may also wish to limit the length of the field to protect against
17680 particularly wide values. For that you can say @samp{%4,6y}, which
17681 means that the field will never be more than 6 characters wide and never
17682 less than 4 characters wide.
17685 @node Mode Line Formatting
17686 @subsection Mode Line Formatting
17688 Mode line formatting variables (e.g.,
17689 @code{gnus-summary-mode-line-format}) follow the same rules as other,
17690 buffer line oriented formatting variables (@pxref{Formatting Basics})
17691 with the following two differences:
17696 There must be no newline (@samp{\n}) at the end.
17699 The special @samp{%%b} spec can be used to display the buffer name.
17700 Well, it's no spec at all, really---@samp{%%} is just a way to quote
17701 @samp{%} to allow it to pass through the formatting machinery unmangled,
17702 so that Emacs receives @samp{%b}, which is something the Emacs mode line
17703 display interprets to mean ``show the buffer name''. For a full list of
17704 mode line specs Emacs understands, see the documentation of the
17705 @code{mode-line-format} variable.
17710 @node Advanced Formatting
17711 @subsection Advanced Formatting
17713 It is frequently useful to post-process the fields in some way.
17714 Padding, limiting, cutting off parts and suppressing certain values can
17715 be achieved by using @dfn{tilde modifiers}. A typical tilde spec might
17716 look like @samp{%~(cut 3)~(ignore "0")y}.
17718 These are the valid modifiers:
17723 Pad the field to the left with spaces until it reaches the required
17727 Pad the field to the right with spaces until it reaches the required
17732 Cut off characters from the left until it reaches the specified length.
17735 Cut off characters from the right until it reaches the specified
17740 Cut off the specified number of characters from the left.
17743 Cut off the specified number of characters from the right.
17746 Return an empty string if the field is equal to the specified value.
17749 Use the specified form as the field value when the @samp{@@} spec is
17753 Let's take an example. The @samp{%o} spec in the summary mode lines
17754 will return a date in compact ISO8601 format---@samp{19960809T230410}.
17755 This is quite a mouthful, so we want to shave off the century number and
17756 the time, leaving us with a six-character date. That would be
17757 @samp{%~(cut-left 2)~(max-right 6)~(pad 6)o}. (Cutting is done before
17758 maxing, and we need the padding to ensure that the date is never less
17759 than 6 characters to make it look nice in columns.)
17761 Ignoring is done first; then cutting; then maxing; and then as the very
17762 last operation, padding.
17764 @vindex gnus-compile-user-specs
17765 If @code{gnus-compile-user-specs} is set to @code{nil} (@code{t} by
17766 default) with your strong personality, and use a lots of these advanced
17767 thingies, you'll find that Gnus gets quite slow. This can be helped
17768 enormously by running @kbd{M-x gnus-compile} when you are satisfied with
17769 the look of your lines.
17770 @xref{Compilation}.
17773 @node User-Defined Specs
17774 @subsection User-Defined Specs
17776 All the specs allow for inserting user defined specifiers---@samp{u}.
17777 The next character in the format string should be a letter. Gnus
17778 will call the function @code{gnus-user-format-function-}@samp{X}, where
17779 @samp{X} is the letter following @samp{%u}. The function will be passed
17780 a single parameter---what the parameter means depends on what buffer
17781 it's being called from. The function should return a string, which will
17782 be inserted into the buffer just like information from any other
17783 specifier. This function may also be called with dummy values, so it
17784 should protect against that.
17786 You can also use tilde modifiers (@pxref{Advanced Formatting} to achieve
17787 much the same without defining new functions. Here's an example:
17788 @samp{%~(form (count-lines (point-min) (point)))@@}. The form
17789 given here will be evaluated to yield the current line number, and then
17793 @node Formatting Fonts
17794 @subsection Formatting Fonts
17796 There are specs for highlighting, and these are shared by all the format
17797 variables. Text inside the @samp{%(} and @samp{%)} specifiers will get
17798 the special @code{mouse-face} property set, which means that it will be
17799 highlighted (with @code{gnus-mouse-face}) when you put the mouse pointer
17802 Text inside the @samp{%@{} and @samp{%@}} specifiers will have their
17803 normal faces set using @code{gnus-face-0}, which is @code{bold} by
17804 default. If you say @samp{%1@{}, you'll get @code{gnus-face-1} instead,
17805 and so on. Create as many faces as you wish. The same goes for the
17806 @code{mouse-face} specs---you can say @samp{%3(hello%)} to have
17807 @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
17809 Text inside the @samp{%<} and @samp{%>} specifiers will get the special
17810 @code{balloon-help} property set to @code{gnus-balloon-face-0}. If you
17811 say @samp{%1<}, you'll get @code{gnus-balloon-face-1} and so on. The
17812 @code{gnus-balloon-face-*} variables should be either strings or symbols
17813 naming functions that return a string. Under @code{balloon-help-mode},
17814 when the mouse passes over text with this property set, a balloon window
17815 will appear and display the string. Please refer to the doc string of
17816 @code{balloon-help-mode} for more information on this.
17818 Here's an alternative recipe for the group buffer:
17821 ;; Create three face types.
17822 (setq gnus-face-1 'bold)
17823 (setq gnus-face-3 'italic)
17825 ;; We want the article count to be in
17826 ;; a bold and green face. So we create
17827 ;; a new face called `my-green-bold'.
17828 (copy-face 'bold 'my-green-bold)
17830 (set-face-foreground 'my-green-bold "ForestGreen")
17831 (setq gnus-face-2 'my-green-bold)
17833 ;; Set the new & fancy format.
17834 (setq gnus-group-line-format
17835 "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
17838 I'm sure you'll be able to use this scheme to create totally unreadable
17839 and extremely vulgar displays. Have fun!
17841 Note that the @samp{%(} specs (and friends) do not make any sense on the
17842 mode-line variables.
17845 @node Windows Configuration
17846 @section Windows Configuration
17847 @cindex windows configuration
17849 No, there's nothing here about X, so be quiet.
17851 @vindex gnus-use-full-window
17852 If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
17853 other windows and occupy the entire Emacs screen by itself. It is
17854 @code{t} by default.
17856 Setting this variable to @code{nil} kinda works, but there are
17857 glitches. Use at your own peril.
17859 @vindex gnus-buffer-configuration
17860 @code{gnus-buffer-configuration} describes how much space each Gnus
17861 buffer should be given. Here's an excerpt of this variable:
17864 ((group (vertical 1.0 (group 1.0 point)
17865 (if gnus-carpal (group-carpal 4))))
17866 (article (vertical 1.0 (summary 0.25 point)
17870 This is an alist. The @dfn{key} is a symbol that names some action or
17871 other. For instance, when displaying the group buffer, the window
17872 configuration function will use @code{group} as the key. A full list of
17873 possible names is listed below.
17875 The @dfn{value} (i.e., the @dfn{split}) says how much space each buffer
17876 should occupy. To take the @code{article} split as an example -
17879 (article (vertical 1.0 (summary 0.25 point)
17883 This @dfn{split} says that the summary buffer should occupy 25% of upper
17884 half of the screen, and that it is placed over the article buffer. As
17885 you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
17886 reaching for that calculator there). However, the special number
17887 @code{1.0} is used to signal that this buffer should soak up all the
17888 rest of the space available after the rest of the buffers have taken
17889 whatever they need. There should be only one buffer with the @code{1.0}
17890 size spec per split.
17892 Point will be put in the buffer that has the optional third element
17893 @code{point}. In a @code{frame} split, the last subsplit having a leaf
17894 split where the tag @code{frame-focus} is a member (i.e. is the third or
17895 fourth element in the list, depending on whether the @code{point} tag is
17896 present) gets focus.
17898 Here's a more complicated example:
17901 (article (vertical 1.0 (group 4)
17902 (summary 0.25 point)
17903 (if gnus-carpal (summary-carpal 4))
17907 If the size spec is an integer instead of a floating point number,
17908 then that number will be used to say how many lines a buffer should
17909 occupy, not a percentage.
17911 If the @dfn{split} looks like something that can be @code{eval}ed (to be
17912 precise---if the @code{car} of the split is a function or a subr), this
17913 split will be @code{eval}ed. If the result is non-@code{nil}, it will
17914 be used as a split. This means that there will be three buffers if
17915 @code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
17918 Not complicated enough for you? Well, try this on for size:
17921 (article (horizontal 1.0
17926 (summary 0.25 point)
17931 Whoops. Two buffers with the mystery 100% tag. And what's that
17932 @code{horizontal} thingie?
17934 If the first element in one of the split is @code{horizontal}, Gnus will
17935 split the window horizontally, giving you two windows side-by-side.
17936 Inside each of these strips you may carry on all you like in the normal
17937 fashion. The number following @code{horizontal} says what percentage of
17938 the screen is to be given to this strip.
17940 For each split, there @emph{must} be one element that has the 100% tag.
17941 The splitting is never accurate, and this buffer will eat any leftover
17942 lines from the splits.
17944 To be slightly more formal, here's a definition of what a valid split
17948 split = frame | horizontal | vertical | buffer | form
17949 frame = "(frame " size *split ")"
17950 horizontal = "(horizontal " size *split ")"
17951 vertical = "(vertical " size *split ")"
17952 buffer = "(" buf-name " " size *[ "point" ] *[ "frame-focus"] ")"
17953 size = number | frame-params
17954 buf-name = group | article | summary ...
17957 The limitations are that the @code{frame} split can only appear as the
17958 top-level split. @var{form} should be an Emacs Lisp form that should
17959 return a valid split. We see that each split is fully recursive, and
17960 may contain any number of @code{vertical} and @code{horizontal} splits.
17962 @vindex gnus-window-min-width
17963 @vindex gnus-window-min-height
17964 @cindex window height
17965 @cindex window width
17966 Finding the right sizes can be a bit complicated. No window may be less
17967 than @code{gnus-window-min-height} (default 1) characters high, and all
17968 windows must be at least @code{gnus-window-min-width} (default 1)
17969 characters wide. Gnus will try to enforce this before applying the
17970 splits. If you want to use the normal Emacs window width/height limit,
17971 you can just set these two variables to @code{nil}.
17973 If you're not familiar with Emacs terminology, @code{horizontal} and
17974 @code{vertical} splits may work the opposite way of what you'd expect.
17975 Windows inside a @code{horizontal} split are shown side-by-side, and
17976 windows within a @code{vertical} split are shown above each other.
17978 @findex gnus-configure-frame
17979 If you want to experiment with window placement, a good tip is to call
17980 @code{gnus-configure-frame} directly with a split. This is the function
17981 that does all the real work when splitting buffers. Below is a pretty
17982 nonsensical configuration with 5 windows; two for the group buffer and
17983 three for the article buffer. (I said it was nonsensical.) If you
17984 @code{eval} the statement below, you can get an idea of how that would
17985 look straight away, without going through the normal Gnus channels.
17986 Play with it until you're satisfied, and then use
17987 @code{gnus-add-configuration} to add your new creation to the buffer
17988 configuration list.
17991 (gnus-configure-frame
17995 (article 0.3 point))
18003 You might want to have several frames as well. No prob---just use the
18004 @code{frame} split:
18007 (gnus-configure-frame
18010 (summary 0.25 point frame-focus)
18012 (vertical ((height . 5) (width . 15)
18013 (user-position . t)
18014 (left . -1) (top . 1))
18019 This split will result in the familiar summary/article window
18020 configuration in the first (or ``main'') frame, while a small additional
18021 frame will be created where picons will be shown. As you can see,
18022 instead of the normal @code{1.0} top-level spec, each additional split
18023 should have a frame parameter alist as the size spec.
18024 @xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp
18025 Reference Manual}. Under XEmacs, a frame property list will be
18026 accepted, too---for instance, @code{(height 5 width 15 left -1 top 1)}
18028 The list of all possible keys for @code{gnus-buffer-configuration} can
18029 be found in its default value.
18031 Note that the @code{message} key is used for both
18032 @code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If
18033 it is desirable to distinguish between the two, something like this
18037 (message (horizontal 1.0
18038 (vertical 1.0 (message 1.0 point))
18040 (if (buffer-live-p gnus-summary-buffer)
18045 One common desire for a multiple frame split is to have a separate frame
18046 for composing mail and news while leaving the original frame intact. To
18047 accomplish that, something like the following can be done:
18052 (if (not (buffer-live-p gnus-summary-buffer))
18053 (car (cdr (assoc 'group gnus-buffer-configuration)))
18054 (car (cdr (assoc 'summary gnus-buffer-configuration))))
18055 (vertical ((user-position . t) (top . 1) (left . 1)
18056 (name . "Message"))
18057 (message 1.0 point))))
18060 @findex gnus-add-configuration
18061 Since the @code{gnus-buffer-configuration} variable is so long and
18062 complicated, there's a function you can use to ease changing the config
18063 of a single setting: @code{gnus-add-configuration}. If, for instance,
18064 you want to change the @code{article} setting, you could say:
18067 (gnus-add-configuration
18068 '(article (vertical 1.0
18070 (summary .25 point)
18074 You'd typically stick these @code{gnus-add-configuration} calls in your
18075 @file{.gnus.el} file or in some startup hook---they should be run after
18076 Gnus has been loaded.
18078 @vindex gnus-always-force-window-configuration
18079 If all windows mentioned in the configuration are already visible, Gnus
18080 won't change the window configuration. If you always want to force the
18081 ``right'' window configuration, you can set
18082 @code{gnus-always-force-window-configuration} to non-@code{nil}.
18084 If you're using tree displays (@pxref{Tree Display}), and the tree
18085 window is displayed vertically next to another window, you may also want
18086 to fiddle with @code{gnus-tree-minimize-window} to avoid having the
18089 @subsection Example Window Configurations
18093 Narrow left hand side occupied by group buffer. Right hand side split
18094 between summary buffer (top one-sixth) and article buffer (bottom).
18109 (gnus-add-configuration
18112 (vertical 25 (group 1.0))
18114 (summary 0.16 point)
18117 (gnus-add-configuration
18120 (vertical 25 (group 1.0))
18121 (vertical 1.0 (summary 1.0 point)))))
18127 @node Faces and Fonts
18128 @section Faces and Fonts
18133 Fiddling with fonts and faces used to be very difficult, but these days
18134 it is very simple. You simply say @kbd{M-x customize-face}, pick out
18135 the face you want to alter, and alter it via the standard Customize
18140 @section Compilation
18141 @cindex compilation
18142 @cindex byte-compilation
18144 @findex gnus-compile
18146 Remember all those line format specification variables?
18147 @code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
18148 on. By default, T-gnus will use the byte-compiled codes of these
18149 variables and we can keep a slow-down to a minimum. However, if you set
18150 @code{gnus-compile-user-specs} to @code{nil} (@code{t} by default),
18151 unfortunately, changing them will mean a quite significant slow-down.
18152 (The default values of these variables have byte-compiled functions
18153 associated with them, while the user-generated versions do not, of
18156 To help with this, you can run @kbd{M-x gnus-compile} after you've
18157 fiddled around with the variables and feel that you're (kind of)
18158 satisfied. This will result in the new specs being byte-compiled, and
18159 you'll get top speed again. Note that T-gnus will not save these
18160 compiled specs in the @file{.newsrc.eld} file.
18163 @item gnus-compile-user-specs
18164 @vindex gnus-compile-user-specs
18165 If it is non-nil, the user-defined format specs will be byte-compiled
18166 automatically. The default value of this variable is @code{t}. It has
18167 an effect on the values of @code{gnus-*-line-format-spec}.
18172 @section Mode Lines
18175 @vindex gnus-updated-mode-lines
18176 @code{gnus-updated-mode-lines} says what buffers should keep their mode
18177 lines updated. It is a list of symbols. Supported symbols include
18178 @code{group}, @code{article}, @code{summary}, @code{server},
18179 @code{browse}, and @code{tree}. If the corresponding symbol is present,
18180 Gnus will keep that mode line updated with information that may be
18181 pertinent. If this variable is @code{nil}, screen refresh may be
18184 @cindex display-time
18186 @vindex gnus-mode-non-string-length
18187 By default, Gnus displays information on the current article in the mode
18188 lines of the summary and article buffers. The information Gnus wishes
18189 to display (e.g. the subject of the article) is often longer than the
18190 mode lines, and therefore have to be cut off at some point. The
18191 @code{gnus-mode-non-string-length} variable says how long the other
18192 elements on the line is (i.e., the non-info part). If you put
18193 additional elements on the mode line (e.g. a clock), you should modify
18196 @c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
18198 (add-hook 'display-time-hook
18199 (lambda () (setq gnus-mode-non-string-length
18201 (if line-number-mode 5 0)
18202 (if column-number-mode 4 0)
18203 (length display-time-string)))))
18206 If this variable is @code{nil} (which is the default), the mode line
18207 strings won't be chopped off, and they won't be padded either. Note
18208 that the default is unlikely to be desirable, as even the percentage
18209 complete in the buffer may be crowded off the mode line; the user should
18210 configure this variable appropriately for her configuration.
18213 @node Highlighting and Menus
18214 @section Highlighting and Menus
18216 @cindex highlighting
18219 @vindex gnus-visual
18220 The @code{gnus-visual} variable controls most of the Gnus-prettifying
18221 aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy
18222 colors or fonts. This will also inhibit loading the @file{gnus-vis.el}
18225 This variable can be a list of visual properties that are enabled. The
18226 following elements are valid, and are all included by default:
18229 @item group-highlight
18230 Do highlights in the group buffer.
18231 @item summary-highlight
18232 Do highlights in the summary buffer.
18233 @item article-highlight
18234 Do highlights in the article buffer.
18236 Turn on highlighting in all buffers.
18238 Create menus in the group buffer.
18240 Create menus in the summary buffers.
18242 Create menus in the article buffer.
18244 Create menus in the browse buffer.
18246 Create menus in the server buffer.
18248 Create menus in the score buffers.
18250 Create menus in all buffers.
18253 So if you only want highlighting in the article buffer and menus in all
18254 buffers, you could say something like:
18257 (setq gnus-visual '(article-highlight menu))
18260 If you want highlighting only and no menus whatsoever, you'd say:
18263 (setq gnus-visual '(highlight))
18266 If @code{gnus-visual} is @code{t}, highlighting and menus will be used
18267 in all Gnus buffers.
18269 Other general variables that influence the look of all buffers include:
18272 @item gnus-mouse-face
18273 @vindex gnus-mouse-face
18274 This is the face (i.e., font) used for mouse highlighting in Gnus. No
18275 mouse highlights will be done if @code{gnus-visual} is @code{nil}.
18279 There are hooks associated with the creation of all the different menus:
18283 @item gnus-article-menu-hook
18284 @vindex gnus-article-menu-hook
18285 Hook called after creating the article mode menu.
18287 @item gnus-group-menu-hook
18288 @vindex gnus-group-menu-hook
18289 Hook called after creating the group mode menu.
18291 @item gnus-summary-menu-hook
18292 @vindex gnus-summary-menu-hook
18293 Hook called after creating the summary mode menu.
18295 @item gnus-server-menu-hook
18296 @vindex gnus-server-menu-hook
18297 Hook called after creating the server mode menu.
18299 @item gnus-browse-menu-hook
18300 @vindex gnus-browse-menu-hook
18301 Hook called after creating the browse mode menu.
18303 @item gnus-score-menu-hook
18304 @vindex gnus-score-menu-hook
18305 Hook called after creating the score mode menu.
18316 Those new-fangled @dfn{mouse} contraptions is very popular with the
18317 young, hep kids who don't want to learn the proper way to do things
18318 these days. Why, I remember way back in the summer of '89, when I was
18319 using Emacs on a Tops 20 system. Three hundred users on one single
18320 machine, and every user was running Simula compilers. Bah!
18324 @vindex gnus-carpal
18325 Well, you can make Gnus display bufferfuls of buttons you can click to
18326 do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
18327 really. Tell the chiropractor I sent you.
18332 @item gnus-carpal-mode-hook
18333 @vindex gnus-carpal-mode-hook
18334 Hook run in all carpal mode buffers.
18336 @item gnus-carpal-button-face
18337 @vindex gnus-carpal-button-face
18338 Face used on buttons.
18340 @item gnus-carpal-header-face
18341 @vindex gnus-carpal-header-face
18342 Face used on carpal buffer headers.
18344 @item gnus-carpal-group-buffer-buttons
18345 @vindex gnus-carpal-group-buffer-buttons
18346 Buttons in the group buffer.
18348 @item gnus-carpal-summary-buffer-buttons
18349 @vindex gnus-carpal-summary-buffer-buttons
18350 Buttons in the summary buffer.
18352 @item gnus-carpal-server-buffer-buttons
18353 @vindex gnus-carpal-server-buffer-buttons
18354 Buttons in the server buffer.
18356 @item gnus-carpal-browse-buffer-buttons
18357 @vindex gnus-carpal-browse-buffer-buttons
18358 Buttons in the browse buffer.
18361 All the @code{buttons} variables are lists. The elements in these list
18362 are either cons cells where the @code{car} contains a text to be displayed and
18363 the @code{cdr} contains a function symbol, or a simple string.
18371 Gnus, being larger than any program ever written (allegedly), does lots
18372 of strange stuff that you may wish to have done while you're not
18373 present. For instance, you may want it to check for new mail once in a
18374 while. Or you may want it to close down all connections to all servers
18375 when you leave Emacs idle. And stuff like that.
18377 Gnus will let you do stuff like that by defining various
18378 @dfn{handlers}. Each handler consists of three elements: A
18379 @var{function}, a @var{time}, and an @var{idle} parameter.
18381 Here's an example of a handler that closes connections when Emacs has
18382 been idle for thirty minutes:
18385 (gnus-demon-close-connections nil 30)
18388 Here's a handler that scans for PGP headers every hour when Emacs is
18392 (gnus-demon-scan-pgp 60 t)
18395 This @var{time} parameter and than @var{idle} parameter work together
18396 in a strange, but wonderful fashion. Basically, if @var{idle} is
18397 @code{nil}, then the function will be called every @var{time} minutes.
18399 If @var{idle} is @code{t}, then the function will be called after
18400 @var{time} minutes only if Emacs is idle. So if Emacs is never idle,
18401 the function will never be called. But once Emacs goes idle, the
18402 function will be called every @var{time} minutes.
18404 If @var{idle} is a number and @var{time} is a number, the function will
18405 be called every @var{time} minutes only when Emacs has been idle for
18406 @var{idle} minutes.
18408 If @var{idle} is a number and @var{time} is @code{nil}, the function
18409 will be called once every time Emacs has been idle for @var{idle}
18412 And if @var{time} is a string, it should look like @samp{07:31}, and
18413 the function will then be called once every day somewhere near that
18414 time. Modified by the @var{idle} parameter, of course.
18416 @vindex gnus-demon-timestep
18417 (When I say ``minute'' here, I really mean @code{gnus-demon-timestep}
18418 seconds. This is 60 by default. If you change that variable,
18419 all the timings in the handlers will be affected.)
18421 So, if you want to add a handler, you could put something like this in
18422 your @file{.gnus} file:
18424 @findex gnus-demon-add-handler
18426 (gnus-demon-add-handler 'gnus-demon-close-connections 30 t)
18429 @findex gnus-demon-add-nocem
18430 @findex gnus-demon-add-scanmail
18431 @findex gnus-demon-add-rescan
18432 @findex gnus-demon-add-scan-timestamps
18433 @findex gnus-demon-add-disconnection
18434 Some ready-made functions to do this have been created:
18435 @code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection},
18436 @code{gnus-demon-add-nntp-close-connection},
18437 @code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and
18438 @code{gnus-demon-add-scanmail}. Just put those functions in your
18439 @file{.gnus} if you want those abilities.
18441 @findex gnus-demon-init
18442 @findex gnus-demon-cancel
18443 @vindex gnus-demon-handlers
18444 If you add handlers to @code{gnus-demon-handlers} directly, you should
18445 run @code{gnus-demon-init} to make the changes take hold. To cancel all
18446 daemons, you can use the @code{gnus-demon-cancel} function.
18448 Note that adding daemons can be pretty naughty if you over do it. Adding
18449 functions that scan all news and mail from all servers every two seconds
18450 is a sure-fire way of getting booted off any respectable system. So
18459 @dfn{Spamming} is posting the same article lots and lots of times.
18460 Spamming is bad. Spamming is evil.
18462 Spamming is usually canceled within a day or so by various anti-spamming
18463 agencies. These agencies usually also send out @dfn{NoCeM} messages.
18464 NoCeM is pronounced ``no see-'em'', and means what the name
18465 implies---these are messages that make the offending articles, like, go
18468 What use are these NoCeM messages if the articles are canceled anyway?
18469 Some sites do not honor cancel messages and some sites just honor cancels
18470 from a select few people. Then you may wish to make use of the NoCeM
18471 messages, which are distributed in the @samp{alt.nocem.misc} newsgroup.
18473 Gnus can read and parse the messages in this group automatically, and
18474 this will make spam disappear.
18476 There are some variables to customize, of course:
18479 @item gnus-use-nocem
18480 @vindex gnus-use-nocem
18481 Set this variable to @code{t} to set the ball rolling. It is @code{nil}
18484 @item gnus-nocem-groups
18485 @vindex gnus-nocem-groups
18486 Gnus will look for NoCeM messages in the groups in this list. The
18487 default is @code{("news.lists.filters" "news.admin.net-abuse.bulletins"
18488 "alt.nocem.misc" "news.admin.net-abuse.announce")}.
18490 @item gnus-nocem-issuers
18491 @vindex gnus-nocem-issuers
18492 There are many people issuing NoCeM messages. This list says what
18493 people you want to listen to. The default is @code{("Automoose-1"
18494 "clewis@@ferret.ocunix.on.ca" "cosmo.roadkill" "SpamHippo"
18495 "hweede@@snafu.de")}; fine, upstanding citizens all of them.
18497 Known despammers that you can put in this list are listed at
18498 @uref{http://www.xs4all.nl/~rosalind/nocemreg/nocemreg.html}.
18500 You do not have to heed NoCeM messages from all these people---just the
18501 ones you want to listen to. You also don't have to accept all NoCeM
18502 messages from the people you like. Each NoCeM message has a @dfn{type}
18503 header that gives the message a (more or less, usually less) rigorous
18504 definition. Common types are @samp{spam}, @samp{spew}, @samp{mmf},
18505 @samp{binary}, and @samp{troll}. To specify this, you have to use
18506 @code{(@var{issuer} @var{conditions} @dots{})} elements in the list.
18507 Each condition is either a string (which is a regexp that matches types
18508 you want to use) or a list on the form @code{(not @var{string})}, where
18509 @var{string} is a regexp that matches types you don't want to use.
18511 For instance, if you want all NoCeM messages from Chris Lewis except his
18512 @samp{troll} messages, you'd say:
18515 ("clewis@@ferret.ocunix.on.ca" ".*" (not "troll"))
18518 On the other hand, if you just want nothing but his @samp{spam} and
18519 @samp{spew} messages, you'd say:
18522 ("clewis@@ferret.ocunix.on.ca" (not ".*") "spew" "spam")
18525 The specs are applied left-to-right.
18528 @item gnus-nocem-verifyer
18529 @vindex gnus-nocem-verifyer
18531 This should be a function for verifying that the NoCeM issuer is who she
18532 says she is. The default is @code{mc-verify}, which is a Mailcrypt
18533 function. If this is too slow and you don't care for verification
18534 (which may be dangerous), you can set this variable to @code{nil}.
18536 If you want signed NoCeM messages to be verified and unsigned messages
18537 not to be verified (but used anyway), you could do something like:
18540 (setq gnus-nocem-verifyer 'my-gnus-mc-verify)
18542 (defun my-gnus-mc-verify ()
18550 This might be dangerous, though.
18552 @item gnus-nocem-directory
18553 @vindex gnus-nocem-directory
18554 This is where Gnus will store its NoCeM cache files. The default is
18555 @file{~/News/NoCeM/}.
18557 @item gnus-nocem-expiry-wait
18558 @vindex gnus-nocem-expiry-wait
18559 The number of days before removing old NoCeM entries from the cache.
18560 The default is 15. If you make it shorter Gnus will be faster, but you
18561 might then see old spam.
18563 @item gnus-nocem-check-from
18564 @vindex gnus-nocem-check-from
18565 Non-@code{nil} means check for valid issuers in message bodies.
18566 Otherwise don't bother fetching articles unless their author matches a
18567 valid issuer; that is much faster if you are selective about the
18570 @item gnus-nocem-check-article-limit
18571 @vindex gnus-nocem-check-article-limit
18572 If non-@code{nil}, the maximum number of articles to check in any NoCeM
18573 group. NoCeM groups can be huge and very slow to process.
18577 Using NoCeM could potentially be a memory hog. If you have many living
18578 (i. e., subscribed or unsubscribed groups), your Emacs process will grow
18579 big. If this is a problem, you should kill off all (or most) of your
18580 unsubscribed groups (@pxref{Subscription Commands}).
18587 It is very useful to be able to undo actions one has done. In normal
18588 Emacs buffers, it's easy enough---you just push the @code{undo} button.
18589 In Gnus buffers, however, it isn't that simple.
18591 The things Gnus displays in its buffer is of no value whatsoever to
18592 Gnus---it's all just data designed to look nice to the user.
18593 Killing a group in the group buffer with @kbd{C-k} makes the line
18594 disappear, but that's just a side-effect of the real action---the
18595 removal of the group in question from the internal Gnus structures.
18596 Undoing something like that can't be done by the normal Emacs
18597 @code{undo} function.
18599 Gnus tries to remedy this somewhat by keeping track of what the user
18600 does and coming up with actions that would reverse the actions the user
18601 takes. When the user then presses the @code{undo} key, Gnus will run
18602 the code to reverse the previous action, or the previous actions.
18603 However, not all actions are easily reversible, so Gnus currently offers
18604 a few key functions to be undoable. These include killing groups,
18605 yanking groups, and changing the list of read articles of groups.
18606 That's it, really. More functions may be added in the future, but each
18607 added function means an increase in data to be stored, so Gnus will
18608 never be totally undoable.
18610 @findex gnus-undo-mode
18611 @vindex gnus-use-undo
18613 The undoability is provided by the @code{gnus-undo-mode} minor mode. It
18614 is used if @code{gnus-use-undo} is non-@code{nil}, which is the
18615 default. The @kbd{M-C-_} key performs the @code{gnus-undo}
18616 command, which should feel kinda like the normal Emacs @code{undo}
18621 @section Moderation
18624 If you are a moderator, you can use the @file{gnus-mdrtn.el} package.
18625 It is not included in the standard Gnus package. Write a mail to
18626 @samp{larsi@@gnus.org} and state what group you moderate, and you'll
18629 The moderation package is implemented as a minor mode for summary
18633 (add-hook 'gnus-summary-mode-hook 'gnus-moderate)
18636 in your @file{.gnus.el} file.
18638 If you are the moderator of @samp{rec.zoofle}, this is how it's
18643 You split your incoming mail by matching on
18644 @samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted
18645 articles in some mail group---for instance, @samp{nnml:rec.zoofle}.
18648 You enter that group once in a while and post articles using the @kbd{e}
18649 (edit-and-post) or @kbd{s} (just send unedited) commands.
18652 If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some
18653 articles that weren't approved by you, you can cancel them with the
18657 To use moderation mode in these two groups, say:
18660 (setq gnus-moderated-list
18661 "^nnml:rec.zoofle$\\|^rec.zoofle$")
18665 @node XEmacs Enhancements
18666 @section XEmacs Enhancements
18669 XEmacs is able to display pictures and stuff, so Gnus has taken
18673 * Picons:: How to display pictures of what your reading.
18674 * Smileys:: Show all those happy faces the way they were meant to be shown.
18675 * Toolbar:: Click'n'drool.
18676 * XVarious:: Other XEmacsy Gnusey variables.
18689 So@dots{} You want to slow down your news reader even more! This is a
18690 good way to do so. Its also a great way to impress people staring
18691 over your shoulder as you read news.
18694 * Picon Basics:: What are picons and How do I get them.
18695 * Picon Requirements:: Don't go further if you aren't using XEmacs.
18696 * Easy Picons:: Displaying Picons---the easy way.
18697 * Hard Picons:: The way you should do it. You'll learn something.
18698 * Picon Useless Configuration:: Other variables you can trash/tweak/munge/play with.
18703 @subsubsection Picon Basics
18705 What are Picons? To quote directly from the Picons Web site:
18714 @dfn{Picons} is short for ``personal icons''. They're small,
18715 constrained images used to represent users and domains on the net,
18716 organized into databases so that the appropriate image for a given
18717 e-mail address can be found. Besides users and domains, there are picon
18718 databases for Usenet newsgroups and weather forecasts. The picons are
18719 in either monochrome @code{XBM} format or color @code{XPM} and
18720 @code{GIF} formats.
18723 @vindex gnus-picons-piconsearch-url
18724 If you have a permanent connection to the Internet you can use Steve
18725 Kinzler's Picons Search engine by setting
18726 @code{gnus-picons-piconsearch-url} to the string @*
18727 @uref{http://www.cs.indiana.edu/picons/search.html}.
18729 @vindex gnus-picons-database
18730 Otherwise you need a local copy of his database. For instructions on
18731 obtaining and installing the picons databases, point your Web browser at @*
18732 @uref{http://www.cs.indiana.edu/picons/ftp/index.html}. Gnus expects
18733 picons to be installed into a location pointed to by
18734 @code{gnus-picons-database}.
18737 @node Picon Requirements
18738 @subsubsection Picon Requirements
18740 To have Gnus display Picons for you, you must be running XEmacs
18741 19.13 or greater since all other versions of Emacs aren't yet able to
18744 Additionally, you must have @code{x} support compiled into XEmacs. To
18745 display color picons which are much nicer than the black & white one,
18746 you also need one of @code{xpm} or @code{gif} compiled into XEmacs.
18748 @vindex gnus-picons-convert-x-face
18749 If you want to display faces from @code{X-Face} headers, you should have
18750 the @code{xface} support compiled into XEmacs. Otherwise you must have
18751 the @code{netpbm} utilities installed, or munge the
18752 @code{gnus-picons-convert-x-face} variable to use something else.
18756 @subsubsection Easy Picons
18758 To enable displaying picons, simply put the following line in your
18759 @file{~/.gnus} file and start Gnus.
18762 (setq gnus-use-picons t)
18763 (setq gnus-treat-display-picons t)
18766 and make sure @code{gnus-picons-database} points to the directory
18767 containing the Picons databases.
18769 Alternatively if you want to use the web piconsearch engine add this:
18772 (setq gnus-picons-piconsearch-url
18773 "http://www.cs.indiana.edu:800/piconsearch")
18778 @subsubsection Hard Picons
18786 Gnus can display picons for you as you enter and leave groups and
18787 articles. It knows how to interact with three sections of the picons
18788 database. Namely, it can display the picons newsgroup pictures,
18789 author's face picture(s), and the authors domain. To enable this
18790 feature, you need to select where to get the picons from, and where to
18795 @item gnus-picons-database
18796 @vindex gnus-picons-database
18797 The location of the picons database. Should point to a directory
18798 containing the @file{news}, @file{domains}, @file{users} (and so on)
18799 subdirectories. This is only useful if
18800 @code{gnus-picons-piconsearch-url} is @code{nil}. Defaults to
18801 @file{/usr/local/faces/}.
18803 @item gnus-picons-piconsearch-url
18804 @vindex gnus-picons-piconsearch-url
18805 The URL for the web picons search engine. The only currently known
18806 engine is @uref{http://www.cs.indiana.edu:800/piconsearch}. To
18807 workaround network delays, icons will be fetched in the background. If
18808 this is @code{nil} 'the default), then picons are fetched from local
18809 database indicated by @code{gnus-picons-database}.
18811 @item gnus-picons-display-where
18812 @vindex gnus-picons-display-where
18813 Where the picon images should be displayed. It is @code{picons} by
18814 default (which by default maps to the buffer @samp{*Picons*}). Other
18815 valid places could be @code{article}, @code{summary}, or
18816 @samp{*scratch*} for all I care. Just make sure that you've made the
18817 buffer visible using the standard Gnus window configuration
18818 routines---@pxref{Windows Configuration}.
18820 @item gnus-picons-group-excluded-groups
18821 @vindex gnus-picons-group-excluded-groups
18822 Groups that are matched by this regexp won't have their group icons
18827 Note: If you set @code{gnus-use-picons} to @code{t}, it will set up your
18828 window configuration for you to include the @code{picons} buffer.
18830 Now that you've made those decision, you need to add the following
18831 functions to the appropriate hooks so these pictures will get displayed
18834 @vindex gnus-picons-display-where
18836 @item gnus-article-display-picons
18837 @findex gnus-article-display-picons
18838 Looks up and displays the picons for the author and the author's domain
18839 in the @code{gnus-picons-display-where} buffer.
18841 @item gnus-picons-article-display-x-face
18842 @findex gnus-article-display-picons
18843 Decodes and displays the X-Face header if present.
18849 @node Picon Useless Configuration
18850 @subsubsection Picon Useless Configuration
18858 The following variables offer further control over how things are
18859 done, where things are located, and other useless stuff you really
18860 don't need to worry about.
18864 @item gnus-picons-news-directories
18865 @vindex gnus-picons-news-directories
18866 List of subdirectories to search in @code{gnus-picons-database} for
18867 newsgroups faces. @code{("news")} is the default.
18869 @item gnus-picons-user-directories
18870 @vindex gnus-picons-user-directories
18871 List of subdirectories to search in @code{gnus-picons-database} for user
18872 faces. @code{("local" "users" "usenix" "misc")} is the default.
18874 @item gnus-picons-domain-directories
18875 @vindex gnus-picons-domain-directories
18876 List of subdirectories to search in @code{gnus-picons-database} for
18877 domain name faces. Defaults to @code{("domains")}. Some people may
18878 want to add @samp{"unknown"} to this list.
18880 @item gnus-picons-convert-x-face
18881 @vindex gnus-picons-convert-x-face
18882 If you don't have @code{xface} support builtin XEmacs, this is the
18883 command to use to convert the @code{X-Face} header to an X bitmap
18884 (@code{xbm}). Defaults to @code{(format "@{ echo '/* Width=48,
18885 Height=48 */'; uncompface; @} | icontopbm | pbmtoxbm > %s"
18886 gnus-picons-x-face-file-name)}
18888 @item gnus-picons-x-face-file-name
18889 @vindex gnus-picons-x-face-file-name
18890 Names a temporary file to store the @code{X-Face} bitmap in. Defaults
18891 to @code{(format "/tmp/picon-xface.%s.xbm" (user-login-name))}.
18893 @item gnus-picons-has-modeline-p
18894 @vindex gnus-picons-has-modeline-p
18895 If you have set @code{gnus-picons-display-where} to @code{picons}, your
18896 XEmacs frame will become really cluttered. To alleviate this a bit you
18897 can set @code{gnus-picons-has-modeline-p} to @code{nil}; this will
18898 remove the mode line from the Picons buffer. This is only useful if
18899 @code{gnus-picons-display-where} is @code{picons}.
18901 @item gnus-picons-refresh-before-display
18902 @vindex gnus-picons-refresh-before-display
18903 If non-nil, display the article buffer before computing the picons.
18904 Defaults to @code{nil}.
18906 @item gnus-picons-display-as-address
18907 @vindex gnus-picons-display-as-address
18908 If @code{t} display textual email addresses along with pictures.
18909 Defaults to @code{t}.
18911 @item gnus-picons-file-suffixes
18912 @vindex gnus-picons-file-suffixes
18913 Ordered list of suffixes on picon file names to try. Defaults to
18914 @code{("xpm" "gif" "xbm")} minus those not builtin your XEmacs.
18916 @item gnus-picons-setup-hook
18917 @vindex gnus-picons-setup-hook
18918 Hook run in the picon buffer, if that is displayed.
18920 @item gnus-picons-display-article-move-p
18921 @vindex gnus-picons-display-article-move-p
18922 Whether to move point to first empty line when displaying picons. This
18923 has only an effect if `gnus-picons-display-where' has value `article'.
18925 If @code{nil}, display the picons in the @code{From} and
18926 @code{Newsgroups} lines. This is the default.
18928 @item gnus-picons-clear-cache-on-shutdown
18929 @vindex gnus-picons-clear-cache-on-shutdown
18930 Whether to clear the picons cache when exiting gnus. Gnus caches every
18931 picons it finds while it is running. This saves some time in the search
18932 process but eats some memory. If this variable is set to @code{nil},
18933 Gnus will never clear the cache itself; you will have to manually call
18934 @code{gnus-picons-clear-cache} to clear it. Otherwise the cache will be
18935 cleared every time you exit Gnus. Defaults to @code{t}.
18946 @subsection Smileys
18951 \gnusfig{-3cm}{0.5cm}{\epsfig{figure=tmp/BigFace.ps,height=20cm}}
18956 @dfn{Smiley} is a package separate from Gnus, but since Gnus is
18957 currently the only package that uses Smiley, it is documented here.
18959 In short---to use Smiley in Gnus, put the following in your
18960 @file{.gnus.el} file:
18963 (setq gnus-treat-display-smileys t)
18966 Smiley maps text smiley faces---@samp{:-)}, @samp{:-=}, @samp{:-(} and
18967 the like---to pictures and displays those instead of the text smiley
18968 faces. The conversion is controlled by a list of regexps that matches
18969 text and maps that to file names.
18971 @vindex smiley-nosey-regexp-alist
18972 @vindex smiley-deformed-regexp-alist
18973 Smiley supplies two example conversion alists by default:
18974 @code{smiley-deformed-regexp-alist} (which matches @samp{:)}, @samp{:(}
18975 and so on), and @code{smiley-nosey-regexp-alist} (which matches
18976 @samp{:-)}, @samp{:-(} and so on).
18978 The alist used is specified by the @code{smiley-regexp-alist} variable,
18979 which defaults to the value of @code{smiley-deformed-regexp-alist}.
18981 The first item in each element is the regexp to be matched; the second
18982 element is the regexp match group that is to be replaced by the picture;
18983 and the third element is the name of the file to be displayed.
18985 The following variables customize where Smiley will look for these
18986 files, as well as the color to be used and stuff:
18990 @item smiley-data-directory
18991 @vindex smiley-data-directory
18992 Where Smiley will look for smiley faces files.
18994 @item smiley-flesh-color
18995 @vindex smiley-flesh-color
18996 Skin color. The default is @samp{yellow}, which is really racist.
18998 @item smiley-features-color
18999 @vindex smiley-features-color
19000 Color of the features of the face. The default is @samp{black}.
19002 @item smiley-tongue-color
19003 @vindex smiley-tongue-color
19004 Color of the tongue. The default is @samp{red}.
19006 @item smiley-circle-color
19007 @vindex smiley-circle-color
19008 Color of the circle around the face. The default is @samp{black}.
19010 @item smiley-mouse-face
19011 @vindex smiley-mouse-face
19012 Face used for mouse highlighting over the smiley face.
19018 @subsection Toolbar
19028 @item gnus-use-toolbar
19029 @vindex gnus-use-toolbar
19030 If @code{nil}, don't display toolbars. If non-@code{nil}, it should be
19031 one of @code{default-toolbar}, @code{top-toolbar}, @code{bottom-toolbar},
19032 @code{right-toolbar}, or @code{left-toolbar}.
19034 @item gnus-group-toolbar
19035 @vindex gnus-group-toolbar
19036 The toolbar in the group buffer.
19038 @item gnus-summary-toolbar
19039 @vindex gnus-summary-toolbar
19040 The toolbar in the summary buffer.
19042 @item gnus-summary-mail-toolbar
19043 @vindex gnus-summary-mail-toolbar
19044 The toolbar in the summary buffer of mail groups.
19050 @subsection Various XEmacs Variables
19053 @item gnus-xmas-glyph-directory
19054 @vindex gnus-xmas-glyph-directory
19055 This is where Gnus will look for pictures. Gnus will normally
19056 auto-detect this directory, but you may set it manually if you have an
19057 unusual directory structure.
19059 @item gnus-xmas-logo-color-alist
19060 @vindex gnus-xmas-logo-color-alist
19061 This is an alist where the key is a type symbol and the values are the
19062 foreground and background color of the splash page glyph.
19064 @item gnus-xmas-logo-color-style
19065 @vindex gnus-xmas-logo-color-style
19066 This is the key used to look up the color in the alist described above.
19067 Valid values include @code{flame}, @code{pine}, @code{moss},
19068 @code{irish}, @code{sky}, @code{tin}, @code{velvet}, @code{grape},
19069 @code{labia}, @code{berry}, @code{neutral}, and @code{september}.
19071 @item gnus-xmas-modeline-glyph
19072 @vindex gnus-xmas-modeline-glyph
19073 A glyph displayed in all Gnus mode lines. It is a tiny gnu head by
19087 @node Fuzzy Matching
19088 @section Fuzzy Matching
19089 @cindex fuzzy matching
19091 Gnus provides @dfn{fuzzy matching} of @code{Subject} lines when doing
19092 things like scoring, thread gathering and thread comparison.
19094 As opposed to regular expression matching, fuzzy matching is very fuzzy.
19095 It's so fuzzy that there's not even a definition of what @dfn{fuzziness}
19096 means, and the implementation has changed over time.
19098 Basically, it tries to remove all noise from lines before comparing.
19099 @samp{Re: }, parenthetical remarks, white space, and so on, are filtered
19100 out of the strings before comparing the results. This often leads to
19101 adequate results---even when faced with strings generated by text
19102 manglers masquerading as newsreaders.
19105 @node Thwarting Email Spam
19106 @section Thwarting Email Spam
19110 @cindex unsolicited commercial email
19112 In these last days of the Usenet, commercial vultures are hanging about
19113 and grepping through news like crazy to find email addresses they can
19114 foist off their scams and products to. As a reaction to this, many
19115 people have started putting nonsense addresses into their @code{From}
19116 lines. I think this is counterproductive---it makes it difficult for
19117 people to send you legitimate mail in response to things you write, as
19118 well as making it difficult to see who wrote what. This rewriting may
19119 perhaps be a bigger menace than the unsolicited commercial email itself
19122 The biggest problem I have with email spam is that it comes in under
19123 false pretenses. I press @kbd{g} and Gnus merrily informs me that I
19124 have 10 new emails. I say ``Golly gee! Happy is me!'' and select the
19125 mail group, only to find two pyramid schemes, seven advertisements
19126 (``New! Miracle tonic for growing full, lustrous hair on your toes!'')
19127 and one mail asking me to repent and find some god.
19131 The way to deal with this is having Gnus split out all spam into a
19132 @samp{spam} mail group (@pxref{Splitting Mail}).
19134 First, pick one (1) valid mail address that you can be reached at, and
19135 put it in your @code{From} header of all your news articles. (I've
19136 chosen @samp{larsi@@trym.ifi.uio.no}, but for many addresses on the form
19137 @samp{larsi+usenet@@ifi.uio.no} will be a better choice. Ask your
19138 sysadmin whether your sendmail installation accepts keywords in the local
19139 part of the mail address.)
19142 (setq message-default-news-headers
19143 "From: Lars Magne Ingebrigtsen <larsi@@trym.ifi.uio.no>\n")
19146 Then put the following split rule in @code{nnmail-split-fancy}
19147 (@pxref{Fancy Mail Splitting}):
19152 (to "larsi@@trym.ifi.uio.no"
19153 (| ("subject" "re:.*" "misc")
19154 ("references" ".*@@.*" "misc")
19160 This says that all mail to this address is suspect, but if it has a
19161 @code{Subject} that starts with a @samp{Re:} or has a @code{References}
19162 header, it's probably ok. All the rest goes to the @samp{spam} group.
19163 (This idea probably comes from Tim Pierce.)
19165 In addition, many mail spammers talk directly to your @code{smtp} server
19166 and do not include your email address explicitly in the @code{To}
19167 header. Why they do this is unknown---perhaps it's to thwart this
19168 thwarting scheme? In any case, this is trivial to deal with---you just
19169 put anything not addressed to you in the @samp{spam} group by ending
19170 your fancy split rule in this way:
19175 (to "larsi" "misc")
19179 In my experience, this will sort virtually everything into the right
19180 group. You still have to check the @samp{spam} group from time to time to
19181 check for legitimate mail, though. If you feel like being a good net
19182 citizen, you can even send off complaints to the proper authorities on
19183 each unsolicited commercial email---at your leisure.
19185 If you are also a lazy net citizen, you will probably prefer complaining
19186 automatically with the @file{gnus-junk.el} package, available FOR FREE
19187 at @* @uref{http://stud2.tuwien.ac.at/~e9426626/gnus-junk.html}.
19188 Since most e-mail spam is sent automatically, this may reconcile the
19189 cosmic balance somewhat.
19191 This works for me. It allows people an easy way to contact me (they can
19192 just press @kbd{r} in the usual way), and I'm not bothered at all with
19193 spam. It's a win-win situation. Forging @code{From} headers to point
19194 to non-existent domains is yucky, in my opinion.
19197 @node Various Various
19198 @section Various Various
19204 @item gnus-home-directory
19205 All Gnus path variables will be initialized from this variable, which
19206 defaults to @file{~/}.
19208 @item gnus-directory
19209 @vindex gnus-directory
19210 Most Gnus storage path variables will be initialized from this variable,
19211 which defaults to the @samp{SAVEDIR} environment variable, or
19212 @file{~/News/} if that variable isn't set.
19214 Note that gnus is mostly loaded when the @file{.gnus.el} file is read.
19215 This means that other directory variables that are initialized from this
19216 variable won't be set properly if you set this variable in
19217 @file{.gnus.el}. Set this variable in @file{.emacs} instead.
19219 @item gnus-default-directory
19220 @vindex gnus-default-directory
19221 Not related to the above variable at all---this variable says what the
19222 default directory of all Gnus buffers should be. If you issue commands
19223 like @kbd{C-x C-f}, the prompt you'll get starts in the current buffer's
19224 default directory. If this variable is @code{nil} (which is the
19225 default), the default directory will be the default directory of the
19226 buffer you were in when you started Gnus.
19229 @vindex gnus-verbose
19230 This variable is an integer between zero and ten. The higher the value,
19231 the more messages will be displayed. If this variable is zero, Gnus
19232 will never flash any messages, if it is seven (which is the default),
19233 most important messages will be shown, and if it is ten, Gnus won't ever
19234 shut up, but will flash so many messages it will make your head swim.
19236 @item gnus-verbose-backends
19237 @vindex gnus-verbose-backends
19238 This variable works the same way as @code{gnus-verbose}, but it applies
19239 to the Gnus backends instead of Gnus proper.
19241 @item nnheader-max-head-length
19242 @vindex nnheader-max-head-length
19243 When the backends read straight heads of articles, they all try to read
19244 as little as possible. This variable (default 4096) specifies
19245 the absolute max length the backends will try to read before giving up
19246 on finding a separator line between the head and the body. If this
19247 variable is @code{nil}, there is no upper read bound. If it is
19248 @code{t}, the backends won't try to read the articles piece by piece,
19249 but read the entire articles. This makes sense with some versions of
19250 @code{ange-ftp} or @code{efs}.
19252 @item nnheader-head-chop-length
19253 @vindex nnheader-head-chop-length
19254 This variable (default 2048) says how big a piece of each article to
19255 read when doing the operation described above.
19257 @item nnheader-file-name-translation-alist
19258 @vindex nnheader-file-name-translation-alist
19260 @cindex invalid characters in file names
19261 @cindex characters in file names
19262 This is an alist that says how to translate characters in file names.
19263 For instance, if @samp{:} is invalid as a file character in file names
19264 on your system (you OS/2 user you), you could say something like:
19267 (setq nnheader-file-name-translation-alist
19271 In fact, this is the default value for this variable on OS/2 and MS
19272 Windows (phooey) systems.
19274 @item gnus-hidden-properties
19275 @vindex gnus-hidden-properties
19276 This is a list of properties to use to hide ``invisible'' text. It is
19277 @code{(invisible t intangible t)} by default on most systems, which
19278 makes invisible text invisible and intangible.
19280 @item gnus-parse-headers-hook
19281 @vindex gnus-parse-headers-hook
19282 A hook called before parsing headers. It can be used, for instance, to
19283 gather statistics on the headers fetched, or perhaps you'd like to prune
19284 some headers. I don't see why you'd want that, though.
19286 @item gnus-shell-command-separator
19287 @vindex gnus-shell-command-separator
19288 String used to separate two shell commands. The default is @samp{;}.
19290 @item gnus-invalid-group-regexp
19291 @vindex gnus-invalid-group-regexp
19293 Regexp to match ``invalid'' group names when querying user for a group
19294 name. The default value catches some @strong{really} invalid group
19295 names who could possibly mess up Gnus internally (like allowing
19296 @samp{:} in a group name, which is normally used to delimit method and
19299 @sc{imap} users might want to allow @samp{/} in group names though.
19308 Well, that's the manual---you can get on with your life now. Keep in
19309 touch. Say hello to your cats from me.
19311 My @strong{ghod}---I just can't stand goodbyes. Sniffle.
19313 Ol' Charles Reznikoff said it pretty well, so I leave the floor to him:
19319 Not because of victories @*
19322 but for the common sunshine,@*
19324 the largess of the spring.
19328 but for the day's work done@*
19329 as well as I was able;@*
19330 not for a seat upon the dais@*
19331 but at the common table.@*
19336 @chapter Appendices
19339 * History:: How Gnus got where it is today.
19340 * On Writing Manuals:: Why this is not a beginner's guide.
19341 * Terminology:: We use really difficult, like, words here.
19342 * Customization:: Tailoring Gnus to your needs.
19343 * Troubleshooting:: What you might try if things do not work.
19344 * Gnus Reference Guide:: Rilly, rilly technical stuff.
19345 * Emacs for Heathens:: A short introduction to Emacsian terms.
19346 * Frequently Asked Questions:: A question-and-answer session.
19354 @sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in
19355 '94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
19357 If you want to investigate the person responsible for this outrage,
19358 you can point your (feh!) web browser to
19359 @uref{http://quimby.gnus.org/}. This is also the primary
19360 distribution point for the new and spiffy versions of Gnus, and is
19361 known as The Site That Destroys Newsrcs And Drives People Mad.
19363 During the first extended alpha period of development, the new Gnus was
19364 called ``(ding) Gnus''. @dfn{(ding)} is, of course, short for
19365 @dfn{ding is not Gnus}, which is a total and utter lie, but who cares?
19366 (Besides, the ``Gnus'' in this abbreviation should probably be
19367 pronounced ``news'' as @sc{Umeda} intended, which makes it a more
19368 appropriate name, don't you think?)
19370 In any case, after spending all that energy on coming up with a new and
19371 spunky name, we decided that the name was @emph{too} spunky, so we
19372 renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs.
19373 ``@sc{gnus}''. New vs. old.
19376 * Gnus Versions:: What Gnus versions have been released.
19377 * Other Gnus Versions:: Other Gnus versions that also have been released.
19378 * Why?:: What's the point of Gnus?
19379 * Compatibility:: Just how compatible is Gnus with @sc{gnus}?
19380 * Conformity:: Gnus tries to conform to all standards.
19381 * Emacsen:: Gnus can be run on a few modern Emacsen.
19382 * Gnus Development:: How Gnus is developed.
19383 * Contributors:: Oodles of people.
19384 * New Features:: Pointers to some of the new stuff in Gnus.
19388 @node Gnus Versions
19389 @subsection Gnus Versions
19390 @cindex Pterodactyl Gnus
19392 @cindex September Gnus
19393 @cindex Quassia Gnus
19395 The first ``proper'' release of Gnus 5 was done in November 1995 when it
19396 was included in the Emacs 19.30 distribution (132 (ding) Gnus releases
19397 plus 15 Gnus 5.0 releases).
19399 In May 1996 the next Gnus generation (aka. ``September Gnus'' (after 99
19400 releases)) was released under the name ``Gnus 5.2'' (40 releases).
19402 On July 28th 1996 work on Red Gnus was begun, and it was released on
19403 January 25th 1997 (after 84 releases) as ``Gnus 5.4'' (67 releases).
19405 On September 13th 1997, Quassia Gnus was started and lasted 37 releases.
19406 If was released as ``Gnus 5.6'' on March 8th 1998 (46 releases).
19408 Gnus 5.6 begat Pterodactyl Gnus on August 29th 1998 and was released as
19409 ``Gnus 5.8'' (after 99 releases and a CVS repository) on December 3rd
19412 On the 26th of October 2000, Oort Gnus was begun.
19414 If you happen upon a version of Gnus that has a prefixed name --
19415 ``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'',
19416 ``Pterodactyl Gnus'', ``Oort Gnus'' -- don't panic. Don't let it know
19417 that you're frightened. Back away. Slowly. Whatever you do, don't
19418 run. Walk away, calmly, until you're out of its reach. Find a proper
19419 released version of Gnus and snuggle up to that instead.
19422 @node Other Gnus Versions
19423 @subsection Other Gnus Versions
19426 In addition to the versions of Gnus which have had their releases
19427 coordinated by Lars, one major development has been Semi-gnus from
19428 Japan. It's based on a library called @sc{semi}, which provides
19429 @sc{mime} capabilities.
19431 These Gnusae are based mainly on Gnus 5.6 and Pterodactyl Gnus.
19432 Collectively, they are called ``Semi-gnus'', and different strains are
19433 called T-gnus, ET-gnus, Nana-gnus and Chaos. These provide powerful
19434 @sc{mime} and multilingualization things, especially important for
19441 What's the point of Gnus?
19443 I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep''
19444 newsreader, that lets you do anything you can think of. That was my
19445 original motivation, but while working on Gnus, it has become clear to
19446 me that this generation of newsreaders really belong in the stone age.
19447 Newsreaders haven't developed much since the infancy of the net. If the
19448 volume continues to rise with the current rate of increase, all current
19449 newsreaders will be pretty much useless. How do you deal with
19450 newsgroups that have thousands of new articles each day? How do you
19451 keep track of millions of people who post?
19453 Gnus offers no real solutions to these questions, but I would very much
19454 like to see Gnus being used as a testing ground for new methods of
19455 reading and fetching news. Expanding on @sc{Umeda}-san's wise decision
19456 to separate the newsreader from the backends, Gnus now offers a simple
19457 interface for anybody who wants to write new backends for fetching mail
19458 and news from different sources. I have added hooks for customizations
19459 everywhere I could imagine it being useful. By doing so, I'm inviting
19460 every one of you to explore and invent.
19462 May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs} and
19463 @kbd{C-u 100 M-x all-hail-xemacs}.
19466 @node Compatibility
19467 @subsection Compatibility
19469 @cindex compatibility
19470 Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
19471 bindings have been kept. More key bindings have been added, of course,
19472 but only in one or two obscure cases have old bindings been changed.
19477 @center In a cloud bones of steel.
19481 All commands have kept their names. Some internal functions have changed
19484 The @code{gnus-uu} package has changed drastically. @xref{Decoding
19487 One major compatibility question is the presence of several summary
19488 buffers. All variables relevant while reading a group are
19489 buffer-local to the summary buffer they belong in. Although many
19490 important variables have their values copied into their global
19491 counterparts whenever a command is executed in the summary buffer, this
19492 change might lead to incorrect values being used unless you are careful.
19494 All code that relies on knowledge of @sc{gnus} internals will probably
19495 fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or
19496 changing it in any way, as a matter of fact) is strictly verboten. Gnus
19497 maintains a hash table that points to the entries in this alist (which
19498 speeds up many functions), and changing the alist directly will lead to
19502 @cindex highlighting
19503 Old hilit19 code does not work at all. In fact, you should probably
19504 remove all hilit code from all Gnus hooks
19505 (@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}).
19506 Gnus provides various integrated functions for highlighting. These are
19507 faster and more accurate. To make life easier for everybody, Gnus will
19508 by default remove all hilit calls from all hilit hooks. Uncleanliness!
19511 Packages like @code{expire-kill} will no longer work. As a matter of
19512 fact, you should probably remove all old @sc{gnus} packages (and other
19513 code) when you start using Gnus. More likely than not, Gnus already
19514 does what you have written code to make @sc{gnus} do. (Snicker.)
19516 Even though old methods of doing things are still supported, only the
19517 new methods are documented in this manual. If you detect a new method of
19518 doing something while reading this manual, that does not mean you have
19519 to stop doing it the old way.
19521 Gnus understands all @sc{gnus} startup files.
19523 @kindex M-x gnus-bug
19525 @cindex reporting bugs
19527 Overall, a casual user who hasn't written much code that depends on
19528 @sc{gnus} internals should suffer no problems. If problems occur,
19529 please let me know by issuing that magic command @kbd{M-x gnus-bug}.
19531 @vindex gnus-bug-create-help-buffer
19532 If you are in the habit of sending bug reports @emph{very} often, you
19533 may find the helpful help buffer annoying after a while. If so, set
19534 @code{gnus-bug-create-help-buffer} to @code{nil} to avoid having it pop
19539 @subsection Conformity
19541 No rebels without a clue here, ma'am. We conform to all standards known
19542 to (wo)man. Except for those standards and/or conventions we disagree
19549 There are no known breaches of this standard.
19553 There are no known breaches of this standard, either.
19555 @item Son-of-RFC 1036
19556 @cindex Son-of-RFC 1036
19557 We do have some breaches to this one.
19563 These are considered to be ``vanity headers'', while I consider them
19564 to be consumer information. After seeing so many badly formatted
19565 articles coming from @code{tin} and @code{Netscape} I know not to use
19566 either of those for posting articles. I would not have known that if
19567 it wasn't for the @code{X-Newsreader} header.
19572 USEFOR is an IETF working group writing a successor to RFC 1036, based
19573 on Son-of-RFC 1036. They have produced a number of drafts proposing
19574 various changes to the format of news articles. The Gnus towers will
19575 look into implementing the changes when the draft is accepted as an RFC.
19579 If you ever notice Gnus acting non-compliant with regards to the texts
19580 mentioned above, don't hesitate to drop a note to Gnus Towers and let us
19585 @subsection Emacsen
19591 Gnus should work on :
19599 XEmacs 21.1.1 and up.
19603 This Gnus version will absolutely not work on any Emacsen older than
19604 that. Not reliably, at least. Older versions of Gnus may work on older
19605 Emacs versions. However, T-gnus does support ``Mule 2.3 based on Emacs
19606 19.34'' and possibly the versions of XEmacs prior to 21.1.1, e.g. 20.4.
19607 See the file ``README'' in the T-gnus distribution for more details.
19609 There are some vague differences between Gnus on the various
19610 platforms---XEmacs features more graphics (a logo and a toolbar)---but
19611 other than that, things should look pretty much the same under all
19615 @node Gnus Development
19616 @subsection Gnus Development
19618 Gnus is developed in a two-phased cycle. The first phase involves much
19619 discussion on the @samp{ding@@gnus.org} mailing list, where people
19620 propose changes and new features, post patches and new backends. This
19621 phase is called the @dfn{alpha} phase, since the Gnusae released in this
19622 phase are @dfn{alpha releases}, or (perhaps more commonly in other
19623 circles) @dfn{snapshots}. During this phase, Gnus is assumed to be
19624 unstable and should not be used by casual users. Gnus alpha releases
19625 have names like ``Red Gnus'' and ``Quassia Gnus''.
19627 After futzing around for 50-100 alpha releases, Gnus is declared
19628 @dfn{frozen}, and only bug fixes are applied. Gnus loses the prefix,
19629 and is called things like ``Gnus 5.6.32'' instead. Normal people are
19630 supposed to be able to use these, and these are mostly discussed on the
19631 @samp{gnu.emacs.gnus} newsgroup.
19634 @vindex mail-source-delete-incoming
19635 Some variable defaults differ between alpha Gnusae and released Gnusae.
19636 In particular, @code{mail-source-delete-incoming} defaults to @code{nil} in
19637 alpha Gnusae and @code{t} in released Gnusae. This is to prevent
19638 lossage of mail if an alpha release hiccups while handling the mail.
19640 The division of discussion between the ding mailing list and the Gnus
19641 newsgroup is not purely based on publicity concerns. It's true that
19642 having people write about the horrible things that an alpha Gnus release
19643 can do (sometimes) in a public forum may scare people off, but more
19644 importantly, talking about new experimental features that have been
19645 introduced may confuse casual users. New features are frequently
19646 introduced, fiddled with, and judged to be found wanting, and then
19647 either discarded or totally rewritten. People reading the mailing list
19648 usually keep up with these rapid changes, while people on the newsgroup
19649 can't be assumed to do so.
19654 @subsection Contributors
19655 @cindex contributors
19657 The new Gnus version couldn't have been done without the help of all the
19658 people on the (ding) mailing list. Every day for over a year I have
19659 gotten billions of nice bug reports from them, filling me with joy,
19660 every single one of them. Smooches. The people on the list have been
19661 tried beyond endurance, what with my ``oh, that's a neat idea <type
19662 type>, yup, I'll release it right away <ship off> no wait, that doesn't
19663 work at all <type type>, yup, I'll ship that one off right away <ship
19664 off> no, wait, that absolutely does not work'' policy for releases.
19665 Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that
19666 ``worser''? ``much worser''? ``worsest''?)
19668 I would like to take this opportunity to thank the Academy for... oops,
19674 Masanobu @sc{Umeda}---the writer of the original @sc{gnus}.
19677 Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el, webmail.el,
19678 nnwarchive and many, many other things connected with @sc{mime} and
19679 other types of en/decoding, as well as general bug fixing, new
19680 functionality and stuff.
19683 Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as
19684 well as numerous other things).
19687 Luis Fernandes---design and graphics.
19690 Justin Sheehy--the FAQ maintainer.
19693 Erik Naggum---help, ideas, support, code and stuff.
19696 Wes Hardaker---@file{gnus-picon.el} and the manual section on
19697 @dfn{picons} (@pxref{Picons}).
19700 Kim-Minh Kaplan---further work on the picon code.
19703 Brad Miller---@file{gnus-gl.el} and the GroupLens manual section
19704 (@pxref{GroupLens}).
19707 Sudish Joseph---innumerable bug fixes.
19710 Ilja Weis---@file{gnus-topic.el}.
19713 Steven L. Baur---lots and lots and lots of bugs detections and fixes.
19716 Vladimir Alexiev---the refcard and reference booklets.
19719 Felix Lee & Jamie Zawinski---I stole some pieces from the XGnus
19720 distribution by Felix Lee and JWZ.
19723 Scott Byer---@file{nnfolder.el} enhancements & rewrite.
19726 Peter Mutsaers---orphan article scoring code.
19729 Ken Raeburn---POP mail support.
19732 Hallvard B Furuseth---various bits and pieces, especially dealing with
19736 Brian Edmonds---@file{gnus-bbdb.el}.
19739 David Moore---rewrite of @file{nnvirtual.el} and many other things.
19742 Kevin Davidson---came up with the name @dfn{ding}, so blame him.
19745 François Pinard---many, many interesting and thorough bug reports, as
19746 well as autoconf support.
19750 This manual was proof-read by Adrian Aichner, with Ricardo Nassif, Mark
19751 Borges, and Jost Krieger proof-reading parts of the manual.
19753 The following people have contributed many patches and suggestions:
19762 Jason L. Tibbitts, III,
19766 Also thanks to the following for patches and stuff:
19776 Alexei V. Barantsev,
19791 Massimo Campostrini,
19796 Jae-you Chung, @c ?
19797 James H. Cloos, Jr.,
19801 Andrew J. Cosgriff,
19804 Geoffrey T. Dairiki,
19810 Michael Welsh Duggan,
19815 Enami Tsugutomo, @c Enami
19819 Nelson Jose dos Santos Ferreira,
19827 Arne Georg Gleditsch,
19829 Michelangelo Grigni,
19833 Kenichi Handa, @c Handa
19835 Yoshiki Hayashi, @c ?
19837 Hisashige Kenji, @c Hisashige
19844 François Felix Ingrand,
19845 Tatsuya Ichikawa, @c ?
19846 Ishikawa Ichiro, @c Ishikawa
19848 Iwamuro Motonori, @c Iwamuro
19859 Peter Skov Knudsen,
19860 Shuhei Kobayashi, @c Kobayashi
19862 Koseki Yoshinori, @c Koseki
19863 Thor Kristoffersen,
19866 Seokchan Lee, @c Lee
19884 Morioka Tomohiko, @c Morioka
19885 Erik Toubro Nielsen,
19892 Masaharu Onishi, @c Onishi
19897 Jens-Ulrik Holger Petersen,
19901 John McClary Prevost,
19907 Lars Balker Rasmussen,
19912 Christian von Roques,
19915 Wolfgang Rupprecht,
19922 Philippe Schnoebelen,
19924 Randal L. Schwartz,
19938 Kiyokazu Suto, @c Suto
19943 Tozawa Akihiko, @c Tozawa
19959 Katsumi Yamaoka @c Yamaoka
19964 For a full overview of what each person has done, the ChangeLogs
19965 included in the Gnus alpha distributions should give ample reading
19966 (550kB and counting).
19968 Apologies to everybody that I've forgotten, of which there are many, I'm
19971 Gee, that's quite a list of people. I guess that must mean that there
19972 actually are people who are using Gnus. Who'd'a thunk it!
19976 @subsection New Features
19977 @cindex new features
19980 * ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus.
19981 * September Gnus:: The Thing Formally Known As Gnus 5.2/5.3.
19982 * Red Gnus:: Third time best---Gnus 5.4/5.5.
19983 * Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7.
19984 * Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9.
19987 These lists are, of course, just @emph{short} overviews of the
19988 @emph{most} important new features. No, really. There are tons more.
19989 Yes, we have feeping creaturism in full effect.
19992 @subsubsection (ding) Gnus
19994 New features in Gnus 5.0/5.1:
19999 The look of all buffers can be changed by setting format-like variables
20000 (@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
20003 Local spool and several @sc{nntp} servers can be used at once
20004 (@pxref{Select Methods}).
20007 You can combine groups into virtual groups (@pxref{Virtual Groups}).
20010 You can read a number of different mail formats (@pxref{Getting Mail}).
20011 All the mail backends implement a convenient mail expiry scheme
20012 (@pxref{Expiring Mail}).
20015 Gnus can use various strategies for gathering threads that have lost
20016 their roots (thereby gathering loose sub-threads into one thread) or it
20017 can go back and retrieve enough headers to build a complete thread
20018 (@pxref{Customizing Threading}).
20021 Killed groups can be displayed in the group buffer, and you can read
20022 them as well (@pxref{Listing Groups}).
20025 Gnus can do partial group updates---you do not have to retrieve the
20026 entire active file just to check for new articles in a few groups
20027 (@pxref{The Active File}).
20030 Gnus implements a sliding scale of subscribedness to groups
20031 (@pxref{Group Levels}).
20034 You can score articles according to any number of criteria
20035 (@pxref{Scoring}). You can even get Gnus to find out how to score
20036 articles for you (@pxref{Adaptive Scoring}).
20039 Gnus maintains a dribble buffer that is auto-saved the normal Emacs
20040 manner, so it should be difficult to lose much data on what you have
20041 read if your machine should go down (@pxref{Auto Save}).
20044 Gnus now has its own startup file (@file{.gnus}) to avoid cluttering up
20045 the @file{.emacs} file.
20048 You can set the process mark on both groups and articles and perform
20049 operations on all the marked items (@pxref{Process/Prefix}).
20052 You can grep through a subset of groups and create a group from the
20053 results (@pxref{Kibozed Groups}).
20056 You can list subsets of groups according to, well, anything
20057 (@pxref{Listing Groups}).
20060 You can browse foreign servers and subscribe to groups from those
20061 servers (@pxref{Browse Foreign Server}).
20064 Gnus can fetch articles, asynchronously, on a second connection to the
20065 server (@pxref{Asynchronous Fetching}).
20068 You can cache articles locally (@pxref{Article Caching}).
20071 The uudecode functions have been expanded and generalized
20072 (@pxref{Decoding Articles}).
20075 You can still post uuencoded articles, which was a little-known feature
20076 of @sc{gnus}' past (@pxref{Uuencoding and Posting}).
20079 Fetching parents (and other articles) now actually works without
20080 glitches (@pxref{Finding the Parent}).
20083 Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
20086 Digests (and other files) can be used as the basis for groups
20087 (@pxref{Document Groups}).
20090 Articles can be highlighted and customized (@pxref{Customizing
20094 URLs and other external references can be buttonized (@pxref{Article
20098 You can do lots of strange stuff with the Gnus window & frame
20099 configuration (@pxref{Windows Configuration}).
20102 You can click on buttons instead of using the keyboard
20108 @node September Gnus
20109 @subsubsection September Gnus
20113 \gnusfig{-28cm}{0cm}{\epsfig{figure=tmp/september.ps,height=20cm}}
20117 New features in Gnus 5.2/5.3:
20122 A new message composition mode is used. All old customization variables
20123 for @code{mail-mode}, @code{rnews-reply-mode} and @code{gnus-msg} are
20127 Gnus is now able to generate @dfn{sparse} threads---threads where
20128 missing articles are represented by empty nodes (@pxref{Customizing
20132 (setq gnus-build-sparse-threads 'some)
20136 Outgoing articles are stored on a special archive server
20137 (@pxref{Archived Messages}).
20140 Partial thread regeneration now happens when articles are
20144 Gnus can make use of GroupLens predictions (@pxref{GroupLens}).
20147 Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}).
20150 A @code{trn}-like tree buffer can be displayed (@pxref{Tree Display}).
20153 (setq gnus-use-trees t)
20157 An @code{nn}-like pick-and-read minor mode is available for the summary
20158 buffers (@pxref{Pick and Read}).
20161 (add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
20165 In binary groups you can use a special binary minor mode (@pxref{Binary
20169 Groups can be grouped in a folding topic hierarchy (@pxref{Group
20173 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
20177 Gnus can re-send and bounce mail (@pxref{Summary Mail Commands}).
20180 Groups can now have a score, and bubbling based on entry frequency
20181 is possible (@pxref{Group Score}).
20184 (add-hook 'gnus-summary-exit-hook 'gnus-summary-bubble-group)
20188 Groups can be process-marked, and commands can be performed on
20189 groups of groups (@pxref{Marking Groups}).
20192 Caching is possible in virtual groups.
20195 @code{nndoc} now understands all kinds of digests, mail boxes, rnews
20196 news batches, ClariNet briefs collections, and just about everything
20197 else (@pxref{Document Groups}).
20200 Gnus has a new backend (@code{nnsoup}) to create/read SOUP packets
20204 The Gnus cache is much faster.
20207 Groups can be sorted according to many criteria (@pxref{Sorting
20211 New group parameters have been introduced to set list-addresses and
20212 expiry times (@pxref{Group Parameters}).
20215 All formatting specs allow specifying faces to be used
20216 (@pxref{Formatting Fonts}).
20219 There are several more commands for setting/removing/acting on process
20220 marked articles on the @kbd{M P} submap (@pxref{Setting Process Marks}).
20223 The summary buffer can be limited to show parts of the available
20224 articles based on a wide range of criteria. These commands have been
20225 bound to keys on the @kbd{/} submap (@pxref{Limiting}).
20228 Articles can be made persistent with the @kbd{*} command
20229 (@pxref{Persistent Articles}).
20232 All functions for hiding article elements are now toggles.
20235 Article headers can be buttonized (@pxref{Article Washing}).
20238 All mail backends support fetching articles by @code{Message-ID}.
20241 Duplicate mail can now be treated properly (@pxref{Duplicates}).
20244 All summary mode commands are available directly from the article
20245 buffer (@pxref{Article Keymap}).
20248 Frames can be part of @code{gnus-buffer-configuration} (@pxref{Windows
20252 Mail can be re-scanned by a daemonic process (@pxref{Daemons}).
20255 \marginpar[\mbox{}\hfill\epsfig{figure=tmp/fseptember.ps,height=5cm}]{\epsfig{figure=tmp/fseptember.ps,height=5cm}}
20260 Gnus can make use of NoCeM files to weed out spam (@pxref{NoCeM}).
20263 (setq gnus-use-nocem t)
20267 Groups can be made permanently visible (@pxref{Listing Groups}).
20270 (setq gnus-permanently-visible-groups "^nnml:")
20274 Many new hooks have been introduced to make customizing easier.
20277 Gnus respects the @code{Mail-Copies-To} header.
20280 Threads can be gathered by looking at the @code{References} header
20281 (@pxref{Customizing Threading}).
20284 (setq gnus-summary-thread-gathering-function
20285 'gnus-gather-threads-by-references)
20289 Read articles can be stored in a special backlog buffer to avoid
20290 refetching (@pxref{Article Backlog}).
20293 (setq gnus-keep-backlog 50)
20297 A clean copy of the current article is always stored in a separate
20298 buffer to allow easier treatment.
20301 Gnus can suggest where to save articles (@pxref{Saving Articles}).
20304 Gnus doesn't have to do as much prompting when saving (@pxref{Saving
20308 (setq gnus-prompt-before-saving t)
20312 @code{gnus-uu} can view decoded files asynchronously while fetching
20313 articles (@pxref{Other Decode Variables}).
20316 (setq gnus-uu-grabbed-file-functions 'gnus-uu-grab-view)
20320 Filling in the article buffer now works properly on cited text
20321 (@pxref{Article Washing}).
20324 Hiding cited text adds buttons to toggle hiding, and how much
20325 cited text to hide is now customizable (@pxref{Article Hiding}).
20328 (setq gnus-cited-lines-visible 2)
20332 Boring headers can be hidden (@pxref{Article Hiding}).
20335 Default scoring values can now be set from the menu bar.
20338 Further syntax checking of outgoing articles have been added.
20344 @subsubsection Red Gnus
20346 New features in Gnus 5.4/5.5:
20350 \gnusfig{-5.5cm}{-4cm}{\epsfig{figure=tmp/red.ps,height=20cm}}
20357 @file{nntp.el} has been totally rewritten in an asynchronous fashion.
20360 Article prefetching functionality has been moved up into
20361 Gnus (@pxref{Asynchronous Fetching}).
20364 Scoring can now be performed with logical operators like @code{and},
20365 @code{or}, @code{not}, and parent redirection (@pxref{Advanced
20369 Article washing status can be displayed in the
20370 article mode line (@pxref{Misc Article}).
20373 @file{gnus.el} has been split into many smaller files.
20376 Suppression of duplicate articles based on Message-ID can be done
20377 (@pxref{Duplicate Suppression}).
20380 (setq gnus-suppress-duplicates t)
20384 New variables for specifying what score and adapt files are to be
20385 considered home score and adapt files (@pxref{Home Score File}) have
20389 @code{nndoc} was rewritten to be easily extendable (@pxref{Document
20390 Server Internals}).
20393 Groups can inherit group parameters from parent topics (@pxref{Topic
20397 Article editing has been revamped and is now actually usable.
20400 Signatures can be recognized in more intelligent fashions
20401 (@pxref{Article Signature}).
20404 Summary pick mode has been made to look more @code{nn}-like. Line
20405 numbers are displayed and the @kbd{.} command can be used to pick
20406 articles (@code{Pick and Read}).
20409 Commands for moving the @file{.newsrc.eld} from one server to
20410 another have been added (@pxref{Changing Servers}).
20413 There's a way now to specify that ``uninteresting'' fields be suppressed
20414 when generating lines in buffers (@pxref{Advanced Formatting}).
20417 Several commands in the group buffer can be undone with @kbd{M-C-_}
20421 Scoring can be done on words using the new score type @code{w}
20422 (@pxref{Score File Format}).
20425 Adaptive scoring can be done on a Subject word-by-word basis
20426 (@pxref{Adaptive Scoring}).
20429 (setq gnus-use-adaptive-scoring '(word))
20433 Scores can be decayed (@pxref{Score Decays}).
20436 (setq gnus-decay-scores t)
20440 Scoring can be performed using a regexp on the Date header. The Date is
20441 normalized to compact ISO 8601 format first (@pxref{Score File Format}).
20444 A new command has been added to remove all data on articles from
20445 the native server (@pxref{Changing Servers}).
20448 A new command for reading collections of documents
20449 (@code{nndoc} with @code{nnvirtual} on top) has been added---@kbd{M-C-d}
20450 (@pxref{Really Various Summary Commands}).
20453 Process mark sets can be pushed and popped (@pxref{Setting Process
20457 A new mail-to-news backend makes it possible to post even when the @sc{nntp}
20458 server doesn't allow posting (@pxref{Mail-To-News Gateways}).
20461 A new backend for reading searches from Web search engines
20462 (@dfn{DejaNews}, @dfn{Alta Vista}, @dfn{InReference}) has been added
20463 (@pxref{Web Searches}).
20466 Groups inside topics can now be sorted using the standard sorting
20467 functions, and each topic can be sorted independently (@pxref{Topic
20471 Subsets of the groups can be sorted independently (@code{Sorting
20475 Cached articles can be pulled into the groups (@pxref{Summary Generation
20479 \marginpar[\mbox{}\hfill\epsfig{figure=tmp/fred.ps,width=3cm}]{\epsfig{figure=tmp/fred.ps,width=3cm}}
20484 Score files are now applied in a more reliable order (@pxref{Score
20488 Reports on where mail messages end up can be generated (@pxref{Splitting
20492 More hooks and functions have been added to remove junk from incoming
20493 mail before saving the mail (@pxref{Washing Mail}).
20496 Emphasized text can be properly fontisized:
20502 @subsubsection Quassia Gnus
20504 New features in Gnus 5.6:
20509 New functionality for using Gnus as an offline newsreader has been
20510 added. A plethora of new commands and modes have been added. See
20511 @pxref{Gnus Unplugged} for the full story.
20514 The @code{nndraft} backend has returned, but works differently than
20515 before. All Message buffers are now also articles in the @code{nndraft}
20516 group, which is created automatically.
20519 @code{gnus-alter-header-function} can now be used to alter header
20523 @code{gnus-summary-goto-article} now accept Message-ID's.
20526 A new Message command for deleting text in the body of a message
20527 outside the region: @kbd{C-c C-v}.
20530 You can now post to component group in @code{nnvirtual} groups with
20534 @code{nntp-rlogin-program}---new variable to ease customization.
20537 @code{C-u C-c C-c} in @code{gnus-article-edit-mode} will now inhibit
20538 re-highlighting of the article buffer.
20541 New element in @code{gnus-boring-article-headers}---@code{long-to}.
20544 @kbd{M-i} symbolic prefix command. See the section "Symbolic
20545 Prefixes" in the Gnus manual for details.
20548 @kbd{L} and @kbd{I} in the summary buffer now take the symbolic prefix
20549 @kbd{a} to add the score rule to the "all.SCORE" file.
20552 @code{gnus-simplify-subject-functions} variable to allow greater
20553 control over simplification.
20556 @kbd{A T}---new command for fetching the current thread.
20559 @kbd{/ T}---new command for including the current thread in the
20563 @kbd{M-RET} is a new Message command for breaking cited text.
20566 @samp{\\1}-expressions are now valid in @code{nnmail-split-methods}.
20569 The @code{custom-face-lookup} function has been removed.
20570 If you used this function in your initialization files, you must
20571 rewrite them to use @code{face-spec-set} instead.
20574 Canceling now uses the current select method. Symbolic prefix
20575 @kbd{a} forces normal posting method.
20578 New command to translate M******** sm*rtq**t*s into proper
20582 For easier debugging of @code{nntp}, you can set
20583 @code{nntp-record-commands} to a non-@code{nil} value.
20586 @code{nntp} now uses @file{~/.authinfo}, a @file{.netrc}-like file, for
20587 controlling where and how to send @sc{authinfo} to @sc{nntp} servers.
20590 A command for editing group parameters from the summary buffer
20594 A history of where mails have been split is available.
20597 A new article date command has been added---@code{article-date-iso8601}.
20600 Subjects can be simplified when threading by setting
20601 @code{gnus-score-thread-simplify}.
20604 A new function for citing in Message has been
20605 added---@code{message-cite-original-without-signature}.
20608 @code{article-strip-all-blank-lines}---new article command.
20611 A new Message command to kill to the end of the article has
20615 A minimum adaptive score can be specified by using the
20616 @code{gnus-adaptive-word-minimum} variable.
20619 The "lapsed date" article header can be kept continually
20620 updated by the @code{gnus-start-date-timer} command.
20623 Web listserv archives can be read with the @code{nnlistserv} backend.
20626 Old dejanews archives can now be read by @code{nnweb}.
20630 @node Pterodactyl Gnus
20631 @subsubsection Pterodactyl Gnus
20633 New features in Gnus 5.8:
20637 @item The mail-fetching functions have changed. See the manual for the
20638 many details. In particular, all procmail fetching variables are gone.
20640 If you used procmail like in
20643 (setq nnmail-use-procmail t)
20644 (setq nnmail-spool-file 'procmail)
20645 (setq nnmail-procmail-directory "~/mail/incoming/")
20646 (setq nnmail-procmail-suffix "\\.in")
20649 this now has changed to
20653 '((directory :path "~/mail/incoming/"
20657 More information is available in the info doc at Select Methods ->
20658 Getting Mail -> Mail Sources
20660 @item Gnus is now a MIME-capable reader. This affects many parts of
20661 Gnus, and adds a slew of new commands. See the manual for details.
20663 @item Gnus has also been multilingualized. This also affects too
20664 many parts of Gnus to summarize here, and adds many new variables.
20666 @item @code{gnus-auto-select-first} can now be a function to be
20667 called to position point.
20669 @item The user can now decide which extra headers should be included in
20670 summary buffers and NOV files.
20672 @item @code{gnus-article-display-hook} has been removed. Instead, a number
20673 of variables starting with @code{gnus-treat-} have been added.
20675 @item The Gnus posting styles have been redone again and now works in a
20676 subtly different manner.
20678 @item New web-based backends have been added: @code{nnslashdot},
20679 @code{nnwarchive} and @code{nnultimate}. nnweb has been revamped,
20680 again, to keep up with ever-changing layouts.
20682 @item Gnus can now read IMAP mail via @code{nnimap}.
20690 @section The Manual
20694 This manual was generated from a TeXinfo file and then run through
20695 either @code{texi2dvi}
20697 or my own home-brewed TeXinfo to \LaTeX\ transformer,
20698 and then run through @code{latex} and @code{dvips}
20700 to get what you hold in your hands now.
20702 The following conventions have been used:
20707 This is a @samp{string}
20710 This is a @kbd{keystroke}
20713 This is a @file{file}
20716 This is a @code{symbol}
20720 So if I were to say ``set @code{flargnoze} to @samp{yes}'', that would
20724 (setq flargnoze "yes")
20727 If I say ``set @code{flumphel} to @code{yes}'', that would mean:
20730 (setq flumphel 'yes)
20733 @samp{yes} and @code{yes} are two @emph{very} different things---don't
20734 ever get them confused.
20738 Of course, everything in this manual is of vital interest, so you should
20739 read it all. Several times. However, if you feel like skimming the
20740 manual, look for that gnu head you should see in the margin over
20741 there---it means that what's being discussed is of more importance than
20742 the rest of the stuff. (On the other hand, if everything is infinitely
20743 important, how can anything be more important than that? Just one more
20744 of the mysteries of this world, I guess.)
20750 @node On Writing Manuals
20751 @section On Writing Manuals
20753 I guess most manuals are written after-the-fact; documenting a program
20754 that's already there. This is not how this manual is written. When
20755 implementing something, I write the manual entry for that something
20756 straight away. I then see that it's difficult to explain the
20757 functionality, so I write how it's supposed to be, and then I change the
20758 implementation. Writing the documentation and writing the code goes
20761 This, of course, means that this manual has no, or little, flow. It
20762 documents absolutely everything in Gnus, but often not where you're
20763 looking for it. It is a reference manual, and not a guide to how to get
20766 That would be a totally different book, that should be written using the
20767 reference manual as source material. It would look quite differently.
20772 @section Terminology
20774 @cindex terminology
20779 This is what you are supposed to use this thing for---reading news.
20780 News is generally fetched from a nearby @sc{nntp} server, and is
20781 generally publicly available to everybody. If you post news, the entire
20782 world is likely to read just what you have written, and they'll all
20783 snigger mischievously. Behind your back.
20787 Everything that's delivered to you personally is mail. Some news/mail
20788 readers (like Gnus) blur the distinction between mail and news, but
20789 there is a difference. Mail is private. News is public. Mailing is
20790 not posting, and replying is not following up.
20794 Send a mail to the person who has written what you are reading.
20798 Post an article to the current newsgroup responding to the article you
20803 Gnus gets fed articles from a number of backends, both news and mail
20804 backends. Gnus does not handle the underlying media, so to speak---this
20805 is all done by the backends.
20809 Gnus will always use one method (and backend) as the @dfn{native}, or
20810 default, way of getting news.
20814 You can also have any number of foreign groups active at the same time.
20815 These are groups that use non-native non-secondary backends for getting
20820 Secondary backends are somewhere half-way between being native and being
20821 foreign, but they mostly act like they are native.
20825 A message that has been posted as news.
20828 @cindex mail message
20829 A message that has been mailed.
20833 A mail message or news article
20837 The top part of a message, where administrative information (etc.) is
20842 The rest of an article. Everything not in the head is in the
20847 A line from the head of an article.
20851 A collection of such lines, or a collection of heads. Or even a
20852 collection of @sc{nov} lines.
20856 When Gnus enters a group, it asks the backend for the headers of all
20857 unread articles in the group. Most servers support the News OverView
20858 format, which is more compact and much faster to read and parse than the
20859 normal @sc{head} format.
20863 Each group is subscribed at some @dfn{level} or other (1-9). The ones
20864 that have a lower level are ``more'' subscribed than the groups with a
20865 higher level. In fact, groups on levels 1-5 are considered
20866 @dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
20867 are @dfn{killed}. Commands for listing groups and scanning for new
20868 articles will all use the numeric prefix as @dfn{working level}.
20870 @item killed groups
20871 @cindex killed groups
20872 No information on killed groups is stored or updated, which makes killed
20873 groups much easier to handle than subscribed groups.
20875 @item zombie groups
20876 @cindex zombie groups
20877 Just like killed groups, only slightly less dead.
20880 @cindex active file
20881 The news server has to keep track of what articles it carries, and what
20882 groups exist. All this information in stored in the active file, which
20883 is rather large, as you might surmise.
20886 @cindex bogus groups
20887 A group that exists in the @file{.newsrc} file, but isn't known to the
20888 server (i.e., it isn't in the active file), is a @emph{bogus group}.
20889 This means that the group probably doesn't exist (any more).
20892 @cindex activating groups
20893 The act of asking the server for info on a group and computing the
20894 number of unread articles is called @dfn{activating the group}.
20895 Un-activated groups are listed with @samp{*} in the group buffer.
20899 A machine one can connect to and get news (or mail) from.
20901 @item select method
20902 @cindex select method
20903 A structure that specifies the backend, the server and the virtual
20906 @item virtual server
20907 @cindex virtual server
20908 A named select method. Since a select method defines all there is to
20909 know about connecting to a (physical) server, taking the thing as a
20910 whole is a virtual server.
20914 Taking a buffer and running it through a filter of some sort. The
20915 result will (more often than not) be cleaner and more pleasing than the
20918 @item ephemeral groups
20919 @cindex ephemeral groups
20920 Most groups store data on what articles you have read. @dfn{Ephemeral}
20921 groups are groups that will have no data stored---when you exit the
20922 group, it'll disappear into the aether.
20925 @cindex solid groups
20926 This is the opposite of ephemeral groups. All groups listed in the
20927 group buffer are solid groups.
20929 @item sparse articles
20930 @cindex sparse articles
20931 These are article placeholders shown in the summary buffer when
20932 @code{gnus-build-sparse-threads} has been switched on.
20936 To put responses to articles directly after the articles they respond
20937 to---in a hierarchical fashion.
20941 @cindex thread root
20942 The first article in a thread is the root. It is the ancestor of all
20943 articles in the thread.
20947 An article that has responses.
20951 An article that responds to a different article---its parent.
20955 A collection of messages in one file. The most common digest format is
20956 specified by RFC 1153.
20962 @node Customization
20963 @section Customization
20964 @cindex general customization
20966 All variables are properly documented elsewhere in this manual. This
20967 section is designed to give general pointers on how to customize Gnus
20968 for some quite common situations.
20971 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
20972 * Slow Terminal Connection:: You run a remote Emacs.
20973 * Little Disk Space:: You feel that having large setup files is icky.
20974 * Slow Machine:: You feel like buying a faster machine.
20978 @node Slow/Expensive Connection
20979 @subsection Slow/Expensive @sc{nntp} Connection
20981 If you run Emacs on a machine locally, and get your news from a machine
20982 over some very thin strings, you want to cut down on the amount of data
20983 Gnus has to get from the @sc{nntp} server.
20987 @item gnus-read-active-file
20988 Set this to @code{nil}, which will inhibit Gnus from requesting the
20989 entire active file from the server. This file is often v. large. You
20990 also have to set @code{gnus-check-new-newsgroups} and
20991 @code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
20992 doesn't suddenly decide to fetch the active file anyway.
20994 @item gnus-nov-is-evil
20995 This one has to be @code{nil}. If not, grabbing article headers from
20996 the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
20997 support @sc{xover}; Gnus will detect this by itself.
21001 @node Slow Terminal Connection
21002 @subsection Slow Terminal Connection
21004 Let's say you use your home computer for dialing up the system that runs
21005 Emacs and Gnus. If your modem is slow, you want to reduce (as much as
21006 possible) the amount of data sent over the wires.
21010 @item gnus-auto-center-summary
21011 Set this to @code{nil} to inhibit Gnus from re-centering the summary
21012 buffer all the time. If it is @code{vertical}, do only vertical
21013 re-centering. If it is neither @code{nil} nor @code{vertical}, do both
21014 horizontal and vertical recentering.
21016 @item gnus-visible-headers
21017 Cut down on the headers included in the articles to the
21018 minimum. You can, in fact, make do without them altogether---most of the
21019 useful data is in the summary buffer, anyway. Set this variable to
21020 @samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need.
21022 Set this hook to all the available hiding commands:
21024 (setq gnus-treat-hide-headers 'head
21025 gnus-treat-hide-signature t
21026 gnus-treat-hide-citation t)
21029 @item gnus-use-full-window
21030 By setting this to @code{nil}, you can make all the windows smaller.
21031 While this doesn't really cut down much generally, it means that you
21032 have to see smaller portions of articles before deciding that you didn't
21033 want to read them anyway.
21035 @item gnus-thread-hide-subtree
21036 If this is non-@code{nil}, all threads in the summary buffer will be
21039 @item gnus-updated-mode-lines
21040 If this is @code{nil}, Gnus will not put information in the buffer mode
21041 lines, which might save some time.
21045 @node Little Disk Space
21046 @subsection Little Disk Space
21049 The startup files can get rather large, so you may want to cut their
21050 sizes a bit if you are running out of space.
21054 @item gnus-save-newsrc-file
21055 If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
21056 only save @file{.newsrc.eld}. This means that you will not be able to
21057 use any other newsreaders than Gnus. This variable is @code{t} by
21060 @item gnus-read-newsrc-file
21061 If this is @code{nil}, Gnus will never read @file{.newsrc}---it will
21062 only read @file{.newsrc.eld}. This means that you will not be able to
21063 use any other newsreaders than Gnus. This variable is @code{t} by
21066 @item gnus-save-killed-list
21067 If this is @code{nil}, Gnus will not save the list of dead groups. You
21068 should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
21069 and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
21070 variable to @code{nil}. This variable is @code{t} by default.
21076 @subsection Slow Machine
21077 @cindex slow machine
21079 If you have a slow machine, or are just really impatient, there are a
21080 few things you can do to make Gnus run faster.
21082 Set @code{gnus-check-new-newsgroups} and
21083 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
21085 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
21086 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
21087 summary buffer faster.
21091 @node Troubleshooting
21092 @section Troubleshooting
21093 @cindex troubleshooting
21095 Gnus works @emph{so} well straight out of the box---I can't imagine any
21103 Make sure your computer is switched on.
21106 Make sure that you really load the current Gnus version. If you have
21107 been running @sc{gnus}, you need to exit Emacs and start it up again before
21111 Try doing an @kbd{M-x gnus-version}. If you get something that looks
21112 like @samp{T-gnus 6.15.* (based on Oort Gnus v0.*; for SEMI 1.1*, FLIM
21113 1.1*)} you have the right files loaded. If, on the other hand, you get
21114 something like @samp{NNTP 3.x} or @samp{nntp flee}, you have some old
21115 @file{.el} files lying around. Delete these.
21118 Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
21122 @vindex max-lisp-eval-depth
21123 Gnus works on many recursive structures, and in some extreme (and very
21124 rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at
21125 you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or
21126 something like that.
21129 If all else fails, report the problem as a bug.
21132 @cindex reporting bugs
21134 @kindex M-x gnus-bug
21136 If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
21137 command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
21138 me the backtrace. I will fix bugs, but I can only fix them if you send
21139 me a precise description as to how to reproduce the bug.
21141 You really can never be too detailed in a bug report. Always use the
21142 @kbd{M-x gnus-bug} command when you make bug reports, even if it creates
21143 a 10Kb mail each time you use it, and even if you have sent me your
21144 environment 500 times before. I don't care. I want the full info each
21147 It is also important to remember that I have no memory whatsoever. If
21148 you send a bug report, and I send you a reply, and then you just send
21149 back ``No, it's not! Moron!'', I will have no idea what you are
21150 insulting me about. Always over-explain everything. It's much easier
21151 for all of us---if I don't have all the information I need, I will just
21152 mail you and ask for more info, and everything takes more time.
21154 If the problem you're seeing is very visual, and you can't quite explain
21155 it, copy the Emacs window to a file (with @code{xwd}, for instance), put
21156 it somewhere it can be reached, and include the URL of the picture in
21160 If you would like to contribute a patch to fix bugs or make
21161 improvements, please produce the patch using @samp{diff -u}.
21163 If you just need help, you are better off asking on
21164 @samp{gnu.emacs.gnus}. I'm not very helpful.
21166 @cindex gnu.emacs.gnus
21167 @cindex ding mailing list
21168 You can also ask on the ding mailing list---@samp{ding@@gnus.org}.
21169 Write to @samp{ding-request@@gnus.org} to subscribe.
21173 @node Gnus Reference Guide
21174 @section Gnus Reference Guide
21176 It is my hope that other people will figure out smart stuff that Gnus
21177 can do, and that other people will write those smart things as well. To
21178 facilitate that I thought it would be a good idea to describe the inner
21179 workings of Gnus. And some of the not-so-inner workings, while I'm at
21182 You can never expect the internals of a program not to change, but I
21183 will be defining (in some details) the interface between Gnus and its
21184 backends (this is written in stone), the format of the score files
21185 (ditto), data structures (some are less likely to change than others)
21186 and general methods of operation.
21189 * Gnus Utility Functions:: Common functions and variable to use.
21190 * Backend Interface:: How Gnus communicates with the servers.
21191 * Score File Syntax:: A BNF definition of the score file standard.
21192 * Headers:: How Gnus stores headers internally.
21193 * Ranges:: A handy format for storing mucho numbers.
21194 * Group Info:: The group info format.
21195 * Extended Interactive:: Symbolic prefixes and stuff.
21196 * Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen.
21197 * Various File Formats:: Formats of files that Gnus use.
21201 @node Gnus Utility Functions
21202 @subsection Gnus Utility Functions
21203 @cindex Gnus utility functions
21204 @cindex utility functions
21206 @cindex internal variables
21208 When writing small functions to be run from hooks (and stuff), it's
21209 vital to have access to the Gnus internal functions and variables.
21210 Below is a list of the most common ones.
21214 @item gnus-newsgroup-name
21215 @vindex gnus-newsgroup-name
21216 This variable holds the name of the current newsgroup.
21218 @item gnus-find-method-for-group
21219 @findex gnus-find-method-for-group
21220 A function that returns the select method for @var{group}.
21222 @item gnus-group-real-name
21223 @findex gnus-group-real-name
21224 Takes a full (prefixed) Gnus group name, and returns the unprefixed
21227 @item gnus-group-prefixed-name
21228 @findex gnus-group-prefixed-name
21229 Takes an unprefixed group name and a select method, and returns the full
21230 (prefixed) Gnus group name.
21232 @item gnus-get-info
21233 @findex gnus-get-info
21234 Returns the group info list for @var{group}.
21236 @item gnus-group-unread
21237 @findex gnus-group-unread
21238 The number of unread articles in @var{group}, or @code{t} if that is
21242 @findex gnus-active
21243 The active entry for @var{group}.
21245 @item gnus-set-active
21246 @findex gnus-set-active
21247 Set the active entry for @var{group}.
21249 @item gnus-add-current-to-buffer-list
21250 @findex gnus-add-current-to-buffer-list
21251 Adds the current buffer to the list of buffers to be killed on Gnus
21254 @item gnus-continuum-version
21255 @findex gnus-continuum-version
21256 Takes a Gnus version string as a parameter and returns a floating point
21257 number. Earlier versions will always get a lower number than later
21260 @item gnus-group-read-only-p
21261 @findex gnus-group-read-only-p
21262 Says whether @var{group} is read-only or not.
21264 @item gnus-news-group-p
21265 @findex gnus-news-group-p
21266 Says whether @var{group} came from a news backend.
21268 @item gnus-ephemeral-group-p
21269 @findex gnus-ephemeral-group-p
21270 Says whether @var{group} is ephemeral or not.
21272 @item gnus-server-to-method
21273 @findex gnus-server-to-method
21274 Returns the select method corresponding to @var{server}.
21276 @item gnus-server-equal
21277 @findex gnus-server-equal
21278 Says whether two virtual servers are equal.
21280 @item gnus-group-native-p
21281 @findex gnus-group-native-p
21282 Says whether @var{group} is native or not.
21284 @item gnus-group-secondary-p
21285 @findex gnus-group-secondary-p
21286 Says whether @var{group} is secondary or not.
21288 @item gnus-group-foreign-p
21289 @findex gnus-group-foreign-p
21290 Says whether @var{group} is foreign or not.
21292 @item group-group-find-parameter
21293 @findex group-group-find-parameter
21294 Returns the parameter list of @var{group}. If given a second parameter,
21295 returns the value of that parameter for @var{group}.
21297 @item gnus-group-set-parameter
21298 @findex gnus-group-set-parameter
21299 Takes three parameters; @var{group}, @var{parameter} and @var{value}.
21301 @item gnus-narrow-to-body
21302 @findex gnus-narrow-to-body
21303 Narrows the current buffer to the body of the article.
21305 @item gnus-check-backend-function
21306 @findex gnus-check-backend-function
21307 Takes two parameters, @var{function} and @var{group}. If the backend
21308 @var{group} comes from supports @var{function}, return non-@code{nil}.
21311 (gnus-check-backend-function "request-scan" "nnml:misc")
21315 @item gnus-read-method
21316 @findex gnus-read-method
21317 Prompts the user for a select method.
21322 @node Backend Interface
21323 @subsection Backend Interface
21325 Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
21326 groups. It only knows how to talk to @dfn{virtual servers}. A virtual
21327 server is a @dfn{backend} and some @dfn{backend variables}. As examples
21328 of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
21329 examples of the latter we have @code{nntp-port-number} and
21330 @code{nnmbox-directory}.
21332 When Gnus asks for information from a backend---say @code{nntp}---on
21333 something, it will normally include a virtual server name in the
21334 function parameters. (If not, the backend should use the ``current''
21335 virtual server.) For instance, @code{nntp-request-list} takes a virtual
21336 server as its only (optional) parameter. If this virtual server hasn't
21337 been opened, the function should fail.
21339 Note that a virtual server name has no relation to some physical server
21340 name. Take this example:
21344 (nntp-address "ifi.uio.no")
21345 (nntp-port-number 4324))
21348 Here the virtual server name is @samp{odd-one} while the name of
21349 the physical server is @samp{ifi.uio.no}.
21351 The backends should be able to switch between several virtual servers.
21352 The standard backends implement this by keeping an alist of virtual
21353 server environments that they pull down/push up when needed.
21355 There are two groups of interface functions: @dfn{required functions},
21356 which must be present, and @dfn{optional functions}, which Gnus will
21357 always check for presence before attempting to call 'em.
21359 All these functions are expected to return data in the buffer
21360 @code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat
21361 unfortunately named, but we'll have to live with it. When I talk about
21362 @dfn{resulting data}, I always refer to the data in that buffer. When I
21363 talk about @dfn{return value}, I talk about the function value returned by
21364 the function call. Functions that fail should return @code{nil} as the
21367 Some backends could be said to be @dfn{server-forming} backends, and
21368 some might be said not to be. The latter are backends that generally
21369 only operate on one group at a time, and have no concept of ``server''
21370 -- they have a group, and they deliver info on that group and nothing
21373 Gnus identifies each message by way of group name and article number. A
21374 few remarks about these article numbers might be useful. First of all,
21375 the numbers are positive integers. Secondly, it is normally not
21376 possible for later articles to `re-use' older article numbers without
21377 confusing Gnus. That is, if a group has ever contained a message
21378 numbered 42, then no other message may get that number, or Gnus will get
21379 mightily confused.@footnote{See the function
21380 @code{nnchoke-request-update-info}, @ref{Optional Backend Functions}.}
21381 Third, article numbers must be assigned in order of arrival in the
21382 group; this is not necessarily the same as the date of the message.
21384 The previous paragraph already mentions all the `hard' restrictions that
21385 article numbers must fulfill. But it seems that it might be useful to
21386 assign @emph{consecutive} article numbers, for Gnus gets quite confused
21387 if there are holes in the article numbering sequence. However, due to
21388 the `no-reuse' restriction, holes cannot be avoided altogether. It's
21389 also useful for the article numbers to start at 1 to avoid running out
21390 of numbers as long as possible.
21392 In the examples and definitions I will refer to the imaginary backend
21395 @cindex @code{nnchoke}
21398 * Required Backend Functions:: Functions that must be implemented.
21399 * Optional Backend Functions:: Functions that need not be implemented.
21400 * Error Messaging:: How to get messages and report errors.
21401 * Writing New Backends:: Extending old backends.
21402 * Hooking New Backends Into Gnus:: What has to be done on the Gnus end.
21403 * Mail-like Backends:: Some tips on mail backends.
21407 @node Required Backend Functions
21408 @subsubsection Required Backend Functions
21412 @item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
21414 @var{articles} is either a range of article numbers or a list of
21415 @code{Message-ID}s. Current backends do not fully support either---only
21416 sequences (lists) of article numbers, and most backends do not support
21417 retrieval of @code{Message-ID}s. But they should try for both.
21419 The result data should either be HEADs or NOV lines, and the result
21420 value should either be @code{headers} or @code{nov} to reflect this.
21421 This might later be expanded to @code{various}, which will be a mixture
21422 of HEADs and NOV lines, but this is currently not supported by Gnus.
21424 If @var{fetch-old} is non-@code{nil} it says to try fetching "extra
21425 headers", in some meaning of the word. This is generally done by
21426 fetching (at most) @var{fetch-old} extra headers less than the smallest
21427 article number in @code{articles}, and filling the gaps as well. The
21428 presence of this parameter can be ignored if the backend finds it
21429 cumbersome to follow the request. If this is non-@code{nil} and not a
21430 number, do maximum fetches.
21432 Here's an example HEAD:
21435 221 1056 Article retrieved.
21436 Path: ifi.uio.no!sturles
21437 From: sturles@@ifi.uio.no (Sturle Sunde)
21438 Newsgroups: ifi.discussion
21439 Subject: Re: Something very droll
21440 Date: 27 Oct 1994 14:02:57 +0100
21441 Organization: Dept. of Informatics, University of Oslo, Norway
21443 Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
21444 References: <38jdmq$4qu@@visbur.ifi.uio.no>
21445 NNTP-Posting-Host: holmenkollen.ifi.uio.no
21449 So a @code{headers} return value would imply that there's a number of
21450 these in the data buffer.
21452 Here's a BNF definition of such a buffer:
21456 head = error / valid-head
21457 error-message = [ "4" / "5" ] 2number " " <error message> eol
21458 valid-head = valid-message *header "." eol
21459 valid-message = "221 " <number> " Article retrieved." eol
21460 header = <text> eol
21463 If the return value is @code{nov}, the data buffer should contain
21464 @dfn{network overview database} lines. These are basically fields
21468 nov-buffer = *nov-line
21469 nov-line = 8*9 [ field <TAB> ] eol
21470 field = <text except TAB>
21473 For a closer look at what should be in those fields,
21477 @item (nnchoke-open-server SERVER &optional DEFINITIONS)
21479 @var{server} is here the virtual server name. @var{definitions} is a
21480 list of @code{(VARIABLE VALUE)} pairs that define this virtual server.
21482 If the server can't be opened, no error should be signaled. The backend
21483 may then choose to refuse further attempts at connecting to this
21484 server. In fact, it should do so.
21486 If the server is opened already, this function should return a
21487 non-@code{nil} value. There should be no data returned.
21490 @item (nnchoke-close-server &optional SERVER)
21492 Close connection to @var{server} and free all resources connected
21493 to it. Return @code{nil} if the server couldn't be closed for some
21496 There should be no data returned.
21499 @item (nnchoke-request-close)
21501 Close connection to all servers and free all resources that the backend
21502 have reserved. All buffers that have been created by that backend
21503 should be killed. (Not the @code{nntp-server-buffer}, though.) This
21504 function is generally only called when Gnus is shutting down.
21506 There should be no data returned.
21509 @item (nnchoke-server-opened &optional SERVER)
21511 If @var{server} is the current virtual server, and the connection to the
21512 physical server is alive, then this function should return a
21513 non-@code{nil} vlue. This function should under no circumstances
21514 attempt to reconnect to a server we have lost connection to.
21516 There should be no data returned.
21519 @item (nnchoke-status-message &optional SERVER)
21521 This function should return the last error message from @var{server}.
21523 There should be no data returned.
21526 @item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
21528 The result data from this function should be the article specified by
21529 @var{article}. This might either be a @code{Message-ID} or a number.
21530 It is optional whether to implement retrieval by @code{Message-ID}, but
21531 it would be nice if that were possible.
21533 If @var{to-buffer} is non-@code{nil}, the result data should be returned
21534 in this buffer instead of the normal data buffer. This is to make it
21535 possible to avoid copying large amounts of data from one buffer to
21536 another, while Gnus mainly requests articles to be inserted directly
21537 into its article buffer.
21539 If it is at all possible, this function should return a cons cell where
21540 the @code{car} is the group name the article was fetched from, and the @code{cdr} is
21541 the article number. This will enable Gnus to find out what the real
21542 group and article numbers are when fetching articles by
21543 @code{Message-ID}. If this isn't possible, @code{t} should be returned
21544 on successful article retrieval.
21547 @item (nnchoke-request-group GROUP &optional SERVER FAST)
21549 Get data on @var{group}. This function also has the side effect of
21550 making @var{group} the current group.
21552 If @var{fast}, don't bother to return useful data, just make @var{group}
21555 Here's an example of some result data and a definition of the same:
21558 211 56 1000 1059 ifi.discussion
21561 The first number is the status, which should be 211. Next is the
21562 total number of articles in the group, the lowest article number, the
21563 highest article number, and finally the group name. Note that the total
21564 number of articles may be less than one might think while just
21565 considering the highest and lowest article numbers, but some articles
21566 may have been canceled. Gnus just discards the total-number, so
21567 whether one should take the bother to generate it properly (if that is a
21568 problem) is left as an exercise to the reader.
21571 group-status = [ error / info ] eol
21572 error = [ "4" / "5" ] 2<number> " " <Error message>
21573 info = "211 " 3* [ <number> " " ] <string>
21577 @item (nnchoke-close-group GROUP &optional SERVER)
21579 Close @var{group} and free any resources connected to it. This will be
21580 a no-op on most backends.
21582 There should be no data returned.
21585 @item (nnchoke-request-list &optional SERVER)
21587 Return a list of all groups available on @var{server}. And that means
21590 Here's an example from a server that only carries two groups:
21593 ifi.test 0000002200 0000002000 y
21594 ifi.discussion 3324 3300 n
21597 On each line we have a group name, then the highest article number in
21598 that group, the lowest article number, and finally a flag.
21601 active-file = *active-line
21602 active-line = name " " <number> " " <number> " " flags eol
21604 flags = "n" / "y" / "m" / "x" / "j" / "=" name
21607 The flag says whether the group is read-only (@samp{n}), is moderated
21608 (@samp{m}), is dead (@samp{x}), is aliased to some other group
21609 (@samp{=other-group}) or none of the above (@samp{y}).
21612 @item (nnchoke-request-post &optional SERVER)
21614 This function should post the current buffer. It might return whether
21615 the posting was successful or not, but that's not required. If, for
21616 instance, the posting is done asynchronously, it has generally not been
21617 completed by the time this function concludes. In that case, this
21618 function should set up some kind of sentinel to beep the user loud and
21619 clear if the posting could not be completed.
21621 There should be no result data from this function.
21626 @node Optional Backend Functions
21627 @subsubsection Optional Backend Functions
21631 @item (nnchoke-retrieve-groups GROUPS &optional SERVER)
21633 @var{groups} is a list of groups, and this function should request data
21634 on all those groups. How it does it is of no concern to Gnus, but it
21635 should attempt to do this in a speedy fashion.
21637 The return value of this function can be either @code{active} or
21638 @code{group}, which says what the format of the result data is. The
21639 former is in the same format as the data from
21640 @code{nnchoke-request-list}, while the latter is a buffer full of lines
21641 in the same format as @code{nnchoke-request-group} gives.
21644 group-buffer = *active-line / *group-status
21648 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
21650 A Gnus group info (@pxref{Group Info}) is handed to the backend for
21651 alterations. This comes in handy if the backend really carries all the
21652 information (as is the case with virtual and imap groups). This
21653 function should destructively alter the info to suit its needs, and
21654 should return the (altered) group info.
21656 There should be no result data from this function.
21659 @item (nnchoke-request-type GROUP &optional ARTICLE)
21661 When the user issues commands for ``sending news'' (@kbd{F} in the
21662 summary buffer, for instance), Gnus has to know whether the article the
21663 user is following up on is news or mail. This function should return
21664 @code{news} if @var{article} in @var{group} is news, @code{mail} if it
21665 is mail and @code{unknown} if the type can't be decided. (The
21666 @var{article} parameter is necessary in @code{nnvirtual} groups which
21667 might very well combine mail groups and news groups.) Both @var{group}
21668 and @var{article} may be @code{nil}.
21670 There should be no result data from this function.
21673 @item (nnchoke-request-set-mark GROUP ACTION &optional SERVER)
21675 Set/remove/add marks on articles. Normally Gnus handles the article
21676 marks (such as read, ticked, expired etc) internally, and store them in
21677 @code{~/.newsrc.eld}. Some backends (such as @sc{imap}) however carry
21678 all information about the articles on the server, so Gnus need to
21679 propagate the mark information to the server.
21681 ACTION is a list of mark setting requests, having this format:
21684 (RANGE ACTION MARK)
21687 RANGE is a range of articles you wish to update marks on. ACTION is
21688 @code{set}, @code{add} or @code{del}, respectively used for removing all
21689 existing marks and setting them as specified, adding (preserving the
21690 marks not mentioned) mark and removing (preserving the marks not
21691 mentioned) marks. MARK is a list of marks; where each mark is a symbol.
21692 Currently used marks are @code{read}, @code{tick}, @code{reply},
21693 @code{expire}, @code{killed}, @code{dormant}, @code{save},
21694 @code{download} and @code{unsend}, but your backend should, if possible,
21695 not limit itself to these.
21697 Given contradictory actions, the last action in the list should be the
21698 effective one. That is, if your action contains a request to add the
21699 @code{tick} mark on article 1 and, later in the list, a request to
21700 remove the mark on the same article, the mark should in fact be removed.
21702 An example action list:
21705 (((5 12 30) 'del '(tick))
21706 ((10 . 90) 'add '(read expire))
21707 ((92 94) 'del '(read)))
21710 The function should return a range of articles it wasn't able to set the
21711 mark on (currently not used for anything).
21713 There should be no result data from this function.
21715 @item (nnchoke-request-update-mark GROUP ARTICLE MARK)
21717 If the user tries to set a mark that the backend doesn't like, this
21718 function may change the mark. Gnus will use whatever this function
21719 returns as the mark for @var{article} instead of the original
21720 @var{mark}. If the backend doesn't care, it must return the original
21721 @var{mark}, and not @code{nil} or any other type of garbage.
21723 The only use for this I can see is what @code{nnvirtual} does with
21724 it---if a component group is auto-expirable, marking an article as read
21725 in the virtual group should result in the article being marked as
21728 There should be no result data from this function.
21731 @item (nnchoke-request-scan &optional GROUP SERVER)
21733 This function may be called at any time (by Gnus or anything else) to
21734 request that the backend check for incoming articles, in one way or
21735 another. A mail backend will typically read the spool file or query the
21736 POP server when this function is invoked. The @var{group} doesn't have
21737 to be heeded---if the backend decides that it is too much work just
21738 scanning for a single group, it may do a total scan of all groups. It
21739 would be nice, however, to keep things local if that's practical.
21741 There should be no result data from this function.
21744 @item (nnchoke-request-group-description GROUP &optional SERVER)
21746 The result data from this function should be a description of
21750 description-line = name <TAB> description eol
21752 description = <text>
21755 @item (nnchoke-request-list-newsgroups &optional SERVER)
21757 The result data from this function should be the description of all
21758 groups available on the server.
21761 description-buffer = *description-line
21765 @item (nnchoke-request-newgroups DATE &optional SERVER)
21767 The result data from this function should be all groups that were
21768 created after @samp{date}, which is in normal human-readable date
21769 format. The data should be in the active buffer format.
21772 @item (nnchoke-request-create-group GROUP &optional SERVER)
21774 This function should create an empty group with name @var{group}.
21776 There should be no return data.
21779 @item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
21781 This function should run the expiry process on all articles in the
21782 @var{articles} range (which is currently a simple list of article
21783 numbers.) It is left up to the backend to decide how old articles
21784 should be before they are removed by this function. If @var{force} is
21785 non-@code{nil}, all @var{articles} should be deleted, no matter how new
21788 This function should return a list of articles that it did not/was not
21791 There should be no result data returned.
21794 @item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
21797 This function should move @var{article} (which is a number) from
21798 @var{group} by calling @var{accept-form}.
21800 This function should ready the article in question for moving by
21801 removing any header lines it has added to the article, and generally
21802 should ``tidy up'' the article. Then it should @code{eval}
21803 @var{accept-form} in the buffer where the ``tidy'' article is. This
21804 will do the actual copying. If this @code{eval} returns a
21805 non-@code{nil} value, the article should be removed.
21807 If @var{last} is @code{nil}, that means that there is a high likelihood
21808 that there will be more requests issued shortly, so that allows some
21811 The function should return a cons where the @code{car} is the group name and
21812 the @code{cdr} is the article number that the article was entered as.
21814 There should be no data returned.
21817 @item (nnchoke-request-accept-article GROUP &optional SERVER LAST)
21819 This function takes the current buffer and inserts it into @var{group}.
21820 If @var{last} in @code{nil}, that means that there will be more calls to
21821 this function in short order.
21823 The function should return a cons where the @code{car} is the group name and
21824 the @code{cdr} is the article number that the article was entered as.
21826 There should be no data returned.
21829 @item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
21831 This function should remove @var{article} (which is a number) from
21832 @var{group} and insert @var{buffer} there instead.
21834 There should be no data returned.
21837 @item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
21839 This function should delete @var{group}. If @var{force}, it should
21840 really delete all the articles in the group, and then delete the group
21841 itself. (If there is such a thing as ``the group itself''.)
21843 There should be no data returned.
21846 @item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
21848 This function should rename @var{group} into @var{new-name}. All
21849 articles in @var{group} should move to @var{new-name}.
21851 There should be no data returned.
21856 @node Error Messaging
21857 @subsubsection Error Messaging
21859 @findex nnheader-report
21860 @findex nnheader-get-report
21861 The backends should use the function @code{nnheader-report} to report
21862 error conditions---they should not raise errors when they aren't able to
21863 perform a request. The first argument to this function is the backend
21864 symbol, and the rest are interpreted as arguments to @code{format} if
21865 there are multiple of them, or just a string if there is one of them.
21866 This function must always returns @code{nil}.
21869 (nnheader-report 'nnchoke "You did something totally bogus")
21871 (nnheader-report 'nnchoke "Could not request group %s" group)
21874 Gnus, in turn, will call @code{nnheader-get-report} when it gets a
21875 @code{nil} back from a server, and this function returns the most
21876 recently reported message for the backend in question. This function
21877 takes one argument---the server symbol.
21879 Internally, these functions access @var{backend}@code{-status-string},
21880 so the @code{nnchoke} backend will have its error message stored in
21881 @code{nnchoke-status-string}.
21884 @node Writing New Backends
21885 @subsubsection Writing New Backends
21887 Many backends are quite similar. @code{nnml} is just like
21888 @code{nnspool}, but it allows you to edit the articles on the server.
21889 @code{nnmh} is just like @code{nnml}, but it doesn't use an active file,
21890 and it doesn't maintain overview databases. @code{nndir} is just like
21891 @code{nnml}, but it has no concept of ``groups'', and it doesn't allow
21894 It would make sense if it were possible to ``inherit'' functions from
21895 backends when writing new backends. And, indeed, you can do that if you
21896 want to. (You don't have to if you don't want to, of course.)
21898 All the backends declare their public variables and functions by using a
21899 package called @code{nnoo}.
21901 To inherit functions from other backends (and allow other backends to
21902 inherit functions from the current backend), you should use the
21908 This macro declares the first parameter to be a child of the subsequent
21909 parameters. For instance:
21912 (nnoo-declare nndir
21916 @code{nndir} has declared here that it intends to inherit functions from
21917 both @code{nnml} and @code{nnmh}.
21920 This macro is equivalent to @code{defvar}, but registers the variable as
21921 a public server variable. Most state-oriented variables should be
21922 declared with @code{defvoo} instead of @code{defvar}.
21924 In addition to the normal @code{defvar} parameters, it takes a list of
21925 variables in the parent backends to map the variable to when executing
21926 a function in those backends.
21929 (defvoo nndir-directory nil
21930 "Where nndir will look for groups."
21931 nnml-current-directory nnmh-current-directory)
21934 This means that @code{nnml-current-directory} will be set to
21935 @code{nndir-directory} when an @code{nnml} function is called on behalf
21936 of @code{nndir}. (The same with @code{nnmh}.)
21938 @item nnoo-define-basics
21939 This macro defines some common functions that almost all backends should
21943 (nnoo-define-basics nndir)
21947 This macro is just like @code{defun} and takes the same parameters. In
21948 addition to doing the normal @code{defun} things, it registers the
21949 function as being public so that other backends can inherit it.
21951 @item nnoo-map-functions
21952 This macro allows mapping of functions from the current backend to
21953 functions from the parent backends.
21956 (nnoo-map-functions nndir
21957 (nnml-retrieve-headers 0 nndir-current-group 0 0)
21958 (nnmh-request-article 0 nndir-current-group 0 0))
21961 This means that when @code{nndir-retrieve-headers} is called, the first,
21962 third, and fourth parameters will be passed on to
21963 @code{nnml-retrieve-headers}, while the second parameter is set to the
21964 value of @code{nndir-current-group}.
21967 This macro allows importing functions from backends. It should be the
21968 last thing in the source file, since it will only define functions that
21969 haven't already been defined.
21975 nnmh-request-newgroups)
21979 This means that calls to @code{nndir-request-list} should just be passed
21980 on to @code{nnmh-request-list}, while all public functions from
21981 @code{nnml} that haven't been defined in @code{nndir} yet should be
21986 Below is a slightly shortened version of the @code{nndir} backend.
21989 ;;; nndir.el --- single directory newsgroup access for Gnus
21990 ;; Copyright (C) 1995,96 Free Software Foundation, Inc.
21994 (require 'nnheader)
21998 (eval-when-compile (require 'cl))
22000 (nnoo-declare nndir
22003 (defvoo nndir-directory nil
22004 "Where nndir will look for groups."
22005 nnml-current-directory nnmh-current-directory)
22007 (defvoo nndir-nov-is-evil nil
22008 "*Non-nil means that nndir will never retrieve NOV headers."
22011 (defvoo nndir-current-group ""
22013 nnml-current-group nnmh-current-group)
22014 (defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
22015 (defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)
22017 (defvoo nndir-status-string "" nil nnmh-status-string)
22018 (defconst nndir-version "nndir 1.0")
22020 ;;; Interface functions.
22022 (nnoo-define-basics nndir)
22024 (deffoo nndir-open-server (server &optional defs)
22025 (setq nndir-directory
22026 (or (cadr (assq 'nndir-directory defs))
22028 (unless (assq 'nndir-directory defs)
22029 (push `(nndir-directory ,server) defs))
22030 (push `(nndir-current-group
22031 ,(file-name-nondirectory
22032 (directory-file-name nndir-directory)))
22034 (push `(nndir-top-directory
22035 ,(file-name-directory (directory-file-name nndir-directory)))
22037 (nnoo-change-server 'nndir server defs))
22039 (nnoo-map-functions nndir
22040 (nnml-retrieve-headers 0 nndir-current-group 0 0)
22041 (nnmh-request-article 0 nndir-current-group 0 0)
22042 (nnmh-request-group nndir-current-group 0 0)
22043 (nnmh-close-group nndir-current-group 0))
22047 nnmh-status-message
22049 nnmh-request-newgroups))
22055 @node Hooking New Backends Into Gnus
22056 @subsubsection Hooking New Backends Into Gnus
22058 @vindex gnus-valid-select-methods
22059 Having Gnus start using your new backend is rather easy---you just
22060 declare it with the @code{gnus-declare-backend} functions. This will
22061 enter the backend into the @code{gnus-valid-select-methods} variable.
22063 @code{gnus-declare-backend} takes two parameters---the backend name and
22064 an arbitrary number of @dfn{abilities}.
22069 (gnus-declare-backend "nnchoke" 'mail 'respool 'address)
22072 The abilities can be:
22076 This is a mailish backend---followups should (probably) go via mail.
22078 This is a newsish backend---followups should (probably) go via news.
22080 This backend supports both mail and news.
22082 This is neither a post nor mail backend---it's something completely
22085 It supports respooling---or rather, it is able to modify its source
22086 articles and groups.
22088 The name of the server should be in the virtual server name. This is
22089 true for almost all backends.
22090 @item prompt-address
22091 The user should be prompted for an address when doing commands like
22092 @kbd{B} in the group buffer. This is true for backends like
22093 @code{nntp}, but not @code{nnmbox}, for instance.
22097 @node Mail-like Backends
22098 @subsubsection Mail-like Backends
22100 One of the things that separate the mail backends from the rest of the
22101 backends is the heavy dependence by the mail backends on common
22102 functions in @file{nnmail.el}. For instance, here's the definition of
22103 @code{nnml-request-scan}:
22106 (deffoo nnml-request-scan (&optional group server)
22107 (setq nnml-article-file-alist nil)
22108 (nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group))
22111 It simply calls @code{nnmail-get-new-mail} with a few parameters,
22112 and @code{nnmail} takes care of all the moving and splitting of the
22115 This function takes four parameters.
22119 This should be a symbol to designate which backend is responsible for
22122 @item exit-function
22123 This function should be called after the splitting has been performed.
22125 @item temp-directory
22126 Where the temporary files should be stored.
22129 This optional argument should be a group name if the splitting is to be
22130 performed for one group only.
22133 @code{nnmail-get-new-mail} will call @var{backend}@code{-save-mail} to
22134 save each article. @var{backend}@code{-active-number} will be called to
22135 find the article number assigned to this article.
22137 The function also uses the following variables:
22138 @var{backend}@code{-get-new-mail} (to see whether to get new mail for
22139 this backend); and @var{backend}@code{-group-alist} and
22140 @var{backend}@code{-active-file} to generate the new active file.
22141 @var{backend}@code{-group-alist} should be a group-active alist, like
22145 (("a-group" (1 . 10))
22146 ("some-group" (34 . 39)))
22150 @node Score File Syntax
22151 @subsection Score File Syntax
22153 Score files are meant to be easily parseable, but yet extremely
22154 mallable. It was decided that something that had the same read syntax
22155 as an Emacs Lisp list would fit that spec.
22157 Here's a typical score file:
22161 ("win95" -10000 nil s)
22168 BNF definition of a score file:
22171 score-file = "" / "(" *element ")"
22172 element = rule / atom
22173 rule = string-rule / number-rule / date-rule
22174 string-rule = "(" quote string-header quote space *string-match ")"
22175 number-rule = "(" quote number-header quote space *number-match ")"
22176 date-rule = "(" quote date-header quote space *date-match ")"
22178 string-header = "subject" / "from" / "references" / "message-id" /
22179 "xref" / "body" / "head" / "all" / "followup"
22180 number-header = "lines" / "chars"
22181 date-header = "date"
22182 string-match = "(" quote <string> quote [ "" / [ space score [ "" /
22183 space date [ "" / [ space string-match-t ] ] ] ] ] ")"
22184 score = "nil" / <integer>
22185 date = "nil" / <natural number>
22186 string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
22187 "r" / "regex" / "R" / "Regex" /
22188 "e" / "exact" / "E" / "Exact" /
22189 "f" / "fuzzy" / "F" / "Fuzzy"
22190 number-match = "(" <integer> [ "" / [ space score [ "" /
22191 space date [ "" / [ space number-match-t ] ] ] ] ] ")"
22192 number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
22193 date-match = "(" quote <string> quote [ "" / [ space score [ "" /
22194 space date [ "" / [ space date-match-t ] ] ] ] ")"
22195 date-match-t = "nil" / "at" / "before" / "after"
22196 atom = "(" [ required-atom / optional-atom ] ")"
22197 required-atom = mark / expunge / mark-and-expunge / files /
22198 exclude-files / read-only / touched
22199 optional-atom = adapt / local / eval
22200 mark = "mark" space nil-or-number
22201 nil-or-number = "nil" / <integer>
22202 expunge = "expunge" space nil-or-number
22203 mark-and-expunge = "mark-and-expunge" space nil-or-number
22204 files = "files" *[ space <string> ]
22205 exclude-files = "exclude-files" *[ space <string> ]
22206 read-only = "read-only" [ space "nil" / space "t" ]
22207 adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ]
22208 adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
22209 local = "local" *[ space "(" <string> space <form> ")" ]
22210 eval = "eval" space <form>
22211 space = *[ " " / <TAB> / <NEWLINE> ]
22214 Any unrecognized elements in a score file should be ignored, but not
22217 As you can see, white space is needed, but the type and amount of white
22218 space is irrelevant. This means that formatting of the score file is
22219 left up to the programmer---if it's simpler to just spew it all out on
22220 one looong line, then that's ok.
22222 The meaning of the various atoms are explained elsewhere in this
22223 manual (@pxref{Score File Format}).
22227 @subsection Headers
22229 Internally Gnus uses a format for storing article headers that
22230 corresponds to the @sc{nov} format in a mysterious fashion. One could
22231 almost suspect that the author looked at the @sc{nov} specification and
22232 just shamelessly @emph{stole} the entire thing, and one would be right.
22234 @dfn{Header} is a severely overloaded term. ``Header'' is used in
22235 RFC 1036 to talk about lines in the head of an article (e.g.,
22236 @code{From}). It is used by many people as a synonym for
22237 ``head''---``the header and the body''. (That should be avoided, in my
22238 opinion.) And Gnus uses a format internally that it calls ``header'',
22239 which is what I'm talking about here. This is a 9-element vector,
22240 basically, with each header (ouch) having one slot.
22242 These slots are, in order: @code{number}, @code{subject}, @code{from},
22243 @code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
22244 @code{xref}, and @code{extra}. There are macros for accessing and
22245 setting these slots---they all have predictable names beginning with
22246 @code{mail-header-} and @code{mail-header-set-}, respectively.
22248 All these slots contain strings, except the @code{extra} slot, which
22249 contains an alist of header/value pairs (@pxref{To From Newsgroups}).
22255 @sc{gnus} introduced a concept that I found so useful that I've started
22256 using it a lot and have elaborated on it greatly.
22258 The question is simple: If you have a large amount of objects that are
22259 identified by numbers (say, articles, to take a @emph{wild} example)
22260 that you want to qualify as being ``included'', a normal sequence isn't
22261 very useful. (A 200,000 length sequence is a bit long-winded.)
22263 The solution is as simple as the question: You just collapse the
22267 (1 2 3 4 5 6 10 11 12)
22270 is transformed into
22273 ((1 . 6) (10 . 12))
22276 To avoid having those nasty @samp{(13 . 13)} elements to denote a
22277 lonesome object, a @samp{13} is a valid element:
22280 ((1 . 6) 7 (10 . 12))
22283 This means that comparing two ranges to find out whether they are equal
22284 is slightly tricky:
22287 ((1 . 5) 7 8 (10 . 12))
22293 ((1 . 5) (7 . 8) (10 . 12))
22296 are equal. In fact, any non-descending list is a range:
22302 is a perfectly valid range, although a pretty long-winded one. This is
22309 and is equal to the previous range.
22311 Here's a BNF definition of ranges. Of course, one must remember the
22312 semantic requirement that the numbers are non-descending. (Any number
22313 of repetition of the same number is allowed, but apt to disappear in
22317 range = simple-range / normal-range
22318 simple-range = "(" number " . " number ")"
22319 normal-range = "(" start-contents ")"
22320 contents = "" / simple-range *[ " " contents ] /
22321 number *[ " " contents ]
22324 Gnus currently uses ranges to keep track of read articles and article
22325 marks. I plan on implementing a number of range operators in C if The
22326 Powers That Be are willing to let me. (I haven't asked yet, because I
22327 need to do some more thinking on what operators I need to make life
22328 totally range-based without ever having to convert back to normal
22333 @subsection Group Info
22335 Gnus stores all permanent info on groups in a @dfn{group info} list.
22336 This list is from three to six elements (or more) long and exhaustively
22337 describes the group.
22339 Here are two example group infos; one is a very simple group while the
22340 second is a more complex one:
22343 ("no.group" 5 ((1 . 54324)))
22345 ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
22346 ((tick (15 . 19)) (replied 3 6 (19 . 3)))
22348 ((auto-expire . t) (to-address . "ding@@gnus.org")))
22351 The first element is the @dfn{group name}---as Gnus knows the group,
22352 anyway. The second element is the @dfn{subscription level}, which
22353 normally is a small integer. (It can also be the @dfn{rank}, which is a
22354 cons cell where the @code{car} is the level and the @code{cdr} is the
22355 score.) The third element is a list of ranges of read articles. The
22356 fourth element is a list of lists of article marks of various kinds.
22357 The fifth element is the select method (or virtual server, if you like).
22358 The sixth element is a list of @dfn{group parameters}, which is what
22359 this section is about.
22361 Any of the last three elements may be missing if they are not required.
22362 In fact, the vast majority of groups will normally only have the first
22363 three elements, which saves quite a lot of cons cells.
22365 Here's a BNF definition of the group info format:
22368 info = "(" group space ralevel space read
22369 [ "" / [ space marks-list [ "" / [ space method [ "" /
22370 space parameters ] ] ] ] ] ")"
22371 group = quote <string> quote
22372 ralevel = rank / level
22373 level = <integer in the range of 1 to inf>
22374 rank = "(" level "." score ")"
22375 score = <integer in the range of 1 to inf>
22377 marks-lists = nil / "(" *marks ")"
22378 marks = "(" <string> range ")"
22379 method = "(" <string> *elisp-forms ")"
22380 parameters = "(" *elisp-forms ")"
22383 Actually that @samp{marks} rule is a fib. A @samp{marks} is a
22384 @samp{<string>} consed on to a @samp{range}, but that's a bitch to say
22387 If you have a Gnus info and want to access the elements, Gnus offers a
22388 series of macros for getting/setting these elements.
22391 @item gnus-info-group
22392 @itemx gnus-info-set-group
22393 @findex gnus-info-group
22394 @findex gnus-info-set-group
22395 Get/set the group name.
22397 @item gnus-info-rank
22398 @itemx gnus-info-set-rank
22399 @findex gnus-info-rank
22400 @findex gnus-info-set-rank
22401 Get/set the group rank (@pxref{Group Score}).
22403 @item gnus-info-level
22404 @itemx gnus-info-set-level
22405 @findex gnus-info-level
22406 @findex gnus-info-set-level
22407 Get/set the group level.
22409 @item gnus-info-score
22410 @itemx gnus-info-set-score
22411 @findex gnus-info-score
22412 @findex gnus-info-set-score
22413 Get/set the group score (@pxref{Group Score}).
22415 @item gnus-info-read
22416 @itemx gnus-info-set-read
22417 @findex gnus-info-read
22418 @findex gnus-info-set-read
22419 Get/set the ranges of read articles.
22421 @item gnus-info-marks
22422 @itemx gnus-info-set-marks
22423 @findex gnus-info-marks
22424 @findex gnus-info-set-marks
22425 Get/set the lists of ranges of marked articles.
22427 @item gnus-info-method
22428 @itemx gnus-info-set-method
22429 @findex gnus-info-method
22430 @findex gnus-info-set-method
22431 Get/set the group select method.
22433 @item gnus-info-params
22434 @itemx gnus-info-set-params
22435 @findex gnus-info-params
22436 @findex gnus-info-set-params
22437 Get/set the group parameters.
22440 All the getter functions take one parameter---the info list. The setter
22441 functions take two parameters---the info list and the new value.
22443 The last three elements in the group info aren't mandatory, so it may be
22444 necessary to extend the group info before setting the element. If this
22445 is necessary, you can just pass on a non-@code{nil} third parameter to
22446 the three final setter functions to have this happen automatically.
22449 @node Extended Interactive
22450 @subsection Extended Interactive
22451 @cindex interactive
22452 @findex gnus-interactive
22454 Gnus extends the standard Emacs @code{interactive} specification
22455 slightly to allow easy use of the symbolic prefix (@pxref{Symbolic
22456 Prefixes}). Here's an example of how this is used:
22459 (defun gnus-summary-increase-score (&optional score symp)
22460 (interactive (gnus-interactive "P\ny"))
22465 The best thing to do would have been to implement
22466 @code{gnus-interactive} as a macro which would have returned an
22467 @code{interactive} form, but this isn't possible since Emacs checks
22468 whether a function is interactive or not by simply doing an @code{assq}
22469 on the lambda form. So, instead we have @code{gnus-interactive}
22470 function that takes a string and returns values that are usable to
22471 @code{interactive}.
22473 This function accepts (almost) all normal @code{interactive} specs, but
22478 @vindex gnus-current-prefix-symbol
22479 The current symbolic prefix---the @code{gnus-current-prefix-symbol}
22483 @vindex gnus-current-prefix-symbols
22484 A list of the current symbolic prefixes---the
22485 @code{gnus-current-prefix-symbol} variable.
22488 The current article number---the @code{gnus-summary-article-number}
22492 The current article header---the @code{gnus-summary-article-header}
22496 The current group name---the @code{gnus-group-group-name}
22502 @node Emacs/XEmacs Code
22503 @subsection Emacs/XEmacs Code
22507 While Gnus runs under Emacs, XEmacs and Mule, I decided that one of the
22508 platforms must be the primary one. I chose Emacs. Not because I don't
22509 like XEmacs or Mule, but because it comes first alphabetically.
22511 This means that Gnus will byte-compile under Emacs with nary a warning,
22512 while XEmacs will pump out gigabytes of warnings while byte-compiling.
22513 As I use byte-compilation warnings to help me root out trivial errors in
22514 Gnus, that's very useful.
22516 I've also consistently used Emacs function interfaces, but have used
22517 Gnusey aliases for the functions. To take an example: Emacs defines a
22518 @code{run-at-time} function while XEmacs defines a @code{start-itimer}
22519 function. I then define a function called @code{gnus-run-at-time} that
22520 takes the same parameters as the Emacs @code{run-at-time}. When running
22521 Gnus under Emacs, the former function is just an alias for the latter.
22522 However, when running under XEmacs, the former is an alias for the
22523 following function:
22526 (defun gnus-xmas-run-at-time (time repeat function &rest args)
22530 (,function ,@@args))
22534 This sort of thing has been done for bunches of functions. Gnus does
22535 not redefine any native Emacs functions while running under XEmacs---it
22536 does this @code{defalias} thing with Gnus equivalents instead. Cleaner
22539 In the cases where the XEmacs function interface was obviously cleaner,
22540 I used it instead. For example @code{gnus-region-active-p} is an alias
22541 for @code{region-active-p} in XEmacs, whereas in Emacs it is a function.
22543 Of course, I could have chosen XEmacs as my native platform and done
22544 mapping functions the other way around. But I didn't. The performance
22545 hit these indirections impose on Gnus under XEmacs should be slight.
22548 @node Various File Formats
22549 @subsection Various File Formats
22552 * Active File Format:: Information on articles and groups available.
22553 * Newsgroups File Format:: Group descriptions.
22557 @node Active File Format
22558 @subsubsection Active File Format
22560 The active file lists all groups available on the server in
22561 question. It also lists the highest and lowest current article numbers
22564 Here's an excerpt from a typical active file:
22567 soc.motss 296030 293865 y
22568 alt.binaries.pictures.fractals 3922 3913 n
22569 comp.sources.unix 1605 1593 m
22570 comp.binaries.ibm.pc 5097 5089 y
22571 no.general 1000 900 y
22574 Here's a pseudo-BNF definition of this file:
22577 active = *group-line
22578 group-line = group spc high-number spc low-number spc flag <NEWLINE>
22579 group = <non-white-space string>
22581 high-number = <non-negative integer>
22582 low-number = <positive integer>
22583 flag = "y" / "n" / "m" / "j" / "x" / "=" group
22586 For a full description of this file, see the manual pages for
22587 @samp{innd}, in particular @samp{active(5)}.
22590 @node Newsgroups File Format
22591 @subsubsection Newsgroups File Format
22593 The newsgroups file lists groups along with their descriptions. Not all
22594 groups on the server have to be listed, and not all groups in the file
22595 have to exist on the server. The file is meant purely as information to
22598 The format is quite simple; a group name, a tab, and the description.
22599 Here's the definition:
22603 line = group tab description <NEWLINE>
22604 group = <non-white-space string>
22606 description = <string>
22611 @node Emacs for Heathens
22612 @section Emacs for Heathens
22614 Believe it or not, but some people who use Gnus haven't really used
22615 Emacs much before they embarked on their journey on the Gnus Love Boat.
22616 If you are one of those unfortunates whom ``@kbd{M-C-a}'', ``kill the
22617 region'', and ``set @code{gnus-flargblossen} to an alist where the key
22618 is a regexp that is used for matching on the group name'' are magical
22619 phrases with little or no meaning, then this appendix is for you. If
22620 you are already familiar with Emacs, just ignore this and go fondle your
22624 * Keystrokes:: Entering text and executing commands.
22625 * Emacs Lisp:: The built-in Emacs programming language.
22630 @subsection Keystrokes
22634 Q: What is an experienced Emacs user?
22637 A: A person who wishes that the terminal had pedals.
22640 Yes, when you use Emacs, you are apt to use the control key, the shift
22641 key and the meta key a lot. This is very annoying to some people
22642 (notably @code{vi}le users), and the rest of us just love the hell out
22643 of it. Just give up and submit. Emacs really does stand for
22644 ``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you
22645 may have heard from other disreputable sources (like the Emacs author).
22647 The shift keys are normally located near your pinky fingers, and are
22648 normally used to get capital letters and stuff. You probably use it all
22649 the time. The control key is normally marked ``CTRL'' or something like
22650 that. The meta key is, funnily enough, never marked as such on any
22651 keyboard. The one I'm currently at has a key that's marked ``Alt'',
22652 which is the meta key on this keyboard. It's usually located somewhere
22653 to the left hand side of the keyboard, usually on the bottom row.
22655 Now, us Emacs people don't say ``press the meta-control-m key'',
22656 because that's just too inconvenient. We say ``press the @kbd{M-C-m}
22657 key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the
22658 prefix that means ``control''. So ``press @kbd{C-k}'' means ``press
22659 down the control key, and hold it down while you press @kbd{k}''.
22660 ``Press @kbd{M-C-k}'' means ``press down and hold down the meta key and
22661 the control key and then press @kbd{k}''. Simple, ay?
22663 This is somewhat complicated by the fact that not all keyboards have a
22664 meta key. In that case you can use the ``escape'' key. Then @kbd{M-k}
22665 means ``press escape, release escape, press @kbd{k}''. That's much more
22666 work than if you have a meta key, so if that's the case, I respectfully
22667 suggest you get a real keyboard with a meta key. You can't live without
22673 @subsection Emacs Lisp
22675 Emacs is the King of Editors because it's really a Lisp interpreter.
22676 Each and every key you tap runs some Emacs Lisp code snippet, and since
22677 Emacs Lisp is an interpreted language, that means that you can configure
22678 any key to run any arbitrary code. You just, like, do it.
22680 Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
22681 functions. (These are byte-compiled for speed, but it's still
22682 interpreted.) If you decide that you don't like the way Gnus does
22683 certain things, it's trivial to have it do something a different way.
22684 (Well, at least if you know how to write Lisp code.) However, that's
22685 beyond the scope of this manual, so we are simply going to talk about
22686 some common constructs that you normally use in your @file{.emacs} file
22689 If you want to set the variable @code{gnus-florgbnize} to four (4), you
22690 write the following:
22693 (setq gnus-florgbnize 4)
22696 This function (really ``special form'') @code{setq} is the one that can
22697 set a variable to some value. This is really all you need to know. Now
22698 you can go and fill your @code{.emacs} file with lots of these to change
22701 If you have put that thing in your @code{.emacs} file, it will be read
22702 and @code{eval}ed (which is lisp-ese for ``run'') the next time you
22703 start Emacs. If you want to change the variable right away, simply say
22704 @kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
22705 previous ``form'', which is a simple @code{setq} statement here.
22707 Go ahead---just try it, if you're located at your Emacs. After you
22708 @kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
22709 is the return value of the form you @code{eval}ed.
22713 If the manual says ``set @code{gnus-read-active-file} to @code{some}'',
22717 (setq gnus-read-active-file 'some)
22720 On the other hand, if the manual says ``set @code{gnus-nntp-server} to
22721 @samp{nntp.ifi.uio.no}'', that means:
22724 (setq gnus-nntp-server "nntp.ifi.uio.no")
22727 So be careful not to mix up strings (the latter) with symbols (the
22728 former). The manual is unambiguous, but it can be confusing.
22731 @include gnus-faq.texi
22752 % LocalWords: Backend BNF mucho Backends backends detailmenu cindex kindex kbd
22753 % LocalWords: findex Gnusae vindex dfn dfn samp nntp setq nnspool nntpserver
22754 % LocalWords: nnmbox backend newusers Blllrph NEWGROUPS dingnusdingnusdingnus
22755 % LocalWords: pre fab rec comp nnslashdot regex ga ga sci nnml nnbabyl nnmh
22756 % LocalWords: nnfolder emph looong eld newsreaders defun init elc pxref