gnus.texi 976 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 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex pg cp

@copying
Copyright (c) 1995, 1996, 1997, 1998, 1999, 2000, 2001,
2002, 2003, 2004
Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
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
33 34

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

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

\makeindex
\begin{document}

53
\newcommand{\gnusversionname}{Gnus v5.10.6}
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
This manual corresponds to Gnus v5.10.6.
Dave Love's avatar
#  
Dave Love committed
363 364 365 366 367

@end ifinfo

@iftex

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

Dave Love's avatar
#  
Dave Love committed
373 374 375 376 377 378 379 380
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,
381 382
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
383 384 385 386 387 388 389 390 391 392 393

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
394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412
* 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.
* Index::                       Variable, function and concept index.
* Key Index::                   Key Index.

Other related manuals

* 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.
413 414 415 416 417 418

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

Starting Gnus

419 420 421 422 423 424 425 426 427 428 429
* 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.
430 431 432

New Groups

433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455
* 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.
456 457 458

Group Buffer Format

459 460 461
* 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.
462 463 464

Group Topics

465 466 467 468 469
* 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.
470 471 472

Misc Group Stuff

473 474 475 476 477
* 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.
478

479
Summary Buffer
480 481 482 483 484 485

* 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.
486
* Delayed Articles::            Send articles at a later time.
487 488 489
* Marking Articles::            Marking articles as read, expirable, etc.
* Limiting::                    You can limit the summary buffer.
* Threading::                   How threads are made.
490
* Sorting the Summary Buffer::  How articles and threads are sorted.
491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506
* 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.
507 508
* Exiting the Summary Buffer::  Returning to the Group buffer,
                                or reselecting the current group.
509 510
* Crosspost Handling::          How crossposted articles are dealt with.
* Duplicate Suppression::       An alternative when crosspost handling fails.
511 512
* Security::                    Decrypt and Verify.
* Mailing List::                Mailing list minor mode.
513 514 515

Summary Buffer Format

516 517 518 519
* 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.
520 521 522

Choosing Articles

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

Reply, Followup and Post

528 529 530 531 532 533 534 535 536 537
* 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.
538 539 540
* 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.
541 542 543

Threading

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

Customizing Threading

549 550 551 552
* 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!
553 554 555

Decoding Articles

556 557 558 559 560 561
* 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?
562 563 564

Decoding Variables

565 566 567
* 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.
568 569 570

Article Treatment

571 572 573 574 575 576 577 578 579 580 581
* 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.
582 583 584 585 586 587 588 589

Alternative Approaches

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

Various Summary Stuff

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

595
Article Buffer
596

597 598 599 600 601
* 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.
602 603 604

Composing Messages

605 606 607 608 609 610 611 612 613
* 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.
614 615 616

Select Methods

617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634
* 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.
* 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.
635

636
Getting News
637

638 639
* NNTP::                        Reading news from an @acronym{NNTP} server.
* News Spool::                  Reading news from the local spool.
640

641
@acronym{NNTP}
642

643 644 645
* Direct Functions::            Connecting directly to the server.
* Indirect Functions::          Connecting indirectly to the server.
* Common Variables::            Understood by several connection functions.
646 647 648

Getting Mail

649 650 651 652 653 654 655 656 657 658 659 660 661
* 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.
662 663 664

Mail Sources

665 666 667
* 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.
668

ShengHuo ZHU's avatar
ShengHuo ZHU committed
669
Choosing a Mail Back End
670 671

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

Browsing the Web

681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696
* 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.
* Customizing w3::              Doing stuff to Emacs/w3 from Gnus.

@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.
697 698 699

Other Sources

700 701 702 703 704
* 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.
705 706 707 708 709 710 711

Document Groups

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

SOUP

712 713 714
* 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.
715 716 717

Combined Groups

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

Gnus Unplugged

723 724 725 726 727 728 729 730 731 732 733 734 735
* 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.
736 737 738

Agent Categories

739 740 741
* Category Syntax::             What a category looks like.
* Category Buffer::             A buffer for maintaining categories.
* Category Variables::          Customize'r'Us.
742 743 744

Agent Commands

745 746 747
* 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.
748 749 750

Scoring

751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767
* 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.
768 769 770

GroupLens

