gnus.texi 1010 KB
Newer Older
1
\input texinfo
Dave Love's avatar
#  
Dave Love committed
2

Eli Zaretskii's avatar
Eli Zaretskii committed
3
@setfilename ../info/gnus
Dave Love's avatar
#  
Dave Love committed
4
@settitle Gnus Manual
5 6 7 8 9
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex pg cp

@copying
10
Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001,
Glenn Morris's avatar
Glenn Morris committed
11
2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
12 13 14

@quotation
Permission is granted to copy, distribute and/or modify this document
15
under the terms of the GNU Free Documentation License, Version 1.2 or
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
Dave Love's avatar
#  
Dave Love committed
32 33

@iftex
34 35 36 37 38 39
@iflatex
\documentclass[twoside,a4paper,openright,11pt]{book}
\usepackage[latin1]{inputenc}
\usepackage{pagestyle}
\usepackage{epsfig}
\usepackage{pixidx}
40 41 42 43 44 45 46 47
\input{gnusconfig.tex}

\ifx\pdfoutput\undefined
\else
\usepackage[pdftex,bookmarks,colorlinks=true]{hyperref}
\usepackage{thumbpdf}
\pdfcompresslevel=9
\fi
48 49 50 51

\makeindex
\begin{document}

52
% Adjust ../Makefile.in if you change the following line:
Reiner Steib's avatar
Reiner Steib committed
53
\newcommand{\gnusversionname}{Gnus v5.11}
54 55 56 57 58
\newcommand{\gnuschaptername}{}
\newcommand{\gnussectionname}{}

\newcommand{\gnusbackslash}{/}

