b368081775e3c7ae4201e6853e464d62e1e9c988
[gnus] / texi / gnus.texi
1 \input texinfo                  @c -*-texinfo-*-  -*- coding: iso-latin-1 -*-
2
3 @setfilename gnus
4 @settitle Gnus Manual
5 @synindex fn cp
6 @synindex vr cp
7 @synindex pg cp
8 @dircategory Editors
9 @direntry
10 * Gnus: (gnus).         The newsreader Gnus.
11 @end direntry
12 @iftex
13 @finalout
14 @end iftex
15 @setchapternewpage odd
16
17 @iftex
18 @iflatex
19 \documentclass[twoside,a4paper,openright,11pt]{book}
20 \usepackage[latin1]{inputenc}
21 \usepackage{pagestyle}
22 \usepackage{epsfig}
23 \usepackage{bembo}
24 \usepackage{pixidx}
25
26 \makeindex
27 \begin{document}
28
29 \newcommand{\gnuschaptername}{}
30 \newcommand{\gnussectionname}{}
31
32 \newcommand{\gnusbackslash}{/}
33
34 \newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}}
35 \newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}}
36
37 \newcommand{\gnuskindex}[1]{\index{#1}}
38 \newcommand{\gnusindex}[1]{\index{#1}}
39
40 \newcommand{\gnustt}[1]{{\fontfamily{pfu}\fontsize{10pt}{10}\selectfont #1}}
41 \newcommand{\gnuscode}[1]{\gnustt{#1}}
42 \newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\fontfamily{pfu}\fontsize{10pt}{10}\selectfont #1}''}
43 \newcommand{\gnuslisp}[1]{\gnustt{#1}}
44 \newcommand{\gnuskbd}[1]{`\gnustt{#1}'}
45 \newcommand{\gnusfile}[1]{`\gnustt{#1}'}
46 \newcommand{\gnusdfn}[1]{\textit{#1}}
47 \newcommand{\gnusi}[1]{\textit{#1}}
48 \newcommand{\gnusstrong}[1]{\textbf{#1}}
49 \newcommand{\gnusemph}[1]{\textit{#1}}
50 \newcommand{\gnusvar}[1]{{\fontsize{10pt}{10}\selectfont\textsl{\textsf{#1}}}}
51 \newcommand{\gnussc}[1]{\textsc{#1}}
52 \newcommand{\gnustitle}[1]{{\huge\textbf{#1}}}
53 \newcommand{\gnusauthor}[1]{{\large\textbf{#1}}}
54 \newcommand{\gnusresult}[1]{\gnustt{=> #1}}
55
56 \newcommand{\gnusbullet}{{${\bullet}$}}
57 \newcommand{\gnusdollar}{\$}
58 \newcommand{\gnusampersand}{\&}
59 \newcommand{\gnuspercent}{\%}
60 \newcommand{\gnushash}{\#}
61 \newcommand{\gnushat}{\symbol{"5E}}
62 \newcommand{\gnusunderline}{\symbol{"5F}}
63 \newcommand{\gnusnot}{$\neg$}
64 \newcommand{\gnustilde}{\symbol{"7E}}
65 \newcommand{\gnusless}{{$<$}}
66 \newcommand{\gnusgreater}{{$>$}}
67 \newcommand{\gnusbraceleft}{{$>$}}
68 \newcommand{\gnusbraceright}{{$>$}}
69
70 \newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=ps/gnus-head.eps,height=1cm}}}
71 \newcommand{\gnusinteresting}{
72 \marginpar[\mbox{}\hfill\gnushead]{\gnushead}
73 }
74
75 \newcommand{\gnuscleardoublepage}{\ifodd\count0\mbox{}\clearpage\thispagestyle{empty}\mbox{}\clearpage\else\clearpage\fi}
76
77 \newcommand{\gnuspagechapter}[1]{
78 {\mbox{}}
79 }
80
81 \newdimen{\gnusdimen}
82 \gnusdimen 0pt
83
84 \newcommand{\gnuschapter}[2]{
85 \gnuscleardoublepage
86 \ifdim \gnusdimen = 0pt\setcounter{page}{1}\pagestyle{gnus}\pagenumbering{arabic} \gnusdimen 1pt\fi
87 \chapter{#2}
88 \renewcommand{\gnussectionname}{}
89 \renewcommand{\gnuschaptername}{#2}
90 \thispagestyle{empty}
91 \hspace*{-2cm}
92 \begin{picture}(500,500)(0,0)
93 \put(480,350){\makebox(0,0)[tr]{#1}}
94 \put(40,300){\makebox(500,50)[bl]{{\Huge\bf{#2}}}}
95 \end{picture}
96 \clearpage
97 }
98
99 \newcommand{\gnusfigure}[3]{
100 \begin{figure}
101 \mbox{}\ifodd\count0\hspace*{-0.8cm}\else\hspace*{-3cm}\fi\begin{picture}(440,#2)
102 #3
103 \end{picture}
104 \caption{#1}
105 \end{figure}
106 }
107
108 \newcommand{\gnusicon}[1]{
109 \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}}}
110 }
111
112 \newcommand{\gnuspicon}[1]{
113 \margindex{\epsfig{figure=#1,width=2cm}}
114 }
115
116 \newcommand{\gnusxface}[2]{
117 \margindex{\epsfig{figure=#1,width=1cm}\epsfig{figure=#2,width=1cm}}
118 }
119
120 \newcommand{\gnussmiley}[2]{
121 \margindex{\makebox[2cm]{\hfill\epsfig{figure=#1,width=0.5cm}\hfill\epsfig{figure=#2,width=0.5cm}\hfill}}
122 }
123
124 \newcommand{\gnusitemx}[1]{\mbox{}\vspace*{-\itemsep}\vspace*{-\parsep}\item#1}
125
126 \newcommand{\gnussection}[1]{
127 \renewcommand{\gnussectionname}{#1}
128 \section{#1}
129 }
130
131 \newenvironment{codelist}%
132 {\begin{list}{}{
133 }
134 }{\end{list}}
135
136 \newenvironment{kbdlist}%
137 {\begin{list}{}{
138 \labelwidth=0cm
139 }
140 }{\end{list}}
141
142 \newenvironment{dfnlist}%
143 {\begin{list}{}{
144 }
145 }{\end{list}}
146
147 \newenvironment{stronglist}%
148 {\begin{list}{}{
149 }
150 }{\end{list}}
151
152 \newenvironment{samplist}%
153 {\begin{list}{}{
154 }
155 }{\end{list}}
156
157 \newenvironment{varlist}%
158 {\begin{list}{}{
159 }
160 }{\end{list}}
161
162 \newenvironment{emphlist}%
163 {\begin{list}{}{
164 }
165 }{\end{list}}
166
167 \newlength\gnusheadtextwidth
168 \setlength{\gnusheadtextwidth}{\headtextwidth}
169 \addtolength{\gnusheadtextwidth}{1cm}
170
171 \newpagestyle{gnuspreamble}%
172 {
173 {
174 \ifodd\count0
175 {
176 \hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\mbox{}}\textbf{\hfill\roman{page}}}
177 }
178 \else
179 {
180 \hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\roman{page}\hfill\mbox{}}}
181 }
182 }
183 \fi
184 }
185 }
186 {
187 \ifodd\count0
188 \mbox{} \hfill
189 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
190 \else
191 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
192 \hfill \mbox{}
193 \fi
194 }
195
196 \newpagestyle{gnusindex}%
197 {
198 {
199 \ifodd\count0
200 {
201 \hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\gnuschaptername\hfill\arabic{page}}}}
202 }
203 \else
204 {
205 \hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}
206 }
207 \fi
208 }
209 }
210 {
211 \ifodd\count0
212 \mbox{} \hfill
213 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
214 \else
215 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
216 \hfill \mbox{}
217 \fi
218 }
219
220 \newpagestyle{gnus}%
221 {
222 {
223 \ifodd\count0
224 {
225 \makebox[12cm]{\hspace*{3.1cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{chapter}.\arabic{section}} \textbf{\gnussectionname\hfill\arabic{page}}}}}
226 }
227 \else
228 {
229 \makebox[12cm]{\hspace*{-2.95cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}}
230 }
231 \fi
232 }
233 }
234 {
235 \ifodd\count0
236 \mbox{} \hfill
237 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
238 \else
239 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}}
240 \hfill \mbox{}
241 \fi
242 }
243
244 \pagenumbering{roman}
245 \pagestyle{gnuspreamble}
246
247 @end iflatex
248 @end iftex
249
250 @iftex
251 @iflatex
252 \begin{titlepage}
253 {
254
255 %\addtolength{\oddsidemargin}{-5cm}
256 %\addtolength{\evensidemargin}{-5cm}
257 \parindent=0cm
258 \addtolength{\textheight}{2cm}
259
260 \gnustitle{\gnustitlename}\\
261 \rule{15cm}{1mm}\\
262 \vfill
263 \hspace*{0cm}\epsfig{figure=ps/gnus-big-logo.eps,height=15cm}
264 \vfill
265 \rule{15cm}{1mm}\\
266 \gnusauthor{by Lars Magne Ingebrigtsen}
267 \newpage
268 }
269
270 \mbox{}
271 \vfill
272
273 \thispagestyle{empty}
274
275 Copyright \copyright{} 1995,96,97,98,99,2000 Free Software Foundation, Inc.
276
277
278 Permission is granted to copy, distribute and/or modify this document
279 under the terms of the GNU Free Documentation License, Version 1.1 or
280 any later version published by the Free Software Foundation; with no
281 Invariant Sections, with the Front-Cover texts being ``A GNU
282 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
283 license is included in the section entitled ``GNU Free Documentation
284 License'' in the Emacs manual.
285
286 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
287 this GNU Manual, like GNU software.  Copies published by the Free
288 Software Foundation raise funds for GNU development.''
289
290 This document is part of a collection distributed under the GNU Free
291 Documentation License.  If you want to distribute this document
292 separately from the collection, you can do so by adding a copy of the
293 license to the document, as described in section 6 of the license.
294 \newpage
295 \end{titlepage}
296 @end iflatex
297 @end iftex
298
299 @ifnottex
300
301 This file documents Gnus, the GNU Emacs newsreader.
302
303 Copyright (C) 1995,96,97,98,99,2000 Free Software Foundation, Inc.
304
305 Permission is granted to copy, distribute and/or modify this document
306 under the terms of the GNU Free Documentation License, Version 1.1 or
307 any later version published by the Free Software Foundation; with the
308 Invariant Sections being none, with the Front-Cover texts being ``A GNU
309 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
310 license is included in the section entitled ``GNU Free Documentation
311 License'' in the Emacs manual.
312
313 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
314 this GNU Manual, like GNU software.  Copies published by the Free
315 Software Foundation raise funds for GNU development.''
316
317 This document is part of a collection distributed under the GNU Free
318 Documentation License.  If you want to distribute this document
319 separately from the collection, you can do so by adding a copy of the
320 license to the document, as described in section 6 of the license.
321 @end ifnottex
322
323 @tex
324
325 @titlepage
326 @title Gnus Manual
327
328 @author by Lars Magne Ingebrigtsen
329 @page
330
331 @vskip 0pt plus 1filll
332 Copyright @copyright{} 1995,96,97,98,99,2000 Free Software Foundation, Inc.
333
334 Permission is granted to copy, distribute and/or modify this document
335 under the terms of the GNU Free Documentation License, Version 1.1 or
336 any later version published by the Free Software Foundation; with no
337 Invariant Sections, with the Front-Cover texts being ``A GNU
338 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
339 license is included in the section entitled ``GNU Free Documentation
340 License'' in the Emacs manual.
341
342 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
343 this GNU Manual, like GNU software.  Copies published by the Free
344 Software Foundation raise funds for GNU development.''
345
346 This document is part of a collection distributed under the GNU Free
347 Documentation License.  If you want to distribute this document
348 separately from the collection, you can do so by adding a copy of the
349 license to the document, as described in section 6 of the license.
350
351 @end titlepage
352 @page
353
354 @end tex
355
356
357 @node Top
358 @top The Gnus Newsreader
359
360 @ifinfo
361
362 You can read news (and mail) from within Emacs by using Gnus.  The news
363 can be gotten by any nefarious means you can think of---@sc{nntp}, local
364 spool or your mbox file.  All at the same time, if you want to push your
365 luck.
366
367 This manual corresponds to Oort Gnus v0.01.
368
369 @end ifinfo
370
371 @iftex
372
373 @iflatex
374 \tableofcontents
375 \gnuscleardoublepage
376 @end iflatex
377
378 Gnus is the advanced, self-documenting, customizable, extensible
379 unreal-time newsreader for GNU Emacs.
380
381 Oops.  That sounds oddly familiar, so let's start over again to avoid
382 being accused of plagiarism:
383
384 Gnus is a message-reading laboratory.  It will let you look at just
385 about anything as if it were a newsgroup.  You can read mail with it,
386 you can browse directories with it, you can @code{ftp} with it---you
387 can even read news with it!
388
389 Gnus tries to empower people who read news the same way Emacs empowers
390 people who edit text.  Gnus sets no limits to what the user should be
391 allowed to do.  Users are encouraged to extend Gnus to make it behave
392 like they want it to behave.  A program should not control people;
393 people should be empowered to do what they want by using (or abusing)
394 the program.
395
396 @end iftex
397
398 @menu
399 * Starting Up::           Finding news can be a pain.
400 * The Group Buffer::      Selecting, subscribing and killing groups.
401 * The Summary Buffer::    Reading, saving and posting articles.
402 * The Article Buffer::    Displaying and handling articles.
403 * Composing Messages::    Information on sending mail and news.
404 * Select Methods::        Gnus reads all messages from various select methods.
405 * Scoring::               Assigning values to articles.
406 * Various::               General purpose settings.
407 * The End::               Farewell and goodbye.
408 * Appendices::            Terminology, Emacs intro, FAQ, History, Internals.
409 * Index::                 Variable, function and concept index.
410 * Key Index::             Key Index.
411
412 @detailmenu
413  --- The Detailed Node Listing ---
414
415 Starting Gnus
416
417 * Finding the News::    Choosing a method for getting news.
418 * The First Time::      What does Gnus do the first time you start it?
419 * The Server is Down::  How can I read my mail then?
420 * Slave Gnusae::        You can have more than one Gnus active at a time.
421 * Fetching a Group::    Starting Gnus just to read a group.
422 * New Groups::          What is Gnus supposed to do with new groups?
423 * Startup Files::       Those pesky startup files---@file{.newsrc}.
424 * Auto Save::           Recovering from a crash.
425 * The Active File::     Reading the active file over a slow line Takes Time.
426 * Changing Servers::    You may want to move from one server to another.
427 * Startup Variables::   Other variables you might change.
428
429 New Groups
430
431 * Checking New Groups::      Determining what groups are new.
432 * Subscription Methods::     What Gnus should do with new groups.
433 * Filtering New Groups::     Making Gnus ignore certain new groups.
434
435 The Group Buffer
436
437 * Group Buffer Format::    Information listed and how you can change it.
438 * Group Maneuvering::      Commands for moving in the group buffer.
439 * Selecting a Group::      Actually reading news.
440 * Group Data::             Changing the info for a group.
441 * Subscription Commands::  Unsubscribing, killing, subscribing.
442 * Group Levels::           Levels? What are those, then?
443 * Group Score::            A mechanism for finding out what groups you like.
444 * Marking Groups::         You can mark groups for later processing.
445 * Foreign Groups::         Creating and editing groups.
446 * Group Parameters::       Each group may have different parameters set.
447 * Listing Groups::         Gnus can list various subsets of the groups.
448 * Sorting Groups::         Re-arrange the group order.
449 * Group Maintenance::      Maintaining a tidy @file{.newsrc} file.
450 * Browse Foreign Server::  You can browse a server.  See what it has to offer.
451 * Exiting Gnus::           Stop reading news and get some work done.
452 * Group Topics::           A folding group mode divided into topics.
453 * Misc Group Stuff::       Other stuff that you can to do.
454
455 Group Buffer Format
456
457 * Group Line Specification::       Deciding how the group buffer is to look.
458 * Group Modeline Specification::   The group buffer modeline.
459 * Group Highlighting::             Having nice colors in the group buffer.
460
461 Group Topics
462
463 * Topic Variables::    How to customize the topics the Lisp Way.
464 * Topic Commands::     Interactive E-Z commands.
465 * Topic Sorting::      Sorting each topic individually.
466 * Topic Topology::     A map of the world.
467 * Topic Parameters::   Parameters that apply to all groups in a topic.
468
469 Misc Group Stuff
470
471 * Scanning New Messages:: Asking Gnus to see whether new messages have arrived.
472 * Group Information::     Information and help on groups and Gnus.
473 * Group Timestamp::       Making Gnus keep track of when you last read a group.
474 * File Commands::         Reading and writing the Gnus files.
475
476 The Summary Buffer
477
478 * Summary Buffer Format::       Deciding how the summary buffer is to look.
479 * Summary Maneuvering::         Moving around the summary buffer.
480 * Choosing Articles::           Reading articles.
481 * Paging the Article::          Scrolling the current article.
482 * Reply Followup and Post::     Posting articles.
483 * Marking Articles::            Marking articles as read, expirable, etc.
484 * Limiting::                    You can limit the summary buffer.
485 * Threading::                   How threads are made.
486 * Sorting::                     How articles and threads are sorted.
487 * Asynchronous Fetching::       Gnus might be able to pre-fetch articles.
488 * Article Caching::             You may store articles in a cache.
489 * Persistent Articles::         Making articles expiry-resistant.
490 * Article Backlog::             Having already read articles hang around.
491 * Saving Articles::             Ways of customizing article saving.
492 * Decoding Articles::           Gnus can treat series of (uu)encoded articles.
493 * Article Treatment::           The article buffer can be mangled at will.
494 * MIME Commands::               Doing MIMEy things with the articles.
495 * Charsets::                    Character set issues.
496 * Article Commands::            Doing various things with the article buffer.
497 * Summary Sorting::             Sorting the summary buffer in various ways.
498 * Finding the Parent::          No child support? Get the parent.
499 * Alternative Approaches::      Reading using non-default summaries.
500 * Tree Display::                A more visual display of threads.
501 * Mail Group Commands::         Some commands can only be used in mail groups.
502 * Various Summary Stuff::       What didn't fit anywhere else.
503 * Exiting the Summary Buffer::  Returning to the Group buffer.
504 * Crosspost Handling::          How crossposted articles are dealt with.
505 * Duplicate Suppression::       An alternative when crosspost handling fails.
506 * Security::                    Decrypt and Verify.
507
508 Summary Buffer Format
509
510 * Summary Buffer Lines::     You can specify how summary lines should look.
511 * To From Newsgroups::       How to not display your own name.
512 * Summary Buffer Mode Line:: You can say how the mode line should look.
513 * Summary Highlighting::     Making the summary buffer all pretty and nice.
514
515 Choosing Articles
516
517 * Choosing Commands::        Commands for choosing articles.
518 * Choosing Variables::       Variables that influence these commands.
519
520 Reply, Followup and Post
521
522 * Summary Mail Commands::    Sending mail.
523 * Summary Post Commands::    Sending news.
524 * Summary Message Commands:: Other Message-related commands.
525 * Canceling and Superseding:: ``Whoops, I shouldn't have called him that.''
526
527 Marking Articles
528
529 * Unread Articles::          Marks for unread articles.
530 * Read Articles::            Marks for read articles.
531 * Other Marks::              Marks that do not affect readedness.
532 * Setting Marks::            How to set and remove marks.
533 * Generic Marking Commands:: How to customize the marking.
534 * Setting Process Marks::    How to mark articles for later processing.
535
536 Threading
537
538 * Customizing Threading::    Variables you can change to affect the threading.
539 * Thread Commands::          Thread based commands in the summary buffer.
540
541 Customizing Threading
542
543 * Loose Threads::        How Gnus gathers loose threads into bigger threads.
544 * Filling In Threads::   Making the threads displayed look fuller.
545 * More Threading::       Even more variables for fiddling with threads.
546 * Low-Level Threading::  You thought it was over... but you were wrong!
547
548 Decoding Articles
549
550 * Uuencoded Articles::    Uudecode articles.
551 * Shell Archives::        Unshar articles.
552 * PostScript Files::      Split PostScript.
553 * Other Files::           Plain save and binhex.
554 * Decoding Variables::    Variables for a happy decoding.
555 * Viewing Files::         You want to look at the result of the decoding?
556
557 Decoding Variables
558
559 * Rule Variables::          Variables that say how a file is to be viewed.
560 * Other Decode Variables::  Other decode variables.
561 * Uuencoding and Posting::  Variables for customizing uuencoding.
562
563 Article Treatment
564
565 * Article Highlighting::    You want to make the article look like fruit salad.
566 * Article Fontisizing::     Making emphasized text look nice.
567 * Article Hiding::          You also want to make certain info go away.
568 * Article Washing::         Lots of way-neat functions to make life better.
569 * Article Buttons::         Click on URLs, Message-IDs, addresses and the like.
570 * Article Date::            Grumble, UT!
571 * Article Signature::       What is a signature?
572 * Article Miscellania::     Various other stuff.
573
574 Alternative Approaches
575
576 * Pick and Read::               First mark articles and then read them.
577 * Binary Groups::               Auto-decode all articles.
578
579 Various Summary Stuff
580
581 * Summary Group Information::         Information oriented commands.
582 * Searching for Articles::            Multiple article commands.
583 * Summary Generation Commands::       (Re)generating the summary buffer.
584 * Really Various Summary Commands::   Those pesky non-conformant commands.
585
586 The Article Buffer
587
588 * Hiding Headers::        Deciding what headers should be displayed.
589 * Using MIME::            Pushing articles through @sc{mime} before reading them.
590 * Customizing Articles::  Tailoring the look of the articles.
591 * Article Keymap::        Keystrokes available in the article buffer.
592 * Misc Article::          Other stuff.
593
594 Composing Messages
595
596 * Mail::                 Mailing and replying.
597 * Post::                 Posting and following up.
598 * Posting Server::       What server should you post via?
599 * Mail and Post::        Mailing and posting at the same time.
600 * Archived Messages::    Where Gnus stores the messages you've sent.
601 * Posting Styles::       An easier way to specify who you are.
602 * Drafts::               Postponing messages and rejected messages.
603 * Rejected Articles::    What happens if the server doesn't like your article?
604
605 Select Methods
606
607 * The Server Buffer::     Making and editing virtual servers.
608 * Getting News::          Reading USENET news with Gnus.
609 * Getting Mail::          Reading your personal mail with Gnus.
610 * Browsing the Web::      Getting messages from a plethora of Web sources.
611 * Other Sources::         Reading directories, files, SOUP packets.
612 * Combined Groups::       Combining groups into one group.
613 * Gnus Unplugged::        Reading news and mail offline.
614
615 The Server Buffer
616
617 * Server Buffer Format::      You can customize the look of this buffer.
618 * Server Commands::           Commands to manipulate servers.
619 * Example Methods::           Examples server specifications.
620 * Creating a Virtual Server:: An example session.
621 * Server Variables::          Which variables to set.
622 * Servers and Methods::       You can use server names as select methods.
623 * Unavailable Servers::       Some servers you try to contact may be down.
624
625 Getting News
626
627 * NNTP::               Reading news from an @sc{nntp} server.
628 * News Spool::         Reading news from the local spool.
629
630 Getting Mail
631
632 * Mail in a Newsreader::         Important introductory notes.  
633 * Getting Started Reading Mail:: A simple cookbook example.
634 * Splitting Mail::               How to create mail groups.
635 * Mail Sources::                 How to tell Gnus where to get mail from.
636 * Mail Backend Variables::       Variables for customizing mail handling.
637 * Fancy Mail Splitting::         Gnus can do hairy splitting of incoming mail.
638 * Group Mail Splitting::         Use group customize to drive mail splitting.
639 * Incorporating Old Mail::       What about the old mail you have?
640 * Expiring Mail::                Getting rid of unwanted mail.
641 * Washing Mail::                 Removing gruft from the mail you get.
642 * Duplicates::                   Dealing with duplicated mail.
643 * Not Reading Mail::             Using mail backends for reading other files.
644 * Choosing a Mail Backend::      Gnus can read a variety of mail formats.
645
646 Mail Sources
647
648 * Mail Source Specifiers::       How to specify what a mail source is.
649 * Mail Source Customization::    Some variables that influence things.
650 * Fetching Mail::                Using the mail source specifiers.
651
652 Choosing a Mail Backend
653
654 * Unix Mail Box::               Using the (quite) standard Un*x mbox.
655 * Rmail Babyl::                 Emacs programs use the rmail babyl format.
656 * Mail Spool::                  Store your mail in a private spool?
657 * MH Spool::                    An mhspool-like backend.
658 * Mail Folders::                Having one file for each group.
659 * Comparing Mail Backends::     An in-depth looks at pros and cons.
660
661 Browsing the Web
662
663 * Web Searches::          Creating groups from articles that match a string.
664 * Slashdot::              Reading the Slashdot comments.
665 * Ultimate::              The Ultimate Bulletin Board systems.
666 * Web Archive::           Reading mailing list archived on web.
667
668 Other Sources
669
670 * Directory Groups::      You can read a directory as if it was a newsgroup.
671 * Anything Groups::       Dired?  Who needs dired?
672 * Document Groups::       Single files can be the basis of a group.
673 * SOUP::                  Reading @sc{soup} packets ``offline''.
674 * Mail-To-News Gateways:: Posting articles via mail-to-news gateways.
675 * IMAP::                  Using Gnus as a @sc{imap} client.
676
677 Document Groups
678
679 * Document Server Internals::   How to add your own document types.
680
681 SOUP
682
683 * SOUP Commands::     Commands for creating and sending @sc{soup} packets
684 * SOUP Groups::       A backend for reading @sc{soup} packets.
685 * SOUP Replies::      How to enable @code{nnsoup} to take over mail and news.
686
687 @sc{imap}
688
689 * Splitting in IMAP::     Splitting mail with nnimap.
690 * Editing IMAP ACLs::     Limiting/enabling other users access to a mailbox.
691 * Expunging mailboxes::   Equivalent of a "compress mailbox" button.
692
693 Combined Groups
694
695 * Virtual Groups::     Combining articles from many groups.
696 * Kibozed Groups::     Looking through parts of the newsfeed for articles.
697
698 Gnus Unplugged
699
700 * Agent Basics::           How it all is supposed to work.
701 * Agent Categories::       How to tell the Gnus Agent what to download.
702 * Agent Commands::         New commands for all the buffers.
703 * Agent Expiry::           How to make old articles go away.
704 * Agent and IMAP::         How to use the Agent with IMAP.
705 * Outgoing Messages::      What happens when you post/mail something?
706 * Agent Variables::        Customizing is fun.
707 * Example Setup::          An example @file{.gnus.el} file for offline people.
708 * Batching Agents::        How to fetch news from a @code{cron} job.
709 * Agent Caveats::          What you think it'll do and what it does.
710
711 Agent Categories
712
713 * Category Syntax::       What a category looks like.
714 * The Category Buffer::   A buffer for maintaining categories.
715 * Category Variables::    Customize'r'Us.
716
717 Agent Commands
718
719 * Group Agent Commands::
720 * Summary Agent Commands::
721 * Server Agent Commands::
722
723 Scoring
724
725 * Summary Score Commands::   Adding score entries for the current group.
726 * Group Score Commands::     General score commands.
727 * Score Variables::          Customize your scoring.  (My, what terminology).
728 * Score File Format::        What a score file may contain.
729 * Score File Editing::       You can edit score files by hand as well.
730 * Adaptive Scoring::         Big Sister Gnus knows what you read.
731 * Home Score File::          How to say where new score entries are to go.
732 * Followups To Yourself::    Having Gnus notice when people answer you.
733 * Scoring Tips::             How to score effectively.
734 * Reverse Scoring::          That problem child of old is not problem.
735 * Global Score Files::       Earth-spanning, ear-splitting score files.
736 * Kill Files::               They are still here, but they can be ignored.
737 * Converting Kill Files::    Translating kill files to score files.
738 * GroupLens::                Getting predictions on what you like to read.
739 * Advanced Scoring::         Using logical expressions to build score rules.
740 * Score Decays::             It can be useful to let scores wither away.
741
742 GroupLens
743
744 * Using GroupLens::          How to make Gnus use GroupLens.
745 * Rating Articles::          Letting GroupLens know how you rate articles.
746 * Displaying Predictions::   Displaying predictions given by GroupLens.
747 * GroupLens Variables::      Customizing GroupLens.
748
749 Advanced Scoring
750
751 * Advanced Scoring Syntax::     A definition.
752 * Advanced Scoring Examples::   What they look like.
753 * Advanced Scoring Tips::       Getting the most out of it.
754
755 Various
756
757 * Process/Prefix::             A convention used by many treatment commands.
758 * Interactive::                Making Gnus ask you many questions.
759 * Symbolic Prefixes::          How to supply some Gnus functions with options.
760 * Formatting Variables::       You can specify what buffers should look like.
761 * Windows Configuration::      Configuring the Gnus buffer windows.
762 * Faces and Fonts::            How to change how faces look.
763 * Compilation::                How to speed Gnus up.
764 * Mode Lines::                 Displaying information in the mode lines.
765 * Highlighting and Menus::     Making buffers look all nice and cozy.
766 * Buttons::                    Get tendonitis in ten easy steps!
767 * Daemons::                    Gnus can do things behind your back.
768 * NoCeM::                      How to avoid spam and other fatty foods.
769 * Undo::                       Some actions can be undone.
770 * Moderation::                 What to do if you're a moderator.
771 * XEmacs Enhancements::        There are more pictures and stuff under XEmacs.
772 * Fuzzy Matching::             What's the big fuzz?
773 * Thwarting Email Spam::       A how-to on avoiding unsolicited commercial email.
774 * Various Various::            Things that are really various.
775
776 Formatting Variables
777
778 * Formatting Basics::     A formatting variable is basically a format string.
779 * Mode Line Formatting::  Some rules about mode line formatting variables.
780 * Advanced Formatting::   Modifying output in various ways.
781 * User-Defined Specs::    Having Gnus call your own functions.
782 * Formatting Fonts::      Making the formatting look colorful and nice.
783
784 XEmacs Enhancements
785
786 * Picons::    How to display pictures of what your reading.
787 * Smileys::   Show all those happy faces the way they were meant to be shown.
788 * Toolbar::   Click'n'drool.
789 * XVarious::  Other XEmacsy Gnusey variables.
790
791 Picons
792
793 * Picon Basics::           What are picons and How do I get them.
794 * Picon Requirements::     Don't go further if you aren't using XEmacs.
795 * Easy Picons::            Displaying Picons---the easy way.
796 * Hard Picons::            The way you should do it.  You'll learn something.
797 * Picon Useless Configuration:: Other variables you can trash/tweak/munge/play with.
798
799 Appendices
800
801 * History::                        How Gnus got where it is today.
802 * On Writing Manuals::             Why this is not a beginner's guide.
803 * Terminology::                    We use really difficult, like, words here.
804 * Customization::                  Tailoring Gnus to your needs.
805 * Troubleshooting::                What you might try if things do not work.
806 * Gnus Reference Guide::           Rilly, rilly technical stuff.
807 * Emacs for Heathens::             A short introduction to Emacsian terms.
808 * Frequently Asked Questions::     A question-and-answer session.
809
810 History
811
812 * Gnus Versions::       What Gnus versions have been released.
813 * Other Gnus Versions:: Other Gnus versions that also have been released.
814 * Why?::                What's the point of Gnus?
815 * Compatibility::       Just how compatible is Gnus with @sc{gnus}?
816 * Conformity::          Gnus tries to conform to all standards.
817 * Emacsen::             Gnus can be run on a few modern Emacsen.
818 * Gnus Development::    How Gnus is developed.
819 * Contributors::        Oodles of people.
820 * New Features::        Pointers to some of the new stuff in Gnus.
821 * Newest Features::     Features so new that they haven't been written yet.
822
823 New Features
824
825 * ding Gnus::          New things in Gnus 5.0/5.1, the first new Gnus.
826 * September Gnus::     The Thing Formally Known As Gnus 5.3/5.3.
827 * Red Gnus::           Third time best---Gnus 5.4/5.5.
828 * Quassia Gnus::       Two times two is four, or Gnus 5.6/5.7.
829
830 Customization
831
832 * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
833 * Slow Terminal Connection::  You run a remote Emacs.
834 * Little Disk Space::         You feel that having large setup files is icky.
835 * Slow Machine::              You feel like buying a faster machine.
836
837 Gnus Reference Guide
838
839 * Gnus Utility Functions::   Common functions and variable to use.
840 * Backend Interface::        How Gnus communicates with the servers.
841 * Score File Syntax::        A BNF definition of the score file standard.
842 * Headers::                  How Gnus stores headers internally.
843 * Ranges::                   A handy format for storing mucho numbers.
844 * Group Info::               The group info format.
845 * Extended Interactive::     Symbolic prefixes and stuff.
846 * Emacs/XEmacs Code::        Gnus can be run under all modern Emacsen.
847 * Various File Formats::     Formats of files that Gnus use.
848
849 Backend Interface
850
851 * Required Backend Functions::        Functions that must be implemented.
852 * Optional Backend Functions::        Functions that need not be implemented.
853 * Error Messaging::                   How to get messages and report errors.
854 * Writing New Backends::              Extending old backends.
855 * Hooking New Backends Into Gnus::    What has to be done on the Gnus end.
856 * Mail-like Backends::                Some tips on mail backends.
857
858 Various File Formats
859
860 * Active File Format::      Information on articles and groups available.
861 * Newsgroups File Format::  Group descriptions.
862
863 Emacs for Heathens
864
865 * Keystrokes::      Entering text and executing commands.
866 * Emacs Lisp::      The built-in Emacs programming language.
867
868 @end detailmenu
869 @end menu
870
871 @node Starting Up
872 @chapter Starting Gnus
873 @cindex starting up
874
875 @kindex M-x gnus
876 @findex gnus
877 If your system administrator has set things up properly, starting Gnus
878 and reading news is extremely easy---you just type @kbd{M-x gnus} in
879 your Emacs.
880
881 @findex gnus-other-frame
882 @kindex M-x gnus-other-frame
883 If you want to start Gnus in a different frame, you can use the command
884 @kbd{M-x gnus-other-frame} instead.
885
886 If things do not go smoothly at startup, you have to twiddle some
887 variables in your @file{~/.gnus} file.  This file is similar to
888 @file{~/.emacs}, but is read when gnus starts.
889
890 If you puzzle at any terms used in this manual, please refer to the
891 terminology section (@pxref{Terminology}).
892
893 @menu
894 * Finding the News::    Choosing a method for getting news.
895 * The First Time::      What does Gnus do the first time you start it?
896 * The Server is Down::  How can I read my mail then?
897 * Slave Gnusae::        You can have more than one Gnus active at a time.
898 * Fetching a Group::    Starting Gnus just to read a group.
899 * New Groups::          What is Gnus supposed to do with new groups?
900 * Startup Files::       Those pesky startup files---@file{.newsrc}.
901 * Auto Save::           Recovering from a crash.
902 * The Active File::     Reading the active file over a slow line Takes Time.
903 * Changing Servers::    You may want to move from one server to another.
904 * Startup Variables::   Other variables you might change.
905 @end menu
906
907
908 @node Finding the News
909 @section Finding the News
910 @cindex finding news
911
912 @vindex gnus-select-method
913 @c @head
914 The @code{gnus-select-method} variable says where Gnus should look for
915 news.  This variable should be a list where the first element says
916 @dfn{how} and the second element says @dfn{where}.  This method is your
917 native method.  All groups not fetched with this method are
918 foreign groups.
919
920 For instance, if the @samp{news.somewhere.edu} @sc{nntp} server is where
921 you want to get your daily dosage of news from, you'd say:
922
923 @lisp
924 (setq gnus-select-method '(nntp "news.somewhere.edu"))
925 @end lisp
926
927 If you want to read directly from the local spool, say:
928
929 @lisp
930 (setq gnus-select-method '(nnspool ""))
931 @end lisp
932
933 If you can use a local spool, you probably should, as it will almost
934 certainly be much faster.
935
936 @vindex gnus-nntpserver-file
937 @cindex NNTPSERVER
938 @cindex @sc{nntp} server
939 If this variable is not set, Gnus will take a look at the
940 @code{NNTPSERVER} environment variable.  If that variable isn't set,
941 Gnus will see whether @code{gnus-nntpserver-file}
942 (@file{/etc/nntpserver} by default) has any opinions on the matter.  If
943 that fails as well, Gnus will try to use the machine running Emacs as an @sc{nntp} server.  That's a long shot, though.
944
945 @vindex gnus-nntp-server
946 If @code{gnus-nntp-server} is set, this variable will override
947 @code{gnus-select-method}.  You should therefore set
948 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
949
950 @vindex gnus-secondary-servers
951 @vindex gnus-nntp-server
952 You can also make Gnus prompt you interactively for the name of an
953 @sc{nntp} server.  If you give a non-numerical prefix to @code{gnus}
954 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
955 in the @code{gnus-secondary-servers} list (if any).  You can also just
956 type in the name of any server you feel like visiting.  (Note that this
957 will set @code{gnus-nntp-server}, which means that if you then @kbd{M-x
958 gnus} later in the same Emacs session, Gnus will contact the same
959 server.)
960
961 @findex gnus-group-browse-foreign-server
962 @kindex B (Group)
963 However, if you use one @sc{nntp} server regularly and are just
964 interested in a couple of groups from a different server, you would be
965 better served by using the @kbd{B} command in the group buffer.  It will
966 let you have a look at what groups are available, and you can subscribe
967 to any of the groups you want to.  This also makes @file{.newsrc}
968 maintenance much tidier.  @xref{Foreign Groups}.
969
970 @vindex gnus-secondary-select-methods
971 @c @head
972 A slightly different approach to foreign groups is to set the
973 @code{gnus-secondary-select-methods} variable.  The select methods
974 listed in this variable are in many ways just as native as the
975 @code{gnus-select-method} server.  They will also be queried for active
976 files during startup (if that's required), and new newsgroups that
977 appear on these servers will be subscribed (or not) just as native
978 groups are.
979
980 For instance, if you use the @code{nnmbox} backend to read your mail, you
981 would typically set this variable to
982
983 @lisp
984 (setq gnus-secondary-select-methods '((nnmbox "")))
985 @end lisp
986
987
988 @node The First Time
989 @section The First Time
990 @cindex first time usage
991
992 If no startup files exist, Gnus will try to determine what groups should
993 be subscribed by default.
994
995 @vindex gnus-default-subscribed-newsgroups
996 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
997 will subscribe you to just those groups in that list, leaving the rest
998 killed.  Your system administrator should have set this variable to
999 something useful.
1000
1001 Since she hasn't, Gnus will just subscribe you to a few arbitrarily
1002 picked groups (i.e., @samp{*.newusers}).  (@dfn{Arbitrary} is defined
1003 here as @dfn{whatever Lars thinks you should read}.)
1004
1005 You'll also be subscribed to the Gnus documentation group, which should
1006 help you with most common problems.
1007
1008 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
1009 use the normal functions for handling new groups, and not do anything
1010 special.
1011
1012
1013 @node The Server is Down
1014 @section The Server is Down
1015 @cindex server errors
1016
1017 If the default server is down, Gnus will understandably have some
1018 problems starting.  However, if you have some mail groups in addition to
1019 the news groups, you may want to start Gnus anyway.
1020
1021 Gnus, being the trusting sort of program, will ask whether to proceed
1022 without a native select method if that server can't be contacted.  This
1023 will happen whether the server doesn't actually exist (i.e., you have
1024 given the wrong address) or the server has just momentarily taken ill
1025 for some reason or other.  If you decide to continue and have no foreign
1026 groups, you'll find it difficult to actually do anything in the group
1027 buffer.  But, hey, that's your problem.  Blllrph!
1028
1029 @findex gnus-no-server
1030 @kindex M-x gnus-no-server
1031 @c @head
1032 If you know that the server is definitely down, or you just want to read
1033 your mail without bothering with the server at all, you can use the
1034 @code{gnus-no-server} command to start Gnus.  That might come in handy
1035 if you're in a hurry as well.  This command will not attempt to contact
1036 your primary server---instead, it will just activate all groups on level
1037 1 and 2.  (You should preferably keep no native groups on those two
1038 levels.)
1039
1040
1041 @node Slave Gnusae
1042 @section Slave Gnusae
1043 @cindex slave
1044
1045 You might want to run more than one Emacs with more than one Gnus at the
1046 same time.  If you are using different @file{.newsrc} files (e.g., if you
1047 are using the two different Gnusae to read from two different servers),
1048 that is no problem whatsoever.  You just do it.
1049
1050 The problem appears when you want to run two Gnusae that use the same
1051 @code{.newsrc} file.
1052
1053 To work around that problem some, we here at the Think-Tank at the Gnus
1054 Towers have come up with a new concept: @dfn{Masters} and
1055 @dfn{slaves}.  (We have applied for a patent on this concept, and have
1056 taken out a copyright on those words.  If you wish to use those words in
1057 conjunction with each other, you have to send $1 per usage instance to
1058 me.  Usage of the patent (@dfn{Master/Slave Relationships In Computer
1059 Applications}) will be much more expensive, of course.)
1060
1061 Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
1062 however you do it).  Each subsequent slave Gnusae should be started with
1063 @kbd{M-x gnus-slave}.  These slaves won't save normal @file{.newsrc}
1064 files, but instead save @dfn{slave files} that contain information only
1065 on what groups have been read in the slave session.  When a master Gnus
1066 starts, it will read (and delete) these slave files, incorporating all
1067 information from them.  (The slave files will be read in the sequence
1068 they were created, so the latest changes will have precedence.)
1069
1070 Information from the slave files has, of course, precedence over the
1071 information in the normal (i.e., master) @code{.newsrc} file.
1072
1073
1074 @node Fetching a Group
1075 @section Fetching a Group
1076 @cindex fetching a group
1077
1078 @findex gnus-fetch-group
1079 It is sometimes convenient to be able to just say ``I want to read this
1080 group and I don't care whether Gnus has been started or not''.  This is
1081 perhaps more useful for people who write code than for users, but the
1082 command @code{gnus-fetch-group} provides this functionality in any case.
1083 It takes the group name as a parameter.
1084
1085
1086 @node New Groups
1087 @section New Groups
1088 @cindex new groups
1089 @cindex subscription
1090
1091 @vindex gnus-check-new-newsgroups
1092 If you are satisfied that you really never want to see any new groups,
1093 you can set @code{gnus-check-new-newsgroups} to @code{nil}.  This will
1094 also save you some time at startup.  Even if this variable is
1095 @code{nil}, you can always subscribe to the new groups just by pressing
1096 @kbd{U} in the group buffer (@pxref{Group Maintenance}).  This variable
1097 is @code{ask-server} by default.  If you set this variable to
1098 @code{always}, then Gnus will query the backends for new groups even
1099 when you do the @kbd{g} command (@pxref{Scanning New Messages}).
1100
1101 @menu
1102 * Checking New Groups::      Determining what groups are new.
1103 * Subscription Methods::     What Gnus should do with new groups.
1104 * Filtering New Groups::     Making Gnus ignore certain new groups.
1105 @end menu
1106
1107
1108 @node Checking New Groups
1109 @subsection Checking New Groups
1110
1111 Gnus normally determines whether a group is new or not by comparing the
1112 list of groups from the active file(s) with the lists of subscribed and
1113 dead groups.  This isn't a particularly fast method.  If
1114 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
1115 server for new groups since the last time.  This is both faster and
1116 cheaper.  This also means that you can get rid of the list of killed
1117 groups altogether, so you may set @code{gnus-save-killed-list} to
1118 @code{nil}, which will save time both at startup, at exit, and all over.
1119 Saves disk space, too.  Why isn't this the default, then?
1120 Unfortunately, not all servers support this command.
1121
1122 I bet I know what you're thinking now: How do I find out whether my
1123 server supports @code{ask-server}?  No?  Good, because I don't have a
1124 fail-safe answer.  I would suggest just setting this variable to
1125 @code{ask-server} and see whether any new groups appear within the next
1126 few days.  If any do, then it works.  If none do, then it doesn't
1127 work.  I could write a function to make Gnus guess whether the server
1128 supports @code{ask-server}, but it would just be a guess.  So I won't.
1129 You could @code{telnet} to the server and say @code{HELP} and see
1130 whether it lists @samp{NEWGROUPS} among the commands it understands.  If
1131 it does, then it might work.  (But there are servers that lists
1132 @samp{NEWGROUPS} without supporting the function properly.)
1133
1134 This variable can also be a list of select methods.  If so, Gnus will
1135 issue an @code{ask-server} command to each of the select methods, and
1136 subscribe them (or not) using the normal methods.  This might be handy
1137 if you are monitoring a few servers for new groups.  A side effect is
1138 that startup will take much longer, so you can meditate while waiting.
1139 Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss.
1140
1141
1142 @node Subscription Methods
1143 @subsection Subscription Methods
1144
1145 @vindex gnus-subscribe-newsgroup-method
1146 What Gnus does when it encounters a new group is determined by the
1147 @code{gnus-subscribe-newsgroup-method} variable.
1148
1149 This variable should contain a function.  This function will be called
1150 with the name of the new group as the only parameter.
1151
1152 Some handy pre-fab functions are:
1153
1154 @table @code
1155
1156 @item gnus-subscribe-zombies
1157 @vindex gnus-subscribe-zombies
1158 Make all new groups zombies.  This is the default.  You can browse the
1159 zombies later (with @kbd{A z}) and either kill them all off properly
1160 (with @kbd{S z}), or subscribe to them (with @kbd{u}).
1161
1162 @item gnus-subscribe-randomly
1163 @vindex gnus-subscribe-randomly
1164 Subscribe all new groups in arbitrary order.  This really means that all
1165 new groups will be added at ``the top'' of the group buffer.
1166
1167 @item gnus-subscribe-alphabetically
1168 @vindex gnus-subscribe-alphabetically
1169 Subscribe all new groups in alphabetical order.
1170
1171 @item gnus-subscribe-hierarchically
1172 @vindex gnus-subscribe-hierarchically
1173 Subscribe all new groups hierarchically.  The difference between this
1174 function and @code{gnus-subscribe-alphabetically} is slight.
1175 @code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly
1176 alphabetical fashion, while this function will enter groups into its
1177 hierarchy.  So if you want to have the @samp{rec} hierarchy before the
1178 @samp{comp} hierarchy, this function will not mess that configuration
1179 up.  Or something like that.
1180
1181 @item gnus-subscribe-interactively
1182 @vindex gnus-subscribe-interactively
1183 Subscribe new groups interactively.  This means that Gnus will ask
1184 you about @strong{all} new groups.  The groups you choose to subscribe
1185 to will be subscribed hierarchically.
1186
1187 @item gnus-subscribe-killed
1188 @vindex gnus-subscribe-killed
1189 Kill all new groups.
1190
1191 @item gnus-subscribe-topics
1192 @vindex gnus-subscribe-topics
1193 Put the groups into the topic that has a matching @code{subscribe} topic 
1194 parameter (@pxref{Topic Parameters}).  For instance, a @code{subscribe}
1195 topic parameter that looks like
1196
1197 @example
1198 "nnslashdot"
1199 @end example
1200
1201 will mean that all groups that match that regex will be subscribed under 
1202 that topic.
1203
1204 If no topics match the groups, the groups will be subscribed in the
1205 top-level topic.
1206
1207 @end table
1208
1209 @vindex gnus-subscribe-hierarchical-interactive
1210 A closely related variable is
1211 @code{gnus-subscribe-hierarchical-interactive}.  (That's quite a
1212 mouthful.)  If this variable is non-@code{nil}, Gnus will ask you in a
1213 hierarchical fashion whether to subscribe to new groups or not.  Gnus
1214 will ask you for each sub-hierarchy whether you want to descend the
1215 hierarchy or not.
1216
1217 One common mistake is to set the variable a few paragraphs above
1218 (@code{gnus-subscribe-newsgroup-method}) to
1219 @code{gnus-subscribe-hierarchical-interactive}.  This is an error.  This
1220 will not work.  This is ga-ga.  So don't do it.
1221
1222
1223 @node Filtering New Groups
1224 @subsection Filtering New Groups
1225
1226 A nice and portable way to control which new newsgroups should be
1227 subscribed (or ignored) is to put an @dfn{options} line at the start of
1228 the @file{.newsrc} file.  Here's an example:
1229
1230 @example
1231 options -n !alt.all !rec.all sci.all
1232 @end example
1233
1234 @vindex gnus-subscribe-options-newsgroup-method
1235 This line obviously belongs to a serious-minded intellectual scientific
1236 person (or she may just be plain old boring), because it says that all
1237 groups that have names beginning with @samp{alt} and @samp{rec} should
1238 be ignored, and all groups with names beginning with @samp{sci} should
1239 be subscribed.  Gnus will not use the normal subscription method for
1240 subscribing these groups.
1241 @code{gnus-subscribe-options-newsgroup-method} is used instead.  This
1242 variable defaults to @code{gnus-subscribe-alphabetically}.
1243
1244 @vindex gnus-options-not-subscribe
1245 @vindex gnus-options-subscribe
1246 If you don't want to mess with your @file{.newsrc} file, you can just
1247 set the two variables @code{gnus-options-subscribe} and
1248 @code{gnus-options-not-subscribe}.  These two variables do exactly the
1249 same as the @file{.newsrc} @samp{options -n} trick.  Both are regexps,
1250 and if the new group matches the former, it will be unconditionally
1251 subscribed, and if it matches the latter, it will be ignored.
1252
1253 @vindex gnus-auto-subscribed-groups
1254 Yet another variable that meddles here is
1255 @code{gnus-auto-subscribed-groups}.  It works exactly like
1256 @code{gnus-options-subscribe}, and is therefore really superfluous, but I
1257 thought it would be nice to have two of these.  This variable is more
1258 meant for setting some ground rules, while the other variable is used
1259 more for user fiddling.  By default this variable makes all new groups
1260 that come from mail backends (@code{nnml}, @code{nnbabyl},
1261 @code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed.  If you
1262 don't like that, just set this variable to @code{nil}.
1263
1264 New groups that match this regexp are subscribed using
1265 @code{gnus-subscribe-options-newsgroup-method}.
1266
1267
1268 @node Changing Servers
1269 @section Changing Servers
1270 @cindex changing servers
1271
1272 Sometimes it is necessary to move from one @sc{nntp} server to another.
1273 This happens very rarely, but perhaps you change jobs, or one server is
1274 very flaky and you want to use another.
1275
1276 Changing the server is pretty easy, right?  You just change
1277 @code{gnus-select-method} to point to the new server?
1278
1279 @emph{Wrong!}
1280
1281 Article numbers are not (in any way) kept synchronized between different
1282 @sc{nntp} servers, and the only way Gnus keeps track of what articles
1283 you have read is by keeping track of article numbers.  So when you
1284 change @code{gnus-select-method}, your @file{.newsrc} file becomes
1285 worthless.
1286
1287 Gnus provides a few functions to attempt to translate a @file{.newsrc}
1288 file from one server to another.  They all have one thing in
1289 common---they take a looong time to run.  You don't want to use these
1290 functions more than absolutely necessary.
1291
1292 @kindex M-x gnus-change-server
1293 @findex gnus-change-server
1294 If you have access to both servers, Gnus can request the headers for all
1295 the articles you have read and compare @code{Message-ID}s and map the
1296 article numbers of the read articles and article marks.  The @kbd{M-x
1297 gnus-change-server} command will do this for all your native groups.  It
1298 will prompt for the method you want to move to.
1299
1300 @kindex M-x gnus-group-move-group-to-server
1301 @findex gnus-group-move-group-to-server
1302 You can also move individual groups with the @kbd{M-x
1303 gnus-group-move-group-to-server} command.  This is useful if you want to
1304 move a (foreign) group from one server to another.
1305
1306 @kindex M-x gnus-group-clear-data-on-native-groups
1307 @findex gnus-group-clear-data-on-native-groups
1308 If you don't have access to both the old and new server, all your marks
1309 and read ranges have become worthless.  You can use the @kbd{M-x
1310 gnus-group-clear-data-on-native-groups} command to clear out all data
1311 that you have on your native groups.  Use with caution.
1312
1313 After changing servers, you @strong{must} move the cache hierarchy away,
1314 since the cached articles will have wrong article numbers, which will
1315 affect which articles Gnus thinks are read.
1316
1317
1318 @node Startup Files
1319 @section Startup Files
1320 @cindex startup files
1321 @cindex .newsrc
1322 @cindex .newsrc.el
1323 @cindex .newsrc.eld
1324
1325 Now, you all know about the @file{.newsrc} file.  All subscription
1326 information is traditionally stored in this file.
1327
1328 Things got a bit more complicated with @sc{gnus}.  In addition to
1329 keeping the @file{.newsrc} file updated, it also used a file called
1330 @file{.newsrc.el} for storing all the information that didn't fit into
1331 the @file{.newsrc} file.  (Actually, it also duplicated everything in
1332 the @file{.newsrc} file.)  @sc{gnus} would read whichever one of these
1333 files was the most recently saved, which enabled people to swap between
1334 @sc{gnus} and other newsreaders.
1335
1336 That was kinda silly, so Gnus went one better: In addition to the
1337 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
1338 @file{.newsrc.eld}.  It will read whichever of these files that are most
1339 recent, but it will never write a @file{.newsrc.el} file.  You should
1340 never delete the @file{.newsrc.eld} file---it contains much information
1341 not stored in the @file{.newsrc} file.
1342
1343 @vindex gnus-save-newsrc-file
1344 @vindex gnus-read-newsrc-file
1345 You can turn off writing the @file{.newsrc} file by setting
1346 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
1347 the file and save some space, as well as exiting from Gnus faster.
1348 However, this will make it impossible to use other newsreaders than
1349 Gnus.  But hey, who would want to, right?  Similarly, setting
1350 @code{gnus-read-newsrc-file} to @code{nil} makes Gnus ignore the
1351 @file{.newsrc} file and any @file{.newsrc-SERVER} files, which is
1352 convenient if you have a tendency to use Netscape once in a while.
1353
1354 @vindex gnus-save-killed-list
1355 If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus
1356 will not save the list of killed groups to the startup file.  This will
1357 save both time (when starting and quitting) and space (on disk).  It
1358 will also mean that Gnus has no record of what groups are new or old,
1359 so the automatic new groups subscription methods become meaningless.
1360 You should always set @code{gnus-check-new-newsgroups} to @code{nil} or
1361 @code{ask-server} if you set this variable to @code{nil} (@pxref{New
1362 Groups}).  This variable can also be a regular expression.  If that's
1363 the case, remove all groups that do not match this regexp before
1364 saving.  This can be useful in certain obscure situations that involve
1365 several servers where not all servers support @code{ask-server}.
1366
1367 @vindex gnus-startup-file
1368 The @code{gnus-startup-file} variable says where the startup files are.
1369 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
1370 file being whatever that one is, with a @samp{.eld} appended.
1371
1372 @vindex gnus-save-newsrc-hook
1373 @vindex gnus-save-quick-newsrc-hook
1374 @vindex gnus-save-standard-newsrc-hook
1375 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
1376 files, while @code{gnus-save-quick-newsrc-hook} is called just before
1377 saving the @file{.newsrc.eld} file, and
1378 @code{gnus-save-standard-newsrc-hook} is called just before saving the
1379 @file{.newsrc} file.  The latter two are commonly used to turn version
1380 control on or off.  Version control is on by default when saving the
1381 startup files.  If you want to turn backup creation off, say something like:
1382
1383 @lisp
1384 (defun turn-off-backup ()
1385   (set (make-local-variable 'backup-inhibited) t))
1386
1387 (add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup)
1388 (add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup)
1389 @end lisp
1390
1391 @vindex gnus-init-file
1392 When Gnus starts, it will read the @code{gnus-site-init-file}
1393 (@file{.../site-lisp/gnus} by default) and @code{gnus-init-file}
1394 (@file{~/.gnus} by default) files.  These are normal Emacs Lisp files
1395 and can be used to avoid cluttering your @file{~/.emacs} and
1396 @file{site-init} files with Gnus stuff.  Gnus will also check for files
1397 with the same names as these, but with @file{.elc} and @file{.el}
1398 suffixes.  In other words, if you have set @code{gnus-init-file} to
1399 @file{~/.gnus}, it will look for @file{~/.gnus.elc}, @file{~/.gnus.el},
1400 and finally @file{~/.gnus} (in this order).
1401
1402
1403
1404 @node Auto Save
1405 @section Auto Save
1406 @cindex dribble file
1407 @cindex auto-save
1408
1409 Whenever you do something that changes the Gnus data (reading articles,
1410 catching up, killing/subscribing groups), the change is added to a
1411 special @dfn{dribble buffer}.  This buffer is auto-saved the normal
1412 Emacs way.  If your Emacs should crash before you have saved the
1413 @file{.newsrc} files, all changes you have made can be recovered from
1414 this file.
1415
1416 If Gnus detects this file at startup, it will ask the user whether to
1417 read it.  The auto save file is deleted whenever the real startup file is
1418 saved.
1419
1420 @vindex gnus-use-dribble-file
1421 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
1422 maintain a dribble buffer.  The default is @code{t}.
1423
1424 @vindex gnus-dribble-directory
1425 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}.  If
1426 this variable is @code{nil}, which it is by default, Gnus will dribble
1427 into the directory where the @file{.newsrc} file is located.  (This is
1428 normally the user's home directory.)  The dribble file will get the same
1429 file permissions as the @code{.newsrc} file.
1430
1431 @vindex gnus-always-read-dribble-file
1432 If @code{gnus-always-read-dribble-file} is non-@code{nil}, Gnus will
1433 read the dribble file on startup without querying the user.
1434
1435
1436 @node The Active File
1437 @section The Active File
1438 @cindex active file
1439 @cindex ignored groups
1440
1441 When Gnus starts, or indeed whenever it tries to determine whether new
1442 articles have arrived, it reads the active file.  This is a very large
1443 file that lists all the active groups and articles on the server.
1444
1445 @vindex gnus-ignored-newsgroups
1446 Before examining the active file, Gnus deletes all lines that match the
1447 regexp @code{gnus-ignored-newsgroups}.  This is done primarily to reject
1448 any groups with bogus names, but you can use this variable to make Gnus
1449 ignore hierarchies you aren't ever interested in.  However, this is not
1450 recommended.  In fact, it's highly discouraged.  Instead, @pxref{New
1451 Groups} for an overview of other variables that can be used instead.
1452
1453 @c This variable is
1454 @c @code{nil} by default, and will slow down active file handling somewhat
1455 @c if you set it to anything else.
1456
1457 @vindex gnus-read-active-file
1458 @c @head
1459 The active file can be rather Huge, so if you have a slow network, you
1460 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
1461 reading the active file.  This variable is @code{some} by default.
1462
1463 Gnus will try to make do by getting information just on the groups that
1464 you actually subscribe to.
1465
1466 Note that if you subscribe to lots and lots of groups, setting this
1467 variable to @code{nil} will probably make Gnus slower, not faster.  At
1468 present, having this variable @code{nil} will slow Gnus down
1469 considerably, unless you read news over a 2400 baud modem.
1470
1471 This variable can also have the value @code{some}.  Gnus will then
1472 attempt to read active info only on the subscribed groups.  On some
1473 servers this is quite fast (on sparkling, brand new INN servers that
1474 support the @code{LIST ACTIVE group} command), on others this isn't fast
1475 at all.  In any case, @code{some} should be faster than @code{nil}, and
1476 is certainly faster than @code{t} over slow lines.
1477
1478 Some news servers (Leafnode and old versions of INN, for instance) do
1479 not support the @code{LIST ACTIVE group}.  For these servers, @code{nil}
1480 is probably the most efficient value for this variable.
1481
1482 If this variable is @code{nil}, Gnus will ask for group info in total
1483 lock-step, which isn't very fast.  If it is @code{some} and you use an
1484 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
1485 read all the replies in one swoop.  This will normally result in better
1486 performance, but if the server does not support the aforementioned
1487 @code{LIST ACTIVE group} command, this isn't very nice to the server.
1488
1489 If you think that starting up Gnus takes too long, try all the three
1490 different values for this variable and see what works best for you. 
1491
1492 In any case, if you use @code{some} or @code{nil}, you should definitely
1493 kill all groups that you aren't interested in to speed things up.
1494
1495 Note that this variable also affects active file retrieval from
1496 secondary select methods.
1497
1498
1499 @node Startup Variables
1500 @section Startup Variables
1501
1502 @table @code
1503
1504 @item gnus-load-hook
1505 @vindex gnus-load-hook
1506 A hook run while Gnus is being loaded.  Note that this hook will
1507 normally be run just once in each Emacs session, no matter how many
1508 times you start Gnus.
1509
1510 @item gnus-before-startup-hook
1511 @vindex gnus-before-startup-hook
1512 A hook run after starting up Gnus successfully.
1513
1514 @item gnus-startup-hook
1515 @vindex gnus-startup-hook
1516 A hook run as the very last thing after starting up Gnus
1517
1518 @item gnus-started-hook
1519 @vindex gnus-started-hook
1520 A hook that is run as the very last thing after starting up Gnus
1521 successfully.
1522
1523 @item gnus-setup-news-hook
1524 @vindex gnus-setup-news-hook
1525 A hook that is run after reading the @file{.newsrc} file(s), but before
1526 generating the group buffer.
1527
1528 @item gnus-check-bogus-newsgroups
1529 @vindex gnus-check-bogus-newsgroups
1530 If non-@code{nil}, Gnus will check for and delete all bogus groups at
1531 startup.  A @dfn{bogus group} is a group that you have in your
1532 @file{.newsrc} file, but doesn't exist on the news server.  Checking for
1533 bogus groups can take quite a while, so to save time and resources it's
1534 best to leave this option off, and do the checking for bogus groups once
1535 in a while from the group buffer instead (@pxref{Group Maintenance}).
1536
1537 @item gnus-inhibit-startup-message
1538 @vindex gnus-inhibit-startup-message
1539 If non-@code{nil}, the startup message won't be displayed.  That way,
1540 your boss might not notice as easily that you are reading news instead
1541 of doing your job.  Note that this variable is used before
1542 @file{.gnus.el} is loaded, so it should be set in @code{.emacs} instead.
1543
1544 @item gnus-no-groups-message
1545 @vindex gnus-no-groups-message
1546 Message displayed by Gnus when no groups are available.
1547
1548 @item gnus-play-startup-jingle
1549 @vindex gnus-play-startup-jingle
1550 If non-@code{nil}, play the Gnus jingle at startup.
1551
1552 @item gnus-startup-jingle
1553 @vindex gnus-startup-jingle
1554 Jingle to be played if the above variable is non-@code{nil}.  The
1555 default is @samp{Tuxedomoon.Jingle4.au}.
1556
1557 @end table
1558
1559
1560 @node The Group Buffer
1561 @chapter The Group Buffer
1562 @cindex group buffer
1563
1564 The @dfn{group buffer} lists all (or parts) of the available groups.  It
1565 is the first buffer shown when Gnus starts, and will never be killed as
1566 long as Gnus is active.
1567
1568 @iftex
1569 @iflatex
1570 \gnusfigure{The Group Buffer}{320}{
1571 \put(75,50){\epsfig{figure=tmp/group.ps,height=9cm}}
1572 \put(120,37){\makebox(0,0)[t]{Buffer name}}
1573 \put(120,38){\vector(1,2){10}}
1574 \put(40,60){\makebox(0,0)[r]{Mode line}}
1575 \put(40,58){\vector(1,0){30}}
1576 \put(200,28){\makebox(0,0)[t]{Native select method}}
1577 \put(200,26){\vector(-1,2){15}}
1578 }
1579 @end iflatex
1580 @end iftex
1581
1582 @menu
1583 * Group Buffer Format::    Information listed and how you can change it.
1584 * Group Maneuvering::      Commands for moving in the group buffer.
1585 * Selecting a Group::      Actually reading news.
1586 * Group Data::             Changing the info for a group.
1587 * Subscription Commands::  Unsubscribing, killing, subscribing.
1588 * Group Levels::           Levels? What are those, then?
1589 * Group Score::            A mechanism for finding out what groups you like.
1590 * Marking Groups::         You can mark groups for later processing.
1591 * Foreign Groups::         Creating and editing groups.
1592 * Group Parameters::       Each group may have different parameters set.
1593 * Listing Groups::         Gnus can list various subsets of the groups.
1594 * Sorting Groups::         Re-arrange the group order.
1595 * Group Maintenance::      Maintaining a tidy @file{.newsrc} file.
1596 * Browse Foreign Server::  You can browse a server.  See what it has to offer.
1597 * Exiting Gnus::           Stop reading news and get some work done.
1598 * Group Topics::           A folding group mode divided into topics.
1599 * Misc Group Stuff::       Other stuff that you can to do.
1600 @end menu
1601
1602
1603 @node Group Buffer Format
1604 @section Group Buffer Format
1605
1606 @menu
1607 * Group Line Specification::       Deciding how the group buffer is to look.
1608 * Group Modeline Specification::   The group buffer modeline.
1609 * Group Highlighting::             Having nice colors in the group buffer.
1610 @end menu
1611
1612
1613 @node Group Line Specification
1614 @subsection Group Line Specification
1615 @cindex group buffer format
1616
1617 The default format of the group buffer is nice and dull, but you can
1618 make it as exciting and ugly as you feel like.
1619
1620 Here's a couple of example group lines:
1621
1622 @example
1623      25: news.announce.newusers
1624  *    0: alt.fan.andrea-dworkin
1625 @end example
1626
1627 Quite simple, huh?
1628
1629 You can see that there are 25 unread articles in
1630 @samp{news.announce.newusers}.  There are no unread articles, but some
1631 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1632 asterisk at the beginning of the line?).
1633
1634 @vindex gnus-group-line-format
1635 You can change that format to whatever you want by fiddling with the
1636 @code{gnus-group-line-format} variable.  This variable works along the
1637 lines of a @code{format} specification, which is pretty much the same as
1638 a @code{printf} specifications, for those of you who use (feh!) C.
1639 @xref{Formatting Variables}.
1640
1641 @samp{%M%S%5y: %(%g%)\n} is the value that produced those lines above.
1642
1643 There should always be a colon on the line; the cursor always moves to
1644 the colon after performing an operation.  Nothing else is required---not
1645 even the group name.  All displayed text is just window dressing, and is
1646 never examined by Gnus.  Gnus stores all real information it needs using
1647 text properties.
1648
1649 (Note that if you make a really strange, wonderful, spreadsheet-like
1650 layout, everybody will believe you are hard at work with the accounting
1651 instead of wasting time reading news.)
1652
1653 Here's a list of all available format characters:
1654
1655 @table @samp
1656
1657 @item M
1658 An asterisk if the group only has marked articles.
1659
1660 @item S
1661 Whether the group is subscribed.
1662
1663 @item L
1664 Level of subscribedness.
1665
1666 @item N
1667 Number of unread articles.
1668
1669 @item I
1670 Number of dormant articles.
1671
1672 @item T
1673 Number of ticked articles.