771 772 773 774
* 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.
775 776 777 778 779 780 781 782 783

Advanced Scoring

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

Various

784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803
* 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?
* Thwarting Email Spam::        A how-to on avoiding unsolicited commercial email.
* Other modes::                 Interaction with other modes.
* Various Various::             Things that are really various.
804 805 806

Formatting Variables

807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855
* 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.
* Smileys::                     Show all those happy faces the way they were meant to be shown.
* 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.
* Filtering Spam Using The Spam ELisp Package::
* Filtering Spam Using Statistics with spam-stat::

Filtering Spam Using The Spam ELisp Package

* Spam ELisp Package Sequence of Events::  
* Spam ELisp Package Filtering of Incoming Mail::  
* Spam ELisp Package Global Variables::  
* Spam ELisp Package Configuration Examples::  
* Blacklists and Whitelists::   
* BBDB Whitelists::             
* Gmane Spam Reporting::        
* Anti-spam Hashcash Payments::  
* Blackholes::                  
* Regular Expressions Header Matching::  
* Bogofilter::                  
* ifile spam filtering::        
* spam-stat spam filtering::    
* SpamOracle::                  
* Extending the Spam ELisp package::  

Filtering Spam Using Statistics with spam-stat

* Creating a spam-stat dictionary::
* Splitting mail using spam-stat::
* Low-level interface to the spam-stat dictionary::
856 857 858

Appendices

859 860 861 862 863 864 865 866 867
* 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
868 869 870

History

871 872 873 874 875 876 877 878 879
* 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.
880 881 882

New Features

883 884 885 886 887 888
* 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.
* Oort Gnus::                   It's big.  It's far out.  Gnus 5.10.
889 890 891

Customization

892 893 894 895
* 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.
896 897 898

Gnus Reference Guide

899 900 901 902 903 904 905 906 907
* 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.
908

ShengHuo ZHU's avatar
ShengHuo ZHU committed
909
Back End Interface
910

911 912 913 914 915 916
* 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.
917 918 919

Various File Formats

920 921
* Active File Format::          Information on articles and groups available.
* Newsgroups File Format::      Group descriptions.
922 923 924

Emacs for Heathens

925 926
* Keystrokes::                  Entering text and executing commands.
* Emacs Lisp::                  The built-in Emacs programming language.
927 928

@end detailmenu
Dave Love's avatar
#  
Dave Love committed
929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946
@end menu

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

@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
your Emacs.

@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
947 948
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
949 950 951 952 953

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

@menu
954 955 956 957 958 959 960 961 962 963 964
* 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.
Dave Love's avatar
#  
Dave Love committed
965 966 967 968 969 970 971 972 973 974 975 976 977 978 979
@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.

980
For instance, if the @samp{news.somewhere.edu} @acronym{NNTP} server is where
Dave Love's avatar
#  
Dave Love committed
981 982 983 984 985 986 987 988 989 990 991 992 993
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
994 995
certainly be much faster.  But do not use the local spool if your
server is running Leafnode; in this case, use @code{(nntp "localhost")}.
Dave Love's avatar
#  
Dave Love committed
996 997 998

@vindex gnus-nntpserver-file
@cindex NNTPSERVER
999
@cindex @acronym{NNTP} server
Dave Love's avatar
#  
Dave Love committed
1000
If this variable is not set, Gnus will take a look at the
1001
@env{NNTPSERVER} environment variable.  If that variable isn't set,
Dave Love's avatar
#  
Dave Love committed
1002
Gnus will see whether @code{gnus-nntpserver-file}
1003 1004 1005
(@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
1006 1007 1008 1009 1010 1011 1012

@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
1013
@vindex gnus-nntp-server
Dave Love's avatar
#  
Dave Love committed
1014
You can also make Gnus prompt you interactively for the name of an
1015
@acronym{NNTP} server.  If you give a non-numerical prefix to @code{gnus}
Dave Love's avatar
#  
Dave Love committed
1016 1017
(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
1018 1019 1020 1021
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
1022 1023

@findex gnus-group-browse-foreign-server
1024 1025
@kindex B (Group)
However, if you use one @acronym{NNTP} server regularly and are just
Dave Love's avatar
#  
Dave Love committed
1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041
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
1042 1043
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
1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099

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


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

If no startup files exist, Gnus will try to determine what groups should
be subscribed by default.

@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
1100
levels.) Also @pxref{Group Levels}.
Dave Love's avatar
#  
Dave Love committed
1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112


@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
1113
@file{.newsrc} file.
Dave Love's avatar
#  
Dave Love committed
1114 1115 1116 1117 1118 1119 1120 1121 1122

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.)

