Release commit
[gnus] / texi / gnus.texi
1 \input texinfo
2
3 @setfilename gnus
4 @settitle Gnus Manual
5 @synindex fn cp
6 @synindex vr cp
7 @synindex pg cp
8 @dircategory Emacs
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{pixidx}
24 \input{gnusconfig.tex}
25
26 \ifx\pdfoutput\undefined
27 \else
28 \usepackage[pdftex,bookmarks,colorlinks=true]{hyperref}
29 \usepackage{thumbpdf}
30 \pdfcompresslevel=9
31 \fi
32
33 \makeindex
34 \begin{document}
35
36 \newcommand{\gnusversionname}{Oort Gnus v0.12}
37 \newcommand{\gnuschaptername}{}
38 \newcommand{\gnussectionname}{}
39
40 \newcommand{\gnusbackslash}{/}
41
42 \newcommand{\gnusref}[1]{``#1'' on page \pageref{#1}}
43 \ifx\pdfoutput\undefined
44 \newcommand{\gnusuref}[1]{\gnustt{#1}}
45 \else
46 \newcommand{\gnusuref}[1]{\href{#1}{\gnustt{#1}}}
47 \fi
48 \newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}}
49 \newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}}
50
51 \newcommand{\gnuskindex}[1]{\index{#1}}
52 \newcommand{\gnusindex}[1]{\index{#1}}
53
54 \newcommand{\gnustt}[1]{{\gnusselectttfont{}#1}}
55 \newcommand{\gnuscode}[1]{\gnustt{#1}}
56 \newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\gnusselectttfont{}#1}''}
57 \newcommand{\gnuslisp}[1]{\gnustt{#1}}
58 \newcommand{\gnuskbd}[1]{`\gnustt{#1}'}
59 \newcommand{\gnuskey}[1]{`\gnustt{#1}'}
60 \newcommand{\gnusfile}[1]{`\gnustt{#1}'}
61 \newcommand{\gnusdfn}[1]{\textit{#1}}
62 \newcommand{\gnusi}[1]{\textit{#1}}
63 \newcommand{\gnusstrong}[1]{\textbf{#1}}
64 \newcommand{\gnusemph}[1]{\textit{#1}}
65 \newcommand{\gnusvar}[1]{{\fontsize{10pt}{10}\selectfont\textsl{\textsf{#1}}}}
66 \newcommand{\gnussc}[1]{\textsc{#1}}
67 \newcommand{\gnustitle}[1]{{\huge\textbf{#1}}}
68 \newcommand{\gnusversion}[1]{{\small\textit{#1}}}
69 \newcommand{\gnusauthor}[1]{{\large\textbf{#1}}}
70 \newcommand{\gnusresult}[1]{\gnustt{=> #1}}
71
72 \newcommand{\gnusbullet}{{${\bullet}$}}
73 \newcommand{\gnusdollar}{\$}
74 \newcommand{\gnusampersand}{\&}
75 \newcommand{\gnuspercent}{\%}
76 \newcommand{\gnushash}{\#}
77 \newcommand{\gnushat}{\symbol{"5E}}
78 \newcommand{\gnusunderline}{\symbol{"5F}}
79 \newcommand{\gnusnot}{$\neg$}
80 \newcommand{\gnustilde}{\symbol{"7E}}
81 \newcommand{\gnusless}{{$<$}}
82 \newcommand{\gnusgreater}{{$>$}}
83 \newcommand{\gnusbraceleft}{{$>$}}
84 \newcommand{\gnusbraceright}{{$>$}}
85
86 \newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=ps/gnus-head,height=1cm}}}
87 \newcommand{\gnusinteresting}{
88 \marginpar[\mbox{}\hfill\gnushead]{\gnushead}
89 }
90
91 \newcommand{\gnuscleardoublepage}{\ifodd\count0\mbox{}\clearpage\thispagestyle{empty}\mbox{}\clearpage\else\clearpage\fi}
92
93 \newcommand{\gnuspagechapter}[1]{
94 {\mbox{}}
95 }
96
97 \newdimen{\gnusdimen}
98 \gnusdimen 0pt
99
100 \newcommand{\gnuschapter}[2]{
101 \gnuscleardoublepage
102 \ifdim \gnusdimen = 0pt\setcounter{page}{1}\pagestyle{gnus}\pagenumbering{arabic} \gnusdimen 1pt\fi
103 \chapter{#2}
104 \renewcommand{\gnussectionname}{}
105 \renewcommand{\gnuschaptername}{#2}
106 \thispagestyle{empty}
107 \hspace*{-2cm}
108 \begin{picture}(500,500)(0,0)
109 \put(480,350){\makebox(0,0)[tr]{#1}}
110 \put(40,300){\makebox(500,50)[bl]{{\Huge\bf{#2}}}}
111 \end{picture}
112 \clearpage
113 }
114
115 \newcommand{\gnusfigure}[3]{
116 \begin{figure}
117 \mbox{}\ifodd\count0\hspace*{-0.8cm}\else\hspace*{-3cm}\fi\begin{picture}(440,#2)
118 #3
119 \end{picture}
120 \caption{#1}
121 \end{figure}
122 }
123
124 \newcommand{\gnusicon}[1]{
125 \marginpar[\mbox{}\hfill\raisebox{-1.5cm}{\epsfig{figure=ps/#1-up,height=1.5cm}}]{\raisebox{-1cm}{\epsfig{figure=ps/#1-up,height=1cm}}}
126 }
127
128 \newcommand{\gnuspicon}[1]{
129 \margindex{\epsfig{figure=#1,width=2cm}}
130 }
131
132 \newcommand{\gnusxface}[2]{
133 \margindex{\epsfig{figure=#1,width=1cm}\epsfig{figure=#2,width=1cm}}
134 }
135
136 \newcommand{\gnussmiley}[2]{
137 \margindex{\makebox[2cm]{\hfill\epsfig{figure=#1,width=0.5cm}\hfill\epsfig{figure=#2,width=0.5cm}\hfill}}
138 }
139
140 \newcommand{\gnusitemx}[1]{\mbox{}\vspace*{-\itemsep}\vspace*{-\parsep}\item#1}
141
142 \newcommand{\gnussection}[1]{
143 \renewcommand{\gnussectionname}{#1}
144 \section{#1}
145 }
146
147 \newenvironment{codelist}%
148 {\begin{list}{}{
149 }
150 }{\end{list}}
151
152 \newenvironment{kbdlist}%
153 {\begin{list}{}{
154 \labelwidth=0cm
155 }
156 }{\end{list}}
157
158 \newenvironment{dfnlist}%
159 {\begin{list}{}{
160 }
161 }{\end{list}}
162
163 \newenvironment{stronglist}%
164 {\begin{list}{}{
165 }
166 }{\end{list}}
167
168 \newenvironment{samplist}%
169 {\begin{list}{}{
170 }
171 }{\end{list}}
172
173 \newenvironment{varlist}%
174 {\begin{list}{}{
175 }
176 }{\end{list}}
177
178 \newenvironment{emphlist}%
179 {\begin{list}{}{
180 }
181 }{\end{list}}
182
183 \newlength\gnusheadtextwidth
184 \setlength{\gnusheadtextwidth}{\headtextwidth}
185 \addtolength{\gnusheadtextwidth}{1cm}
186
187 \newpagestyle{gnuspreamble}%
188 {
189 {
190 \ifodd\count0
191 {
192 \hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\mbox{}}\textbf{\hfill\roman{page}}}
193 }
194 \else
195 {
196 \hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\roman{page}\hfill\mbox{}}}
197 }
198 }
199 \fi
200 }
201 }
202 {
203 \ifodd\count0
204 \mbox{} \hfill
205 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
206 \else
207 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
208 \hfill \mbox{}
209 \fi
210 }
211
212 \newpagestyle{gnusindex}%
213 {
214 {
215 \ifodd\count0
216 {
217 \hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\gnuschaptername\hfill\arabic{page}}}}
218 }
219 \else
220 {
221 \hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}
222 }
223 \fi
224 }
225 }
226 {
227 \ifodd\count0
228 \mbox{} \hfill
229 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
230 \else
231 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
232 \hfill \mbox{}
233 \fi
234 }
235
236 \newpagestyle{gnus}%
237 {
238 {
239 \ifodd\count0
240 {
241 \makebox[12cm]{\hspace*{3.1cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{chapter}.\arabic{section}} \textbf{\gnussectionname\hfill\arabic{page}}}}}
242 }
243 \else
244 {
245 \makebox[12cm]{\hspace*{-2.95cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}}
246 }
247 \fi
248 }
249 }
250 {
251 \ifodd\count0
252 \mbox{} \hfill
253 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
254 \else
255 \raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
256 \hfill \mbox{}
257 \fi
258 }
259
260 \pagenumbering{roman}
261 \pagestyle{gnuspreamble}
262
263 @end iflatex
264 @end iftex
265
266 @iftex
267 @iflatex
268 \begin{titlepage}
269 {
270
271 %\addtolength{\oddsidemargin}{-5cm}
272 %\addtolength{\evensidemargin}{-5cm}
273 \parindent=0cm
274 \addtolength{\textheight}{2cm}
275
276 \gnustitle{\gnustitlename}\hfill\gnusversion{\gnusversionname}\\
277 \rule{15cm}{1mm}\\
278 \vfill
279 \hspace*{0cm}\epsfig{figure=ps/gnus-big-logo,height=15cm}
280 \vfill
281 \rule{15cm}{1mm}\\
282 \gnusauthor{by Lars Magne Ingebrigtsen}
283 \newpage
284 }
285
286 \mbox{}
287 \vfill
288
289 \thispagestyle{empty}
290
291 Copyright \copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001,
292 2002, 2003
293 Free Software Foundation, Inc.
294
295
296 Permission is granted to copy, distribute and/or modify this document
297 under the terms of the GNU Free Documentation License, Version 1.1 or
298 any later version published by the Free Software Foundation; with no
299 Invariant Sections, with the Front-Cover texts being ``A GNU
300 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
301 license is included in the section entitled ``GNU Free Documentation
302 License'' in the Emacs manual.
303
304 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
305 this GNU Manual, like GNU software.  Copies published by the Free
306 Software Foundation raise funds for GNU development.''
307
308 This document is part of a collection distributed under the GNU Free
309 Documentation License.  If you want to distribute this document
310 separately from the collection, you can do so by adding a copy of the
311 license to the document, as described in section 6 of the license.
312 \newpage
313 \end{titlepage}
314 @end iflatex
315 @end iftex
316
317 @ifnottex
318
319 This file documents Gnus, the GNU Emacs newsreader.
320
321 Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003
322         Free Software Foundation, Inc.
323
324 Permission is granted to copy, distribute and/or modify this document
325 under the terms of the GNU Free Documentation License, Version 1.1 or
326 any later version published by the Free Software Foundation; with the
327 Invariant Sections being none, with the Front-Cover texts being ``A GNU
328 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
329 license is included in the section entitled ``GNU Free Documentation
330 License'' in the Emacs manual.
331
332 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
333 this GNU Manual, like GNU software.  Copies published by the Free
334 Software Foundation raise funds for GNU development.''
335
336 This document is part of a collection distributed under the GNU Free
337 Documentation License.  If you want to distribute this document
338 separately from the collection, you can do so by adding a copy of the
339 license to the document, as described in section 6 of the license.
340 @end ifnottex
341
342 @tex
343
344 @titlepage
345 @title Gnus Manual
346
347 @author by Lars Magne Ingebrigtsen
348 @page
349
350 @vskip 0pt plus 1filll
351 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001,
352 2002, 2003
353         Free Software Foundation, Inc.
354
355 Permission is granted to copy, distribute and/or modify this document
356 under the terms of the GNU Free Documentation License, Version 1.1 or
357 any later version published by the Free Software Foundation; with no
358 Invariant Sections, with the Front-Cover texts being ``A GNU
359 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
360 license is included in the section entitled ``GNU Free Documentation
361 License'' in the Emacs manual.
362
363 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
364 this GNU Manual, like GNU software.  Copies published by the Free
365 Software Foundation raise funds for GNU development.''
366
367 This document is part of a collection distributed under the GNU Free
368 Documentation License.  If you want to distribute this document
369 separately from the collection, you can do so by adding a copy of the
370 license to the document, as described in section 6 of the license.
371
372 @end titlepage
373 @page
374
375 @end tex
376
377
378 @node Top
379 @top The Gnus Newsreader
380
381 @ifinfo
382
383 You can read news (and mail) from within Emacs by using Gnus.  The news
384 can be gotten by any nefarious means you can think of---@sc{nntp}, local
385 spool or your mbox file.  All at the same time, if you want to push your
386 luck.
387
388 This manual corresponds to Oort Gnus v0.12.
389
390 @end ifinfo
391
392 @iftex
393
394 @iflatex
395 \tableofcontents
396 \gnuscleardoublepage
397 @end iflatex
398
399 Gnus is the advanced, self-documenting, customizable, extensible
400 unreal-time newsreader for GNU Emacs.
401
402 Oops.  That sounds oddly familiar, so let's start over again to avoid
403 being accused of plagiarism:
404
405 Gnus is a message-reading laboratory.  It will let you look at just
406 about anything as if it were a newsgroup.  You can read mail with it,
407 you can browse directories with it, you can @code{ftp} with it---you
408 can even read news with it!
409
410 Gnus tries to empower people who read news the same way Emacs empowers
411 people who edit text.  Gnus sets no limits to what the user should be
412 allowed to do.  Users are encouraged to extend Gnus to make it behave
413 like they want it to behave.  A program should not control people;
414 people should be empowered to do what they want by using (or abusing)
415 the program.
416
417 @end iftex
418
419 @menu
420 * Starting Up::                 Finding news can be a pain.
421 * Group Buffer::                Selecting, subscribing and killing groups.
422 * Summary Buffer::              Reading, saving and posting articles.
423 * Article Buffer::              Displaying and handling articles.
424 * Composing Messages::          Information on sending mail and news.
425 * Select Methods::              Gnus reads all messages from various select methods.
426 * Scoring::                     Assigning values to articles.
427 * Various::                     General purpose settings.
428 * The End::                     Farewell and goodbye.
429 * Appendices::                  Terminology, Emacs intro, FAQ, History, Internals.
430 * Index::                       Variable, function and concept index.
431 * Key Index::                   Key Index.
432
433 Other related manuals
434
435 * Message:(message).            Composing messages.
436 * Emacs-MIME:(emacs-mime).      Composing messages; MIME-specific parts.
437 * Sieve:(sieve).                Managing Sieve scripts in Emacs.
438 * PGG:(pgg).                    PGP/MIME with Gnus.
439
440 @detailmenu
441  --- The Detailed Node Listing ---
442
443 Starting Gnus
444
445 * Finding the News::            Choosing a method for getting news.
446 * The First Time::              What does Gnus do the first time you start it?
447 * The Server is Down::          How can I read my mail then?
448 * Slave Gnusae::                You can have more than one Gnus active at a time.
449 * Fetching a Group::            Starting Gnus just to read a group.
450 * New Groups::                  What is Gnus supposed to do with new groups?
451 * Changing Servers::            You may want to move from one server to another.
452 * Startup Files::               Those pesky startup files---@file{.newsrc}.
453 * Auto Save::                   Recovering from a crash.
454 * The Active File::             Reading the active file over a slow line Takes Time.
455 * Startup Variables::           Other variables you might change.
456
457 New Groups
458
459 * Checking New Groups::         Determining what groups are new.
460 * Subscription Methods::        What Gnus should do with new groups.
461 * Filtering New Groups::        Making Gnus ignore certain new groups.
462
463 Group Buffer
464
465 * Group Buffer Format::         Information listed and how you can change it.
466 * Group Maneuvering::           Commands for moving in the group buffer.
467 * Selecting a Group::           Actually reading news.
468 * Subscription Commands::       Unsubscribing, killing, subscribing.
469 * Group Data::                  Changing the info for a group.
470 * Group Levels::                Levels? What are those, then?
471 * Group Score::                 A mechanism for finding out what groups you like.
472 * Marking Groups::              You can mark groups for later processing.
473 * Foreign Groups::              Creating and editing groups.
474 * Group Parameters::            Each group may have different parameters set.
475 * Listing Groups::              Gnus can list various subsets of the groups.
476 * Sorting Groups::              Re-arrange the group order.
477 * Group Maintenance::           Maintaining a tidy @file{.newsrc} file.
478 * Browse Foreign Server::       You can browse a server.  See what it has to offer.
479 * Exiting Gnus::                Stop reading news and get some work done.
480 * Group Topics::                A folding group mode divided into topics.
481 * Misc Group Stuff::            Other stuff that you can to do.
482
483 Group Buffer Format
484
485 * Group Line Specification::    Deciding how the group buffer is to look.
486 * Group Modeline Specification::  The group buffer modeline.
487 * Group Highlighting::          Having nice colors in the group buffer.
488
489 Group Topics
490
491 * Topic Commands::              Interactive E-Z commands.
492 * Topic Variables::             How to customize the topics the Lisp Way.
493 * Topic Sorting::               Sorting each topic individually.
494 * Topic Topology::              A map of the world.
495 * Topic Parameters::            Parameters that apply to all groups in a topic.
496
497 Misc Group Stuff
498
499 * Scanning New Messages::       Asking Gnus to see whether new messages have arrived.
500 * Group Information::           Information and help on groups and Gnus.
501 * Group Timestamp::             Making Gnus keep track of when you last read a group.
502 * File Commands::               Reading and writing the Gnus files.
503 * Sieve Commands::              Managing Sieve scripts.
504
505 Summary Buffer
506
507 * Summary Buffer Format::       Deciding how the summary buffer is to look.
508 * Summary Maneuvering::         Moving around the summary buffer.
509 * Choosing Articles::           Reading articles.
510 * Paging the Article::          Scrolling the current article.
511 * Reply Followup and Post::     Posting articles.
512 * Delayed Articles::            Send articles at a later time.
513 * Marking Articles::            Marking articles as read, expirable, etc.
514 * Limiting::                    You can limit the summary buffer.
515 * Threading::                   How threads are made.
516 * Sorting the Summary Buffer::  How articles and threads are sorted.
517 * Asynchronous Fetching::       Gnus might be able to pre-fetch articles.
518 * Article Caching::             You may store articles in a cache.
519 * Persistent Articles::         Making articles expiry-resistant.
520 * Article Backlog::             Having already read articles hang around.
521 * Saving Articles::             Ways of customizing article saving.
522 * Decoding Articles::           Gnus can treat series of (uu)encoded articles.
523 * Article Treatment::           The article buffer can be mangled at will.
524 * MIME Commands::               Doing MIMEy things with the articles.
525 * Charsets::                    Character set issues.
526 * Article Commands::            Doing various things with the article buffer.
527 * Summary Sorting::             Sorting the summary buffer in various ways.
528 * Finding the Parent::          No child support? Get the parent.
529 * Alternative Approaches::      Reading using non-default summaries.
530 * Tree Display::                A more visual display of threads.
531 * Mail Group Commands::         Some commands can only be used in mail groups.
532 * Various Summary Stuff::       What didn't fit anywhere else.
533 * Exiting the Summary Buffer::  Returning to the Group buffer,
534                                 or reselecting the current group.
535 * Crosspost Handling::          How crossposted articles are dealt with.
536 * Duplicate Suppression::       An alternative when crosspost handling fails.
537 * Security::                    Decrypt and Verify.
538 * Mailing List::                Mailing list minor mode.
539
540 Summary Buffer Format
541
542 * Summary Buffer Lines::        You can specify how summary lines should look.
543 * To From Newsgroups::          How to not display your own name.
544 * Summary Buffer Mode Line::    You can say how the mode line should look.
545 * Summary Highlighting::        Making the summary buffer all pretty and nice.
546
547 Choosing Articles
548
549 * Choosing Commands::           Commands for choosing articles.
550 * Choosing Variables::          Variables that influence these commands.
551
552 Reply, Followup and Post
553
554 * Summary Mail Commands::       Sending mail.
555 * Summary Post Commands::       Sending news.
556 * Summary Message Commands::    Other Message-related commands.
557 * Canceling and Superseding::   
558
559 Marking Articles
560
561 * Unread Articles::             Marks for unread articles.
562 * Read Articles::               Marks for read articles.
563 * Other Marks::                 Marks that do not affect readedness.
564 * Setting Marks::               
565 * Generic Marking Commands::    
566 * Setting Process Marks::       
567
568 Marking Articles
569
570 * Setting Marks::             How to set and remove marks.
571 * Generic Marking Commands::  How to customize the marking.
572 * Setting Process Marks::     How to mark articles for later processing.
573
574 Threading
575
576 * Customizing Threading::       Variables you can change to affect the threading.
577 * Thread Commands::             Thread based commands in the summary buffer.
578
579 Customizing Threading
580
581 * Loose Threads::               How Gnus gathers loose threads into bigger threads.
582 * Filling In Threads::          Making the threads displayed look fuller.
583 * More Threading::              Even more variables for fiddling with threads.
584 * Low-Level Threading::         You thought it was over... but you were wrong!
585
586 Decoding Articles
587
588 * Uuencoded Articles::          Uudecode articles.
589 * Shell Archives::              Unshar articles.
590 * PostScript Files::            Split PostScript.
591 * Other Files::                 Plain save and binhex.
592 * Decoding Variables::          Variables for a happy decoding.
593 * Viewing Files::               You want to look at the result of the decoding?
594
595 Decoding Variables
596
597 * Rule Variables::              Variables that say how a file is to be viewed.
598 * Other Decode Variables::      Other decode variables.
599 * Uuencoding and Posting::      Variables for customizing uuencoding.
600
601 Article Treatment
602
603 * Article Highlighting::        You want to make the article look like fruit salad.
604 * Article Fontisizing::         Making emphasized text look nice.
605 * Article Hiding::              You also want to make certain info go away.
606 * Article Washing::             Lots of way-neat functions to make life better.
607 * Article Header::              Doing various header transformations.
608 * Article Buttons::             Click on URLs, Message-IDs, addresses and the like.
609 * Article Date::                Grumble, UT!
610 * Article Display::             Display various stuff---X-Face, Picons, Smileys
611 * Article Signature::           What is a signature?
612 * Article Miscellania::         Various other stuff.
613
614 Alternative Approaches
615
616 * Pick and Read::               First mark articles and then read them.
617 * Binary Groups::               Auto-decode all articles.
618
619 Various Summary Stuff
620
621 * Summary Group Information::   Information oriented commands.
622 * Searching for Articles::      Multiple article commands.
623 * Summary Generation Commands::  
624 * Really Various Summary Commands::  Those pesky non-conformant commands.
625
626 Article Buffer
627
628 * Hiding Headers::              Deciding what headers should be displayed.
629 * Using MIME::                  Pushing articles through @sc{mime} before reading them.
630 * Customizing Articles::        Tailoring the look of the articles.
631 * Article Keymap::              Keystrokes available in the article buffer.
632 * Misc Article::                Other stuff.
633
634 Composing Messages
635
636 * Mail::                        Mailing and replying.
637 * Posting Server::              What server should you post and mail via?
638 * Mail and Post::               Mailing and posting at the same time.
639 * Archived Messages::           Where Gnus stores the messages you've sent.
640 * Posting Styles::              An easier way to specify who you are.
641 * Drafts::                      Postponing messages and rejected messages.
642 * Rejected Articles::           What happens if the server doesn't like your article?
643 * Signing and encrypting::      How to compose secure messages.
644
645 Select Methods
646
647 * Server Buffer::               Making and editing virtual servers.
648 * Getting News::                Reading USENET news with Gnus.
649 * Getting Mail::                Reading your personal mail with Gnus.
650 * Browsing the Web::            Getting messages from a plethora of Web sources.
651 * IMAP::                        Using Gnus as a @sc{imap} client.
652 * Other Sources::               Reading directories, files, SOUP packets.
653 * Combined Groups::             Combining groups into one group.
654 * Gnus Unplugged::              Reading news and mail offline.
655
656 Server Buffer
657
658 * Server Buffer Format::        You can customize the look of this buffer.
659 * Server Commands::             Commands to manipulate servers.
660 * Example Methods::             Examples server specifications.
661 * Creating a Virtual Server::   An example session.
662 * Server Variables::            Which variables to set.
663 * Servers and Methods::         You can use server names as select methods.
664 * Unavailable Servers::         Some servers you try to contact may be down.
665
666 Getting News
667
668 * NNTP::                        Reading news from an @sc{nntp} server.
669 * News Spool::                  Reading news from the local spool.
670
671 @sc{nntp}
672
673 * Direct Functions::            Connecting directly to the server.
674 * Indirect Functions::          Connecting indirectly to the server.
675 * Common Variables::            Understood by several connection functions.
676
677 Getting Mail
678
679 * Mail in a Newsreader::        Important introductory notes.
680 * Getting Started Reading Mail::  A simple cookbook example.
681 * Splitting Mail::              How to create mail groups.
682 * Mail Sources::                How to tell Gnus where to get mail from.
683 * Mail Back End Variables::     Variables for customizing mail handling.
684 * Fancy Mail Splitting::        Gnus can do hairy splitting of incoming mail.
685 * Group Mail Splitting::        Use group customize to drive mail splitting.
686 * Incorporating Old Mail::      What about the old mail you have?
687 * Expiring Mail::               Getting rid of unwanted mail.
688 * Washing Mail::                Removing gruft from the mail you get.
689 * Duplicates::                  Dealing with duplicated mail.
690 * Not Reading Mail::            Using mail back ends for reading other files.
691 * Choosing a Mail Back End::    Gnus can read a variety of mail formats.
692
693 Mail Sources
694
695 * Mail Source Specifiers::      How to specify what a mail source is.
696 * Mail Source Customization::   Some variables that influence things.
697 * Fetching Mail::               Using the mail source specifiers.
698
699 Choosing a Mail Back End
700
701 * Unix Mail Box::               Using the (quite) standard Un*x mbox.
702 * Rmail Babyl::                 Emacs programs use the rmail babyl format.
703 * Mail Spool::                  Store your mail in a private spool?
704 * MH Spool::                    An mhspool-like back end.
705 * Mail Folders::                Having one file for each group.
706 * Comparing Mail Back Ends::    An in-depth looks at pros and cons.
707
708 Browsing the Web
709
710 * Archiving Mail::              
711 * Web Searches::                Creating groups from articles that match a string.
712 * Slashdot::                    Reading the Slashdot comments.
713 * Ultimate::                    The Ultimate Bulletin Board systems.
714 * Web Archive::                 Reading mailing list archived on web.
715 * RSS::                         Reading RDF site summary.
716 * Customizing w3::              Doing stuff to Emacs/w3 from Gnus.
717
718 @sc{imap}
719
720 * Splitting in IMAP::           Splitting mail with nnimap.
721 * Expiring in IMAP::            Expiring mail with nnimap.
722 * Editing IMAP ACLs::           Limiting/enabling other users access to a mailbox.
723 * Expunging mailboxes::         Equivalent of a "compress mailbox" button.
724 * A note on namespaces::        How to (not) use IMAP namespace in Gnus.
725
726 Other Sources
727
728 * Directory Groups::            You can read a directory as if it was a newsgroup.
729 * Anything Groups::             Dired?  Who needs dired?
730 * Document Groups::             Single files can be the basis of a group.
731 * SOUP::                        Reading @sc{soup} packets ``offline''.
732 * Mail-To-News Gateways::       Posting articles via mail-to-news gateways.
733
734 Document Groups
735
736 * Document Server Internals::   How to add your own document types.
737
738 SOUP
739
740 * SOUP Commands::               Commands for creating and sending @sc{soup} packets
741 * SOUP Groups::                 A back end for reading @sc{soup} packets.
742 * SOUP Replies::                How to enable @code{nnsoup} to take over mail and news.
743
744 Combined Groups
745
746 * Virtual Groups::              Combining articles from many groups.
747 * Kibozed Groups::              Looking through parts of the newsfeed for articles.
748
749 Gnus Unplugged
750
751 * Agent Basics::                How it all is supposed to work.
752 * Agent Categories::            How to tell the Gnus Agent what to download.
753 * Agent Commands::              New commands for all the buffers.
754 * Agent as Cache::              The Agent is a big cache too.
755 * Agent Expiry::                How to make old articles go away.
756 * Agent and IMAP::              How to use the Agent with IMAP.
757 * Outgoing Messages::           What happens when you post/mail something?
758 * Agent Variables::             Customizing is fun.
759 * Example Setup::               An example @file{.gnus.el} file for offline people.
760 * Batching Agents::             How to fetch news from a @code{cron} job.
761 * Agent Caveats::               What you think it'll do and what it does.
762
763 Agent Categories
764
765 * Category Syntax::             What a category looks like.
766 * Category Buffer::             A buffer for maintaining categories.
767 * Category Variables::          Customize'r'Us.
768
769 Agent Commands
770
771 * Group Agent Commands::        
772 * Summary Agent Commands::      
773 * Server Agent Commands::       
774
775 Scoring
776
777 * Summary Score Commands::      Adding score entries for the current group.
778 * Group Score Commands::        General score commands.
779 * Score Variables::             Customize your scoring.  (My, what terminology).
780 * Score File Format::           What a score file may contain.
781 * Score File Editing::          You can edit score files by hand as well.
782 * Adaptive Scoring::            Big Sister Gnus knows what you read.
783 * Home Score File::             How to say where new score entries are to go.
784 * Followups To Yourself::       Having Gnus notice when people answer you.
785 * Scoring On Other Headers::    Scoring on non-standard headers.
786 * Scoring Tips::                How to score effectively.
787 * Reverse Scoring::             That problem child of old is not problem.
788 * Global Score Files::          Earth-spanning, ear-splitting score files.
789 * Kill Files::                  They are still here, but they can be ignored.
790 * Converting Kill Files::       Translating kill files to score files.
791 * GroupLens::                   Getting predictions on what you like to read.
792 * Advanced Scoring::            Using logical expressions to build score rules.
793 * Score Decays::                It can be useful to let scores wither away.
794
795 GroupLens
796
797 * Using GroupLens::             How to make Gnus use GroupLens.
798 * Rating Articles::             Letting GroupLens know how you rate articles.
799 * Displaying Predictions::      Displaying predictions given by GroupLens.
800 * GroupLens Variables::         Customizing GroupLens.
801
802 Advanced Scoring
803
804 * Advanced Scoring Syntax::     A definition.
805 * Advanced Scoring Examples::   What they look like.
806 * Advanced Scoring Tips::       Getting the most out of it.
807
808 Various
809
810 * Process/Prefix::              A convention used by many treatment commands.
811 * Interactive::                 Making Gnus ask you many questions.
812 * Symbolic Prefixes::           How to supply some Gnus functions with options.
813 * Formatting Variables::        You can specify what buffers should look like.
814 * Window Layout::               Configuring the Gnus buffer windows.
815 * Faces and Fonts::             How to change how faces look.
816 * Compilation::                 How to speed Gnus up.
817 * Mode Lines::                  Displaying information in the mode lines.
818 * Highlighting and Menus::      Making buffers look all nice and cozy.
819 * Buttons::                     Get tendinitis in ten easy steps!
820 * Daemons::                     Gnus can do things behind your back.
821 * NoCeM::                       How to avoid spam and other fatty foods.
822 * Undo::                        Some actions can be undone.
823 * Predicate Specifiers::        Specifying predicates.
824 * Moderation::                  What to do if you're a moderator.
825 * Image Enhancements::          Modern versions of Emacs/XEmacs can display images.
826 * Fuzzy Matching::              What's the big fuzz?
827 * Thwarting Email Spam::        A how-to on avoiding unsolicited commercial email.
828 * Various Various::             Things that are really various.
829
830 Formatting Variables
831
832 * Formatting Basics::           A formatting variable is basically a format string.
833 * Mode Line Formatting::        Some rules about mode line formatting variables.
834 * Advanced Formatting::         Modifying output in various ways.
835 * User-Defined Specs::          Having Gnus call your own functions.
836 * Formatting Fonts::            Making the formatting look colorful and nice.
837 * Positioning Point::           Moving point to a position after an operation.
838 * Tabulation::                  Tabulating your output.
839 * Wide Characters::             Dealing with wide characters.
840
841 Image Enhancements
842
843 * Picons::                      How to display pictures of what you're reading.
844 * Smileys::                     Show all those happy faces the way they were meant to be shown.
845 * X-Face::                      Display a funky, teensy black-and-white image.
846 * Toolbar::                     Click'n'drool.
847 * XVarious::                    Other XEmacsy Gnusey variables.
848
849 Picons
850
851 * Picon Basics::                What are picons and How do I get them.
852 * Picon Requirements::          Don't go further if you aren't using XEmacs.
853 * Easy Picons::                 Displaying Picons---the easy way.
854 * Hard Picons::                 The way you should do it.  You'll learn something.
855 * Picon Useless Configuration::  Other variables you can trash/tweak/munge/play with.
856
857 Thwarting Email Spam
858
859 * The problem of spam::         Some background, and some solutions
860 * Anti-Spam Basics::            Simple steps to reduce the amount of spam.
861 * SpamAssassin::                How to use external anti-spam tools.
862 * Hashcash::                    Reduce spam by burning CPU time.
863 * Filtering Spam Using spam.el::  
864 * Filtering Spam Using Statistics (spam-stat.el)::  
865
866 Appendices
867
868 * XEmacs::                      Requirements for installing under XEmacs.
869 * History::                     How Gnus got where it is today.
870 * On Writing Manuals::          Why this is not a beginner's guide.
871 * Terminology::                 We use really difficult, like, words here.
872 * Customization::               Tailoring Gnus to your needs.
873 * Troubleshooting::             What you might try if things do not work.
874 * Gnus Reference Guide::        Rilly, rilly technical stuff.
875 * Emacs for Heathens::          A short introduction to Emacsian terms.
876 * Frequently Asked Questions::
877
878 History
879
880 * Gnus Versions::               What Gnus versions have been released.
881 * Other Gnus Versions::         Other Gnus versions that also have been released.
882 * Why?::                        What's the point of Gnus?
883 * Compatibility::               Just how compatible is Gnus with @sc{gnus}?
884 * Conformity::                  Gnus tries to conform to all standards.
885 * Emacsen::                     Gnus can be run on a few modern Emacsen.
886 * Gnus Development::            How Gnus is developed.
887 * Contributors::                Oodles of people.
888 * New Features::                Pointers to some of the new stuff in Gnus.
889
890 New Features
891
892 * ding Gnus::                   New things in Gnus 5.0/5.1, the first new Gnus.
893 * September Gnus::              The Thing Formally Known As Gnus 5.2/5.3.
894 * Red Gnus::                    Third time best---Gnus 5.4/5.5.
895 * Quassia Gnus::                Two times two is four, or Gnus 5.6/5.7.
896 * Pterodactyl Gnus::            Pentad also starts with P, AKA Gnus 5.8/5.9.
897
898 Customization
899
900 * Slow/Expensive Connection::   You run a local Emacs and get the news elsewhere.
901 * Slow Terminal Connection::    You run a remote Emacs.
902 * Little Disk Space::           You feel that having large setup files is icky.
903 * Slow Machine::                You feel like buying a faster machine.
904
905 Gnus Reference Guide
906
907 * Gnus Utility Functions::      Common functions and variable to use.
908 * Back End Interface::          How Gnus communicates with the servers.
909 * Score File Syntax::           A BNF definition of the score file standard.
910 * Headers::                     How Gnus stores headers internally.
911 * Ranges::                      A handy format for storing mucho numbers.
912 * Group Info::                  The group info format.
913 * Extended Interactive::        Symbolic prefixes and stuff.
914 * Emacs/XEmacs Code::           Gnus can be run under all modern Emacsen.
915 * Various File Formats::        Formats of files that Gnus use.
916
917 Back End Interface
918
919 * Required Back End Functions::  Functions that must be implemented.
920 * Optional Back End Functions::  Functions that need not be implemented.
921 * Error Messaging::             How to get messages and report errors.
922 * Writing New Back Ends::       Extending old back ends.
923 * Hooking New Back Ends Into Gnus::  What has to be done on the Gnus end.
924 * Mail-like Back Ends::         Some tips on mail back ends.
925
926 Various File Formats
927
928 * Active File Format::          Information on articles and groups available.
929 * Newsgroups File Format::      Group descriptions.
930
931 Emacs for Heathens
932
933 * Keystrokes::                  Entering text and executing commands.
934 * Emacs Lisp::                  The built-in Emacs programming language.
935
936 @end detailmenu
937 @end menu
938
939 @node Starting Up
940 @chapter Starting Gnus
941 @cindex starting up
942
943 @kindex M-x gnus
944 @findex gnus
945 If your system administrator has set things up properly, starting Gnus
946 and reading news is extremely easy---you just type @kbd{M-x gnus} in
947 your Emacs.
948
949 @findex gnus-other-frame
950 @kindex M-x gnus-other-frame
951 If you want to start Gnus in a different frame, you can use the command
952 @kbd{M-x gnus-other-frame} instead.
953
954 If things do not go smoothly at startup, you have to twiddle some
955 variables in your @file{~/.gnus} file.  This file is similar to
956 @file{~/.emacs}, but is read when gnus starts.
957
958 If you puzzle at any terms used in this manual, please refer to the
959 terminology section (@pxref{Terminology}).
960
961 @menu
962 * Finding the News::            Choosing a method for getting news.
963 * The First Time::              What does Gnus do the first time you start it?
964 * The Server is Down::          How can I read my mail then?
965 * Slave Gnusae::                You can have more than one Gnus active at a time.
966 * Fetching a Group::            Starting Gnus just to read a group.
967 * New Groups::                  What is Gnus supposed to do with new groups?
968 * Changing Servers::            You may want to move from one server to another.
969 * Startup Files::               Those pesky startup files---@file{.newsrc}.
970 * Auto Save::                   Recovering from a crash.
971 * The Active File::             Reading the active file over a slow line Takes Time.
972 * Startup Variables::           Other variables you might change.
973 @end menu
974
975
976 @node Finding the News
977 @section Finding the News
978 @cindex finding news
979
980 @vindex gnus-select-method
981 @c @head
982 The @code{gnus-select-method} variable says where Gnus should look for
983 news.  This variable should be a list where the first element says
984 @dfn{how} and the second element says @dfn{where}.  This method is your
985 native method.  All groups not fetched with this method are
986 foreign groups.
987
988 For instance, if the @samp{news.somewhere.edu} @sc{nntp} server is where
989 you want to get your daily dosage of news from, you'd say:
990
991 @lisp
992 (setq gnus-select-method '(nntp "news.somewhere.edu"))
993 @end lisp
994
995 If you want to read directly from the local spool, say:
996
997 @lisp
998 (setq gnus-select-method '(nnspool ""))
999 @end lisp
1000
1001 If you can use a local spool, you probably should, as it will almost
1002 certainly be much faster.  But do not use the local spool if your
1003 server is running Leafnode; in this case, use @code{(nntp "localhost")}.
1004
1005 @vindex gnus-nntpserver-file
1006 @cindex NNTPSERVER
1007 @cindex @sc{nntp} server
1008 If this variable is not set, Gnus will take a look at the
1009 @code{NNTPSERVER} environment variable.  If that variable isn't set,
1010 Gnus will see whether @code{gnus-nntpserver-file}
1011 (@file{/etc/nntpserver} by default) has any opinions on the matter.  If
1012 that fails as well, Gnus will try to use the machine running Emacs as an @sc{nntp} server.  That's a long shot, though.
1013
1014 @vindex gnus-nntp-server
1015 If @code{gnus-nntp-server} is set, this variable will override
1016 @code{gnus-select-method}.  You should therefore set
1017 @code{gnus-nntp-server} to @code{nil}, which is what it is by default.
1018
1019 @vindex gnus-secondary-servers
1020 @vindex gnus-nntp-server
1021 You can also make Gnus prompt you interactively for the name of an
1022 @sc{nntp} server.  If you give a non-numerical prefix to @code{gnus}
1023 (i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
1024 in the @code{gnus-secondary-servers} list (if any).  You can also just
1025 type in the name of any server you feel like visiting.  (Note that this
1026 will set @code{gnus-nntp-server}, which means that if you then @kbd{M-x
1027 gnus} later in the same Emacs session, Gnus will contact the same
1028 server.)
1029
1030 @findex gnus-group-browse-foreign-server
1031 @kindex B (Group)
1032 However, if you use one @sc{nntp} server regularly and are just
1033 interested in a couple of groups from a different server, you would be
1034 better served by using the @kbd{B} command in the group buffer.  It will
1035 let you have a look at what groups are available, and you can subscribe
1036 to any of the groups you want to.  This also makes @file{.newsrc}
1037 maintenance much tidier.  @xref{Foreign Groups}.
1038
1039 @vindex gnus-secondary-select-methods
1040 @c @head
1041 A slightly different approach to foreign groups is to set the
1042 @code{gnus-secondary-select-methods} variable.  The select methods
1043 listed in this variable are in many ways just as native as the
1044 @code{gnus-select-method} server.  They will also be queried for active
1045 files during startup (if that's required), and new newsgroups that
1046 appear on these servers will be subscribed (or not) just as native
1047 groups are.
1048
1049 For instance, if you use the @code{nnmbox} back end to read your mail,
1050 you would typically set this variable to
1051
1052 @lisp
1053 (setq gnus-secondary-select-methods '((nnmbox "")))
1054 @end lisp
1055
1056
1057 @node The First Time
1058 @section The First Time
1059 @cindex first time usage
1060
1061 If no startup files exist, Gnus will try to determine what groups should
1062 be subscribed by default.
1063
1064 @vindex gnus-default-subscribed-newsgroups
1065 If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
1066 will subscribe you to just those groups in that list, leaving the rest
1067 killed.  Your system administrator should have set this variable to
1068 something useful.
1069
1070 Since she hasn't, Gnus will just subscribe you to a few arbitrarily
1071 picked groups (i.e., @samp{*.newusers}).  (@dfn{Arbitrary} is defined
1072 here as @dfn{whatever Lars thinks you should read}.)
1073
1074 You'll also be subscribed to the Gnus documentation group, which should
1075 help you with most common problems.
1076
1077 If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
1078 use the normal functions for handling new groups, and not do anything
1079 special.
1080
1081
1082 @node The Server is Down
1083 @section The Server is Down
1084 @cindex server errors
1085
1086 If the default server is down, Gnus will understandably have some
1087 problems starting.  However, if you have some mail groups in addition to
1088 the news groups, you may want to start Gnus anyway.
1089
1090 Gnus, being the trusting sort of program, will ask whether to proceed
1091 without a native select method if that server can't be contacted.  This
1092 will happen whether the server doesn't actually exist (i.e., you have
1093 given the wrong address) or the server has just momentarily taken ill
1094 for some reason or other.  If you decide to continue and have no foreign
1095 groups, you'll find it difficult to actually do anything in the group
1096 buffer.  But, hey, that's your problem.  Blllrph!
1097
1098 @findex gnus-no-server
1099 @kindex M-x gnus-no-server
1100 @c @head
1101 If you know that the server is definitely down, or you just want to read
1102 your mail without bothering with the server at all, you can use the
1103 @code{gnus-no-server} command to start Gnus.  That might come in handy
1104 if you're in a hurry as well.  This command will not attempt to contact
1105 your primary server---instead, it will just activate all groups on level
1106 1 and 2.  (You should preferably keep no native groups on those two
1107 levels.) Also @pxref{Group Levels}.
1108
1109
1110 @node Slave Gnusae
1111 @section Slave Gnusae
1112 @cindex slave
1113
1114 You might want to run more than one Emacs with more than one Gnus at the
1115 same time.  If you are using different @file{.newsrc} files (e.g., if you
1116 are using the two different Gnusae to read from two different servers),
1117 that is no problem whatsoever.  You just do it.
1118
1119 The problem appears when you want to run two Gnusae that use the same
1120 @code{.newsrc} file.
1121
1122 To work around that problem some, we here at the Think-Tank at the Gnus
1123 Towers have come up with a new concept: @dfn{Masters} and
1124 @dfn{slaves}.  (We have applied for a patent on this concept, and have
1125 taken out a copyright on those words.  If you wish to use those words in
1126 conjunction with each other, you have to send $1 per usage instance to
1127 me.  Usage of the patent (@dfn{Master/Slave Relationships In Computer
1128 Applications}) will be much more expensive, of course.)
1129
1130 Anyway, you start one Gnus up the normal way with @kbd{M-x gnus} (or
1131 however you do it).  Each subsequent slave Gnusae should be started with
1132 @kbd{M-x gnus-slave}.  These slaves won't save normal @file{.newsrc}
1133 files, but instead save @dfn{slave files} that contain information only
1134 on what groups have been read in the slave session.  When a master Gnus
1135 starts, it will read (and delete) these slave files, incorporating all
1136 information from them.  (The slave files will be read in the sequence
1137 they were created, so the latest changes will have precedence.)
1138
1139 Information from the slave files has, of course, precedence over the
1140 information in the normal (i.e., master) @code{.newsrc} file.
1141
1142 If the @code{.newsrc*} files have not been saved in the master when the
1143 slave starts, you may be prompted as to whether to read an auto-save
1144 file.  If you answer "yes", the unsaved changes to the master will be
1145 incorporated into the slave.  If you answer "no", the slave may see some
1146 messages as unread that have been read in the master.
1147
1148 @node Fetching a Group
1149 @section Fetching a Group
1150 @cindex fetching a group
1151
1152 @findex gnus-fetch-group
1153 It is sometimes convenient to be able to just say ``I want to read this
1154 group and I don't care whether Gnus has been started or not''.  This is
1155 perhaps more useful for people who write code than for users, but the
1156 command @code{gnus-fetch-group} provides this functionality in any case.
1157 It takes the group name as a parameter.
1158
1159
1160 @node New Groups
1161 @section New Groups
1162 @cindex new groups
1163 @cindex subscription
1164
1165 @vindex gnus-check-new-newsgroups
1166 If you are satisfied that you really never want to see any new groups,
1167 you can set @code{gnus-check-new-newsgroups} to @code{nil}.  This will
1168 also save you some time at startup.  Even if this variable is
1169 @code{nil}, you can always subscribe to the new groups just by pressing
1170 @kbd{U} in the group buffer (@pxref{Group Maintenance}).  This variable
1171 is @code{ask-server} by default.  If you set this variable to
1172 @code{always}, then Gnus will query the back ends for new groups even
1173 when you do the @kbd{g} command (@pxref{Scanning New Messages}).
1174
1175 @menu
1176 * Checking New Groups::         Determining what groups are new.
1177 * Subscription Methods::        What Gnus should do with new groups.
1178 * Filtering New Groups::        Making Gnus ignore certain new groups.
1179 @end menu
1180
1181
1182 @node Checking New Groups
1183 @subsection Checking New Groups
1184
1185 Gnus normally determines whether a group is new or not by comparing the
1186 list of groups from the active file(s) with the lists of subscribed and
1187 dead groups.  This isn't a particularly fast method.  If
1188 @code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
1189 server for new groups since the last time.  This is both faster and
1190 cheaper.  This also means that you can get rid of the list of killed
1191 groups altogether, so you may set @code{gnus-save-killed-list} to
1192 @code{nil}, which will save time both at startup, at exit, and all over.
1193 Saves disk space, too.  Why isn't this the default, then?
1194 Unfortunately, not all servers support this command.
1195
1196 I bet I know what you're thinking now: How do I find out whether my
1197 server supports @code{ask-server}?  No?  Good, because I don't have a
1198 fail-safe answer.  I would suggest just setting this variable to
1199 @code{ask-server} and see whether any new groups appear within the next
1200 few days.  If any do, then it works.  If none do, then it doesn't
1201 work.  I could write a function to make Gnus guess whether the server
1202 supports @code{ask-server}, but it would just be a guess.  So I won't.
1203 You could @code{telnet} to the server and say @code{HELP} and see
1204 whether it lists @samp{NEWGROUPS} among the commands it understands.  If
1205 it does, then it might work.  (But there are servers that lists
1206 @samp{NEWGROUPS} without supporting the function properly.)
1207
1208 This variable can also be a list of select methods.  If so, Gnus will
1209 issue an @code{ask-server} command to each of the select methods, and
1210 subscribe them (or not) using the normal methods.  This might be handy
1211 if you are monitoring a few servers for new groups.  A side effect is
1212 that startup will take much longer, so you can meditate while waiting.
1213 Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss.
1214
1215
1216 @node Subscription Methods
1217 @subsection Subscription Methods
1218
1219 @vindex gnus-subscribe-newsgroup-method
1220 What Gnus does when it encounters a new group is determined by the
1221 @code{gnus-subscribe-newsgroup-method} variable.
1222
1223 This variable should contain a function.  This function will be called
1224 with the name of the new group as the only parameter.
1225
1226 Some handy pre-fab functions are:
1227
1228 @table @code
1229
1230 @item gnus-subscribe-zombies
1231 @vindex gnus-subscribe-zombies
1232 Make all new groups zombies.  This is the default.  You can browse the
1233 zombies later (with @kbd{A z}) and either kill them all off properly
1234 (with @kbd{S z}), or subscribe to them (with @kbd{u}).
1235
1236 @item gnus-subscribe-randomly
1237 @vindex gnus-subscribe-randomly
1238 Subscribe all new groups in arbitrary order.  This really means that all
1239 new groups will be added at ``the top'' of the group buffer.
1240
1241 @item gnus-subscribe-alphabetically
1242 @vindex gnus-subscribe-alphabetically
1243 Subscribe all new groups in alphabetical order.
1244
1245 @item gnus-subscribe-hierarchically
1246 @vindex gnus-subscribe-hierarchically
1247 Subscribe all new groups hierarchically.  The difference between this
1248 function and @code{gnus-subscribe-alphabetically} is slight.
1249 @code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly
1250 alphabetical fashion, while this function will enter groups into its
1251 hierarchy.  So if you want to have the @samp{rec} hierarchy before the
1252 @samp{comp} hierarchy, this function will not mess that configuration
1253 up.  Or something like that.
1254
1255 @item gnus-subscribe-interactively
1256 @vindex gnus-subscribe-interactively
1257 Subscribe new groups interactively.  This means that Gnus will ask
1258 you about @strong{all} new groups.  The groups you choose to subscribe
1259 to will be subscribed hierarchically.
1260
1261 @item gnus-subscribe-killed
1262 @vindex gnus-subscribe-killed
1263 Kill all new groups.
1264
1265 @item gnus-subscribe-topics
1266 @vindex gnus-subscribe-topics
1267 Put the groups into the topic that has a matching @code{subscribe} topic
1268 parameter (@pxref{Topic Parameters}).  For instance, a @code{subscribe}
1269 topic parameter that looks like
1270
1271 @example
1272 "nnslashdot"
1273 @end example
1274
1275 will mean that all groups that match that regex will be subscribed under
1276 that topic.
1277
1278 If no topics match the groups, the groups will be subscribed in the
1279 top-level topic.
1280
1281 @end table
1282
1283 @vindex gnus-subscribe-hierarchical-interactive
1284 A closely related variable is
1285 @code{gnus-subscribe-hierarchical-interactive}.  (That's quite a
1286 mouthful.)  If this variable is non-@code{nil}, Gnus will ask you in a
1287 hierarchical fashion whether to subscribe to new groups or not.  Gnus
1288 will ask you for each sub-hierarchy whether you want to descend the
1289 hierarchy or not.
1290
1291 One common mistake is to set the variable a few paragraphs above
1292 (@code{gnus-subscribe-newsgroup-method}) to
1293 @code{gnus-subscribe-hierarchical-interactive}.  This is an error.  This
1294 will not work.  This is ga-ga.  So don't do it.
1295
1296
1297 @node Filtering New Groups
1298 @subsection Filtering New Groups
1299
1300 A nice and portable way to control which new newsgroups should be
1301 subscribed (or ignored) is to put an @dfn{options} line at the start of
1302 the @file{.newsrc} file.  Here's an example:
1303
1304 @example
1305 options -n !alt.all !rec.all sci.all
1306 @end example
1307
1308 @vindex gnus-subscribe-options-newsgroup-method
1309 This line obviously belongs to a serious-minded intellectual scientific
1310 person (or she may just be plain old boring), because it says that all
1311 groups that have names beginning with @samp{alt} and @samp{rec} should
1312 be ignored, and all groups with names beginning with @samp{sci} should
1313 be subscribed.  Gnus will not use the normal subscription method for
1314 subscribing these groups.
1315 @code{gnus-subscribe-options-newsgroup-method} is used instead.  This
1316 variable defaults to @code{gnus-subscribe-alphabetically}.
1317
1318 @vindex gnus-options-not-subscribe
1319 @vindex gnus-options-subscribe
1320 If you don't want to mess with your @file{.newsrc} file, you can just
1321 set the two variables @code{gnus-options-subscribe} and
1322 @code{gnus-options-not-subscribe}.  These two variables do exactly the
1323 same as the @file{.newsrc} @samp{options -n} trick.  Both are regexps,
1324 and if the new group matches the former, it will be unconditionally
1325 subscribed, and if it matches the latter, it will be ignored.
1326
1327 @vindex gnus-auto-subscribed-groups
1328 Yet another variable that meddles here is
1329 @code{gnus-auto-subscribed-groups}.  It works exactly like
1330 @code{gnus-options-subscribe}, and is therefore really superfluous, but I
1331 thought it would be nice to have two of these.  This variable is more
1332 meant for setting some ground rules, while the other variable is used
1333 more for user fiddling.  By default this variable makes all new groups
1334 that come from mail back ends (@code{nnml}, @code{nnbabyl},
1335 @code{nnfolder}, @code{nnmbox}, @code{nnmh}, and @code{nnmaildir})
1336 subscribed.  If you don't like that, just set this variable to
1337 @code{nil}.
1338
1339 New groups that match this regexp are subscribed using
1340 @code{gnus-subscribe-options-newsgroup-method}.
1341
1342
1343 @node Changing Servers
1344 @section Changing Servers
1345 @cindex changing servers
1346
1347 Sometimes it is necessary to move from one @sc{nntp} server to another.
1348 This happens very rarely, but perhaps you change jobs, or one server is
1349 very flaky and you want to use another.
1350
1351 Changing the server is pretty easy, right?  You just change
1352 @code{gnus-select-method} to point to the new server?
1353
1354 @emph{Wrong!}
1355
1356 Article numbers are not (in any way) kept synchronized between different
1357 @sc{nntp} servers, and the only way Gnus keeps track of what articles
1358 you have read is by keeping track of article numbers.  So when you
1359 change @code{gnus-select-method}, your @file{.newsrc} file becomes
1360 worthless.
1361
1362 Gnus provides a few functions to attempt to translate a @file{.newsrc}
1363 file from one server to another.  They all have one thing in
1364 common---they take a looong time to run.  You don't want to use these
1365 functions more than absolutely necessary.
1366
1367 @kindex M-x gnus-change-server
1368 @findex gnus-change-server
1369 If you have access to both servers, Gnus can request the headers for all
1370 the articles you have read and compare @code{Message-ID}s and map the
1371 article numbers of the read articles and article marks.  The @kbd{M-x
1372 gnus-change-server} command will do this for all your native groups.  It
1373 will prompt for the method you want to move to.
1374
1375 @kindex M-x gnus-group-move-group-to-server
1376 @findex gnus-group-move-group-to-server
1377 You can also move individual groups with the @kbd{M-x
1378 gnus-group-move-group-to-server} command.  This is useful if you want to
1379 move a (foreign) group from one server to another.
1380
1381 @kindex M-x gnus-group-clear-data-on-native-groups
1382 @findex gnus-group-clear-data-on-native-groups
1383 If you don't have access to both the old and new server, all your marks
1384 and read ranges have become worthless.  You can use the @kbd{M-x
1385 gnus-group-clear-data-on-native-groups} command to clear out all data
1386 that you have on your native groups.  Use with caution.
1387
1388 @kindex M-x gnus-group-clear-data
1389 @findex gnus-group-clear-data
1390 Clear the data from the current group only---nix out marks and the
1391 list of read articles (@code{gnus-group-clear-data}).
1392
1393 After changing servers, you @strong{must} move the cache hierarchy away,
1394 since the cached articles will have wrong article numbers, which will
1395 affect which articles Gnus thinks are read.
1396 @code{gnus-group-clear-data-on-native-groups} will ask you if you want
1397 to have it done automatically; for @code{gnus-group-clear-data}, you
1398 can use @kbd{M-x gnus-cache-move-cache} (but beware, it will move the
1399 cache for all groups).
1400
1401
1402 @node Startup Files
1403 @section Startup Files
1404 @cindex startup files
1405 @cindex .newsrc
1406 @cindex .newsrc.el
1407 @cindex .newsrc.eld
1408
1409 Now, you all know about the @file{.newsrc} file.  All subscription
1410 information is traditionally stored in this file.
1411
1412 Things got a bit more complicated with @sc{gnus}.  In addition to
1413 keeping the @file{.newsrc} file updated, it also used a file called
1414 @file{.newsrc.el} for storing all the information that didn't fit into
1415 the @file{.newsrc} file.  (Actually, it also duplicated everything in
1416 the @file{.newsrc} file.)  @sc{gnus} would read whichever one of these
1417 files was the most recently saved, which enabled people to swap between
1418 @sc{gnus} and other newsreaders.
1419
1420 That was kinda silly, so Gnus went one better: In addition to the
1421 @file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
1422 @file{.newsrc.eld}.  It will read whichever of these files that are most
1423 recent, but it will never write a @file{.newsrc.el} file.  You should
1424 never delete the @file{.newsrc.eld} file---it contains much information
1425 not stored in the @file{.newsrc} file.
1426
1427 @vindex gnus-save-newsrc-file
1428 @vindex gnus-read-newsrc-file
1429 You can turn off writing the @file{.newsrc} file by setting
1430 @code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
1431 the file and save some space, as well as exiting from Gnus faster.
1432 However, this will make it impossible to use other newsreaders than
1433 Gnus.  But hey, who would want to, right?  Similarly, setting
1434 @code{gnus-read-newsrc-file} to @code{nil} makes Gnus ignore the
1435 @file{.newsrc} file and any @file{.newsrc-SERVER} files, which is
1436 convenient if you have a tendency to use Netscape once in a while.
1437
1438 @vindex gnus-save-killed-list
1439 If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus
1440 will not save the list of killed groups to the startup file.  This will
1441 save both time (when starting and quitting) and space (on disk).  It
1442 will also mean that Gnus has no record of what groups are new or old,
1443 so the automatic new groups subscription methods become meaningless.
1444 You should always set @code{gnus-check-new-newsgroups} to @code{nil} or
1445 @code{ask-server} if you set this variable to @code{nil} (@pxref{New
1446 Groups}).  This variable can also be a regular expression.  If that's
1447 the case, remove all groups that do not match this regexp before
1448 saving.  This can be useful in certain obscure situations that involve
1449 several servers where not all servers support @code{ask-server}.
1450
1451 @vindex gnus-startup-file
1452 The @code{gnus-startup-file} variable says where the startup files are.
1453 The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
1454 file being whatever that one is, with a @samp{.eld} appended.
1455
1456 @vindex gnus-save-newsrc-hook
1457 @vindex gnus-save-quick-newsrc-hook
1458 @vindex gnus-save-standard-newsrc-hook
1459 @code{gnus-save-newsrc-hook} is called before saving any of the newsrc
1460 files, while @code{gnus-save-quick-newsrc-hook} is called just before
1461 saving the @file{.newsrc.eld} file, and
1462 @code{gnus-save-standard-newsrc-hook} is called just before saving the
1463 @file{.newsrc} file.  The latter two are commonly used to turn version
1464 control on or off.  Version control is on by default when saving the
1465 startup files.  If you want to turn backup creation off, say something like:
1466
1467 @lisp
1468 (defun turn-off-backup ()
1469   (set (make-local-variable 'backup-inhibited) t))
1470
1471 (add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup)
1472 (add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup)
1473 @end lisp
1474
1475 @vindex gnus-init-file
1476 When Gnus starts, it will read the @code{gnus-site-init-file}
1477 (@file{.../site-lisp/gnus} by default) and @code{gnus-init-file}
1478 (@file{~/.gnus} by default) files.  These are normal Emacs Lisp files
1479 and can be used to avoid cluttering your @file{~/.emacs} and
1480 @file{site-init} files with Gnus stuff.  Gnus will also check for files
1481 with the same names as these, but with @file{.elc} and @file{.el}
1482 suffixes.  In other words, if you have set @code{gnus-init-file} to
1483 @file{~/.gnus}, it will look for @file{~/.gnus.elc}, @file{~/.gnus.el},
1484 and finally @file{~/.gnus} (in this order).
1485
1486
1487
1488 @node Auto Save
1489 @section Auto Save
1490 @cindex dribble file
1491 @cindex auto-save
1492
1493 Whenever you do something that changes the Gnus data (reading articles,
1494 catching up, killing/subscribing groups), the change is added to a
1495 special @dfn{dribble buffer}.  This buffer is auto-saved the normal
1496 Emacs way.  If your Emacs should crash before you have saved the
1497 @file{.newsrc} files, all changes you have made can be recovered from
1498 this file.
1499
1500 If Gnus detects this file at startup, it will ask the user whether to
1501 read it.  The auto save file is deleted whenever the real startup file is
1502 saved.
1503
1504 @vindex gnus-use-dribble-file
1505 If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
1506 maintain a dribble buffer.  The default is @code{t}.
1507
1508 @vindex gnus-dribble-directory
1509 Gnus will put the dribble file(s) in @code{gnus-dribble-directory}.  If
1510 this variable is @code{nil}, which it is by default, Gnus will dribble
1511 into the directory where the @file{.newsrc} file is located.  (This is
1512 normally the user's home directory.)  The dribble file will get the same
1513 file permissions as the @code{.newsrc} file.
1514
1515 @vindex gnus-always-read-dribble-file
1516 If @code{gnus-always-read-dribble-file} is non-@code{nil}, Gnus will
1517 read the dribble file on startup without querying the user.
1518
1519
1520 @node The Active File
1521 @section The Active File
1522 @cindex active file
1523 @cindex ignored groups
1524
1525 When Gnus starts, or indeed whenever it tries to determine whether new
1526 articles have arrived, it reads the active file.  This is a very large
1527 file that lists all the active groups and articles on the server.
1528
1529 @vindex gnus-ignored-newsgroups
1530 Before examining the active file, Gnus deletes all lines that match the
1531 regexp @code{gnus-ignored-newsgroups}.  This is done primarily to reject
1532 any groups with bogus names, but you can use this variable to make Gnus
1533 ignore hierarchies you aren't ever interested in.  However, this is not
1534 recommended.  In fact, it's highly discouraged.  Instead, @pxref{New
1535 Groups} for an overview of other variables that can be used instead.
1536
1537 @c This variable is
1538 @c @code{nil} by default, and will slow down active file handling somewhat
1539 @c if you set it to anything else.
1540
1541 @vindex gnus-read-active-file
1542 @c @head
1543 The active file can be rather Huge, so if you have a slow network, you
1544 can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
1545 reading the active file.  This variable is @code{some} by default.
1546
1547 Gnus will try to make do by getting information just on the groups that
1548 you actually subscribe to.
1549
1550 Note that if you subscribe to lots and lots of groups, setting this
1551 variable to @code{nil} will probably make Gnus slower, not faster.  At
1552 present, having this variable @code{nil} will slow Gnus down
1553 considerably, unless you read news over a 2400 baud modem.
1554
1555 This variable can also have the value @code{some}.  Gnus will then
1556 attempt to read active info only on the subscribed groups.  On some
1557 servers this is quite fast (on sparkling, brand new INN servers that
1558 support the @code{LIST ACTIVE group} command), on others this isn't fast
1559 at all.  In any case, @code{some} should be faster than @code{nil}, and
1560 is certainly faster than @code{t} over slow lines.
1561
1562 Some news servers (old versions of Leafnode and old versions of INN, for
1563 instance) do not support the @code{LIST ACTIVE group}.  For these
1564 servers, @code{nil} is probably the most efficient value for this
1565 variable.
1566
1567 If this variable is @code{nil}, Gnus will ask for group info in total
1568 lock-step, which isn't very fast.  If it is @code{some} and you use an
1569 @sc{nntp} server, Gnus will pump out commands as fast as it can, and
1570 read all the replies in one swoop.  This will normally result in better
1571 performance, but if the server does not support the aforementioned
1572 @code{LIST ACTIVE group} command, this isn't very nice to the server.
1573
1574 If you think that starting up Gnus takes too long, try all the three
1575 different values for this variable and see what works best for you.
1576
1577 In any case, if you use @code{some} or @code{nil}, you should definitely
1578 kill all groups that you aren't interested in to speed things up.
1579
1580 Note that this variable also affects active file retrieval from
1581 secondary select methods.
1582
1583
1584 @node Startup Variables
1585 @section Startup Variables
1586
1587 @table @code
1588
1589 @item gnus-load-hook
1590 @vindex gnus-load-hook
1591 A hook run while Gnus is being loaded.  Note that this hook will
1592 normally be run just once in each Emacs session, no matter how many
1593 times you start Gnus.
1594
1595 @item gnus-before-startup-hook
1596 @vindex gnus-before-startup-hook
1597 A hook run after starting up Gnus successfully.
1598
1599 @item gnus-startup-hook
1600 @vindex gnus-startup-hook
1601 A hook run as the very last thing after starting up Gnus
1602
1603 @item gnus-started-hook
1604 @vindex gnus-started-hook
1605 A hook that is run as the very last thing after starting up Gnus
1606 successfully.
1607
1608 @item gnus-setup-news-hook
1609 @vindex gnus-setup-news-hook
1610 A hook that is run after reading the @file{.newsrc} file(s), but before
1611 generating the group buffer.
1612
1613 @item gnus-check-bogus-newsgroups
1614 @vindex gnus-check-bogus-newsgroups
1615 If non-@code{nil}, Gnus will check for and delete all bogus groups at
1616 startup.  A @dfn{bogus group} is a group that you have in your
1617 @file{.newsrc} file, but doesn't exist on the news server.  Checking for
1618 bogus groups can take quite a while, so to save time and resources it's
1619 best to leave this option off, and do the checking for bogus groups once
1620 in a while from the group buffer instead (@pxref{Group Maintenance}).
1621
1622 @item gnus-inhibit-startup-message
1623 @vindex gnus-inhibit-startup-message
1624 If non-@code{nil}, the startup message won't be displayed.  That way,
1625 your boss might not notice as easily that you are reading news instead
1626 of doing your job.  Note that this variable is used before
1627 @file{.gnus.el} is loaded, so it should be set in @code{.emacs} instead.
1628
1629 @item gnus-no-groups-message
1630 @vindex gnus-no-groups-message
1631 Message displayed by Gnus when no groups are available.
1632
1633 @item gnus-play-startup-jingle
1634 @vindex gnus-play-startup-jingle
1635 If non-@code{nil}, play the Gnus jingle at startup.
1636
1637 @item gnus-startup-jingle
1638 @vindex gnus-startup-jingle
1639 Jingle to be played if the above variable is non-@code{nil}.  The
1640 default is @samp{Tuxedomoon.Jingle4.au}.
1641
1642 @end table
1643
1644
1645 @node Group Buffer
1646 @chapter Group Buffer
1647 @cindex group buffer
1648
1649 @c Alex Schroeder suggests to rearrange this as follows:
1650 @c
1651 @c <kensanata> ok, just save it for reference.  I'll go to bed in a minute.
1652 @c   1. Selecting a Group, 2. (new) Finding a Group, 3. Group Levels,
1653 @c   4. Subscription Commands, 5. Group Maneuvering, 6. Group Data,
1654 @c   7. Group Score, 8. Group Buffer Format
1655 @c <kensanata> Group Levels should have more information on levels 5 to 9.  I
1656 @c   suggest to split the 4th paragraph ("Gnus considers groups...") as follows:
1657 @c <kensanata> First, "Gnus considers groups... (default 9)."
1658 @c <kensanata> New, a table summarizing what levels 1 to 9 mean.
1659 @c <kensanata> Third, "Gnus treats subscribed ... reasons of efficiency"
1660 @c <kensanata> Then expand the next paragraph or add some more to it.
1661 @c    This short one sentence explains levels 1 and 2, therefore I understand
1662 @c    that I should keep important news at 3 and boring news at 4.
1663 @c    Say so!  Then go on to explain why I should bother with levels 6 to 9.
1664 @c    Maybe keep those that you don't want to read temporarily at 6,
1665 @c    those that you never want to read at 8, those that offend your
1666 @c    human rights at 9...
1667
1668
1669 The @dfn{group buffer} lists all (or parts) of the available groups.  It
1670 is the first buffer shown when Gnus starts, and will never be killed as
1671 long as Gnus is active.
1672
1673 @iftex
1674 @iflatex
1675 \gnusfigure{The Group Buffer}{320}{
1676 \put(75,50){\epsfig{figure=ps/group,height=9cm}}
1677 \put(120,37){\makebox(0,0)[t]{Buffer name}}
1678 \put(120,38){\vector(1,2){10}}
1679 \put(40,60){\makebox(0,0)[r]{Mode line}}
1680 \put(40,58){\vector(1,0){30}}
1681 \put(200,28){\makebox(0,0)[t]{Native select method}}
1682 \put(200,26){\vector(-1,2){15}}
1683 }
1684 @end iflatex
1685 @end iftex
1686
1687 @menu
1688 * Group Buffer Format::         Information listed and how you can change it.
1689 * Group Maneuvering::           Commands for moving in the group buffer.
1690 * Selecting a Group::           Actually reading news.
1691 * Subscription Commands::       Unsubscribing, killing, subscribing.
1692 * Group Data::                  Changing the info for a group.
1693 * Group Levels::                Levels? What are those, then?
1694 * Group Score::                 A mechanism for finding out what groups you like.
1695 * Marking Groups::              You can mark groups for later processing.
1696 * Foreign Groups::              Creating and editing groups.
1697 * Group Parameters::            Each group may have different parameters set.
1698 * Listing Groups::              Gnus can list various subsets of the groups.
1699 * Sorting Groups::              Re-arrange the group order.
1700 * Group Maintenance::           Maintaining a tidy @file{.newsrc} file.
1701 * Browse Foreign Server::       You can browse a server.  See what it has to offer.
1702 * Exiting Gnus::                Stop reading news and get some work done.
1703 * Group Topics::                A folding group mode divided into topics.
1704 * Misc Group Stuff::            Other stuff that you can to do.
1705 @end menu
1706
1707
1708 @node Group Buffer Format
1709 @section Group Buffer Format
1710
1711 @menu
1712 * Group Line Specification::    Deciding how the group buffer is to look.
1713 * Group Modeline Specification::  The group buffer modeline.
1714 * Group Highlighting::          Having nice colors in the group buffer.
1715 @end menu
1716
1717
1718 @node Group Line Specification
1719 @subsection Group Line Specification
1720 @cindex group buffer format
1721
1722 The default format of the group buffer is nice and dull, but you can
1723 make it as exciting and ugly as you feel like.
1724
1725 Here's a couple of example group lines:
1726
1727 @example
1728      25: news.announce.newusers
1729  *    0: alt.fan.andrea-dworkin
1730 @end example
1731
1732 Quite simple, huh?
1733
1734 You can see that there are 25 unread articles in
1735 @samp{news.announce.newusers}.  There are no unread articles, but some
1736 ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
1737 asterisk at the beginning of the line?).
1738
1739 @vindex gnus-group-line-format
1740 You can change that format to whatever you want by fiddling with the
1741 @code{gnus-group-line-format} variable.  This variable works along the
1742 lines of a @code{format} specification, which is pretty much the same as
1743 a @code{printf} specifications, for those of you who use (feh!) C.
1744 @xref{Formatting Variables}.
1745
1746 @samp{%M%S%5y:%B%(%g%)\n} is the value that produced those lines above.
1747
1748 There should always be a colon on the line; the cursor always moves to
1749 the colon after performing an operation.  @xref{Positioning
1750 Point}. Nothing else is required---not even the group name.  All
1751 displayed text is just window dressing, and is never examined by Gnus.
1752 Gnus stores all real information it needs using text properties.
1753
1754 (Note that if you make a really strange, wonderful, spreadsheet-like
1755 layout, everybody will believe you are hard at work with the accounting
1756 instead of wasting time reading news.)
1757
1758 Here's a list of all available format characters:
1759
1760 @table @samp
1761
1762 @item M
1763 An asterisk if the group only has marked articles.
1764
1765 @item S
1766 Whether the group is subscribed.
1767
1768 @item L
1769 Level of subscribedness.
1770
1771 @item N
1772 Number of unread articles.
1773
1774 @item I
1775 Number of dormant articles.
1776
1777 @item T
1778 Number of ticked articles.
1779
1780 @item R
1781 Number of read articles.
1782
1783 @item U
1784 Number of unseen articles.
1785
1786 @item t
1787 Estimated total number of articles.  (This is really @var{max-number}
1788 minus @var{min-number} plus 1.)
1789
1790 Gnus uses this estimation because the @sc{nntp} protocol provides
1791 efficient access to @var{max-number} and @var{min-number} but getting
1792 the true unread message count is not possible efficiently.  For
1793 hysterical raisins, even the mail back ends, where the true number of
1794 unread messages might be available efficiently, use the same limited
1795 interface.  To remove this restriction from Gnus means that the back
1796 end interface has to be changed, which is not an easy job.  If you
1797 want to work on this, please contact the Gnus mailing list.
1798
1799 @item y
1800 Number of unread, unticked, non-dormant articles.
1801
1802 @item i
1803 Number of ticked and dormant articles.
1804
1805 @item g
1806 Full group name.
1807
1808 @item G
1809 Group name.
1810
1811 @item C
1812 Group comment (@pxref{Group Parameters}) or group name if there is no
1813 comment element in the group parameters.
1814
1815 @item D
1816 Newsgroup description.
1817
1818 @item o
1819 @samp{m} if moderated.
1820
1821 @item O
1822 @samp{(m)} if moderated.
1823
1824 @item s
1825 Select method.
1826
1827 @item B
1828 If the summary buffer for the group is open or not.
1829
1830 @item n
1831 Select from where.
1832
1833 @item z
1834 A string that looks like @samp{<%s:%n>} if a foreign select method is
1835 used.
1836
1837 @item P
1838 Indentation based on the level of the topic (@pxref{Group Topics}).
1839
1840 @item c
1841 @vindex gnus-group-uncollapsed-levels
1842 Short (collapsed) group name.  The @code{gnus-group-uncollapsed-levels}
1843 variable says how many levels to leave at the end of the group name.
1844 The default is 1---this will mean that group names like
1845 @samp{gnu.emacs.gnus} will be shortened to @samp{g.e.gnus}.
1846
1847 @item m
1848 @vindex gnus-new-mail-mark
1849 @cindex %
1850 @samp{%} (@code{gnus-new-mail-mark}) if there has arrived new mail to
1851 the group lately.
1852
1853 @item p
1854 @samp{#} (@code{gnus-process-mark}) if the group is process marked.
1855
1856 @item d
1857 A string that says when you last read the group (@pxref{Group
1858 Timestamp}).
1859
1860 @item u
1861 User defined specifier.  The next character in the format string should
1862 be a letter.  Gnus will call the function
1863 @code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
1864 following @samp{%u}.  The function will be passed a single dummy
1865 parameter as argument.  The function should return a string, which will
1866 be inserted into the buffer just like information from any other
1867 specifier.
1868 @end table
1869
1870 @cindex *
1871 All the ``number-of'' specs will be filled with an asterisk (@samp{*})
1872 if no info is available---for instance, if it is a non-activated foreign
1873 group, or a bogus native group.
1874
1875
1876 @node Group Modeline Specification
1877 @subsection Group Modeline Specification
1878 @cindex group modeline
1879
1880 @vindex gnus-group-mode-line-format
1881 The mode line can be changed by setting
1882 @code{gnus-group-mode-line-format} (@pxref{Mode Line Formatting}).  It
1883 doesn't understand that many format specifiers:
1884
1885 @table @samp
1886 @item S
1887 The native news server.
1888 @item M
1889 The native select method.
1890 @end table
1891
1892
1893 @node Group Highlighting
1894 @subsection Group Highlighting
1895 @cindex highlighting
1896 @cindex group highlighting
1897
1898 @vindex gnus-group-highlight
1899 Highlighting in the group buffer is controlled by the
1900 @code{gnus-group-highlight} variable.  This is an alist with elements
1901 that look like @code{(@var{form} . @var{face})}.  If @var{form} evaluates to
1902 something non-@code{nil}, the @var{face} will be used on the line.
1903
1904 Here's an example value for this variable that might look nice if the
1905 background is dark:
1906
1907 @lisp
1908 (cond (window-system
1909        (setq custom-background-mode 'light)
1910        (defface my-group-face-1
1911          '((t (:foreground "Red" :bold t))) "First group face")
1912        (defface my-group-face-2
1913          '((t (:foreground "DarkSeaGreen4" :bold t))) "Second group face")
1914        (defface my-group-face-3
1915          '((t (:foreground "Green4" :bold t))) "Third group face")
1916        (defface my-group-face-4
1917          '((t (:foreground "SteelBlue" :bold t))) "Fourth group face")
1918        (defface my-group-face-5
1919          '((t (:foreground "Blue" :bold t))) "Fifth group face")))
1920
1921 (setq gnus-group-highlight
1922       '(((> unread 200) . my-group-face-1)
1923         ((and (< level 3) (zerop unread)) . my-group-face-2)
1924         ((< level 3) . my-group-face-3)
1925         ((zerop unread) . my-group-face-4)
1926         (t . my-group-face-5)))
1927 @end lisp
1928
1929 Also @pxref{Faces and Fonts}.
1930
1931 Variables that are dynamically bound when the forms are evaluated
1932 include:
1933
1934 @table @code
1935 @item group
1936 The group name.
1937 @item unread
1938 The number of unread articles in the group.
1939 @item method
1940 The select method.
1941 @item mailp
1942 Whether the group is a mail group.
1943 @item level
1944 The level of the group.
1945 @item score
1946 The score of the group.
1947 @item ticked
1948 The number of ticked articles in the group.
1949 @item total
1950 The total number of articles in the group.  Or rather, MAX-NUMBER minus
1951 MIN-NUMBER plus one.
1952 @item topic
1953 When using the topic minor mode, this variable is bound to the current
1954 topic being inserted.
1955 @end table
1956
1957 When the forms are @code{eval}ed, point is at the beginning of the line
1958 of the group in question, so you can use many of the normal Gnus
1959 functions for snarfing info on the group.
1960
1961 @vindex gnus-group-update-hook
1962 @findex gnus-group-highlight-line
1963 @code{gnus-group-update-hook} is called when a group line is changed.
1964 It will not be called when @code{gnus-visual} is @code{nil}.  This hook
1965 calls @code{gnus-group-highlight-line} by default.
1966
1967
1968 @node Group Maneuvering
1969 @section Group Maneuvering
1970 @cindex group movement
1971
1972 All movement commands understand the numeric prefix and will behave as
1973 expected, hopefully.
1974
1975 @table @kbd
1976
1977 @item n
1978 @kindex n (Group)
1979 @findex gnus-group-next-unread-group
1980 Go to the next group that has unread articles
1981 (@code{gnus-group-next-unread-group}).
1982
1983 @item p
1984 @itemx DEL
1985 @kindex DEL (Group)
1986 @kindex p (Group)
1987 @findex gnus-group-prev-unread-group
1988 Go to the previous group that has unread articles
1989 (@code{gnus-group-prev-unread-group}).
1990
1991 @item N
1992 @kindex N (Group)
1993 @findex gnus-group-next-group
1994 Go to the next group (@code{gnus-group-next-group}).
1995
1996 @item P
1997 @kindex P (Group)
1998 @findex gnus-group-prev-group
1999 Go to the previous group (@code{gnus-group-prev-group}).
2000
2001 @item M-n
2002 @kindex M-n (Group)
2003 @findex gnus-group-next-unread-group-same-level
2004 Go to the next unread group on the same (or lower) level
2005 (@code{gnus-group-next-unread-group-same-level}).
2006
2007 @item M-p
2008 @kindex M-p (Group)
2009 @findex gnus-group-prev-unread-group-same-level
2010 Go to the previous unread group on the same (or lower) level
2011 (@code{gnus-group-prev-unread-group-same-level}).
2012 @end table
2013
2014 Three commands for jumping to groups:
2015
2016 @table @kbd
2017
2018 @item j
2019 @kindex j (Group)
2020 @findex gnus-group-jump-to-group
2021 Jump to a group (and make it visible if it isn't already)
2022 (@code{gnus-group-jump-to-group}).  Killed groups can be jumped to, just
2023 like living groups.
2024
2025 @item ,
2026 @kindex , (Group)
2027 @findex gnus-group-best-unread-group
2028 Jump to the unread group with the lowest level
2029 (@code{gnus-group-best-unread-group}).
2030
2031 @item .
2032 @kindex . (Group)
2033 @findex gnus-group-first-unread-group
2034 Jump to the first group with unread articles
2035 (@code{gnus-group-first-unread-group}).
2036 @end table
2037
2038 @vindex gnus-group-goto-unread
2039 If @code{gnus-group-goto-unread} is @code{nil}, all the movement
2040 commands will move to the next group, not the next unread group.  Even
2041 the commands that say they move to the next unread group.  The default
2042 is @code{t}.
2043
2044
2045 @node Selecting a Group
2046 @section Selecting a Group
2047 @cindex group selection
2048
2049 @table @kbd
2050
2051 @item SPACE
2052 @kindex SPACE (Group)
2053 @findex gnus-group-read-group
2054 Select the current group, switch to the summary buffer and display the
2055 first unread article (@code{gnus-group-read-group}).  If there are no
2056 unread articles in the group, or if you give a non-numerical prefix to
2057 this command, Gnus will offer to fetch all the old articles in this
2058 group from the server.  If you give a numerical prefix @var{N}, @var{N}
2059 determines the number of articles Gnus will fetch.  If @var{N} is
2060 positive, Gnus fetches the @var{N} newest articles, if @var{N} is
2061 negative, Gnus fetches the @code{abs(@var{N})} oldest articles.
2062
2063 Thus, @kbd{SPC} enters the group normally, @kbd{C-u SPC} offers old
2064 articles, @kbd{C-u 4 2 SPC} fetches the 42 newest articles, and @kbd{C-u
2065 - 4 2 SPC} fetches the 42 oldest ones.
2066
2067 When you are in the group (in the Summary buffer), you can type
2068 @kbd{M-g} to fetch new articles, or @kbd{C-u M-g} to also show the old
2069 ones.
2070
2071 @item RET
2072 @kindex RET (Group)
2073 @findex gnus-group-select-group
2074 Select the current group and switch to the summary buffer
2075 (@code{gnus-group-select-group}).  Takes the same arguments as
2076 @code{gnus-group-read-group}---the only difference is that this command
2077 does not display the first unread article automatically upon group
2078 entry.
2079
2080 @item M-RET
2081 @kindex M-RET (Group)
2082 @findex gnus-group-quick-select-group
2083 This does the same as the command above, but tries to do it with the
2084 minimum amount of fuzz (@code{gnus-group-quick-select-group}).  No
2085 scoring/killing will be performed, there will be no highlights and no
2086 expunging.  This might be useful if you're in a real hurry and have to
2087 enter some humongous group.  If you give a 0 prefix to this command
2088 (i.e., @kbd{0 M-RET}), Gnus won't even generate the summary buffer,
2089 which is useful if you want to toggle threading before generating the
2090 summary buffer (@pxref{Summary Generation Commands}).
2091
2092 @item M-SPACE
2093 @kindex M-SPACE (Group)
2094 @findex gnus-group-visible-select-group
2095 This is yet one more command that does the same as the @kbd{RET}
2096 command, but this one does it without expunging and hiding dormants
2097 (@code{gnus-group-visible-select-group}).
2098
2099 @item C-M-RET
2100 @kindex C-M-RET (Group)
2101 @findex gnus-group-select-group-ephemerally
2102 Finally, this command selects the current group ephemerally without
2103 doing any processing of its contents
2104 (@code{gnus-group-select-group-ephemerally}).  Even threading has been
2105 turned off.  Everything you do in the group after selecting it in this
2106 manner will have no permanent effects.
2107
2108 @end table
2109
2110 @vindex gnus-large-newsgroup
2111 The @code{gnus-large-newsgroup} variable says what Gnus should consider
2112 to be a big group.  This is 200 by default.  If the group has more
2113 (unread and/or ticked) articles than this, Gnus will query the user
2114 before entering the group.  The user can then specify how many articles
2115 should be fetched from the server.  If the user specifies a negative
2116 number (@code{-n}), the @code{n} oldest articles will be fetched.  If it
2117 is positive, the @code{n} articles that have arrived most recently will
2118 be fetched.
2119
2120 @vindex gnus-select-group-hook
2121 @vindex gnus-auto-select-first
2122 If @code{gnus-auto-select-first} is non-@code{nil}, select an article
2123 automatically when entering a group with the @kbd{SPACE} command.
2124 Which article this is is controlled by the
2125 @code{gnus-auto-select-subject} variable.  Valid values for this
2126 variable is:
2127
2128 @table @code
2129
2130 @item unread
2131 Place point on the subject line of the first unread article.
2132
2133 @item first
2134 Place point on the subject line of the first article.
2135
2136 @item unseen
2137 Place point on the subject line of the first unseen article.
2138
2139 @item unseen-or-unread
2140 Place point on the subject line of the first unseen article, and if
2141 there is no such article, place point on the subject line of the first
2142 unread article.
2143
2144 @item best
2145 Place point on the subject line of the highest-scored unread article.
2146
2147 @end table
2148
2149 This variable can also be a function.  In that case, that function
2150 will be called to place point on a subject line.
2151
2152 If you want to prevent automatic selection in some group (say, in a
2153 binary group with Huge articles) you can set the
2154 @code{gnus-auto-select-first} variable to @code{nil} in
2155 @code{gnus-select-group-hook}, which is called when a group is
2156 selected.
2157
2158
2159 @node Subscription Commands
2160 @section Subscription Commands
2161 @cindex subscription
2162
2163 @table @kbd
2164
2165 @item S t
2166 @itemx u
2167 @kindex S t (Group)
2168 @kindex u (Group)
2169 @findex gnus-group-unsubscribe-current-group
2170 @c @icon{gnus-group-unsubscribe}
2171 Toggle subscription to the current group
2172 (@code{gnus-group-unsubscribe-current-group}).
2173
2174 @item S s
2175 @itemx U
2176 @kindex S s (Group)
2177 @kindex U (Group)
2178 @findex gnus-group-unsubscribe-group
2179 Prompt for a group to subscribe, and then subscribe it.  If it was
2180 subscribed already, unsubscribe it instead
2181 (@code{gnus-group-unsubscribe-group}).
2182
2183 @item S k
2184 @itemx C-k
2185 @kindex S k (Group)
2186 @kindex C-k (Group)
2187 @findex gnus-group-kill-group
2188 @c @icon{gnus-group-kill-group}
2189 Kill the current group (@code{gnus-group-kill-group}).
2190
2191 @item S y
2192 @itemx C-y
2193 @kindex S y (Group)
2194 @kindex C-y (Group)
2195 @findex gnus-group-yank-group
2196 Yank the last killed group (@code{gnus-group-yank-group}).
2197
2198 @item C-x C-t
2199 @kindex C-x C-t (Group)
2200 @findex gnus-group-transpose-groups
2201 Transpose two groups (@code{gnus-group-transpose-groups}).  This isn't
2202 really a subscription command, but you can use it instead of a
2203 kill-and-yank sequence sometimes.
2204
2205 @item S w
2206 @itemx C-w
2207 @kindex S w (Group)
2208 @kindex C-w (Group)
2209 @findex gnus-group-kill-region
2210 Kill all groups in the region (@code{gnus-group-kill-region}).
2211
2212 @item S z
2213 @kindex S z (Group)
2214 @findex gnus-group-kill-all-zombies
2215 Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
2216
2217 @item S C-k
2218 @kindex S C-k (Group)
2219 @findex gnus-group-kill-level
2220 Kill all groups on a certain level (@code{gnus-group-kill-level}).
2221 These groups can't be yanked back after killing, so this command should
2222 be used with some caution.  The only time where this command comes in
2223 really handy is when you have a @file{.newsrc} with lots of unsubscribed
2224 groups that you want to get rid off.  @kbd{S C-k} on level 7 will
2225 kill off all unsubscribed groups that do not have message numbers in the
2226 @file{.newsrc} file.
2227
2228 @end table
2229
2230 Also @pxref{Group Levels}.
2231
2232
2233 @node Group Data
2234 @section Group Data
2235
2236 @table @kbd
2237
2238 @item c
2239 @kindex c (Group)
2240 @findex gnus-group-catchup-current
2241 @vindex gnus-group-catchup-group-hook
2242 @c @icon{gnus-group-catchup-current}
2243 Mark all unticked articles in this group as read
2244 (@code{gnus-group-catchup-current}).
2245 @code{gnus-group-catchup-group-hook} is called when catching up a group from
2246 the group buffer.
2247
2248 @item C
2249 @kindex C (Group)
2250 @findex gnus-group-catchup-current-all
2251 Mark all articles in this group, even the ticked ones, as read
2252 (@code{gnus-group-catchup-current-all}).
2253
2254 @item M-c
2255 @kindex M-c (Group)
2256 @findex gnus-group-clear-data
2257 Clear the data from the current group---nix out marks and the list of
2258 read articles (@code{gnus-group-clear-data}).
2259
2260 @item M-x gnus-group-clear-data-on-native-groups
2261 @kindex M-x gnus-group-clear-data-on-native-groups
2262 @findex gnus-group-clear-data-on-native-groups
2263 If you have switched from one @sc{nntp} server to another, all your marks
2264 and read ranges have become worthless.  You can use this command to
2265 clear out all data that you have on your native groups.  Use with
2266 caution.
2267
2268 @end table
2269
2270
2271 @node Group Levels
2272 @section Group Levels
2273 @cindex group level
2274 @cindex level
2275
2276 All groups have a level of @dfn{subscribedness}.  For instance, if a
2277 group is on level 2, it is more subscribed than a group on level 5.  You
2278 can ask Gnus to just list groups on a given level or lower
2279 (@pxref{Listing Groups}), or to just check for new articles in groups on
2280 a given level or lower (@pxref{Scanning New Messages}).
2281
2282 Remember:  The higher the level of the group, the less important it is.
2283
2284 @table @kbd
2285
2286 @item S l
2287 @kindex S l (Group)
2288 @findex gnus-group-set-current-level
2289 Set the level of the current group.  If a numeric prefix is given, the
2290 next @var{n} groups will have their levels set.  The user will be
2291 prompted for a level.
2292 @end table
2293
2294 @vindex gnus-level-killed
2295 @vindex gnus-level-zombie
2296 @vindex gnus-level-unsubscribed
2297 @vindex gnus-level-subscribed
2298 Gnus considers groups from levels 1 to
2299 @code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
2300 @code{gnus-level-subscribed} (exclusive) and
2301 @code{gnus-level-unsubscribed} (inclusive) (default 7) to be
2302 unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
2303 (default 8) and @code{gnus-level-killed} to be killed (completely dead)
2304 (default 9).  Gnus treats subscribed and unsubscribed groups exactly the
2305 same, but zombie and killed groups have no information on what articles
2306 you have read, etc, stored.  This distinction between dead and living
2307 groups isn't done because it is nice or clever, it is done purely for
2308 reasons of efficiency.
2309
2310 It is recommended that you keep all your mail groups (if any) on quite
2311 low levels (e.g. 1 or 2).
2312
2313 Maybe the following description of the default behavior of Gnus helps to
2314 understand what these levels are all about.  By default, Gnus shows you
2315 subscribed nonempty groups, but by hitting @kbd{L} you can have it show
2316 empty subscribed groups and unsubscribed groups, too.  Type @kbd{l} to
2317 go back to showing nonempty subscribed groups again.  Thus, unsubscribed
2318 groups are hidden, in a way.
2319
2320 Zombie and killed groups are similar to unsubscribed groups in that they
2321 are hidden by default.  But they are different from subscribed and
2322 unsubscribed groups in that Gnus doesn't ask the news server for
2323 information (number of messages, number of unread messages) on zombie
2324 and killed groups.  Normally, you use @kbd{C-k} to kill the groups you
2325 aren't interested in.  If most groups are killed, Gnus is faster.
2326
2327 Why does Gnus distinguish between zombie and killed groups?  Well, when
2328 a new group arrives on the server, Gnus by default makes it a zombie
2329 group.  This means that you are normally not bothered with new groups,
2330 but you can type @kbd{A z} to get a list of all new groups.  Subscribe
2331 the ones you like and kill the ones you don't want.  (@kbd{A k} shows a
2332 list of killed groups.)
2333
2334 If you want to play with the level variables, you should show some care.
2335 Set them once, and don't touch them ever again.  Better yet, don't touch
2336 them at all unless you know exactly what you're doing.
2337
2338 @vindex gnus-level-default-unsubscribed
2339 @vindex gnus-level-default-subscribed
2340 Two closely related variables are @code{gnus-level-default-subscribed}
2341 (default 3) and @code{gnus-level-default-unsubscribed} (default 6),
2342 which are the levels that new groups will be put on if they are
2343 (un)subscribed.  These two variables should, of course, be inside the
2344 relevant valid ranges.
2345
2346 @vindex gnus-keep-same-level
2347 If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
2348 will only move to groups of the same level (or lower).  In
2349 particular, going from the last article in one group to the next group
2350 will go to the next group of the same level (or lower).  This might be
2351 handy if you want to read the most important groups before you read the
2352 rest.
2353
2354 If this variable is @code{best}, Gnus will make the next newsgroup the
2355 one with the best level.
2356
2357 @vindex gnus-group-default-list-level
2358 All groups with a level less than or equal to
2359 @code{gnus-group-default-list-level} will be listed in the group buffer
2360 by default.
2361
2362 @vindex gnus-group-list-inactive-groups
2363 If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
2364 groups will be listed along with the unread groups.  This variable is
2365 @code{t} by default.  If it is @code{nil}, inactive groups won't be
2366 listed.
2367
2368 @vindex gnus-group-use-permanent-levels
2369 If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you
2370 give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
2371 use this level as the ``work'' level.
2372
2373 @vindex gnus-activate-level
2374 Gnus will normally just activate (i. e., query the server about) groups
2375 on level @code{gnus-activate-level} or less.  If you don't want to
2376 activate unsubscribed groups, for instance, you might set this variable
2377 to 5.  The default is 6.
2378
2379
2380 @node Group Score
2381 @section Group Score
2382 @cindex group score
2383 @cindex group rank
2384 @cindex rank
2385
2386 You would normally keep important groups on high levels, but that scheme
2387 is somewhat restrictive.  Don't you wish you could have Gnus sort the
2388 group buffer according to how often you read groups, perhaps?  Within
2389 reason?
2390
2391 This is what @dfn{group score} is for.  You can have Gnus assign a score
2392 to each group through the mechanism described below.  You can then sort
2393 the group buffer based on this score.  Alternatively, you can sort on
2394 score and then level.  (Taken together, the level and the score is
2395 called the @dfn{rank} of the group.  A group that is on level 4 and has
2396 a score of 1 has a higher rank than a group on level 5 that has a score
2397 of 300.  (The level is the most significant part and the score is the
2398 least significant part.))
2399
2400 @findex gnus-summary-bubble-group
2401 If you want groups you read often to get higher scores than groups you
2402 read seldom you can add the @code{gnus-summary-bubble-group} function to
2403 the @code{gnus-summary-exit-hook} hook.  This will result (after
2404 sorting) in a bubbling sort of action.  If you want to see that in
2405 action after each summary exit, you can add
2406 @code{gnus-group-sort-groups-by-rank} or
2407 @code{gnus-group-sort-groups-by-score} to the same hook, but that will
2408 slow things down somewhat.
2409
2410
2411 @node Marking Groups
2412 @section Marking Groups
2413 @cindex marking groups
2414
2415 If you want to perform some command on several groups, and they appear
2416 subsequently in the group buffer, you would normally just give a
2417 numerical prefix to the command.  Most group commands will then do your
2418 bidding on those groups.
2419
2420 However, if the groups are not in sequential order, you can still
2421 perform a command on several groups.  You simply mark the groups first
2422 with the process mark and then execute the command.
2423
2424 @table @kbd
2425
2426 @item #
2427 @kindex # (Group)
2428 @itemx M m
2429 @kindex M m (Group)
2430 @findex gnus-group-mark-group
2431 Set the mark on the current group (@code{gnus-group-mark-group}).
2432
2433 @item M-#
2434 @kindex M-# (Group)
2435 @itemx M u
2436 @kindex M u (Group)
2437 @findex gnus-group-unmark-group
2438 Remove the mark from the current group
2439 (@code{gnus-group-unmark-group}).
2440
2441 @item M U
2442 @kindex M U (Group)
2443 @findex gnus-group-unmark-all-groups
2444 Remove the mark from all groups (@code{gnus-group-unmark-all-groups}).
2445
2446 @item M w
2447 @kindex M w (Group)
2448 @findex gnus-group-mark-region
2449 Mark all groups between point and mark (@code{gnus-group-mark-region}).
2450
2451 @item M b
2452 @kindex M b (Group)
2453 @findex gnus-group-mark-buffer
2454 Mark all groups in the buffer (@code{gnus-group-mark-buffer}).
2455
2456 @item M r
2457 @kindex M r (Group)
2458 @findex gnus-group-mark-regexp
2459 Mark all groups that match some regular expression
2460 (@code{gnus-group-mark-regexp}).
2461 @end table
2462
2463 Also @pxref{Process/Prefix}.
2464
2465 @findex gnus-group-universal-argument
2466 If you want to execute some command on all groups that have been marked
2467 with the process mark, you can use the @kbd{M-&}
2468 (@code{gnus-group-universal-argument}) command.  It will prompt you for
2469 the command to be executed.
2470
2471
2472 @node Foreign Groups
2473 @section Foreign Groups
2474 @cindex foreign groups
2475
2476 Below are some group mode commands for making and editing general foreign
2477 groups, as well as commands to ease the creation of a few
2478 special-purpose groups.  All these commands insert the newly created
2479 groups under point---@code{gnus-subscribe-newsgroup-method} is not
2480 consulted.
2481
2482 @table @kbd
2483
2484 @item G m
2485 @kindex G m (Group)
2486 @findex gnus-group-make-group
2487 @cindex making groups
2488 Make a new group (@code{gnus-group-make-group}).  Gnus will prompt you
2489 for a name, a method and possibly an @dfn{address}.  For an easier way
2490 to subscribe to @sc{nntp} groups, @pxref{Browse Foreign Server}.
2491
2492 @item G r
2493 @kindex G r (Group)
2494 @findex gnus-group-rename-group
2495 @cindex renaming groups
2496 Rename the current group to something else
2497 (@code{gnus-group-rename-group}).  This is valid only on some
2498 groups---mail groups mostly.  This command might very well be quite slow
2499 on some back ends.
2500
2501 @item G c
2502 @kindex G c (Group)
2503 @cindex customizing
2504 @findex gnus-group-customize
2505 Customize the group parameters (@code{gnus-group-customize}).
2506
2507 @item G e
2508 @kindex G e (Group)
2509 @findex gnus-group-edit-group-method
2510 @cindex renaming groups
2511 Enter a buffer where you can edit the select method of the current
2512 group (@code{gnus-group-edit-group-method}).
2513
2514 @item G p
2515 @kindex G p (Group)
2516 @findex gnus-group-edit-group-parameters
2517 Enter a buffer where you can edit the group parameters
2518 (@code{gnus-group-edit-group-parameters}).
2519
2520 @item G E
2521 @kindex G E (Group)
2522 @findex gnus-group-edit-group
2523 Enter a buffer where you can edit the group info
2524 (@code{gnus-group-edit-group}).
2525
2526 @item G d
2527 @kindex G d (Group)
2528 @findex gnus-group-make-directory-group
2529 @cindex nndir
2530 Make a directory group (@pxref{Directory Groups}).  You will be prompted
2531 for a directory name (@code{gnus-group-make-directory-group}).
2532
2533 @item G h
2534 @kindex G h (Group)
2535 @cindex help group
2536 @findex gnus-group-make-help-group
2537 Make the Gnus help group (@code{gnus-group-make-help-group}).
2538
2539 @item G a
2540 @kindex G a (Group)
2541 @cindex (ding) archive
2542 @cindex archive group
2543 @findex gnus-group-make-archive-group
2544 @vindex gnus-group-archive-directory
2545 @vindex gnus-group-recent-archive-directory
2546 Make a Gnus archive group (@code{gnus-group-make-archive-group}).  By
2547 default a group pointing to the most recent articles will be created
2548 (@code{gnus-group-recent-archive-directory}), but given a prefix, a full
2549 group will be created from @code{gnus-group-archive-directory}.
2550
2551 @item G k
2552 @kindex G k (Group)
2553 @findex gnus-group-make-kiboze-group
2554 @cindex nnkiboze
2555 Make a kiboze group.  You will be prompted for a name, for a regexp to
2556 match groups to be ``included'' in the kiboze group, and a series of
2557 strings to match on headers (@code{gnus-group-make-kiboze-group}).
2558 @xref{Kibozed Groups}.
2559
2560 @item G D
2561 @kindex G D (Group)
2562 @findex gnus-group-enter-directory
2563 @cindex nneething
2564 Read an arbitrary directory as if it were a newsgroup with the
2565 @code{nneething} back end (@code{gnus-group-enter-directory}).
2566 @xref{Anything Groups}.
2567
2568 @item G f
2569 @kindex G f (Group)
2570 @findex gnus-group-make-doc-group
2571 @cindex ClariNet Briefs
2572 @cindex nndoc
2573 Make a group based on some file or other
2574 (@code{gnus-group-make-doc-group}).  If you give a prefix to this
2575 command, you will be prompted for a file name and a file type.
2576 Currently supported types are @code{mbox}, @code{babyl},
2577 @code{digest}, @code{news}, @code{rnews}, @code{mmdf}, @code{forward},
2578 @code{rfc934}, @code{rfc822-forward}, @code{mime-parts},
2579 @code{standard-digest}, @code{slack-digest}, @code{clari-briefs},
2580 @code{nsmail}, @code{outlook}, @code{oe-dbx}, and @code{mailman}.  If
2581 you run this command without a prefix, Gnus will guess at the file
2582 type.  @xref{Document Groups}.
2583
2584 @item G u
2585 @kindex G u (Group)
2586 @vindex gnus-useful-groups
2587 @findex gnus-group-make-useful-group
2588 Create one of the groups mentioned in @code{gnus-useful-groups}
2589 (@code{gnus-group-make-useful-group}).
2590
2591 @item G w
2592 @kindex G w (Group)
2593 @findex gnus-group-make-web-group
2594 @cindex Google
2595 @cindex nnweb
2596 @cindex gmane
2597 Make an ephemeral group based on a web search
2598 (@code{gnus-group-make-web-group}).  If you give a prefix to this
2599 command, make a solid group instead.  You will be prompted for the
2600 search engine type and the search string.  Valid search engine types
2601 include @code{google}, @code{dejanews}, and @code{gmane}.
2602 @xref{Web Searches}.
2603
2604 If you use the @code{google} search engine, you can limit the search
2605 to a particular group by using a match string like
2606 @samp{shaving group:alt.sysadmin.recovery}.
2607
2608 @item G DEL
2609 @kindex G DEL (Group)
2610 @findex gnus-group-delete-group
2611 This function will delete the current group
2612 (@code{gnus-group-delete-group}).  If given a prefix, this function will
2613 actually delete all the articles in the group, and forcibly remove the
2614 group itself from the face of the Earth.  Use a prefix only if you are
2615 absolutely sure of what you are doing.  This command can't be used on
2616 read-only groups (like @code{nntp} group), though.
2617
2618 @item G V
2619 @kindex G V (Group)
2620 @findex gnus-group-make-empty-virtual
2621 Make a new, fresh, empty @code{nnvirtual} group
2622 (@code{gnus-group-make-empty-virtual}).  @xref{Virtual Groups}.
2623
2624 @item G v
2625 @kindex G v (Group)
2626 @findex gnus-group-add-to-virtual
2627 Add the current group to an @code{nnvirtual} group
2628 (@code{gnus-group-add-to-virtual}).  Uses the process/prefix convention.
2629 @end table
2630
2631 @xref{Select Methods}, for more information on the various select
2632 methods.
2633
2634 @vindex gnus-activate-foreign-newsgroups
2635 If @code{gnus-activate-foreign-newsgroups} is a positive number,
2636 Gnus will check all foreign groups with this level or lower at startup.
2637 This might take quite a while, especially if you subscribe to lots of
2638 groups from different @sc{nntp} servers.  Also @pxref{Group Levels};
2639 @code{gnus-activate-level} also affects activation of foreign
2640 newsgroups.
2641
2642
2643 @node Group Parameters
2644 @section Group Parameters
2645 @cindex group parameters
2646
2647 The group parameters store information local to a particular group.
2648 Here's an example group parameter list:
2649
2650 @example
2651 ((to-address . "ding@@gnus.org")
2652  (auto-expire . t))
2653 @end example
2654
2655 We see that each element consists of a "dotted pair"---the thing before
2656 the dot is the key, while the thing after the dot is the value.  All the
2657 parameters have this form @emph{except} local variable specs, which are
2658 not dotted pairs, but proper lists.
2659
2660 Some parameters have correspondant customizable variables, each of which
2661 is an alist of regexps and values.
2662
2663 The following group parameters can be used:
2664
2665 @table @code
2666 @item to-address
2667 @cindex to-address
2668 Address used by when doing followups and new posts.
2669
2670 @example
2671 (to-address . "some@@where.com")
2672 @end example
2673
2674 This is primarily useful in mail groups that represent closed mailing
2675 lists---mailing lists where it's expected that everybody that writes to
2676 the mailing list is subscribed to it.  Since using this parameter
2677 ensures that the mail only goes to the mailing list itself, it means
2678 that members won't receive two copies of your followups.
2679
2680 Using @code{to-address} will actually work whether the group is foreign
2681 or not.  Let's say there's a group on the server that is called
2682 @samp{fa.4ad-l}.  This is a real newsgroup, but the server has gotten
2683 the articles from a mail-to-news gateway.  Posting directly to this
2684 group is therefore impossible---you have to send mail to the mailing
2685 list address instead.
2686
2687 See also @code{gnus-parameter-to-address-alist}.
2688
2689 @item to-list
2690 @cindex to-list
2691 Address used when doing @kbd{a} in that group.
2692
2693 @example
2694 (to-list . "some@@where.com")
2695 @end example
2696
2697 It is totally ignored
2698 when doing a followup---except that if it is present in a news group,
2699 you'll get mail group semantics when doing @kbd{f}.
2700
2701 If you do an @kbd{a} command in a mail group and you have neither a
2702 @code{to-list} group parameter nor a @code{to-address} group parameter,
2703 then a @code{to-list} group parameter will be added automatically upon
2704 sending the message if @code{gnus-add-to-list} is set to @code{t}.
2705 @vindex gnus-add-to-list
2706
2707 If you do an @kbd{a} command in a mail group and you don't have a
2708 @code{to-list} group parameter, one will be added automatically upon
2709 sending the message.
2710
2711 @findex gnus-mailing-list-mode
2712 @cindex Mail List Groups
2713 If this variable is set, @code{gnus-mailing-list-mode} is turned on when
2714 entering summary buffer.
2715
2716 See also @code{gnus-parameter-to-list-alist}.
2717
2718 @anchor{subscribed}
2719 @item subscribed
2720 @cindex subscribed
2721 If this parameter is set to @code{t}, Gnus will consider the
2722 to-address and to-list parameters for this group as addresses of
2723 mailing lists you are subscribed to.  Giving Gnus this information is
2724 (only) a first step in getting it to generate correct Mail-Followup-To
2725 headers for your posts to these lists.  Look here @pxref{(message)Mailing
2726 Lists} for a complete treatment of available MFT support.
2727
2728 See also @code{gnus-find-subscribed-addresses}, the function that
2729 directly uses this group parameter.
2730
2731 @item visible
2732 @cindex visible
2733 If the group parameter list has the element @code{(visible . t)},
2734 that group will always be visible in the Group buffer, regardless
2735 of whether it has any unread articles.
2736
2737 @item broken-reply-to
2738 @cindex broken-reply-to
2739 Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To}
2740 headers in this group are to be ignored.  This can be useful if you're
2741 reading a mailing list group where the listserv has inserted
2742 @code{Reply-To} headers that point back to the listserv itself.  This is
2743 broken behavior.  So there!
2744
2745 @item to-group
2746 @cindex to-group
2747 Elements like @code{(to-group . "some.group.name")} means that all
2748 posts in that group will be sent to @code{some.group.name}.
2749
2750 @item newsgroup
2751 @cindex newsgroup
2752 If you have @code{(newsgroup . t)} in the group parameter list, Gnus
2753 will treat all responses as if they were responses to news articles.
2754 This can be useful if you have a mail group that's really a mirror of a
2755 news group.
2756
2757 @item gcc-self
2758 @cindex gcc-self
2759 If @code{(gcc-self . t)} is present in the group parameter list, newly
2760 composed messages will be @code{Gcc}'d to the current group.  If
2761 @code{(gcc-self . none)} is present, no @code{Gcc:} header will be
2762 generated, if @code{(gcc-self . "string")} is present, this string will
2763 be inserted literally as a @code{gcc} header.  This parameter takes
2764 precedence over any default @code{Gcc} rules as described later
2765 (@pxref{Archived Messages}).  CAVEAT:: It yields an error putting
2766 @code{(gcc-self . t)} in groups of a @code{nntp} server or so, because
2767 a @code{nntp} server doesn't accept articles.
2768
2769 @item auto-expire
2770 @cindex auto-expire
2771 If the group parameter has an element that looks like @code{(auto-expire
2772 . t)}, all articles read will be marked as expirable.  For an
2773 alternative approach, @pxref{Expiring Mail}.
2774
2775 See also @code{gnus-auto-expirable-newsgroups}.
2776
2777 @item total-expire
2778 @cindex total-expire
2779 If the group parameter has an element that looks like
2780 @code{(total-expire . t)}, all read articles will be put through the
2781 expiry process, even if they are not marked as expirable.  Use with
2782 caution.  Unread, ticked and dormant articles are not eligible for
2783 expiry.
2784
2785 See also @code{gnus-total-expirable-newsgroups}.
2786
2787 @item expiry-wait
2788 @cindex expiry-wait
2789 @vindex nnmail-expiry-wait-function
2790 If the group parameter has an element that looks like
2791 @code{(expiry-wait . 10)}, this value will override any
2792 @code{nnmail-expiry-wait} and @code{nnmail-expiry-wait-function}
2793 (@pxref{Expiring Mail}) when expiring expirable messages.  The value
2794 can either be a number of days (not necessarily an integer) or the
2795 symbols @code{never} or @code{immediate}.
2796
2797 @item score-file
2798 @cindex score file group parameter
2799 Elements that look like @code{(score-file . "file")} will make
2800 @file{file} into the current score file for the group in question.  All
2801 interactive score entries will be put into this file.
2802
2803 @item adapt-file
2804 @cindex adapt file group parameter
2805 Elements that look like @code{(adapt-file . "file")} will make
2806 @file{file} into the current adaptive file for the group in question.
2807 All adaptive score entries will be put into this file.
2808
2809 @item admin-address
2810 @cindex admin-address
2811 When unsubscribing from a mailing list you should never send the
2812 unsubscription notice to the mailing list itself.  Instead, you'd send
2813 messages to the administrative address.  This parameter allows you to
2814 put the admin address somewhere convenient.
2815
2816 @item display
2817 @cindex display
2818 Elements that look like @code{(display . MODE)} say which articles to
2819 display on entering the group.  Valid values are:
2820
2821 @table @code
2822 @item all
2823 Display all articles, both read and unread.
2824
2825 @item an integer
2826 Display the last INTEGER articles in the group.  This is the same as
2827 entering the group with C-u INTEGER.
2828
2829 @item default
2830 Display the default visible articles, which normally includes unread and
2831 ticked articles.
2832
2833 @item an array
2834 Display articles that satisfy a predicate.
2835
2836 Here are some examples:
2837
2838 @table @code
2839 @item [unread]
2840 Display only unread articles.
2841
2842 @item [not expire]
2843 Display everything except expirable articles.
2844
2845 @item [and (not reply) (not expire)]
2846 Display everything except expirable and articles you've already
2847 responded to.
2848 @end table
2849
2850 The available operators are @code{not}, @code{and} and @code{or}.
2851 Predicates include @code{tick}, @code{unsend}, @code{undownload},
2852 @code{unread}, @code{dormant}, @code{expire}, @code{reply},
2853 @code{killed}, @code{bookmark}, @code{score}, @code{save},
2854 @code{cache}, @code{forward}, @code{unseen} and @code{recent}.
2855
2856 @end table
2857
2858 The @code{display} parameter works by limiting the summary buffer to
2859 the subset specified.  You can pop the limit by using the @kbd{/ w}
2860 command (@pxref{Limiting}).
2861
2862 @item comment
2863 @cindex comment
2864 Elements that look like @code{(comment . "This is a comment")} are
2865 arbitrary comments on the group.  You can display comments in the
2866 group line (@pxref{Group Line Specification}).
2867
2868 @item charset
2869 @cindex charset
2870 Elements that look like @code{(charset . iso-8859-1)} will make
2871 @code{iso-8859-1} the default charset; that is, the charset that will be
2872 used for all articles that do not specify a charset.
2873
2874 See also @code{gnus-group-charset-alist}.
2875
2876 @item ignored-charsets
2877 @cindex ignored-charset
2878 Elements that look like @code{(ignored-charsets x-unknown iso-8859-1)}
2879 will make @code{iso-8859-1} and @code{x-unknown} ignored; that is, the
2880 default charset will be used for decoding articles.
2881
2882 See also @code{gnus-group-ignored-charsets-alist}.
2883
2884 @item posting-style
2885 @cindex posting-style
2886 You can store additional posting style information for this group
2887 here (@pxref{Posting Styles}).  The format is that of an entry in the
2888 @code{gnus-posting-styles} alist, except that there's no regexp matching
2889 the group name (of course).  Style elements in this group parameter will
2890 take precedence over the ones found in @code{gnus-posting-styles}.
2891
2892 For instance, if you want a funky name and signature in this group only,
2893 instead of hacking @code{gnus-posting-styles}, you could put something
2894 like this in the group parameters:
2895
2896 @example
2897 (posting-style
2898   (name "Funky Name")
2899   ("X-My-Header" "Funky Value")
2900   (signature "Funky Signature"))
2901 @end example
2902
2903 @item post-method
2904 @cindex post-method
2905 If it is set, the value is used as the method for posting message
2906 instead of @code{gnus-post-method}.
2907
2908 @item banner
2909 @cindex banner
2910 An item like @code{(banner . "regex")} causes any part of an article
2911 that matches the regular expression "regex" to be stripped. Instead of
2912 "regex", you can also use the symbol @code{signature} which strips the
2913 last signature or any of the elements of the alist
2914 @code{gnus-article-banner-alist}.
2915
2916 @item sieve
2917 @cindex sieve
2918 This parameter contains a Sieve test that should match incoming mail
2919 that should be placed in this group.  From this group parameter, a
2920 Sieve @samp{IF} control structure is generated, having the test as the
2921 condition and @samp{fileinto "group.name";} as the body.
2922
2923 For example, if the INBOX.list.sieve group has the @code{(sieve
2924 address "sender" "sieve-admin@@extundo.com")} group parameter, when
2925 translating the group parameter into a Sieve script (@pxref{Sieve
2926 Commands}) the following Sieve code is generated:
2927
2928 @example
2929 if address \"sender\" \"sieve-admin@@extundo.com\" @{
2930         fileinto \"INBOX.list.sieve\";
2931 @}
2932 @end example
2933
2934 The Sieve language is described in RFC 3028.  @xref{Top, , Top, sieve,
2935 Emacs Sieve}.
2936
2937 @item (@var{variable} @var{form})
2938 You can use the group parameters to set variables local to the group you
2939 are entering.  If you want to turn threading off in @samp{news.answers},
2940 you could put @code{(gnus-show-threads nil)} in the group parameters of
2941 that group.  @code{gnus-show-threads} will be made into a local variable
2942 in the summary buffer you enter, and the form @code{nil} will be
2943 @code{eval}ed there.
2944
2945 @vindex gnus-list-identifiers
2946 A use for this feature, is to remove a mailing list identifier tag in
2947 the subject fields of articles.   E.g. if the news group
2948 @samp{nntp+news.gnus.org:gmane.text.docbook.apps} has the tag
2949 @samp{DOC-BOOK-APPS:} in the subject of all articles, this tag can be
2950 removed from the article subjects in the summary buffer for the group by
2951 putting @code{(gnus-list-identifiers "DOCBOOK-APPS:")} into the group
2952 parameters for the group.
2953
2954
2955 This can also be used as a group-specific hook function, if you'd like.
2956 If you want to hear a beep when you enter a group, you could put
2957 something like @code{(dummy-variable (ding))} in the parameters of that
2958 group.  @code{dummy-variable} will be set to the result of the
2959 @code{(ding)} form, but who cares?
2960
2961 @end table
2962
2963 Use the @kbd{G p} or the @kbd{G c} command to edit group parameters of a
2964 group.  (@kbd{G p} presents you with a Lisp-based interface, @kbd{G c}
2965 presents you with a Customize-like interface.  The latter helps avoid
2966 silly Lisp errors.)  You might also be interested in reading about topic
2967 parameters (@pxref{Topic Parameters}).
2968
2969 Group parameters can be set via the @code{gnus-parameters} variable too.
2970 But some variables, such as @code{visible}, have no effect.  For
2971 example:
2972
2973 @example
2974 (setq gnus-parameters
2975       '(("mail\\..*"
2976          (gnus-show-threads nil)
2977          (gnus-use-scoring nil)
2978          (gnus-summary-line-format
2979           "%U%R%z%I%(%[%d:%ub%-23,23f%]%) %s\n")
2980          (gcc-self . t)
2981          (display . all))
2982
2983         ("^nnimap:\\(foo.bar\\)$"
2984          (to-group . "\\1"))
2985
2986         ("mail\\.me"
2987          (gnus-use-scoring  t))
2988
2989         ("list\\..*"
2990          (total-expire . t)
2991          (broken-reply-to . t))))
2992 @end example
2993
2994 String value of parameters will be subjected to regexp substitution, as
2995 the @code{to-group} example shows.
2996
2997
2998 @node Listing Groups
2999 @section Listing Groups
3000 @cindex group listing
3001
3002 These commands all list various slices of the groups available.
3003
3004 @table @kbd
3005
3006 @item l
3007 @itemx A s
3008 @kindex A s (Group)
3009 @kindex l (Group)
3010 @findex gnus-group-list-groups
3011 List all groups that have unread articles
3012 (@code{gnus-group-list-groups}).  If the numeric prefix is used, this
3013 command will list only groups of level ARG and lower.  By default, it
3014 only lists groups of level five (i. e.,
3015 @code{gnus-group-default-list-level}) or lower (i.e., just subscribed
3016 groups).
3017
3018 @item L
3019 @itemx A u
3020 @kindex A u (Group)
3021 @kindex L (Group)
3022 @findex gnus-group-list-all-groups
3023 List all groups, whether they have unread articles or not
3024 (@code{gnus-group-list-all-groups}).  If the numeric prefix is used,
3025 this command will list only groups of level ARG and lower.  By default,
3026 it lists groups of level seven or lower (i.e., just subscribed and
3027 unsubscribed groups).
3028
3029 @item A l
3030 @kindex A l (Group)
3031 @findex gnus-group-list-level
3032 List all unread groups on a specific level
3033 (@code{gnus-group-list-level}).  If given a prefix, also list the groups
3034 with no unread articles.
3035
3036 @item A k
3037 @kindex A k (Group)
3038 @findex gnus-group-list-killed
3039 List all killed groups (@code{gnus-group-list-killed}).  If given a
3040 prefix argument, really list all groups that are available, but aren't
3041 currently (un)subscribed.  This could entail reading the active file
3042 from the server.
3043
3044 @item A z
3045 @kindex A z (Group)
3046 @findex gnus-group-list-zombies
3047 List all zombie groups (@code{gnus-group-list-zombies}).
3048
3049 @item A m
3050 @kindex A m (Group)
3051 @findex gnus-group-list-matching
3052 List all unread, subscribed groups with names that match a regexp
3053 (@code{gnus-group-list-matching}).
3054
3055 @item A M
3056 @kindex A M (Group)
3057 @findex gnus-group-list-all-matching
3058 List groups that match a regexp (@code{gnus-group-list-all-matching}).
3059
3060 @item A A
3061 @kindex A A (Group)
3062 @findex gnus-group-list-active
3063 List absolutely all groups in the active file(s) of the
3064 server(s) you are connected to (@code{gnus-group-list-active}).  This
3065 might very well take quite a while.  It might actually be a better idea
3066 to do a @kbd{A M} to list all matching, and just give @samp{.} as the
3067 thing to match on.  Also note that this command may list groups that
3068 don't exist (yet)---these will be listed as if they were killed groups.
3069 Take the output with some grains of salt.
3070
3071 @item A a
3072 @kindex A a (Group)
3073 @findex gnus-group-apropos
3074 List all groups that have names that match a regexp
3075 (@code{gnus-group-apropos}).
3076
3077 @item A d
3078 @kindex A d (Group)
3079 @findex gnus-group-description-apropos
3080 List all groups that have names or descriptions that match a regexp
3081 (@code{gnus-group-description-apropos}).
3082
3083 @item A c
3084 @kindex A c (Group)
3085 @findex gnus-group-list-cached
3086 List all groups with cached articles (@code{gnus-group-list-cached}).
3087
3088 @item A ?
3089 @kindex A ? (Group)
3090 @findex gnus-group-list-dormant
3091 List all groups with dormant articles (@code{gnus-group-list-dormant}).
3092
3093 @item A /
3094 @kindex A / (Group)
3095 @findex gnus-group-list-limit
3096 List groups limited within the current selection
3097 (@code{gnus-group-list-limit}).
3098
3099 @item A f
3100 @kindex A f (Group)
3101 @findex gnus-group-list-flush
3102 Flush groups from the current selection (@code{gnus-group-list-flush}).
3103
3104 @item A p
3105 @kindex A p (Group)
3106 @findex gnus-group-list-plus
3107 List groups plus the current selection (@code{gnus-group-list-plus}).
3108
3109 @end table
3110
3111 @vindex gnus-permanently-visible-groups
3112 @cindex visible group parameter
3113 Groups that match the @code{gnus-permanently-visible-groups} regexp will
3114 always be shown, whether they have unread articles or not.  You can also
3115 add the @code{visible} element to the group parameters in question to
3116 get the same effect.
3117
3118 @vindex gnus-list-groups-with-ticked-articles
3119 Groups that have just ticked articles in it are normally listed in the
3120 group buffer.  If @code{gnus-list-groups-with-ticked-articles} is
3121 @code{nil}, these groups will be treated just like totally empty
3122 groups.  It is @code{t} by default.
3123
3124
3125 @node Sorting Groups
3126 @section Sorting Groups
3127 @cindex sorting groups
3128
3129 @kindex C-c C-s (Group)
3130 @findex gnus-group-sort-groups
3131 @vindex gnus-group-sort-function
3132 The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the
3133 group buffer according to the function(s) given by the
3134 @code{gnus-group-sort-function} variable.  Available sorting functions
3135 include:
3136
3137 @table @code
3138
3139 @item gnus-group-sort-by-alphabet
3140 @findex gnus-group-sort-by-alphabet
3141 Sort the group names alphabetically.  This is the default.
3142
3143 @item gnus-group-sort-by-real-name
3144 @findex gnus-group-sort-by-real-name
3145 Sort the group alphabetically on the real (unprefixed) group names.
3146
3147 @item gnus-group-sort-by-level
3148 @findex gnus-group-sort-by-level
3149 Sort by group level.
3150
3151 @item gnus-group-sort-by-score
3152 @findex gnus-group-sort-by-score
3153 Sort by group score.  @xref{Group Score}.
3154
3155 @item gnus-group-sort-by-rank
3156 @findex gnus-group-sort-by-rank
3157 Sort by group score and then the group level.  The level and the score
3158 are, when taken together, the group's @dfn{rank}.  @xref{Group Score}.
3159
3160 @item gnus-group-sort-by-unread
3161 @findex gnus-group-sort-by-unread
3162 Sort by number of unread articles.
3163
3164 @item gnus-group-sort-by-method
3165 @findex gnus-group-sort-by-method
3166 Sort alphabetically on the select method.
3167
3168 @item gnus-group-sort-by-server
3169 @findex gnus-group-sort-by-server
3170 Sort alphabetically on the Gnus server name.
3171
3172
3173 @end table
3174
3175 @code{gnus-group-sort-function} can also be a list of sorting
3176 functions.  In that case, the most significant sort key function must be
3177 the last one.
3178
3179
3180 There are also a number of commands for sorting directly according to
3181 some sorting criteria:
3182
3183 @table @kbd
3184 @item G S a
3185 @kindex G S a (Group)
3186 @findex gnus-group-sort-groups-by-alphabet
3187 Sort the group buffer alphabetically by group name
3188 (@code{gnus-group-sort-groups-by-alphabet}).
3189
3190 @item G S u
3191 @kindex G S u (Group)
3192 @findex gnus-group-sort-groups-by-unread
3193 Sort the group buffer by the number of unread articles
3194 (@code{gnus-group-sort-groups-by-unread}).
3195
3196 @item G S l
3197 @kindex G S l (Group)
3198 @findex gnus-group-sort-groups-by-level
3199 Sort the group buffer by group level
3200 (@code{gnus-group-sort-groups-by-level}).
3201
3202 @item G S v
3203 @kindex G S v (Group)
3204 @findex gnus-group-sort-groups-by-score
3205 Sort the group buffer by group score
3206 (@code{gnus-group-sort-groups-by-score}).  @xref{Group Score}.
3207
3208 @item G S r
3209 @kindex G S r (Group)
3210 @findex gnus-group-sort-groups-by-rank
3211 Sort the group buffer by group rank
3212 (@code{gnus-group-sort-groups-by-rank}).  @xref{Group Score}.
3213
3214 @item G S m
3215 @kindex G S m (Group)
3216 @findex gnus-group-sort-groups-by-method
3217 Sort the group buffer alphabetically by back end name
3218 (@code{gnus-group-sort-groups-by-method}).
3219
3220 @item G S n
3221 @kindex G S n (Group)
3222 @findex gnus-group-sort-groups-by-real-name
3223 Sort the group buffer alphabetically by real (unprefixed) group name
3224 (@code{gnus-group-sort-groups-by-real-name}).
3225
3226 @end table
3227
3228 All the commands below obey the process/prefix convention
3229 (@pxref{Process/Prefix}).
3230
3231 When given a symbolic prefix (@pxref{Symbolic Prefixes}), all these
3232 commands will sort in reverse order.
3233
3234 You can also sort a subset of the groups:
3235
3236 @table @kbd
3237 @item G P a
3238 @kindex G P a (Group)
3239 @findex gnus-group-sort-selected-groups-by-alphabet
3240 Sort the groups alphabetically by group name
3241 (@code{gnus-group-sort-selected-groups-by-alphabet}).
3242
3243 @item G P u
3244 @kindex G P u (Group)
3245 @findex gnus-group-sort-selected-groups-by-unread
3246 Sort the groups by the number of unread articles
3247 (@code{gnus-group-sort-selected-groups-by-unread}).
3248
3249 @item G P l
3250 @kindex G P l (Group)
3251 @findex gnus-group-sort-selected-groups-by-level
3252 Sort the groups by group level
3253 (@code{gnus-group-sort-selected-groups-by-level}).
3254
3255 @item G P v
3256 @kindex G P v (Group)
3257 @findex gnus-group-sort-selected-groups-by-score
3258 Sort the groups by group score
3259 (@code{gnus-group-sort-selected-groups-by-score}).  @xref{Group Score}.
3260
3261 @item G P r
3262 @kindex G P r (Group)
3263 @findex gnus-group-sort-selected-groups-by-rank
3264 Sort the groups by group rank
3265 (@code{gnus-group-sort-selected-groups-by-rank}).  @xref{Group Score}.
3266
3267 @item G P m
3268 @kindex G P m (Group)
3269 @findex gnus-group-sort-selected-groups-by-method
3270 Sort the groups alphabetically by back end name
3271 (@code{gnus-group-sort-selected-groups-by-method}).
3272
3273 @item G P n
3274 @kindex G P n (Group)
3275 @findex gnus-group-sort-selected-groups-by-real-name
3276 Sort the groups alphabetically by real (unprefixed) group name
3277 (@code{gnus-group-sort-selected-groups-by-real-name}).
3278
3279 @item G P s
3280 @kindex G P s (Group)
3281 @findex gnus-group-sort-selected-groups
3282 Sort the groups according to @code{gnus-group-sort-function}.
3283
3284 @end table
3285
3286 And finally, note that you can use @kbd{C-k} and @kbd{C-y} to manually
3287 move groups around.
3288
3289
3290 @node Group Maintenance
3291 @section Group Maintenance
3292 @cindex bogus groups
3293
3294 @table @kbd
3295 @item b
3296 @kindex b (Group)
3297 @findex gnus-group-check-bogus-groups
3298 Find bogus groups and delete them
3299 (@code{gnus-group-check-bogus-groups}).
3300
3301 @item F
3302 @kindex F (Group)
3303 @findex gnus-group-find-new-groups
3304 Find new groups and process them (@code{gnus-group-find-new-groups}).
3305 With 1 @kbd{C-u}, use the @code{ask-server} method to query the server
3306 for new groups.  With 2 @kbd{C-u}'s, use most complete method possible
3307 to query the server for new groups, and subscribe the new groups as
3308 zombies.
3309
3310 @item C-c C-x
3311 @kindex C-c C-x (Group)
3312 @findex gnus-group-expire-articles
3313 Run all expirable articles in the current group through the expiry
3314 process (if any) (@code{gnus-group-expire-articles}).  That is, delete
3315 all expirable articles in the group that have been around for a while.
3316 (@pxref{Expiring Mail}).
3317
3318 @item C-c C-M-x
3319 @kindex C-c C-M-x (Group)
3320 @findex gnus-group-expire-all-groups
3321 Run all expirable articles in all groups through the expiry process
3322 (@code{gnus-group-expire-all-groups}).
3323
3324 @end table
3325
3326
3327 @node Browse Foreign Server
3328 @section Browse Foreign Server
3329 @cindex foreign servers
3330 @cindex browsing servers
3331
3332 @table @kbd
3333 @item B
3334 @kindex B (Group)
3335 @findex gnus-group-browse-foreign-server
3336 You will be queried for a select method and a server name.  Gnus will
3337 then attempt to contact this server and let you browse the groups there
3338 (@code{gnus-group-browse-foreign-server}).
3339 @end table
3340
3341 @findex gnus-browse-mode
3342 A new buffer with a list of available groups will appear.  This buffer
3343 will use the @code{gnus-browse-mode}.  This buffer looks a bit (well,
3344 a lot) like a normal group buffer.
3345
3346 Here's a list of keystrokes available in the browse mode:
3347
3348 @table @kbd
3349 @item n
3350 @kindex n (Browse)
3351 @findex gnus-group-next-group
3352 Go to the next group (@code{gnus-group-next-group}).
3353
3354 @item p
3355 @kindex p (Browse)
3356 @findex gnus-group-prev-group
3357 Go to the previous group (@code{gnus-group-prev-group}).
3358
3359 @item SPACE
3360 @kindex SPACE (Browse)
3361 @findex gnus-browse-read-group
3362 Enter the current group and display the first article
3363 (@code{gnus-browse-read-group}).
3364
3365 @item RET
3366 @kindex RET (Browse)
3367 @findex gnus-browse-select-group
3368 Enter the current group (@code{gnus-browse-select-group}).
3369
3370 @item u
3371 @kindex u (Browse)
3372 @findex gnus-browse-unsubscribe-current-group
3373 Unsubscribe to the current group, or, as will be the case here,
3374 subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
3375
3376 @item l
3377 @itemx q
3378 @kindex q (Browse)
3379 @kindex l (Browse)
3380 @findex gnus-browse-exit
3381 Exit browse mode (@code{gnus-browse-exit}).
3382
3383 @item d
3384 @kindex d (Browse)
3385 @findex gnus-browse-describe-group
3386 Describe the current group (@code{gnus-browse-describe-group}).
3387
3388 @item ?
3389 @kindex ? (Browse)
3390 @findex gnus-browse-describe-briefly
3391 Describe browse mode briefly (well, there's not much to describe, is
3392 there) (@code{gnus-browse-describe-briefly}).
3393 @end table
3394
3395
3396 @node Exiting Gnus
3397 @section Exiting Gnus
3398 @cindex exiting Gnus
3399
3400 Yes, Gnus is ex(c)iting.
3401
3402 @table @kbd
3403 @item z
3404 @kindex z (Group)
3405 @findex gnus-group-suspend
3406 Suspend Gnus (@code{gnus-group-suspend}).  This doesn't really exit Gnus,
3407 but it kills all buffers except the Group buffer.  I'm not sure why this
3408 is a gain, but then who am I to judge?
3409
3410 @item q
3411 @kindex q (Group)
3412 @findex gnus-group-exit
3413 @c @icon{gnus-group-exit}
3414 Quit Gnus (@code{gnus-group-exit}).
3415
3416 @item Q
3417 @kindex Q (Group)
3418 @findex gnus-group-quit
3419 Quit Gnus without saving the @file{.newsrc} files (@code{gnus-group-quit}).
3420 The dribble file will be saved, though (@pxref{Auto Save}).
3421 @end table
3422
3423 @vindex gnus-exit-gnus-hook
3424 @vindex gnus-suspend-gnus-hook
3425 @code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
3426 @code{gnus-exit-gnus-hook} is called when you quit Gnus, while
3427 @code{gnus-after-exiting-gnus-hook} is called as the final item when
3428 exiting Gnus.
3429
3430 @findex gnus-unload
3431 @cindex unloading
3432 If you wish to completely unload Gnus and all its adherents, you can use
3433 the @code{gnus-unload} command.  This command is also very handy when
3434 trying to customize meta-variables.
3435
3436 Note:
3437
3438 @quotation
3439 Miss Lisa Cannifax, while sitting in English class, felt her feet go
3440 numbly heavy and herself fall into a hazy trance as the boy sitting
3441 behind her drew repeated lines with his pencil across the back of her
3442 plastic chair.
3443 @end quotation
3444
3445
3446 @node Group Topics
3447 @section Group Topics
3448 @cindex topics
3449
3450 If you read lots and lots of groups, it might be convenient to group
3451 them hierarchically according to topics.  You put your Emacs groups over
3452 here, your sex groups over there, and the rest (what, two groups or so?)
3453 you put in some misc section that you never bother with anyway.  You can
3454 even group the Emacs sex groups as a sub-topic to either the Emacs
3455 groups or the sex groups---or both!  Go wild!
3456
3457 @iftex
3458 @iflatex
3459 \gnusfigure{Group Topics}{400}{
3460 \put(75,50){\epsfig{figure=ps/group-topic,height=9cm}}
3461 }
3462 @end iflatex
3463 @end iftex
3464
3465 Here's an example:
3466
3467 @example
3468 Gnus
3469   Emacs -- I wuw it!
3470      3: comp.emacs
3471      2: alt.religion.emacs
3472     Naughty Emacs
3473      452: alt.sex.emacs
3474        0: comp.talk.emacs.recovery
3475   Misc
3476      8: comp.binaries.fractals
3477     13: comp.sources.unix
3478 @end example
3479
3480 @findex gnus-topic-mode
3481 @kindex t (Group)
3482 To get this @emph{fab} functionality you simply turn on (ooh!) the
3483 @code{gnus-topic} minor mode---type @kbd{t} in the group buffer.  (This
3484 is a toggling command.)
3485
3486 Go ahead, just try it.  I'll still be here when you get back.  La de
3487 dum...  Nice tune, that...  la la la...  What, you're back?  Yes, and
3488 now press @kbd{l}.  There.  All your groups are now listed under
3489 @samp{misc}.  Doesn't that make you feel all warm and fuzzy?  Hot and
3490 bothered?
3491
3492 If you want this permanently enabled, you should add that minor mode to
3493 the hook for the group mode.  Put the following line in your
3494 @file{~/.gnus} file:
3495
3496 @lisp
3497 (add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
3498 @end lisp
3499
3500 @menu
3501 * Topic Commands::              Interactive E-Z commands.
3502 * Topic Variables::             How to customize the topics the Lisp Way.
3503 * Topic Sorting::               Sorting each topic individually.
3504 * Topic Topology::              A map of the world.
3505 * Topic Parameters::            Parameters that apply to all groups in a topic.
3506 @end menu
3507
3508
3509 @node Topic Commands
3510 @subsection Topic Commands
3511 @cindex topic commands
3512
3513 When the topic minor mode is turned on, a new @kbd{T} submap will be
3514 available.  In addition, a few of the standard keys change their
3515 definitions slightly.
3516
3517 In general, the following kinds of operations are possible on topics.
3518 First of all, you want to create topics.  Secondly, you want to put
3519 groups in topics and to move them around until you have an order you
3520 like.  The third kind of operation is to show/hide parts of the whole
3521 shebang.  You might want to hide a topic including its subtopics and
3522 groups, to get a better overview of the other groups.
3523
3524 Here is a list of the basic keys that you might need to set up topics
3525 the way you like.
3526
3527 @table @kbd
3528
3529 @item T n
3530 @kindex T n (Topic)
3531 @findex gnus-topic-create-topic
3532 Prompt for a new topic name and create it
3533 (@code{gnus-topic-create-topic}).
3534
3535 @item T TAB
3536 @itemx TAB
3537 @kindex T TAB (Topic)
3538 @kindex TAB (Topic)
3539 @findex gnus-topic-indent
3540 ``Indent'' the current topic so that it becomes a sub-topic of the
3541 previous topic (@code{gnus-topic-indent}).  If given a prefix,
3542 ``un-indent'' the topic instead.
3543
3544 @item M-TAB
3545 @kindex M-TAB (Topic)
3546 @findex gnus-topic-unindent
3547 ``Un-indent'' the current topic so that it becomes a sub-topic of the
3548 parent of its current parent (@code{gnus-topic-unindent}).
3549
3550 @end table
3551
3552 The following two keys can be used to move groups and topics around.
3553 They work like the well-known cut and paste.  @kbd{C-k} is like cut and
3554 @kbd{C-y} is like paste.  Of course, this being Emacs, we use the terms
3555 kill and yank rather than cut and paste.
3556
3557 @table @kbd
3558
3559 @item C-k
3560 @kindex C-k (Topic)
3561 @findex gnus-topic-kill-group
3562 Kill a group or topic (@code{gnus-topic-kill-group}).  All groups in the
3563 topic will be removed along with the topic.
3564
3565 @item C-y
3566 @kindex C-y (Topic)
3567 @findex gnus-topic-yank-group
3568 Yank the previously killed group or topic
3569 (@code{gnus-topic-yank-group}).  Note that all topics will be yanked
3570 before all groups.
3571
3572 So, to move a topic to the beginning of the list of topics, just hit
3573 @kbd{C-k} on it.  This is like the `cut' part of cut and paste.  Then,
3574 move the cursor to the beginning of the buffer (just below the `Gnus'
3575 topic) and hit @kbd{C-y}.  This is like the `paste' part of cut and
3576 paste.  Like I said -- E-Z.
3577
3578 You can use @kbd{C-k} and @kbd{C-y} on groups as well as on topics.  So
3579 you can move topics around as well as groups.
3580
3581 @end table
3582
3583 After setting up the topics the way you like them, you might wish to
3584 hide a topic, or to show it again.  That's why we have the following
3585 key.
3586
3587 @table @kbd
3588
3589 @item RET
3590 @kindex RET (Topic)
3591 @findex gnus-topic-select-group
3592 @itemx SPACE
3593 Either select a group or fold a topic (@code{gnus-topic-select-group}).
3594 When you perform this command on a group, you'll enter the group, as
3595 usual.  When done on a topic line, the topic will be folded (if it was
3596 visible) or unfolded (if it was folded already).  So it's basically a
3597 toggling command on topics.  In addition, if you give a numerical
3598 prefix, group on that level (and lower) will be displayed.
3599
3600 @end table
3601
3602 Now for a list of other commands, in no particular order.
3603
3604 @table @kbd
3605
3606 @item T m
3607 @kindex T m (Topic)
3608 @findex gnus-topic-move-group
3609 Move the current group to some other topic
3610 (@code{gnus-topic-move-group}).  This command uses the process/prefix
3611 convention (@pxref{Process/Prefix}).
3612
3613 @item T j
3614 @kindex T j (Topic)
3615 @findex gnus-topic-jump-to-topic
3616 Go to a topic (@code{gnus-topic-jump-to-topic}).
3617
3618 @item T c
3619 @kindex T c (Topic)
3620 @findex gnus-topic-copy-group
3621 Copy the current group to some other topic
3622 (@code{gnus-topic-copy-group}).  This command uses the process/prefix
3623 convention (@pxref{Process/Prefix}).
3624
3625 @item T h
3626 @kindex T h (Topic)
3627 @findex gnus-topic-hide-topic
3628 Hide the current topic (@code{gnus-topic-hide-topic}).  If given
3629 a prefix, hide the topic permanently.
3630
3631 @item T s
3632 @kindex T s (Topic)
3633 @findex gnus-topic-show-topic
3634 Show the current topic (@code{gnus-topic-show-topic}).  If given
3635 a prefix, show the topic permanently.
3636
3637 @item T D
3638 @kindex T D (Topic)
3639 @findex gnus-topic-remove-group
3640 Remove a group from the current topic (@code{gnus-topic-remove-group}).
3641 This command is mainly useful if you have the same group in several
3642 topics and wish to remove it from one of the topics.  You may also
3643 remove a group from all topics, but in that case, Gnus will add it to
3644 the root topic the next time you start Gnus.  In fact, all new groups
3645 (which, naturally, don't belong to any topic) will show up in the root
3646 topic.
3647
3648 This command uses the process/prefix convention
3649 (@pxref{Process/Prefix}).
3650
3651 @item T M
3652 @kindex T M (Topic)
3653 @findex gnus-topic-move-matching
3654 Move all groups that match some regular expression to a topic
3655 (@code{gnus-topic-move-matching}).
3656
3657 @item T C
3658 @kindex T C (Topic)
3659 @findex gnus-topic-copy-matching
3660 Copy all groups that match some regular expression to a topic
3661 (@code{gnus-topic-copy-matching}).
3662
3663 @item T H
3664 @kindex T H (Topic)
3665 @findex gnus-topic-toggle-display-empty-topics
3666 Toggle hiding empty topics
3667 (@code{gnus-topic-toggle-display-empty-topics}).
3668
3669 @item T #
3670 @kindex T # (Topic)
3671 @findex gnus-topic-mark-topic
3672 Mark all groups in the current topic with the process mark
3673 (@code{gnus-topic-mark-topic}).
3674
3675 @item T M-#
3676 @kindex T M-# (Topic)
3677 @findex gnus-topic-unmark-topic
3678 Remove the process mark from all groups in the current topic
3679 (@code{gnus-topic-unmark-topic}).
3680
3681 @item C-c C-x
3682 @kindex C-c C-x (Topic)
3683 @findex gnus-topic-expire-articles
3684 Run all expirable articles in the current group or topic through the
3685 expiry process (if any)
3686 (@code{gnus-topic-expire-articles}). (@pxref{Expiring Mail}).
3687
3688 @item T r
3689 @kindex T r (Topic)
3690 @findex gnus-topic-rename
3691 Rename a topic (@code{gnus-topic-rename}).
3692
3693 @item T DEL
3694 @kindex T DEL (Topic)
3695 @findex gnus-topic-delete
3696 Delete an empty topic (@code{gnus-topic-delete}).
3697
3698 @item A T
3699 @kindex A T (Topic)
3700 @findex gnus-topic-list-active
3701 List all groups that Gnus knows about in a topics-ified way
3702 (@code{gnus-topic-list-active}).
3703
3704 @item T M-n
3705 @kindex T M-n (Topic)
3706 @findex gnus-topic-goto-next-topic
3707 Go to the next topic (@code{gnus-topic-goto-next-topic}).
3708
3709 @item T M-p
3710 @kindex T M-p (Topic)
3711 @findex gnus-topic-goto-previous-topic
3712 Go to the next topic (@code{gnus-topic-goto-previous-topic}).
3713
3714 @item G p
3715 @kindex G p (Topic)
3716 @findex gnus-topic-edit-parameters
3717 @cindex group parameters
3718 @cindex topic parameters
3719 @cindex parameters
3720 Edit the topic parameters (@code{gnus-topic-edit-parameters}).
3721 @xref{Topic Parameters}.
3722
3723 @end table
3724
3725
3726 @node Topic Variables
3727 @subsection Topic Variables
3728 @cindex topic variables
3729
3730 The previous section told you how to tell Gnus which topics to display.
3731 This section explains how to tell Gnus what to display about each topic.
3732
3733 @vindex gnus-topic-line-format
3734 The topic lines themselves are created according to the
3735 @code{gnus-topic-line-format} variable (@pxref{Formatting Variables}).
3736 Valid elements are:
3737
3738 @table @samp
3739 @item i
3740 Indentation.
3741 @item n
3742 Topic name.
3743 @item v
3744 Visibility.
3745 @item l
3746 Level.
3747 @item g
3748 Number of groups in the topic.
3749 @item a
3750 Number of unread articles in the topic.
3751 @item A
3752 Number of unread articles in the topic and all its subtopics.
3753 @end table
3754
3755 @vindex gnus-topic-indent-level
3756 Each sub-topic (and the groups in the sub-topics) will be indented with
3757 @code{gnus-topic-indent-level} times the topic level number of spaces.
3758 The default is 2.
3759
3760 @vindex gnus-topic-mode-hook
3761 @code{gnus-topic-mode-hook} is called in topic minor mode buffers.
3762
3763 @vindex gnus-topic-display-empty-topics
3764 The @code{gnus-topic-display-empty-topics} says whether to display even
3765 topics that have no unread articles in them.  The default is @code{t}.
3766
3767
3768 @node Topic Sorting
3769 @subsection Topic Sorting
3770 @cindex topic sorting
3771
3772 You can sort the groups in each topic individually with the following
3773 commands:
3774
3775
3776 @table @kbd
3777 @item T S a
3778 @kindex T S a (Topic)
3779 @findex gnus-topic-sort-groups-by-alphabet
3780 Sort the current topic alphabetically by group name
3781 (@code{gnus-topic-sort-groups-by-alphabet}).
3782
3783 @item T S u
3784 @kindex T S u (Topic)
3785 @findex gnus-topic-sort-groups-by-unread
3786 Sort the current topic by the number of unread articles
3787 (@code{gnus-topic-sort-groups-by-unread}).
3788
3789 @item T S l
3790 @kindex T S l (Topic)
3791 @findex gnus-topic-sort-groups-by-level
3792 Sort the current topic by group level
3793 (@code{gnus-topic-sort-groups-by-level}).
3794
3795 @item T S v
3796 @kindex T S v (Topic)
3797 @findex gnus-topic-sort-groups-by-score
3798 Sort the current topic by group score
3799 (@code{gnus-topic-sort-groups-by-score}).  @xref{Group Score}.
3800
3801 @item T S r
3802 @kindex T S r (Topic)
3803 @findex gnus-topic-sort-groups-by-rank
3804 Sort the current topic by group rank
3805 (@code{gnus-topic-sort-groups-by-rank}).  @xref{Group Score}.
3806
3807 @item T S m
3808 @kindex T S m (Topic)
3809 @findex gnus-topic-sort-groups-by-method
3810 Sort the current topic alphabetically by back end name
3811 (@code{gnus-topic-sort-groups-by-method}).
3812
3813 @item T S e
3814 @kindex T S e (Topic)
3815 @findex gnus-topic-sort-groups-by-server
3816 Sort the current topic alphabetically by server name
3817 (@code{gnus-topic-sort-groups-by-server}).
3818
3819 @item T S s
3820 @kindex T S s
3821 @findex gnus-topic-sort-groups
3822 Sort the current topic according to the function(s) given by the
3823 @code{gnus-group-sort-function} variable
3824 (@code{gnus-topic-sort-groups}).
3825
3826 @end table
3827
3828 When given a prefix argument, all these commands will sort in reverse
3829 order.  @xref{Sorting Groups}, for more information about group
3830 sorting.
3831
3832
3833 @node Topic Topology
3834 @subsection Topic Topology
3835 @cindex topic topology
3836 @cindex topology
3837
3838 So, let's have a look at an example group buffer:
3839
3840 @example
3841 Gnus
3842   Emacs -- I wuw it!
3843      3: comp.emacs
3844      2: alt.religion.emacs
3845     Naughty Emacs
3846      452: alt.sex.emacs
3847        0: comp.talk.emacs.recovery
3848   Misc
3849      8: comp.binaries.fractals
3850     13: comp.sources.unix
3851 @end example
3852
3853 So, here we have one top-level topic (@samp{Gnus}), two topics under
3854 that, and one sub-topic under one of the sub-topics.  (There is always
3855 just one (1) top-level topic).  This topology can be expressed as
3856 follows:
3857
3858 @lisp
3859 (("Gnus" visible)
3860  (("Emacs -- I wuw it!" visible)
3861   (("Naughty Emacs" visible)))
3862  (("Misc" visible)))
3863 @end lisp
3864
3865 @vindex gnus-topic-topology
3866 This is in fact how the variable @code{gnus-topic-topology} would look
3867 for the display above.  That variable is saved in the @file{.newsrc.eld}
3868 file, and shouldn't be messed with manually---unless you really want
3869 to.  Since this variable is read from the @file{.newsrc.eld} file,
3870 setting it in any other startup files will have no effect.
3871
3872 This topology shows what topics are sub-topics of what topics (right),
3873 and which topics are visible.  Two settings are currently
3874 allowed---@code{visible} and @code{invisible}.
3875
3876
3877 @node Topic Parameters
3878 @subsection Topic Parameters
3879 @cindex topic parameters
3880
3881 All groups in a topic will inherit group parameters from the parent (and
3882 ancestor) topic parameters.  All valid group parameters are valid topic
3883 parameters (@pxref{Group Parameters}).
3884
3885 In addition, the following parameters are only valid as topic
3886 parameters:
3887
3888 @table @code
3889 @item subscribe
3890 When subscribing new groups by topic (@pxref{Subscription Methods}), the
3891 @code{subscribe} topic parameter says what groups go in what topic.  Its
3892 value should be a regexp to match the groups that should go in that
3893 topic.
3894
3895 @item subscribe-level
3896 When subscribing new groups by topic (see the @code{subscribe} parameter),
3897 the group will be subscribed with the level specified in the
3898 @code{subscribe-level} instead of @code{gnus-level-default-subscribed}.
3899
3900 @end table
3901
3902 Group parameters (of course) override topic parameters, and topic
3903 parameters in sub-topics override topic parameters in super-topics.  You
3904 know.  Normal inheritance rules.  (@dfn{Rules} is here a noun, not a
3905 verb, although you may feel free to disagree with me here.)
3906
3907 @example
3908 Gnus
3909   Emacs
3910      3: comp.emacs
3911      2: alt.religion.emacs
3912    452: alt.sex.emacs
3913     Relief
3914      452: alt.sex.emacs
3915        0: comp.talk.emacs.recovery
3916   Misc
3917      8: comp.binaries.fractals
3918     13: comp.sources.unix
3919    452: alt.sex.emacs
3920 @end example
3921
3922 The @samp{Emacs} topic has the topic parameter @code{(score-file
3923 . "emacs.SCORE")}; the @samp{Relief} topic has the topic parameter
3924 @code{(score-file . "relief.SCORE")}; and the @samp{Misc} topic has the
3925 topic parameter @code{(score-file . "emacs.SCORE")}.  In addition,
3926 @* @samp{alt.religion.emacs} has the group parameter @code{(score-file
3927 . "religion.SCORE")}.
3928
3929 Now, when you enter @samp{alt.sex.emacs} in the @samp{Relief} topic, you
3930 will get the @file{relief.SCORE} home score file.  If you enter the same
3931 group in the @samp{Emacs} topic, you'll get the @file{emacs.SCORE} home
3932 score file.  If you enter the group @samp{alt.religion.emacs}, you'll
3933 get the @file{religion.SCORE} home score file.
3934
3935 This seems rather simple and self-evident, doesn't it?  Well, yes.  But
3936 there are some problems, especially with the @code{total-expiry}
3937 parameter.  Say you have a mail group in two topics; one with
3938 @code{total-expiry} and one without.  What happens when you do @kbd{M-x
3939 gnus-expire-all-expirable-groups}?  Gnus has no way of telling which one
3940 of these topics you mean to expire articles from, so anything may
3941 happen.  In fact, I hereby declare that it is @dfn{undefined} what
3942 happens.  You just have to be careful if you do stuff like that.
3943
3944
3945 @node Misc Group Stuff
3946 @section Misc Group Stuff
3947
3948 @menu
3949 * Scanning New Messages::       Asking Gnus to see whether new messages have arrived.
3950 * Group Information::           Information and help on groups and Gnus.
3951 * Group Timestamp::             Making Gnus keep track of when you last read a group.
3952 * File Commands::               Reading and writing the Gnus files.
3953 * Sieve Commands::              Managing Sieve scripts.
3954 @end menu
3955
3956 @table @kbd
3957
3958 @item ^
3959 @kindex ^ (Group)
3960 @findex gnus-group-enter-server-mode
3961 Enter the server buffer (@code{gnus-group-enter-server-mode}).
3962 @xref{Server Buffer}.
3963
3964 @item a
3965 @kindex a (Group)
3966 @findex gnus-group-post-news
3967 Start composing a message (a news by default)
3968 (@code{gnus-group-post-news}).  If given a prefix, post to the group
3969 under the point.  If the prefix is 1, prompt for a group to post to.
3970 Contrary to what the name of this function suggests, the prepared
3971 article might be a mail instead of a news, if a mail group is specified
3972 with the prefix argument.  @xref{Composing Messages}.
3973
3974 @item m
3975 @kindex m (Group)
3976 @findex gnus-group-mail
3977 Mail a message somewhere (@code{gnus-group-mail}).  If given a prefix,
3978 use the posting style of the group under the point.  If the prefix is 1,
3979 prompt for a group name to find the posting style.
3980 @xref{Composing Messages}.
3981
3982 @item i
3983 @kindex i (Group)
3984 @findex gnus-group-news
3985 Start composing a news (@code{gnus-group-news}).  If given a prefix,
3986 post to the group under the point.  If the prefix is 1, prompt
3987 for group to post to.  @xref{Composing Messages}.
3988
3989 This function actually prepares a news even when using mail groups.
3990 This is useful for "posting" messages to mail groups without actually
3991 sending them over the network: they're just saved directly to the group
3992 in question.  The corresponding back end must have a request-post method
3993 for this to work though.
3994
3995 @end table
3996
3997 Variables for the group buffer:
3998
3999 @table @code
4000
4001 @item gnus-group-mode-hook
4002 @vindex gnus-group-mode-hook
4003 is called after the group buffer has been
4004 created.
4005
4006 @item gnus-group-prepare-hook
4007 @vindex gnus-group-prepare-hook
4008 is called after the group buffer is
4009 generated.  It may be used to modify the buffer in some strange,
4010 unnatural way.
4011
4012 @item gnus-group-prepared-hook
4013 @vindex gnus-group-prepare-hook
4014 is called as the very last thing after the group buffer has been
4015 generated.  It may be used to move point around, for instance.
4016
4017 @item gnus-permanently-visible-groups
4018 @vindex gnus-permanently-visible-groups
4019 Groups matching this regexp will always be listed in the group buffer,
4020 whether they are empty or not.
4021
4022 @item gnus-group-name-charset-method-alist
4023 @vindex gnus-group-name-charset-method-alist
4024 An alist of method and the charset for group names. It is used to show
4025 non-ASCII group names.
4026
4027 For example:
4028 @lisp
4029 (setq gnus-group-name-charset-method-alist
4030     '(((nntp "news.com.cn") . cn-gb-2312)))
4031 @end lisp
4032
4033 @item gnus-group-name-charset-group-alist
4034 @cindex UTF-8 group names
4035 @vindex gnus-group-name-charset-group-alist
4036 An alist of regexp of group name and the charset for group names.  It
4037 is used to show non-ASCII group names.  @code{((".*" utf-8))} is the
4038 default value if UTF-8 is supported, otherwise the default is nil.
4039
4040 For example:
4041 @lisp
4042 (setq gnus-group-name-charset-group-alist
4043     '(("\\.com\\.cn:" . cn-gb-2312)))
4044 @end lisp
4045
4046 @end table
4047
4048 @node Scanning New Messages
4049 @subsection Scanning New Messages
4050 @cindex new messages
4051 @cindex scanning new news
4052
4053 @table @kbd
4054
4055 @item g
4056 @kindex g (Group)
4057 @findex gnus-group-get-new-news
4058 @c @icon{gnus-group-get-new-news}
4059 Check the server(s) for new articles.  If the numerical prefix is used,
4060 this command will check only groups of level @var{arg} and lower
4061 (@code{gnus-group-get-new-news}).  If given a non-numerical prefix, this
4062 command will force a total re-reading of the active file(s) from the
4063 back end(s).
4064
4065 @item M-g
4066 @kindex M-g (Group)
4067 @findex gnus-group-get-new-news-this-group
4068 @vindex gnus-goto-next-group-when-activating
4069 @c @icon{gnus-group-get-new-news-this-group}
4070 Check whether new articles have arrived in the current group
4071 (@code{gnus-group-get-new-news-this-group}).
4072 @code{gnus-goto-next-group-when-activating} says whether this command is
4073 to move point to the next group or not.  It is @code{t} by default.
4074
4075 @findex gnus-activate-all-groups
4076 @cindex activating groups
4077 @item C-c M-g
4078 @kindex C-c M-g (Group)
4079 Activate absolutely all groups (@code{gnus-activate-all-groups}).
4080
4081 @item R
4082 @kindex R (Group)
4083 @cindex restarting
4084 @findex gnus-group-restart
4085 Restart Gnus (@code{gnus-group-restart}).  This saves the @file{.newsrc}
4086 file(s), closes the connection to all servers, clears up all run-time
4087 Gnus variables, and then starts Gnus all over again.