59 60 61 62 63 64
\newcommand{\gnusref}[1]{``#1'' on page \pageref{#1}}
\ifx\pdfoutput\undefined
\newcommand{\gnusuref}[1]{\gnustt{#1}}
\else
\newcommand{\gnusuref}[1]{\href{#1}{\gnustt{#1}}}
\fi
65 66 67 68 69 70
\newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}}
\newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}}

\newcommand{\gnuskindex}[1]{\index{#1}}
\newcommand{\gnusindex}[1]{\index{#1}}

71
\newcommand{\gnustt}[1]{{\gnusselectttfont{}#1}}
72
\newcommand{\gnuscode}[1]{\gnustt{#1}}
73 74 75 76 77
\newcommand{\gnusasis}[1]{\gnustt{#1}}
\newcommand{\gnusurl}[1]{\gnustt{#1}}
\newcommand{\gnuscommand}[1]{\gnustt{#1}}
\newcommand{\gnusenv}[1]{\gnustt{#1}}
\newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\gnusselectttfont{}#1}''}
78 79
\newcommand{\gnuslisp}[1]{\gnustt{#1}}
\newcommand{\gnuskbd}[1]{`\gnustt{#1}'}
80
\newcommand{\gnuskey}[1]{`\gnustt{#1}'}
81 82 83
\newcommand{\gnusfile}[1]{`\gnustt{#1}'}
\newcommand{\gnusdfn}[1]{\textit{#1}}
\newcommand{\gnusi}[1]{\textit{#1}}
84
\newcommand{\gnusr}[1]{\textrm{#1}}
85 86 87 88 89
\newcommand{\gnusstrong}[1]{\textbf{#1}}
\newcommand{\gnusemph}[1]{\textit{#1}}
\newcommand{\gnusvar}[1]{{\fontsize{10pt}{10}\selectfont\textsl{\textsf{#1}}}}
\newcommand{\gnussc}[1]{\textsc{#1}}
\newcommand{\gnustitle}[1]{{\huge\textbf{#1}}}
90
\newcommand{\gnusversion}[1]{{\small\textit{#1}}}
91 92
\newcommand{\gnusauthor}[1]{{\large\textbf{#1}}}
\newcommand{\gnusresult}[1]{\gnustt{=> #1}}
93 94
\newcommand{\gnusacronym}[1]{\textsc{#1}}
\newcommand{\gnusemail}[1]{\textit{#1}}
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109

\newcommand{\gnusbullet}{{${\bullet}$}}
\newcommand{\gnusdollar}{\$}
\newcommand{\gnusampersand}{\&}
\newcommand{\gnuspercent}{\%}
\newcommand{\gnushash}{\#}
\newcommand{\gnushat}{\symbol{"5E}}
\newcommand{\gnusunderline}{\symbol{"5F}}
\newcommand{\gnusnot}{$\neg$}
\newcommand{\gnustilde}{\symbol{"7E}}
\newcommand{\gnusless}{{$<$}}
\newcommand{\gnusgreater}{{$>$}}
\newcommand{\gnusbraceleft}{{$>$}}
\newcommand{\gnusbraceright}{{$>$}}

110
\newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=ps/gnus-head,height=1cm}}}
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
\newcommand{\gnusinteresting}{
\marginpar[\mbox{}\hfill\gnushead]{\gnushead}
}

\newcommand{\gnuscleardoublepage}{\ifodd\count0\mbox{}\clearpage\thispagestyle{empty}\mbox{}\clearpage\else\clearpage\fi}

\newcommand{\gnuspagechapter}[1]{
{\mbox{}}
}

\newdimen{\gnusdimen}
\gnusdimen 0pt

\newcommand{\gnuschapter}[2]{
\gnuscleardoublepage
\ifdim \gnusdimen = 0pt\setcounter{page}{1}\pagestyle{gnus}\pagenumbering{arabic} \gnusdimen 1pt\fi
\chapter{#2}
\renewcommand{\gnussectionname}{}
\renewcommand{\gnuschaptername}{#2}
\thispagestyle{empty}
\hspace*{-2cm}
\begin{picture}(500,500)(0,0)
\put(480,350){\makebox(0,0)[tr]{#1}}
\put(40,300){\makebox(500,50)[bl]{{\Huge\bf{#2}}}}
\end{picture}
\clearpage
}

\newcommand{\gnusfigure}[3]{
\begin{figure}
\mbox{}\ifodd\count0\hspace*{-0.8cm}\else\hspace*{-3cm}\fi\begin{picture}(440,#2)
#3
\end{picture}
\caption{#1}
\end{figure}
}

\newcommand{\gnusicon}[1]{
149
\marginpar[\mbox{}\hfill\raisebox{-1.5cm}{\epsfig{figure=ps/#1-up,height=1.5cm}}]{\raisebox{-1cm}{\epsfig{figure=ps/#1-up,height=1cm}}}
150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175
}

\newcommand{\gnuspicon}[1]{
\margindex{\epsfig{figure=#1,width=2cm}}
}

\newcommand{\gnusxface}[2]{
\margindex{\epsfig{figure=#1,width=1cm}\epsfig{figure=#2,width=1cm}}
}

\newcommand{\gnussmiley}[2]{
\margindex{\makebox[2cm]{\hfill\epsfig{figure=#1,width=0.5cm}\hfill\epsfig{figure=#2,width=0.5cm}\hfill}}
}

\newcommand{\gnusitemx}[1]{\mbox{}\vspace*{-\itemsep}\vspace*{-\parsep}\item#1}

\newcommand{\gnussection}[1]{
\renewcommand{\gnussectionname}{#1}
\section{#1}
}

\newenvironment{codelist}%
{\begin{list}{}{
}
}{\end{list}}

176 177 178 179 180
\newenvironment{asislist}%
{\begin{list}{}{
}
}{\end{list}}

181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233
\newenvironment{kbdlist}%
{\begin{list}{}{
\labelwidth=0cm
}
}{\end{list}}

\newenvironment{dfnlist}%
{\begin{list}{}{
}
}{\end{list}}

\newenvironment{stronglist}%
{\begin{list}{}{
}
}{\end{list}}

\newenvironment{samplist}%
{\begin{list}{}{
}
}{\end{list}}

\newenvironment{varlist}%
{\begin{list}{}{
}
}{\end{list}}

\newenvironment{emphlist}%
{\begin{list}{}{
}
}{\end{list}}

\newlength\gnusheadtextwidth
\setlength{\gnusheadtextwidth}{\headtextwidth}
\addtolength{\gnusheadtextwidth}{1cm}

\newpagestyle{gnuspreamble}%
{
{
\ifodd\count0
{
\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\mbox{}}\textbf{\hfill\roman{page}}}
}
\else
{
\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\roman{page}\hfill\mbox{}}}
}
}
\fi
}
}
{
\ifodd\count0
\mbox{} \hfill
234
\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
235
\else
236
\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257
\hfill \mbox{}
\fi
}

\newpagestyle{gnusindex}%
{
{
\ifodd\count0
{
\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\gnuschaptername\hfill\arabic{page}}}}
}
\else
{
\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}
}
\fi
}
}
{
\ifodd\count0
\mbox{} \hfill
258
\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
259
\else
260
\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281
\hfill \mbox{}
\fi
}

\newpagestyle{gnus}%
{
{
\ifodd\count0
{
\makebox[12cm]{\hspace*{3.1cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{chapter}.\arabic{section}} \textbf{\gnussectionname\hfill\arabic{page}}}}}
}
\else
{
\makebox[12cm]{\hspace*{-2.95cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}}
}
\fi
}
}
{
\ifodd\count0
\mbox{} \hfill
282
\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
283
\else
284
\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}}
285 286 287 288 289 290 291 292
\hfill \mbox{}
\fi
}

\pagenumbering{roman}
\pagestyle{gnuspreamble}

@end iflatex
Dave Love's avatar
#  
Dave Love committed
293 294
@end iftex

295 296
@iftex
@iflatex
297

298 299 300 301 302 303 304 305
\begin{titlepage}
{

%\addtolength{\oddsidemargin}{-5cm}
%\addtolength{\evensidemargin}{-5cm}
\parindent=0cm
\addtolength{\textheight}{2cm}

306
\gnustitle{\gnustitlename}\hfill\gnusversion{\gnusversionname}\\
307 308
\rule{15cm}{1mm}\\
\vfill
309
\hspace*{0cm}\epsfig{figure=ps/gnus-big-logo,height=15cm}
310 311 312 313 314 315 316 317 318 319 320
\vfill
\rule{15cm}{1mm}\\
\gnusauthor{by Lars Magne Ingebrigtsen}
\newpage
}

\mbox{}
\vfill

\thispagestyle{empty}

321
@c @insertcopying
322 323 324 325
\newpage
\end{titlepage}
@end iflatex
@end iftex
Dave Love's avatar
#  
Dave Love committed
326

327
@ifnottex
328 329
@insertcopying
@end ifnottex
Dave Love's avatar
#  
Dave Love committed
330

331 332 333 334 335 336 337 338
@dircategory Emacs
@direntry
* Gnus: (gnus).         The newsreader Gnus.
@end direntry
@iftex
@finalout
@end iftex
@setchapternewpage odd
Dave Love's avatar
#  
Dave Love committed
339 340 341 342



@titlepage
343
@title Gnus Manual
Dave Love's avatar
#  
Dave Love committed
344 345 346 347

@author by Lars Magne Ingebrigtsen
@page
@vskip 0pt plus 1filll
348
@insertcopying
Dave Love's avatar
#  
Dave Love committed
349 350 351 352 353 354 355 356 357
@end titlepage


@node Top
@top The Gnus Newsreader

@ifinfo

You can read news (and mail) from within Emacs by using Gnus.  The news
358
can be gotten by any nefarious means you can think of---@acronym{NNTP}, local
Dave Love's avatar
#  
Dave Love committed
359 360 361
spool or your mbox file.  All at the same time, if you want to push your
luck.

362
@c Adjust ../Makefile.in if you change the following line:
Reiner Steib's avatar
Reiner Steib committed
363
This manual corresponds to Gnus v5.11.
Dave Love's avatar
#  
Dave Love committed
364 365 366 367 368

@end ifinfo

@iftex

369 370 371 372 373
@iflatex
\tableofcontents
\gnuscleardoublepage
@end iflatex

Dave Love's avatar
#  
Dave Love committed
374 375 376 377 378 379 380 381
Gnus is the advanced, self-documenting, customizable, extensible
unreal-time newsreader for GNU Emacs.

Oops.  That sounds oddly familiar, so let's start over again to avoid
being accused of plagiarism:

Gnus is a message-reading laboratory.  It will let you look at just
about anything as if it were a newsgroup.  You can read mail with it,
382 383
you can browse directories with it, you can @code{ftp} with it---you
can even read news with it!
Dave Love's avatar
#  
Dave Love committed
384 385 386 387 388 389 390 391 392 393 394

Gnus tries to empower people who read news the same way Emacs empowers
people who edit text.  Gnus sets no limits to what the user should be
allowed to do.  Users are encouraged to extend Gnus to make it behave
like they want it to behave.  A program should not control people;
people should be empowered to do what they want by using (or abusing)
the program.

@end iftex

@menu
395 396 397 398 399 400 401 402 403 404
* Starting Up::              Finding news can be a pain.
* Group Buffer::             Selecting, subscribing and killing groups.
* Summary Buffer::           Reading, saving and posting articles.
* Article Buffer::           Displaying and handling articles.
* Composing Messages::       Information on sending mail and news.
* Select Methods::           Gnus reads all messages from various select methods.
* Scoring::                  Assigning values to articles.
* Various::                  General purpose settings.
* The End::                  Farewell and goodbye.
* Appendices::               Terminology, Emacs intro, @acronym{FAQ}, History, Internals.
Chong Yidong's avatar
Chong Yidong committed
405
* GNU Free Documentation License:: The license for this documentation.
406 407
* Index::                    Variable, function and concept index.
* Key Index::                Key Index.
408 409 410

Other related manuals

411 412 413 414
* Message:(message).         Composing messages.
* Emacs-MIME:(emacs-mime).   Composing messages; @acronym{MIME}-specific parts.
* Sieve:(sieve).             Managing Sieve scripts in Emacs.
* PGG:(pgg).                 @acronym{PGP/MIME} with Gnus.
415 416 417 418 419 420

@detailmenu
 --- The Detailed Node Listing ---

Starting Gnus

421 422 423 424 425 426 427 428 429 430 431
* Finding the News::            Choosing a method for getting news.
* The First Time::              What does Gnus do the first time you start it?
* The Server is Down::          How can I read my mail then?
* Slave Gnusae::                You can have more than one Gnus active at a time.
* Fetching a Group::            Starting Gnus just to read a group.
* New Groups::                  What is Gnus supposed to do with new groups?
* Changing Servers::            You may want to move from one server to another.
* Startup Files::               Those pesky startup files---@file{.newsrc}.
* Auto Save::                   Recovering from a crash.
* The Active File::             Reading the active file over a slow line Takes Time.
* Startup Variables::           Other variables you might change.
432 433 434

New Groups

435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457
* Checking New Groups::         Determining what groups are new.
* Subscription Methods::        What Gnus should do with new groups.
* Filtering New Groups::        Making Gnus ignore certain new groups.

Group Buffer

* Group Buffer Format::         Information listed and how you can change it.
* Group Maneuvering::           Commands for moving in the group buffer.
* Selecting a Group::           Actually reading news.
* Subscription Commands::       Unsubscribing, killing, subscribing.
* Group Data::                  Changing the info for a group.
* Group Levels::                Levels? What are those, then?
* Group Score::                 A mechanism for finding out what groups you like.
* Marking Groups::              You can mark groups for later processing.
* Foreign Groups::              Creating and editing groups.
* Group Parameters::            Each group may have different parameters set.
* Listing Groups::              Gnus can list various subsets of the groups.
* Sorting Groups::              Re-arrange the group order.
* Group Maintenance::           Maintaining a tidy @file{.newsrc} file.
* Browse Foreign Server::       You can browse a server.  See what it has to offer.
* Exiting Gnus::                Stop reading news and get some work done.
* Group Topics::                A folding group mode divided into topics.
* Misc Group Stuff::            Other stuff that you can to do.
458 459 460

Group Buffer Format

461 462 463
* Group Line Specification::    Deciding how the group buffer is to look.
* Group Mode Line Specification::  The group buffer mode line.
* Group Highlighting::          Having nice colors in the group buffer.
464 465 466

Group Topics

467 468 469 470 471
* Topic Commands::              Interactive E-Z commands.
* Topic Variables::             How to customize the topics the Lisp Way.
* Topic Sorting::               Sorting each topic individually.
* Topic Topology::              A map of the world.
* Topic Parameters::            Parameters that apply to all groups in a topic.
472 473 474

Misc Group Stuff

475 476 477 478 479
* Scanning New Messages::       Asking Gnus to see whether new messages have arrived.
* Group Information::           Information and help on groups and Gnus.
* Group Timestamp::             Making Gnus keep track of when you last read a group.
* File Commands::               Reading and writing the Gnus files.
* Sieve Commands::              Managing Sieve scripts.
480

481
Summary Buffer
482 483 484 485 486 487

* Summary Buffer Format::       Deciding how the summary buffer is to look.
* Summary Maneuvering::         Moving around the summary buffer.
* Choosing Articles::           Reading articles.
* Paging the Article::          Scrolling the current article.
* Reply Followup and Post::     Posting articles.
488
* Delayed Articles::            Send articles at a later time.
489 490 491
* Marking Articles::            Marking articles as read, expirable, etc.
* Limiting::                    You can limit the summary buffer.
* Threading::                   How threads are made.
492
* Sorting the Summary Buffer::  How articles and threads are sorted.
493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508
* Asynchronous Fetching::       Gnus might be able to pre-fetch articles.
* Article Caching::             You may store articles in a cache.
* Persistent Articles::         Making articles expiry-resistant.
* Article Backlog::             Having already read articles hang around.
* Saving Articles::             Ways of customizing article saving.
* Decoding Articles::           Gnus can treat series of (uu)encoded articles.
* Article Treatment::           The article buffer can be mangled at will.
* MIME Commands::               Doing MIMEy things with the articles.
* Charsets::                    Character set issues.
* Article Commands::            Doing various things with the article buffer.
* Summary Sorting::             Sorting the summary buffer in various ways.
* Finding the Parent::          No child support? Get the parent.
* Alternative Approaches::      Reading using non-default summaries.
* Tree Display::                A more visual display of threads.
* Mail Group Commands::         Some commands can only be used in mail groups.
* Various Summary Stuff::       What didn't fit anywhere else.
509 510
* Exiting the Summary Buffer::  Returning to the Group buffer,
                                or reselecting the current group.
511 512
* Crosspost Handling::          How crossposted articles are dealt with.
* Duplicate Suppression::       An alternative when crosspost handling fails.
513 514
* Security::                    Decrypt and Verify.
* Mailing List::                Mailing list minor mode.
515 516 517

Summary Buffer Format

518 519 520 521
* Summary Buffer Lines::        You can specify how summary lines should look.
* To From Newsgroups::          How to not display your own name.
* Summary Buffer Mode Line::    You can say how the mode line should look.
* Summary Highlighting::        Making the summary buffer all pretty and nice.
522 523 524

Choosing Articles

525 526
* Choosing Commands::           Commands for choosing articles.
* Choosing Variables::          Variables that influence these commands.
527 528 529

Reply, Followup and Post

530 531 532 533 534 535 536 537 538 539
* Summary Mail Commands::       Sending mail.
* Summary Post Commands::       Sending news.
* Summary Message Commands::    Other Message-related commands.
* Canceling and Superseding::

Marking Articles

* Unread Articles::             Marks for unread articles.
* Read Articles::               Marks for read articles.
* Other Marks::                 Marks that do not affect readedness.
540 541 542
* Setting Marks::               How to set and remove marks.
* Generic Marking Commands::    How to customize the marking.
* Setting Process Marks::       How to mark articles for later processing.
543 544 545

Threading

546 547
* Customizing Threading::       Variables you can change to affect the threading.
* Thread Commands::             Thread based commands in the summary buffer.
548 549 550

Customizing Threading

551 552 553 554
* Loose Threads::               How Gnus gathers loose threads into bigger threads.
* Filling In Threads::          Making the threads displayed look fuller.
* More Threading::              Even more variables for fiddling with threads.
* Low-Level Threading::         You thought it was over@dots{} but you were wrong!
555 556 557

Decoding Articles

558 559 560 561 562 563
* Uuencoded Articles::          Uudecode articles.
* Shell Archives::              Unshar articles.
* PostScript Files::            Split PostScript.
* Other Files::                 Plain save and binhex.
* Decoding Variables::          Variables for a happy decoding.
* Viewing Files::               You want to look at the result of the decoding?
564 565 566

Decoding Variables

567 568 569
* Rule Variables::              Variables that say how a file is to be viewed.
* Other Decode Variables::      Other decode variables.
* Uuencoding and Posting::      Variables for customizing uuencoding.
570 571 572

Article Treatment

573 574 575 576 577 578 579 580 581 582 583
* Article Highlighting::        You want to make the article look like fruit salad.
* Article Fontisizing::         Making emphasized text look nice.
* Article Hiding::              You also want to make certain info go away.
* Article Washing::             Lots of way-neat functions to make life better.
* Article Header::              Doing various header transformations.
* Article Buttons::             Click on URLs, Message-IDs, addresses and the like.
* Article Button Levels::       Controlling appearance of buttons.
* Article Date::                Grumble, UT!
* Article Display::             Display various stuff---X-Face, Picons, Smileys
* Article Signature::           What is a signature?
* Article Miscellanea::         Various other stuff.
584 585 586 587 588 589 590 591

Alternative Approaches

* Pick and Read::               First mark articles and then read them.
* Binary Groups::               Auto-decode all articles.

Various Summary Stuff

592 593 594 595
* Summary Group Information::   Information oriented commands.
* Searching for Articles::      Multiple article commands.
* Summary Generation Commands::
* Really Various Summary Commands::  Those pesky non-conformant commands.
596

597
Article Buffer
598

599 600 601 602 603
* Hiding Headers::              Deciding what headers should be displayed.
* Using MIME::                  Pushing articles through @acronym{MIME} before reading them.
* Customizing Articles::        Tailoring the look of the articles.
* Article Keymap::              Keystrokes available in the article buffer.
* Misc Article::                Other stuff.
604 605 606

Composing Messages

607 608 609 610 611 612 613 614 615
* Mail::                        Mailing and replying.
* Posting Server::              What server should you post and mail via?
* POP before SMTP::             You cannot send a mail unless you read a mail.
* Mail and Post::               Mailing and posting at the same time.
* Archived Messages::           Where Gnus stores the messages you've sent.
* Posting Styles::              An easier way to specify who you are.
* Drafts::                      Postponing messages and rejected messages.
* Rejected Articles::           What happens if the server doesn't like your article?
* Signing and encrypting::      How to compose secure messages.
616 617 618

Select Methods

619 620 621 622 623 624 625
* Server Buffer::               Making and editing virtual servers.
* Getting News::                Reading USENET news with Gnus.
* Getting Mail::                Reading your personal mail with Gnus.
* Browsing the Web::            Getting messages from a plethora of Web sources.
* IMAP::                        Using Gnus as a @acronym{IMAP} client.
* Other Sources::               Reading directories, files, SOUP packets.
* Combined Groups::             Combining groups into one group.
626
* Email Based Diary::           Using mails to manage diary events in Gnus.
627 628 629 630 631 632 633 634 635 636 637
* Gnus Unplugged::              Reading news and mail offline.

Server Buffer

* Server Buffer Format::        You can customize the look of this buffer.
* Server Commands::             Commands to manipulate servers.
* Example Methods::             Examples server specifications.
* Creating a Virtual Server::   An example session.
* Server Variables::            Which variables to set.
* Servers and Methods::         You can use server names as select methods.
* Unavailable Servers::         Some servers you try to contact may be down.
638

639
Getting News
640

641 642
* NNTP::                        Reading news from an @acronym{NNTP} server.
* News Spool::                  Reading news from the local spool.
643

644
@acronym{NNTP}
645

646 647 648
* Direct Functions::            Connecting directly to the server.
* Indirect Functions::          Connecting indirectly to the server.
* Common Variables::            Understood by several connection functions.
649 650 651

Getting Mail

652 653 654 655 656 657 658 659 660 661 662 663 664
* Mail in a Newsreader::        Important introductory notes.
* Getting Started Reading Mail::  A simple cookbook example.
* Splitting Mail::              How to create mail groups.
* Mail Sources::                How to tell Gnus where to get mail from.
* Mail Back End Variables::     Variables for customizing mail handling.
* Fancy Mail Splitting::        Gnus can do hairy splitting of incoming mail.
* Group Mail Splitting::        Use group customize to drive mail splitting.
* Incorporating Old Mail::      What about the old mail you have?
* Expiring Mail::               Getting rid of unwanted mail.
* Washing Mail::                Removing cruft from the mail you get.
* Duplicates::                  Dealing with duplicated mail.
* Not Reading Mail::            Using mail back ends for reading other files.
* Choosing a Mail Back End::    Gnus can read a variety of mail formats.
665 666 667

Mail Sources

668 669 670
* Mail Source Specifiers::      How to specify what a mail source is.
* Mail Source Customization::   Some variables that influence things.
* Fetching Mail::               Using the mail source specifiers.
671

ShengHuo ZHU's avatar
ShengHuo ZHU committed
672
Choosing a Mail Back End
673 674

* Unix Mail Box::               Using the (quite) standard Un*x mbox.
675
* Rmail Babyl::                 Emacs programs use the Rmail Babyl format.
676
* Mail Spool::                  Store your mail in a private spool?
ShengHuo ZHU's avatar
ShengHuo ZHU committed
677
* MH Spool::                    An mhspool-like back end.
678
* Maildir::                     Another one-file-per-message format.
679
* Mail Folders::                Having one file for each group.
ShengHuo ZHU's avatar
ShengHuo ZHU committed
680
* Comparing Mail Back Ends::    An in-depth looks at pros and cons.
681 682 683

Browsing the Web

684 685 686 687 688 689
* Archiving Mail::
* Web Searches::                Creating groups from articles that match a string.
* Slashdot::                    Reading the Slashdot comments.
* Ultimate::                    The Ultimate Bulletin Board systems.
* Web Archive::                 Reading mailing list archived on web.
* RSS::                         Reading RDF site summary.
690
* Customizing W3::              Doing stuff to Emacs/W3 from Gnus.
691 692 693 694 695 696 697 698 699

@acronym{IMAP}

* Splitting in IMAP::           Splitting mail with nnimap.
* Expiring in IMAP::            Expiring mail with nnimap.
* Editing IMAP ACLs::           Limiting/enabling other users access to a mailbox.
* Expunging mailboxes::         Equivalent of a ``compress mailbox'' button.
* A note on namespaces::        How to (not) use @acronym{IMAP} namespace in Gnus.
* Debugging IMAP::              What to do when things don't work.
700 701 702

Other Sources

703 704 705 706 707
* Directory Groups::            You can read a directory as if it was a newsgroup.
* Anything Groups::             Dired?  Who needs dired?
* Document Groups::             Single files can be the basis of a group.
* SOUP::                        Reading @sc{soup} packets ``offline''.
* Mail-To-News Gateways::       Posting articles via mail-to-news gateways.
708 709 710 711 712 713 714

Document Groups

* Document Server Internals::   How to add your own document types.

SOUP

715 716 717
* SOUP Commands::               Commands for creating and sending @sc{soup} packets
* SOUP Groups::                 A back end for reading @sc{soup} packets.
* SOUP Replies::                How to enable @code{nnsoup} to take over mail and news.
718 719 720

Combined Groups

721 722
* Virtual Groups::              Combining articles from many groups.
* Kibozed Groups::              Looking through parts of the newsfeed for articles.
723

724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742
Email Based Diary

* The NNDiary Back End::        Basic setup and usage.
* The Gnus Diary Library::      Utility toolkit on top of nndiary.
* Sending or Not Sending::      A final note on sending diary messages.

The NNDiary Back End

* Diary Messages::              What makes a message valid for nndiary.
* Running NNDiary::             NNDiary has two modes of operation.
* Customizing NNDiary::         Bells and whistles.

The Gnus Diary Library

* Diary Summary Line Format::           A nicer summary buffer line format.
* Diary Articles Sorting::              A nicer way to sort messages.
* Diary Headers Generation::            Not doing it manually.
* Diary Group Parameters::              Not handling them manually.

743 744
Gnus Unplugged

745 746 747 748 749 750 751 752 753 754 755 756 757
* Agent Basics::                How it all is supposed to work.
* Agent Categories::            How to tell the Gnus Agent what to download.
* Agent Commands::              New commands for all the buffers.
* Agent Visuals::               Ways that the agent may effect your summary buffer.
* Agent as Cache::              The Agent is a big cache too.
* Agent Expiry::                How to make old articles go away.
* Agent Regeneration::          How to recover from lost connections and other accidents.
* Agent and IMAP::              How to use the Agent with @acronym{IMAP}.
* Outgoing Messages::           What happens when you post/mail something?
* Agent Variables::             Customizing is fun.
* Example Setup::               An example @file{~/.gnus.el} file for offline people.
* Batching Agents::             How to fetch news from a @code{cron} job.
* Agent Caveats::               What you think it'll do and what it does.
758 759 760

Agent Categories

761 762 763
* Category Syntax::             What a category looks like.
* Category Buffer::             A buffer for maintaining categories.
* Category Variables::          Customize'r'Us.
764 765 766

Agent Commands

767 768 769
* Group Agent Commands::        Configure groups and fetch their contents.
* Summary Agent Commands::      Manually select then fetch specific articles.
* Server Agent Commands::       Select the servers that are supported by the agent.
770 771 772

Scoring

773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789
* Summary Score Commands::      Adding score entries for the current group.
* Group Score Commands::        General score commands.
* Score Variables::             Customize your scoring.  (My, what terminology).
* Score File Format::           What a score file may contain.
* Score File Editing::          You can edit score files by hand as well.
* Adaptive Scoring::            Big Sister Gnus knows what you read.
* Home Score File::             How to say where new score entries are to go.
* Followups To Yourself::       Having Gnus notice when people answer you.
* Scoring On Other Headers::    Scoring on non-standard headers.
* Scoring Tips::                How to score effectively.
* Reverse Scoring::             That problem child of old is not problem.
* Global Score Files::          Earth-spanning, ear-splitting score files.
* Kill Files::                  They are still here, but they can be ignored.
* Converting Kill Files::       Translating kill files to score files.
* GroupLens::                   Getting predictions on what you like to read.
* Advanced Scoring::            Using logical expressions to build score rules.
* Score Decays::                It can be useful to let scores wither away.
790 791 792

GroupLens

793 794 795 796
* Using GroupLens::             How to make Gnus use GroupLens.
* Rating Articles::             Letting GroupLens know how you rate articles.
* Displaying Predictions::      Displaying predictions given by GroupLens.
* GroupLens Variables::         Customizing GroupLens.
797 798 799 800 801 802 803 804 805

Advanced Scoring

* Advanced Scoring Syntax::     A definition.
* Advanced Scoring Examples::   What they look like.
* Advanced Scoring Tips::       Getting the most out of it.

Various

806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822
* Process/Prefix::              A convention used by many treatment commands.
* Interactive::                 Making Gnus ask you many questions.
* Symbolic Prefixes::           How to supply some Gnus functions with options.
* Formatting Variables::        You can specify what buffers should look like.
* Window Layout::               Configuring the Gnus buffer windows.
* Faces and Fonts::             How to change how faces look.
* Compilation::                 How to speed Gnus up.
* Mode Lines::                  Displaying information in the mode lines.
* Highlighting and Menus::      Making buffers look all nice and cozy.
* Buttons::                     Get tendinitis in ten easy steps!
* Daemons::                     Gnus can do things behind your back.
* NoCeM::                       How to avoid spam and other fatty foods.
* Undo::                        Some actions can be undone.
* Predicate Specifiers::        Specifying predicates.
* Moderation::                  What to do if you're a moderator.
* Image Enhancements::          Modern versions of Emacs/XEmacs can display images.
* Fuzzy Matching::              What's the big fuzz?
823 824
* Thwarting Email Spam::        Simple ways to avoid unsolicited commercial email.
* Spam Package::                A package for filtering and processing spam.
825 826
* Other modes::                 Interaction with other modes.
* Various Various::             Things that are really various.
827 828 829

Formatting Variables

830 831 832 833 834 835 836 837 838 839 840 841 842
* Formatting Basics::           A formatting variable is basically a format string.
* Mode Line Formatting::        Some rules about mode line formatting variables.
* Advanced Formatting::         Modifying output in various ways.
* User-Defined Specs::          Having Gnus call your own functions.
* Formatting Fonts::            Making the formatting look colorful and nice.
* Positioning Point::           Moving point to a position after an operation.
* Tabulation::                  Tabulating your output.
* Wide Characters::             Dealing with wide characters.

Image Enhancements

* X-Face::                      Display a funky, teensy black-and-white image.
* Face::                        Display a funkier, teensier colored image.
843 844
* Smileys::                     Show all those happy faces the way they were
                                  meant to be shown.
845 846 847 848 849 850 851 852 853 854
* Picons::                      How to display pictures of what you're reading.
* XVarious::                    Other XEmacsy Gnusey variables.

Thwarting Email Spam

* The problem of spam::         Some background, and some solutions
* Anti-Spam Basics::            Simple steps to reduce the amount of spam.
* SpamAssassin::                How to use external anti-spam tools.
* Hashcash::                    Reduce spam by burning CPU time.

855
Spam Package
856

857 858 859 860 861 862 863 864
* Spam Package Introduction::
* Filtering Incoming Mail::
* Detecting Spam in Groups::
* Spam and Ham Processors::
* Spam Package Configuration Examples::
* Spam Back Ends::
* Extending the Spam package::
* Spam Statistics Package::
865

866
Spam Statistics Package
867 868 869 870

* Creating a spam-stat dictionary::
* Splitting mail using spam-stat::
* Low-level interface to the spam-stat dictionary::
871 872 873

Appendices

874 875 876 877 878 879 880 881 882
* XEmacs::                      Requirements for installing under XEmacs.
* History::                     How Gnus got where it is today.
* On Writing Manuals::          Why this is not a beginner's guide.
* Terminology::                 We use really difficult, like, words here.
* Customization::               Tailoring Gnus to your needs.
* Troubleshooting::             What you might try if things do not work.
* Gnus Reference Guide::        Rilly, rilly technical stuff.
* Emacs for Heathens::          A short introduction to Emacsian terms.
* Frequently Asked Questions::  The Gnus FAQ
883 884 885

History

886 887 888 889 890 891 892 893 894
* Gnus Versions::               What Gnus versions have been released.
* Other Gnus Versions::         Other Gnus versions that also have been released.
* Why?::                        What's the point of Gnus?
* Compatibility::               Just how compatible is Gnus with @sc{gnus}?
* Conformity::                  Gnus tries to conform to all standards.
* Emacsen::                     Gnus can be run on a few modern Emacsen.
* Gnus Development::            How Gnus is developed.
* Contributors::                Oodles of people.
* New Features::                Pointers to some of the new stuff in Gnus.
895 896 897

New Features

898 899 900 901 902
* ding Gnus::                   New things in Gnus 5.0/5.1, the first new Gnus.
* September Gnus::              The Thing Formally Known As Gnus 5.2/5.3.
* Red Gnus::                    Third time best---Gnus 5.4/5.5.
* Quassia Gnus::                Two times two is four, or Gnus 5.6/5.7.
* Pterodactyl Gnus::            Pentad also starts with P, AKA Gnus 5.8/5.9.
903
* Oort Gnus::                   It's big.  It's far out.  Gnus 5.10/5.11.
904 905 906

Customization

907 908 909 910
* Slow/Expensive Connection::   You run a local Emacs and get the news elsewhere.
* Slow Terminal Connection::    You run a remote Emacs.
* Little Disk Space::           You feel that having large setup files is icky.
* Slow Machine::                You feel like buying a faster machine.
911 912 913

Gnus Reference Guide

914 915 916 917 918 919 920 921 922
* Gnus Utility Functions::      Common functions and variable to use.
* Back End Interface::          How Gnus communicates with the servers.
* Score File Syntax::           A BNF definition of the score file standard.
* Headers::                     How Gnus stores headers internally.
* Ranges::                      A handy format for storing mucho numbers.
* Group Info::                  The group info format.
* Extended Interactive::        Symbolic prefixes and stuff.
* Emacs/XEmacs Code::           Gnus can be run under all modern Emacsen.
* Various File Formats::        Formats of files that Gnus use.
923

ShengHuo ZHU's avatar
ShengHuo ZHU committed
924
Back End Interface
925

926 927 928 929 930 931
* Required Back End Functions::  Functions that must be implemented.
* Optional Back End Functions::  Functions that need not be implemented.
* Error Messaging::             How to get messages and report errors.
* Writing New Back Ends::       Extending old back ends.
* Hooking New Back Ends Into Gnus::  What has to be done on the Gnus end.
* Mail-like Back Ends::         Some tips on mail back ends.
932 933 934

Various File Formats

935 936
* Active File Format::          Information on articles and groups available.
* Newsgroups File Format::      Group descriptions.
937 938 939

Emacs for Heathens

940 941
* Keystrokes::                  Entering text and executing commands.
* Emacs Lisp::                  The built-in Emacs programming language.
942 943

@end detailmenu
Dave Love's avatar
#  
Dave Love committed
944 945 946 947 948 949
@end menu

@node Starting Up
@chapter Starting Gnus
@cindex starting up

950 951 952
If you are haven't used Emacs much before using Gnus, read @ref{Emacs
for Heathens} first.

Dave Love's avatar
#  
Dave Love committed
953 954 955 956
@kindex M-x gnus
@findex gnus
If your system administrator has set things up properly, starting Gnus
and reading news is extremely easy---you just type @kbd{M-x gnus} in
957 958 959 960
your Emacs.  If not, you should customize the variable
@code{gnus-select-method} as described in @ref{Finding the News}.  For a
minimal setup for posting should also customize the variables
@code{user-full-name} and @code{user-mail-address}.
Dave Love's avatar
#  
Dave Love committed
961 962 963 964 965 966 967

@findex gnus-other-frame
@kindex M-x gnus-other-frame
If you want to start Gnus in a different frame, you can use the command
@kbd{M-x gnus-other-frame} instead.

If things do not go smoothly at startup, you have to twiddle some
968 969
variables in your @file{~/.gnus.el} file.  This file is similar to
@file{~/.emacs}, but is read when Gnus starts.
Dave Love's avatar
#  
Dave Love committed
970 971 972 973 974

If you puzzle at any terms used in this manual, please refer to the
terminology section (@pxref{Terminology}).

@menu
975 976 977 978 979 980 981 982 983 984
* Finding the News::      Choosing a method for getting news.
* The First Time::        What does Gnus do the first time you start it?
* The Server is Down::    How can I read my mail then?
* Slave Gnusae::          You can have more than one Gnus active at a time.
* New Groups::            What is Gnus supposed to do with new groups?
* Changing Servers::      You may want to move from one server to another.
* Startup Files::         Those pesky startup files---@file{.newsrc}.
* Auto Save::             Recovering from a crash.
* The Active File::       Reading the active file over a slow line Takes Time.
* Startup Variables::     Other variables you might change.
Dave Love's avatar
#  
Dave Love committed
985 986 987 988 989 990 991 992 993 994 995 996 997 998 999
@end menu


@node Finding the News
@section Finding the News
@cindex finding news

@vindex gnus-select-method
@c @head
The @code{gnus-select-method} variable says where Gnus should look for
news.  This variable should be a list where the first element says
@dfn{how} and the second element says @dfn{where}.  This method is your
native method.  All groups not fetched with this method are
foreign groups.

1000
For instance, if the @samp{news.somewhere.edu} @acronym{NNTP} server is where
Dave Love's avatar
#  
Dave Love committed
1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013
you want to get your daily dosage of news from, you'd say:

@lisp
(setq gnus-select-method '(nntp "news.somewhere.edu"))
@end lisp

If you want to read directly from the local spool, say:

@lisp
(setq gnus-select-method '(nnspool ""))
@end lisp

If you can use a local spool, you probably should, as it will almost
1014
certainly be much faster.  But do not use the local spool if your
1015 1016
server is running Leafnode (which is a simple, standalone private news
server); in this case, use @code{(nntp "localhost")}.
Dave Love's avatar
#  
Dave Love committed
1017 1018 1019

@vindex gnus-nntpserver-file
@cindex NNTPSERVER
1020
@cindex @acronym{NNTP} server
Dave Love's avatar
#  
Dave Love committed
1021
If this variable is not set, Gnus will take a look at the
1022
@env{NNTPSERVER} environment variable.  If that variable isn't set,
Dave Love's avatar
#  
Dave Love committed
1023
Gnus will see whether @code{gnus-nntpserver-file}
1024 1025 1026
(@file{/etc/nntpserver} by default) has any opinions on the matter.
If that fails as well, Gnus will try to use the machine running Emacs
as an @acronym{NNTP} server.  That's a long shot, though.
Dave Love's avatar
#  
Dave Love committed
1027 1028 1029 1030 1031 1032 1033

@vindex gnus-nntp-server
If @code{gnus-nntp-server} is set, this variable will override
@code{gnus-select-method}.  You should therefore set
@code{gnus-nntp-server} to @code{nil}, which is what it is by default.

@vindex gnus-secondary-servers
1034
@vindex gnus-nntp-server
Dave Love's avatar
#  
Dave Love committed
1035
You can also make Gnus prompt you interactively for the name of an
1036
@acronym{NNTP} server.  If you give a non-numerical prefix to @code{gnus}
Dave Love's avatar
#  
Dave Love committed
1037 1038
(i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
in the @code{gnus-secondary-servers} list (if any).  You can also just
1039 1040 1041 1042
type in the name of any server you feel like visiting.  (Note that this
will set @code{gnus-nntp-server}, which means that if you then @kbd{M-x
gnus} later in the same Emacs session, Gnus will contact the same
server.)
Dave Love's avatar
#  
Dave Love committed
1043 1044

@findex gnus-group-browse-foreign-server
1045 1046
@kindex B (Group)
However, if you use one @acronym{NNTP} server regularly and are just
Dave Love's avatar
#  
Dave Love committed
1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062
interested in a couple of groups from a different server, you would be
better served by using the @kbd{B} command in the group buffer.  It will
let you have a look at what groups are available, and you can subscribe
to any of the groups you want to.  This also makes @file{.newsrc}
maintenance much tidier.  @xref{Foreign Groups}.

@vindex gnus-secondary-select-methods
@c @head
A slightly different approach to foreign groups is to set the
@code{gnus-secondary-select-methods} variable.  The select methods
listed in this variable are in many ways just as native as the
@code{gnus-select-method} server.  They will also be queried for active
files during startup (if that's required), and new newsgroups that
appear on these servers will be subscribed (or not) just as native
groups are.

ShengHuo ZHU's avatar
ShengHuo ZHU committed
1063 1064
For instance, if you use the @code{nnmbox} back end to read your mail,
you would typically set this variable to
Dave Love's avatar
#  
Dave Love committed
1065 1066 1067 1068 1069 1070 1071 1072 1073 1074

@lisp
(setq gnus-secondary-select-methods '((nnmbox "")))
@end lisp


@node The First Time
@section The First Time
@cindex first time usage

1075 1076
If no startup files exist (@pxref{Startup Files}), Gnus will try to
determine what groups should be subscribed by default.
Dave Love's avatar
#  
Dave Love committed
1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120

@vindex gnus-default-subscribed-newsgroups
If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
will subscribe you to just those groups in that list, leaving the rest
killed.  Your system administrator should have set this variable to
something useful.

Since she hasn't, Gnus will just subscribe you to a few arbitrarily
picked groups (i.e., @samp{*.newusers}).  (@dfn{Arbitrary} is defined
here as @dfn{whatever Lars thinks you should read}.)

You'll also be subscribed to the Gnus documentation group, which should
help you with most common problems.

If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
use the normal functions for handling new groups, and not do anything
special.


@node The Server is Down
@section The Server is Down
@cindex server errors

If the default server is down, Gnus will understandably have some
problems starting.  However, if you have some mail groups in addition to
the news groups, you may want to start Gnus anyway.

Gnus, being the trusting sort of program, will ask whether to proceed
without a native select method if that server can't be contacted.  This
will happen whether the server doesn't actually exist (i.e., you have
given the wrong address) or the server has just momentarily taken ill
for some reason or other.  If you decide to continue and have no foreign
groups, you'll find it difficult to actually do anything in the group
buffer.  But, hey, that's your problem.  Blllrph!

@findex gnus-no-server
@kindex M-x gnus-no-server
@c @head
If you know that the server is definitely down, or you just want to read
your mail without bothering with the server at all, you can use the
@code{gnus-no-server} command to start Gnus.  That might come in handy
if you're in a hurry as well.  This command will not attempt to contact
your primary server---instead, it will just activate all groups on level
1 and 2.  (You should preferably keep no native groups on those two
1121
levels.) Also @pxref{Group Levels}.
Dave Love's avatar
#  
Dave Love committed
1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133


@node Slave Gnusae
@section Slave Gnusae
@cindex slave

You might want to run more than one Emacs with more than one Gnus at the
same time.  If you are using different @file{.newsrc} files (e.g., if you
are using the two different Gnusae to read from two different servers),
that is no problem whatsoever.  You just do it.

The problem appears when you want to run two Gnusae that use the same
1134
@file{.newsrc} file.
Dave Love's avatar
#  
Dave Love committed
1135 1136 1137 1138 1139 1140 1141 1142 1143

To work around that problem some, we here at the Think-Tank at the Gnus
Towers have come up with a new concept: @dfn{Masters} and
@dfn{slaves}.  (We have applied for a patent on this concept, and have
taken out a copyright on those words.  If you wish to use those words in
conjunction with each other, you have to send $1 per usage instance to
me.  Usage of the patent (@dfn{Master/Slave Relationships In Computer
Applications}) will be much more expensive, of course.)

1144
@findex gnus-slave
Dave Love's avatar
Dave Love committed
1145
Anyway, you start one Gnus up the normal way with @kbd{M-x gnus} (or
Dave Love's avatar
#  
Dave Love committed
1146 1147 1148 1149 1150 1151 1152 1153 1154
however you do it).  Each subsequent slave Gnusae should be started with
@kbd{M-x gnus-slave}.  These slaves won't save normal @file{.newsrc}
files, but instead save @dfn{slave files} that contain information only
on what groups have been read in the slave session.  When a master Gnus
starts, it will read (and delete) these slave files, incorporating all
information from them.  (The slave files will be read in the sequence
they were created, so the latest changes will have precedence.)

Information from the slave files has, of course, precedence over the
1155
information in the normal (i.e., master) @file{.newsrc} file.
Dave Love's avatar
#  
Dave Love committed
1156

1157 1158 1159 1160 1161
If the @file{.newsrc*} files have not been saved in the master when the
slave starts, you may be prompted as to whether to read an auto-save
file.  If you answer ``yes'', the unsaved changes to the master will be
incorporated into the slave.  If you answer ``no'', the slave may see some
messages as unread that have been read in the master.
Dave Love's avatar
#  
Dave Love committed
1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176



@node New Groups
@section New Groups
@cindex new groups
@cindex subscription

@vindex gnus-check-new-newsgroups
If you are satisfied that you really never want to see any new groups,
you can set @code{gnus-check-new-newsgroups} to @code{nil}.  This will
also save you some time at startup.  Even if this variable is
@code{nil}, you can always subscribe to the new groups just by pressing
@kbd{U} in the group buffer (@pxref{Group Maintenance}).  This variable
is @code{ask-server} by default.  If you set this variable to
ShengHuo ZHU's avatar
ShengHuo ZHU committed
1177
@code{always}, then Gnus will query the back ends for new groups even
Dave Love's avatar
#  
Dave Love committed
1178 1179 1180
when you do the @kbd{g} command (@pxref{Scanning New Messages}).

@menu
1181 1182 1183
* Checking New Groups::         Determining what groups are new.
* Subscription Methods::        What Gnus should do with new groups.
* Filtering New Groups::        Making Gnus ignore certain new groups.
Dave Love's avatar
#  
Dave Love committed
1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254
@end menu


@node Checking New Groups
@subsection Checking New Groups

Gnus normally determines whether a group is new or not by comparing the
list of groups from the active file(s) with the lists of subscribed and
dead groups.  This isn't a particularly fast method.  If
@code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
server for new groups since the last time.  This is both faster and
cheaper.  This also means that you can get rid of the list of killed
groups altogether, so you may set @code{gnus-save-killed-list} to
@code{nil}, which will save time both at startup, at exit, and all over.
Saves disk space, too.  Why isn't this the default, then?
Unfortunately, not all servers support this command.

I bet I know what you're thinking now: How do I find out whether my
server supports @code{ask-server}?  No?  Good, because I don't have a
fail-safe answer.  I would suggest just setting this variable to
@code{ask-server} and see whether any new groups appear within the next
few days.  If any do, then it works.  If none do, then it doesn't
work.  I could write a function to make Gnus guess whether the server
supports @code{ask-server}, but it would just be a guess.  So I won't.
You could @code{telnet} to the server and say @code{HELP} and see
whether it lists @samp{NEWGROUPS} among the commands it understands.  If
it does, then it might work.  (But there are servers that lists
@samp{NEWGROUPS} without supporting the function properly.)

This variable can also be a list of select methods.  If so, Gnus will
issue an @code{ask-server} command to each of the select methods, and
subscribe them (or not) using the normal methods.  This might be handy
if you are monitoring a few servers for new groups.  A side effect is
that startup will take much longer, so you can meditate while waiting.
Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss.


@node Subscription Methods
@subsection Subscription Methods

@vindex gnus-subscribe-newsgroup-method
What Gnus does when it encounters a new group is determined by the
@code{gnus-subscribe-newsgroup-method} variable.

This variable should contain a function.  This function will be called
with the name of the new group as the only parameter.

Some handy pre-fab functions are:

@table @code

@item gnus-subscribe-zombies
@vindex gnus-subscribe-zombies
Make all new groups zombies.  This is the default.  You can browse the
zombies later (with @kbd{A z}) and either kill them all off properly
(with @kbd{S z}), or subscribe to them (with @kbd{u}).

@item gnus-subscribe-randomly
@vindex gnus-subscribe-randomly
Subscribe all new groups in arbitrary order.  This really means that all
new groups will be added at ``the top'' of the group buffer.

@item gnus-subscribe-alphabetically
@vindex gnus-subscribe-alphabetically
Subscribe all new groups in alphabetical order.

@item gnus-subscribe-hierarchically
@vindex gnus-subscribe-hierarchically
Subscribe all new groups hierarchically.  The difference between this
function and @code{gnus-subscribe-alphabetically} is slight.
@code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly
1255
alphabetical fashion, while this function will enter groups into its
Dave Love's avatar
#  
Dave Love committed
1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269
hierarchy.  So if you want to have the @samp{rec} hierarchy before the
@samp{comp} hierarchy, this function will not mess that configuration
up.  Or something like that.

@item gnus-subscribe-interactively
@vindex gnus-subscribe-interactively
Subscribe new groups interactively.  This means that Gnus will ask
you about @strong{all} new groups.  The groups you choose to subscribe
to will be subscribed hierarchically.

@item gnus-subscribe-killed
@vindex gnus-subscribe-killed
Kill all new groups.

1270 1271
@item gnus-subscribe-topics
@vindex gnus-subscribe-topics
1272
Put the groups into the topic that has a matching @code{subscribe} topic
1273 1274 1275 1276 1277 1278 1279
parameter (@pxref{Topic Parameters}).  For instance, a @code{subscribe}
topic parameter that looks like

@example
"nnslashdot"
@end example

1280
will mean that all groups that match that regex will be subscribed under
1281 1282 1283 1284 1285
that topic.

If no topics match the groups, the groups will be subscribed in the
top-level topic.

Dave Love's avatar
#  
Dave Love committed
1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334
@end table

@vindex gnus-subscribe-hierarchical-interactive
A closely related variable is
@code{gnus-subscribe-hierarchical-interactive}.  (That's quite a
mouthful.)  If this variable is non-@code{nil}, Gnus will ask you in a
hierarchical fashion whether to subscribe to new groups or not.  Gnus
will ask you for each sub-hierarchy whether you want to descend the
hierarchy or not.

One common mistake is to set the variable a few paragraphs above
(@code{gnus-subscribe-newsgroup-method}) to
@code{gnus-subscribe-hierarchical-interactive}.  This is an error.  This
will not work.  This is ga-ga.  So don't do it.


@node Filtering New Groups
@subsection Filtering New Groups

A nice and portable way to control which new newsgroups should be
subscribed (or ignored) is to put an @dfn{options} line at the start of
the @file{.newsrc} file.  Here's an example:

@example
options -n !alt.all !rec.all sci.all
@end example

@vindex gnus-subscribe-options-newsgroup-method
This line obviously belongs to a serious-minded intellectual scientific
person (or she may just be plain old boring), because it says that all
groups that have names beginning with @samp{alt} and @samp{rec} should
be ignored, and all groups with names beginning with @samp{sci} should
be subscribed.  Gnus will not use the normal subscription method for
subscribing these groups.
@code{gnus-subscribe-options-newsgroup-method} is used instead.  This
variable defaults to @code{gnus-subscribe-alphabetically}.

@vindex gnus-options-not-subscribe
@vindex gnus-options-subscribe
If you don't want to mess with your @file{.newsrc} file, you can just
set the two variables @code{gnus-options-subscribe} and
@code{gnus-options-not-subscribe}.  These two variables do exactly the
same as the @file{.newsrc} @samp{options -n} trick.  Both are regexps,
and if the new group matches the former, it will be unconditionally
subscribed, and if it matches the latter, it will be ignored.

@vindex gnus-auto-subscribed-groups
Yet another variable that meddles here is
@code{gnus-auto-subscribed-groups}.  It works exactly like
1335 1336 1337 1338 1339 1340 1341 1342
@code{gnus-options-subscribe}, and is therefore really superfluous,
but I thought it would be nice to have two of these.  This variable is
more meant for setting some ground rules, while the other variable is
used more for user fiddling.  By default this variable makes all new
groups that come from mail back ends (@code{nnml}, @code{nnbabyl},
@code{nnfolder}, @code{nnmbox}, @code{nnmh}, and @code{nnmaildir})
subscribed.  If you don't like that, just set this variable to
@code{nil}.
Dave Love's avatar
#  
Dave Love committed
1343 1344 1345 1346 1347 1348 1349 1350 1351

New groups that match this regexp are subscribed using
@code{gnus-subscribe-options-newsgroup-method}.


@node Changing Servers
@section Changing Servers
@cindex changing servers

1352
Sometimes it is necessary to move from one @acronym{NNTP} server to another.
Dave Love's avatar
#  
Dave Love committed
1353 1354 1355 1356 1357 1358 1359 1360 1361
This happens very rarely, but perhaps you change jobs, or one server is
very flaky and you want to use another.

Changing the server is pretty easy, right?  You just change
@code{gnus-select-method} to point to the new server?

@emph{Wrong!}

Article numbers are not (in any way) kept synchronized between different
1362
@acronym{NNTP} servers, and the only way Gnus keeps track of what articles
Dave Love's avatar
#  
Dave Love committed
1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392
you have read is by keeping track of article numbers.  So when you
change @code{gnus-select-method}, your @file{.newsrc} file becomes
worthless.

Gnus provides a few functions to attempt to translate a @file{.newsrc}
file from one server to another.  They all have one thing in
common---they take a looong time to run.  You don't want to use these
functions more than absolutely necessary.

@kindex M-x gnus-change-server
@findex gnus-change-server
If you have access to both servers, Gnus can request the headers for all
the articles you have read and compare @code{Message-ID}s and map the
article numbers of the read articles and article marks.  The @kbd{M-x
gnus-change-server} command will do this for all your native groups.  It
will prompt for the method you want to move to.

@kindex M-x gnus-group-move-group-to-server
@findex gnus-group-move-group-to-server
You can also move individual groups with the @kbd{M-x
gnus-group-move-group-to-server} command.  This is useful if you want to
move a (foreign) group from one server to another.

@kindex M-x gnus-group-clear-data-on-native-groups
@findex gnus-group-clear-data-on-native-groups
If you don't have access to both the old and new server, all your marks
and read ranges have become worthless.  You can use the @kbd{M-x
gnus-group-clear-data-on-native-groups} command to clear out all data
that you have on your native groups.  Use with caution.

1393 1394 1395 1396 1397
@kindex M-x gnus-group-clear-data
@findex gnus-group-clear-data
Clear the data from the current group only---nix out marks and the
list of read articles (@code{gnus-group-clear-data}).

1398 1399 1400
After changing servers, you @strong{must} move the cache hierarchy away,
since the cached articles will have wrong article numbers, which will
affect which articles Gnus thinks are read.
1401 1402 1403 1404
@code{gnus-group-clear-data-on-native-groups} will ask you if you want
to have it done automatically; for @code{gnus-group-clear-data}, you
can use @kbd{M-x gnus-cache-move-cache} (but beware, it will move the
cache for all groups).
1405

Dave Love's avatar
#  
Dave Love committed
1406 1407 1408 1409 1410 1411 1412 1413

@node Startup Files
@section Startup Files
@cindex startup files
@cindex .newsrc
@cindex .newsrc.el
@cindex .newsrc.eld

1414 1415 1416
Most common Unix news readers use a shared startup file called
@file{.newsrc}.  This file contains all the information about what
groups are subscribed, and which articles in these groups have been
Juanma Barranquero's avatar
Juanma Barranquero committed
1417
read.
Dave Love's avatar
#  
Dave Love committed
1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434

Things got a bit more complicated with @sc{gnus}.  In addition to
keeping the @file{.newsrc} file updated, it also used a file called
@file{.newsrc.el} for storing all the information that didn't fit into
the @file{.newsrc} file.  (Actually, it also duplicated everything in
the @file{.newsrc} file.)  @sc{gnus} would read whichever one of these
files was the most recently saved, which enabled people to swap between
@sc{gnus} and other newsreaders.

That was kinda silly, so Gnus went one better: In addition to the
@file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
@file{.newsrc.eld}.  It will read whichever of these files that are most
recent, but it will never write a @file{.newsrc.el} file.  You should
never delete the @file{.newsrc.eld} file---it contains much information
not stored in the @file{.newsrc} file.

@vindex gnus-save-newsrc-file
1435
@vindex gnus-read-newsrc-file
Dave Love's avatar
#  
Dave Love committed
1436 1437 1438 1439
You can turn off writing the @file{.newsrc} file by setting
@code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
the file and save some space, as well as exiting from Gnus faster.
However, this will make it impossible to use other newsreaders than
1440 1441
Gnus.  But hey, who would want to, right?  Similarly, setting
@code{gnus-read-newsrc-file} to @code{nil} makes Gnus ignore the
1442 1443 1444 1445
@file{.newsrc} file and any @file{.newsrc-SERVER} files, which can be
convenient if you use a different news reader occasionally, and you
want to read a different subset of the available groups with that
news reader.
Dave Love's avatar
#  
Dave Love committed
1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460

@vindex gnus-save-killed-list
If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus
will not save the list of killed groups to the startup file.  This will
save both time (when starting and quitting) and space (on disk).  It
will also mean that Gnus has no record of what groups are new or old,
so the automatic new groups subscription methods become meaningless.
You should always set @code{gnus-check-new-newsgroups} to @code{nil} or
@code{ask-server} if you set this variable to @code{nil} (@pxref{New
Groups}).  This variable can also be a regular expression.  If that's
the case, remove all groups that do not match this regexp before
saving.  This can be useful in certain obscure situations that involve
several servers where not all servers support @code{ask-server}.

@vindex gnus-startup-file
1461 1462
@vindex gnus-backup-startup-file
@vindex version-control
Dave Love's avatar
#  
Dave Love committed
1463 1464 1465
The @code{gnus-startup-file} variable says where the startup files are.
The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
file being whatever that one is, with a @samp{.eld} appended.
1466 1467 1468
If you want version control for this file, set
@code{gnus-backup-startup-file}.  It respects the same values as the
@code{version-control} variable.
Dave Love's avatar
#  
Dave Love committed
1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489

@vindex gnus-save-newsrc-hook
@vindex gnus-save-quick-newsrc-hook
@vindex gnus-save-standard-newsrc-hook
@code{gnus-save-newsrc-hook} is called before saving any of the newsrc
files, while @code{gnus-save-quick-newsrc-hook} is called just before
saving the @file{.newsrc.eld} file, and
@code{gnus-save-standard-newsrc-hook} is called just before saving the
@file{.newsrc} file.  The latter two are commonly used to turn version
control on or off.  Version control is on by default when saving the
startup files.  If you want to turn backup creation off, say something like:

@lisp
(defun turn-off-backup ()
  (set (make-local-variable 'backup-inhibited) t))

(add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup)
(add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup)
@end lisp

@vindex gnus-init-file
1490
@vindex gnus-site-init-file
Dave Love's avatar
#  
Dave Love committed
1491
When Gnus starts, it will read the @code{gnus-site-init-file}
1492
(@file{.../site-lisp/gnus-init} by default) and @code{gnus-init-file}
Dave Love's avatar
#  
Dave Love committed
1493 1494 1495 1496 1497 1498
(@file{~/.gnus} by default) files.  These are normal Emacs Lisp files
and can be used to avoid cluttering your @file{~/.emacs} and
@file{site-init} files with Gnus stuff.  Gnus will also check for files
with the same names as these, but with @file{.elc} and @file{.el}
suffixes.  In other words, if you have set @code{gnus-init-file} to
@file{~/.gnus}, it will look for @file{~/.gnus.elc}, @file{~/.gnus.el},