1123
@findex gnus-slave
Dave Love's avatar
Dave Love committed
1124
Anyway, you start one Gnus up the normal way with @kbd{M-x gnus} (or
Dave Love's avatar
#  
Dave Love committed
1125 1126 1127 1128 1129 1130 1131 1132 1133
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
1134
information in the normal (i.e., master) @file{.newsrc} file.
Dave Love's avatar
#  
Dave Love committed
1135

1136 1137 1138 1139 1140
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
1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165

@node Fetching a Group
@section Fetching a Group
@cindex fetching a group

@findex gnus-fetch-group
It is sometimes convenient to be able to just say ``I want to read this
group and I don't care whether Gnus has been started or not''.  This is
perhaps more useful for people who write code than for users, but the
command @code{gnus-fetch-group} provides this functionality in any case.
It takes the group name as a parameter.


@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
1166
@code{always}, then Gnus will query the back ends for new groups even
Dave Love's avatar
#  
Dave Love committed
1167 1168 1169
when you do the @kbd{g} command (@pxref{Scanning New Messages}).

@menu
1170 1171 1172
* 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
1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 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
@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
1244
alphabetical fashion, while this function will enter groups into its
Dave Love's avatar
#  
Dave Love committed
1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258
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.

1259 1260
@item gnus-subscribe-topics
@vindex gnus-subscribe-topics
1261
Put the groups into the topic that has a matching @code{subscribe} topic
1262 1263 1264 1265 1266 1267 1268
parameter (@pxref{Topic Parameters}).  For instance, a @code{subscribe}
topic parameter that looks like

@example
"nnslashdot"
@end example

1269
will mean that all groups that match that regex will be subscribed under
1270 1271 1272 1273 1274
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
1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 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
@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
1324 1325 1326 1327 1328 1329 1330 1331
@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
1332 1333 1334 1335 1336 1337 1338 1339 1340

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


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

1341
Sometimes it is necessary to move from one @acronym{NNTP} server to another.
Dave Love's avatar
#  
Dave Love committed
1342 1343 1344 1345 1346 1347 1348 1349 1350
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
1351
@acronym{NNTP} servers, and the only way Gnus keeps track of what articles
Dave Love's avatar
#  
Dave Love committed
1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381
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.

1382 1383 1384 1385 1386
@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}).

1387 1388 1389
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.
1390 1391 1392 1393
@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).
1394

Dave Love's avatar
#  
Dave Love committed
1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421

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

Now, you all know about the @file{.newsrc} file.  All subscription
information is traditionally stored in this file.

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
1422
@vindex gnus-read-newsrc-file
Dave Love's avatar
#  
Dave Love committed
1423 1424 1425 1426
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
1427 1428 1429 1430
Gnus.  But hey, who would want to, right?  Similarly, setting
@code{gnus-read-newsrc-file} to @code{nil} makes Gnus ignore the
@file{.newsrc} file and any @file{.newsrc-SERVER} files, which is
convenient if you have a tendency to use Netscape once in a while.
Dave Love's avatar
#  
Dave Love committed
1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445

@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
1446 1447
@vindex gnus-backup-startup-file
@vindex version-control
Dave Love's avatar
#  
Dave Love committed
1448 1449 1450
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.
1451 1452 1453
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
1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474

@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
1475
@vindex gnus-site-init-file
Dave Love's avatar
#  
Dave Love committed
1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512
When Gnus starts, it will read the @code{gnus-site-init-file}
(@file{.../site-lisp/gnus} by default) and @code{gnus-init-file}
(@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},
and finally @file{~/.gnus} (in this order).



@node Auto Save
@section Auto Save
@cindex dribble file
@cindex auto-save

Whenever you do something that changes the Gnus data (reading articles,
catching up, killing/subscribing groups), the change is added to a
special @dfn{dribble buffer}.  This buffer is auto-saved the normal
Emacs way.  If your Emacs should crash before you have saved the
@file{.newsrc} files, all changes you have made can be recovered from
this file.

If Gnus detects this file at startup, it will ask the user whether to
read it.  The auto save file is deleted whenever the real startup file is
saved.

@vindex gnus-use-dribble-file
If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
maintain a dribble buffer.  The default is @code{t}.

@vindex gnus-dribble-directory
Gnus will put the dribble file(s) in @code{gnus-dribble-directory}.  If
this variable is @code{nil}, which it is by default, Gnus will dribble
into the directory where the @file{.newsrc} file is located.  (This is
normally the user's home directory.)  The dribble file will get the same
1513
file permissions as the @file{.newsrc} file.
Dave Love's avatar
#  
Dave Love committed
1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561

@vindex gnus-always-read-dribble-file
If @code{gnus-always-read-dribble-file} is non-@code{nil}, Gnus will
read the dribble file on startup without querying the user.


@node The Active File
@section The Active File
@cindex active file
@cindex ignored groups

When Gnus starts, or indeed whenever it tries to determine whether new
articles have arrived, it reads the active file.  This is a very large
file that lists all the active groups and articles on the server.

@vindex gnus-ignored-newsgroups
Before examining the active file, Gnus deletes all lines that match the
regexp @code{gnus-ignored-newsgroups}.  This is done primarily to reject
any groups with bogus names, but you can use this variable to make Gnus
ignore hierarchies you aren't ever interested in.  However, this is not
recommended.  In fact, it's highly discouraged.  Instead, @pxref{New
Groups} for an overview of other variables that can be used instead.

@c This variable is
@c @code{nil} by default, and will slow down active file handling somewhat
@c if you set it to anything else.

@vindex gnus-read-active-file
@c @head
The active file can be rather Huge, so if you have a slow network, you
can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
reading the active file.  This variable is @code{some} by default.

Gnus will try to make do by getting information just on the groups that
you actually subscribe to.

Note that if you subscribe to lots and lots of groups, setting this
variable to @code{nil} will probably make Gnus slower, not faster.  At
present, having this variable @code{nil} will slow Gnus down
considerably, unless you read news over a 2400 baud modem.

This variable can also have the value @code{some}.  Gnus will then
attempt to read active info only on the subscribed groups.  On some
servers this is quite fast (on sparkling, brand new INN servers that
support the @code{LIST ACTIVE group} command), on others this isn't fast
at all.  In any case, @code{some} should be faster than @code{nil}, and
is certainly faster than @code{t} over slow lines.

1562 1563 1564 1565
Some news servers (old versions of Leafnode and old versions of INN, for
instance) do not support the @code{LIST ACTIVE group}.  For these
servers, @code{nil} is probably the most efficient value for this
variable.
1566

Dave Love's avatar
#  
Dave Love committed
1567 1568
If this variable is @code{nil}, Gnus will ask for group info in total
lock-step, which isn't very fast.  If it is @code{some} and you use an
1569
@acronym{NNTP} server, Gnus will pump out commands as fast as it can, and
Dave Love's avatar
#  
Dave Love committed
1570 1571 1572 1573
read all the replies in one swoop.  This will normally result in better
performance, but if the server does not support the aforementioned
@code{LIST ACTIVE group} command, this isn't very nice to the server.

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

Dave Love's avatar
#  
Dave Love committed
1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607
In any case, if you use @code{some} or @code{nil}, you should definitely
kill all groups that you aren't interested in to speed things up.

Note that this variable also affects active file retrieval from
secondary select methods.


@node Startup Variables
@section Startup Variables

@table @code

@item gnus-load-hook
@vindex gnus-load-hook
A hook run while Gnus is being loaded.  Note that this hook will
normally be run just once in each Emacs session, no matter how many
times you start Gnus.

@item gnus-before-startup-hook
@vindex gnus-before-startup-hook
A hook run after starting up Gnus successfully.

@item gnus-startup-hook
@vindex gnus-startup-hook
A hook run as the very last thing after starting up Gnus

@item gnus-started-hook
@vindex gnus-started-hook
A hook that is run as the very last thing after starting up Gnus
successfully.

1608 1609
@item gnus-setup-news-hook
@vindex gnus-setup-news-hook
Dave Love's avatar
#  
Dave Love committed
1610 1611