From: ichikawa Date: Thu, 24 Sep 1998 15:53:07 +0000 (+0000) Subject: Add gnus.texi and message.texi for correct file. X-Git-Tag: pgnus-ichikawa-199811302358~206 X-Git-Url: http://git.chise.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4f2e90dd408c974990d620e8f92ac9890722d8fb;p=elisp%2Fgnus.git- Add gnus.texi and message.texi for correct file. --- diff --git a/texi/gnus.texi b/texi/gnus.texi new file mode 100644 index 0000000..abb72ac --- /dev/null +++ b/texi/gnus.texi @@ -0,0 +1,20121 @@ +\input texinfo @c -*-texinfo-*- + +@setfilename gnus +@settitle Semi-gnus 6.10.021 Manual +@synindex fn cp +@synindex vr cp +@synindex pg cp +@c @direntry +@c * Gnus: (gnus). The newsreader Gnus. +@c @end direntry +@iftex +@finalout +@end iftex +@setchapternewpage odd + +@iftex +@iflatex +\documentclass[twoside,a4paper,openright,11pt]{book} +\usepackage[latin1]{inputenc} +\usepackage{pagestyle} +\usepackage{epsfig} +\usepackage{bembo} +\usepackage{pixidx} + +\makeindex +\begin{document} + +\newcommand{\gnuschaptername}{} +\newcommand{\gnussectionname}{} + +\newcommand{\gnusbackslash}{/} + +\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}} + +\newcommand{\gnustt}[1]{{\fontfamily{pfu}\fontsize{10pt}{10}\selectfont #1}} +\newcommand{\gnuscode}[1]{\gnustt{#1}} +\newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\fontfamily{pfu}\fontsize{10pt}{10}\selectfont #1}''} +\newcommand{\gnuslisp}[1]{\gnustt{#1}} +\newcommand{\gnuskbd}[1]{`\gnustt{#1}'} +\newcommand{\gnusfile}[1]{`\gnustt{#1}'} +\newcommand{\gnusdfn}[1]{\textit{#1}} +\newcommand{\gnusi}[1]{\textit{#1}} +\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}}} +\newcommand{\gnusauthor}[1]{{\large\textbf{#1}}} + +\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}{{$>$}} + +\newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=ps/gnus-head.eps,height=1cm}}} +\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]{ +\marginpar[\mbox{}\hfill\raisebox{-1.5cm}{\epsfig{figure=tmp/#1-up.ps,height=1.5cm}}]{\raisebox{-1cm}{\epsfig{figure=tmp/#1-up.ps,height=1cm}}} +} + +\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}} + +\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 +\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}} +\else +\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}} +\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 +\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}} +\else +\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}} +\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 +\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}} +\else +\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo.eps,height=1cm}} +\hfill \mbox{} +\fi +} + +\pagenumbering{roman} +\pagestyle{gnuspreamble} + +@end iflatex +@end iftex + +@iftex +@iflatex +\begin{titlepage} +{ + +%\addtolength{\oddsidemargin}{-5cm} +%\addtolength{\evensidemargin}{-5cm} +\parindent=0cm +\addtolength{\textheight}{2cm} + +\gnustitle{\gnustitlename}\\ +\rule{15cm}{1mm}\\ +\vfill +\hspace*{0cm}\epsfig{figure=ps/gnus-big-logo.eps,height=15cm} +\vfill +\rule{15cm}{1mm}\\ +\gnusauthor{by Lars Magne Ingebrigtsen} +\newpage +} + +\mbox{} +\vfill + +\thispagestyle{empty} + +Copyright \copyright{} 1995,96,97,98 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. + +\newpage +\end{titlepage} +@end iflatex +@end iftex + +@ifinfo + +This file documents gnus, the GNU Emacs newsreader. + +Copyright (C) 1995,96 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@tex + +@titlepage +@title Semi-gnus 6.10.021 Manual + +@author by Lars Magne Ingebrigtsen +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1995,96,97 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. + +@end titlepage +@page + +@end tex + + +@node Top +@top The gnus Newsreader + +@ifinfo + +You can read news (and mail) from within Emacs by using gnus. The news +can be gotten by any nefarious means you can think of---@sc{nntp}, local +spool or your mbox file. All at the same time, if you want to push your +luck. + +Semi-gnus provides MIME features based on SEMI API. So Semi-gnus +supports your right to read strange messages including big images or +other various kinds of formats. Semi-gnus also supports +internationalization/localization and multiscript features based on MULE +API. So Semi-gnus does not discriminate various language communities. +Oh, if you are a Klingon, please wait Unicode Next Generation. + +This manual corresponds to Semi-gnus 6.10.021. + +@end ifinfo + +@iftex + +@iflatex +\tableofcontents +\gnuscleardoublepage +@end iflatex + +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, +you can browse directories with it, you can @code{ftp} with it---you can +even read news with it! + +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 +* Starting Up:: Finding news can be a pain. +* The Group Buffer:: Selecting, subscribing and killing groups. +* The Summary Buffer:: Reading, saving and posting articles. +* The 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, FAQ, History, Internals. +* Index:: Variable, function and concept index. +* Key Index:: Key Index. +@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 +variables in your @file{~/.gnus} file. This file is similar to +@file{~/.emacs}, but is read when gnus starts. + +If you puzzle at any terms used in this manual, please refer to the +terminology section (@pxref{Terminology}). + +@menu +* 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? +* 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. +* Changing Servers:: You may want to move from one server to another. +* Startup Variables:: Other variables you might change. +@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. + +For instance, if the @samp{news.somewhere.edu} @sc{nntp} server is where +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 +certainly be much faster. + +@vindex gnus-nntpserver-file +@cindex NNTPSERVER +@cindex @sc{nntp} server +If this variable is not set, gnus will take a look at the +@code{NNTPSERVER} environment variable. If that variable isn't set, +gnus will see whether @code{gnus-nntpserver-file} +(@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 +@sc{nntp} server. That's a long shot, though. + +@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 +You can also make gnus prompt you interactively for the name of an +@sc{nntp} server. If you give a non-numerical prefix to @code{gnus} +(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 +type in the name of any server you feel like visiting. + +@findex gnus-group-browse-foreign-server +@kindex B (Group) +However, if you use one @sc{nntp} server regularly and are just +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. + +For instance, if you use the @code{nnmbox} backend to read your mail, you +would typically set this variable to + +@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 +levels.) + + +@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 +@code{.newsrc} file. + +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.) + +Anyways, you start one gnus up the normal way with @kbd{M-x gnus} (or +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 +information in the normal (i.e., master) @code{.newsrc} file. + + +@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 +@code{always}, then gnus will query the backends for new groups even +when you do the @kbd{g} command (@pxref{Scanning New Messages}). + +@menu +* 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. +@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 +alphabetical fashion, while this function will enter groups into it's +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. + +@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 +@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 backends (@code{nnml}, @code{nnbabyl}, +@code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you +don't like that, just set this variable to @code{nil}. + +New groups that match this regexp are subscribed using +@code{gnus-subscribe-options-newsgroup-method}. + + +@node Changing Servers +@section Changing Servers +@cindex changing servers + +Sometimes it is necessary to move from one @sc{nntp} server to another. +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 +@sc{nntp} servers, and the only way Gnus keeps track of what articles +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. + + +@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. + +In addition, gnus does not change anything. Hail comrade Lars! + +@vindex gnus-save-newsrc-file +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 +gnus. But hey, who would want to, right? + +@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 +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. + +@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 +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 +file permissions as the @code{.newsrc} file. + +@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. + +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 +@sc{nntp} server, gnus will pump out commands as fast as it can, and +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. + +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. + +@item gnus-started-hook +@vindex gnus-started-hook +A hook that is run after reading the @file{.newsrc} file(s), but before +generating the group buffer. + +@item gnus-check-bogus-newsgroups +@vindex gnus-check-bogus-newsgroups +If non-@code{nil}, gnus will check for and delete all bogus groups at +startup. A @dfn{bogus group} is a group that you have in your +@file{.newsrc} file, but doesn't exist on the news server. Checking for +bogus groups can take quite a while, so to save time and resources it's +best to leave this option off, and do the checking for bogus groups once +in a while from the group buffer instead (@pxref{Group Maintenance}). + +@item gnus-inhibit-startup-message +@vindex gnus-inhibit-startup-message +If non-@code{nil}, the startup message won't be displayed. That way, +your boss might not notice as easily that you are reading news instead +of doing your job. Note that this variable is used before +@file{.gnus.el} is loaded, so it should be set in @code{.emacs} instead. + +@item gnus-no-groups-message +@vindex gnus-no-groups-message +Message displayed by gnus when no groups are available. + +@item gnus-play-startup-jingle +@vindex gnus-play-startup-jingle +If non-@code{nil}, play the gnus jingle at startup. + +@item gnus-startup-jingle +@vindex gnus-startup-jingle +Jingle to be played if the above variable is non-@code{nil}. The +default is @samp{Tuxedomoon.Jingle4.au}. + +@end table + + +@node The Group Buffer +@chapter The Group Buffer +@cindex group buffer + +The @dfn{group buffer} lists all (or parts) of the available groups. It +is the first buffer shown when gnus starts, and will never be killed as +long as gnus is active. + +@iftex +@iflatex +\gnusfigure{The Group Buffer}{320}{ +\put(75,50){\epsfig{figure=tmp/group.ps,height=9cm}} +\put(120,37){\makebox(0,0)[t]{Buffer name}} +\put(120,38){\vector(1,2){10}} +\put(40,60){\makebox(0,0)[r]{Mode line}} +\put(40,58){\vector(1,0){30}} +\put(200,28){\makebox(0,0)[t]{Native select method}} +\put(200,26){\vector(-1,2){15}} +} +@end iflatex +@end iftex + +@menu +* 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. +* Group Data:: Changing the info for a group. +* Subscription Commands:: Unsubscribing, killing, subscribing. +* 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. +@end menu + + +@node Group Buffer Format +@section Group Buffer Format + +@menu +* Group Line Specification:: Deciding how the group buffer is to look. +* Group Modeline Specification:: The group buffer modeline. +* Group Highlighting:: Having nice colors in the group buffer. +@end menu + + +@node Group Line Specification +@subsection Group Line Specification +@cindex group buffer format + +The default format of the group buffer is nice and dull, but you can +make it as exciting and ugly as you feel like. + +Here's a couple of example group lines: + +@example + 25: news.announce.newusers + * 0: alt.fan.andrea-dworkin +@end example + +Quite simple, huh? + +You can see that there are 25 unread articles in +@samp{news.announce.newusers}. There are no unread articles, but some +ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little +asterisk at the beginning of the line?). + +@vindex gnus-group-line-format +You can change that format to whatever you want by fiddling with the +@code{gnus-group-line-format} variable. This variable works along the +lines of a @code{format} specification, which is pretty much the same as +a @code{printf} specifications, for those of you who use (feh!) C. +@xref{Formatting Variables}. + +@samp{%M%S%5y: %(%g%)\n} is the value that produced those lines above. + +There should always be a colon on the line; the cursor always moves to +the colon after performing an operation. Nothing else is required---not +even the group name. All displayed text is just window dressing, and is +never examined by gnus. Gnus stores all real information it needs using +text properties. + +(Note that if you make a really strange, wonderful, spreadsheet-like +layout, everybody will believe you are hard at work with the accounting +instead of wasting time reading news.) + +Here's a list of all available format characters: + +@table @samp + +@item M +An asterisk if the group only has marked articles. + +@item S +Whether the group is subscribed. + +@item L +Level of subscribedness. + +@item N +Number of unread articles. + +@item I +Number of dormant articles. + +@item T +Number of ticked articles. + +@item R +Number of read articles. + +@item t +Estimated total number of articles. (This is really @var{max-number} +minus @var{min-number} plus 1.) + +@item y +Number of unread, unticked, non-dormant articles. + +@item i +Number of ticked and dormant articles. + +@item g +Full group name. + +@item G +Group name. + +@item D +Newsgroup description. + +@item o +@samp{m} if moderated. + +@item O +@samp{(m)} if moderated. + +@item s +Select method. + +@item n +Select from where. + +@item z +A string that looks like @samp{<%s:%n>} if a foreign select method is +used. + +@item P +Indentation based on the level of the topic (@pxref{Group Topics}). + +@item c +@vindex gnus-group-uncollapsed-levels +Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels} +variable says how many levels to leave at the end of the group name. +The default is 1---this will mean that group names like +@samp{gnu.emacs.gnus} will be shortened to @samp{g.emacs.gnus}. + +@item m +@vindex gnus-new-mail-mark +@cindex % +@samp{%} (@code{gnus-new-mail-mark}) if there has arrived new mail to +the group lately. + +@item d +A string that says when you last read the group (@pxref{Group +Timestamp}). + +@item u +User defined specifier. The next character in the format string should +be a letter. Gnus will call the function +@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter +following @samp{%u}. The function will be passed a single dummy +parameter as argument. The function should return a string, which will +be inserted into the buffer just like information from any other +specifier. +@end table + +@cindex * +All the ``number-of'' specs will be filled with an asterisk (@samp{*}) +if no info is available---for instance, if it is a non-activated foreign +group, or a bogus native group. + + +@node Group Modeline Specification +@subsection Group Modeline Specification +@cindex group modeline + +@vindex gnus-group-mode-line-format +The mode line can be changed by setting +@code{gnus-group-mode-line-format} (@pxref{Mode Line Formatting}). It +doesn't understand that many format specifiers: + +@table @samp +@item S +The native news server. +@item M +The native select method. +@end table + + +@node Group Highlighting +@subsection Group Highlighting +@cindex highlighting +@cindex group highlighting + +@vindex gnus-group-highlight +Highlighting in the group buffer is controlled by the +@code{gnus-group-highlight} variable. This is an alist with elements +that look like @var{(form . face)}. If @var{form} evaluates to +something non-@code{nil}, the @var{face} will be used on the line. + +Here's an example value for this variable that might look nice if the +background is dark: + +@lisp +(face-spec-set 'my-group-face-1 + '((t (:foreground "Red" :bold t)))) +(face-spec-set 'my-group-face-2 + '((t (:foreground "SeaGreen" :bold t)))) +(face-spec-set 'my-group-face-3 + '((t (:foreground "SpringGreen" :bold t)))) +(face-spec-set 'my-group-face-4 + '((t (:foreground "SteelBlue" :bold t)))) +(face-spec-set 'my-group-face-5 + '((t (:foreground "SkyBlue" :bold t)))) + +(setq gnus-group-highlight + '(((> unread 200) . my-group-face-1) + ((and (< level 3) (zerop unread)) . my-group-face-2) + ((< level 3) . my-group-face-3) + ((zerop unread) . my-group-face-4) + (t . my-group-face-5))) +@end lisp + +Also @pxref{Faces and Fonts}. + +Variables that are dynamically bound when the forms are evaluated +include: + +@table @code +@item group +The group name. +@item unread +The number of unread articles in the group. +@item method +The select method. +@item mailp +Whether the group is a mail group. +@item level +The level of the group. +@item score +The score of the group. +@item ticked +The number of ticked articles in the group. +@item total +The total number of articles in the group. Or rather, MAX-NUMBER minus +MIN-NUMBER plus one. +@item topic +When using the topic minor mode, this variable is bound to the current +topic being inserted. +@end table + +When the forms are @code{eval}ed, point is at the beginning of the line +of the group in question, so you can use many of the normal gnus +functions for snarfing info on the group. + +@vindex gnus-group-update-hook +@findex gnus-group-highlight-line +@code{gnus-group-update-hook} is called when a group line is changed. +It will not be called when @code{gnus-visual} is @code{nil}. This hook +calls @code{gnus-group-highlight-line} by default. + + +@node Group Maneuvering +@section Group Maneuvering +@cindex group movement + +All movement commands understand the numeric prefix and will behave as +expected, hopefully. + +@table @kbd + +@item n +@kindex n (Group) +@findex gnus-group-next-unread-group +Go to the next group that has unread articles +(@code{gnus-group-next-unread-group}). + +@item p +@itemx DEL +@kindex DEL (Group) +@kindex p (Group) +@findex gnus-group-prev-unread-group +Go to the previous group that has unread articles +(@code{gnus-group-prev-unread-group}). + +@item N +@kindex N (Group) +@findex gnus-group-next-group +Go to the next group (@code{gnus-group-next-group}). + +@item P +@kindex P (Group) +@findex gnus-group-prev-group +Go to the previous group (@code{gnus-group-prev-group}). + +@item M-n +@kindex M-n (Group) +@findex gnus-group-next-unread-group-same-level +Go to the next unread group on the same (or lower) level +(@code{gnus-group-next-unread-group-same-level}). + +@item M-p +@kindex M-p (Group) +@findex gnus-group-prev-unread-group-same-level +Go to the previous unread group on the same (or lower) level +(@code{gnus-group-prev-unread-group-same-level}). +@end table + +Three commands for jumping to groups: + +@table @kbd + +@item j +@kindex j (Group) +@findex gnus-group-jump-to-group +Jump to a group (and make it visible if it isn't already) +(@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just +like living groups. + +@item , +@kindex , (Group) +@findex gnus-group-best-unread-group +Jump to the unread group with the lowest level +(@code{gnus-group-best-unread-group}). + +@item . +@kindex . (Group) +@findex gnus-group-first-unread-group +Jump to the first group with unread articles +(@code{gnus-group-first-unread-group}). +@end table + +@vindex gnus-group-goto-unread +If @code{gnus-group-goto-unread} is @code{nil}, all the movement +commands will move to the next group, not the next unread group. Even +the commands that say they move to the next unread group. The default +is @code{t}. + + +@node Selecting a Group +@section Selecting a Group +@cindex group selection + +@table @kbd + +@item SPACE +@kindex SPACE (Group) +@findex gnus-group-read-group +Select the current group, switch to the summary buffer and display the +first unread article (@code{gnus-group-read-group}). If there are no +unread articles in the group, or if you give a non-numerical prefix to +this command, gnus will offer to fetch all the old articles in this +group from the server. If you give a numerical prefix @var{N}, @var{N} +determines the number of articles gnus will fetch. If @var{N} is +positive, gnus fetches the @var{N} newest articles, if @var{N} is +negative, gnus fetches the @var{abs(N)} oldest articles. + +@item RET +@kindex RET (Group) +@findex gnus-group-select-group +Select the current group and switch to the summary buffer +(@code{gnus-group-select-group}). Takes the same arguments as +@code{gnus-group-read-group}---the only difference is that this command +does not display the first unread article automatically upon group +entry. + +@item M-RET +@kindex M-RET (Group) +@findex gnus-group-quick-select-group +This does the same as the command above, but tries to do it with the +minimum amount of fuzz (@code{gnus-group-quick-select-group}). No +scoring/killing will be performed, there will be no highlights and no +expunging. This might be useful if you're in a real hurry and have to +enter some humongous group. If you give a 0 prefix to this command +(i.e., @kbd{0 M-RET}), gnus won't even generate the summary buffer, +which is useful if you want to toggle threading before generating the +summary buffer (@pxref{Summary Generation Commands}). + +@item M-SPACE +@kindex M-SPACE (Group) +@findex gnus-group-visible-select-group +This is yet one more command that does the same as the @kbd{RET} +command, but this one does it without expunging and hiding dormants +(@code{gnus-group-visible-select-group}). + +@item M-C-RET +@kindex M-C-RET (Group) +@findex gnus-group-select-group-ephemerally +Finally, this command selects the current group ephemerally without +doing any processing of its contents +(@code{gnus-group-select-group-ephemerally}). Even threading has been +turned off. Everything you do in the group after selecting it in this +manner will have no permanent effects. + +@end table + +@vindex gnus-large-newsgroup +The @code{gnus-large-newsgroup} variable says what gnus should consider +to be a big group. This is 200 by default. If the group has more +(unread and/or ticked) articles than this, gnus will query the user +before entering the group. The user can then specify how many articles +should be fetched from the server. If the user specifies a negative +number (@code{-n}), the @code{n} oldest articles will be fetched. If it +is positive, the @code{n} articles that have arrived most recently will +be fetched. + +@vindex gnus-select-group-hook +@vindex gnus-auto-select-first +@code{gnus-auto-select-first} control whether any articles are selected +automatically when entering a group with the @kbd{SPACE} command. + +@table @code + +@item nil +Don't select any articles when entering the group. Just display the +full summary buffer. + +@item t +Select the first unread article when entering the group. + +@item best +Select the highest scored article in the group when entering the +group. +@end table + +If you want to prevent automatic selection in some group (say, in a +binary group with Huge articles) you can set this variable to @code{nil} +in @code{gnus-select-group-hook}, which is called when a group is +selected. + + +@node Subscription Commands +@section Subscription Commands +@cindex subscription + +@table @kbd + +@item S t +@itemx u +@kindex S t (Group) +@kindex u (Group) +@findex gnus-group-unsubscribe-current-group +@c @icon{gnus-group-unsubscribe} +Toggle subscription to the current group +(@code{gnus-group-unsubscribe-current-group}). + +@item S s +@itemx U +@kindex S s (Group) +@kindex U (Group) +@findex gnus-group-unsubscribe-group +Prompt for a group to subscribe, and then subscribe it. If it was +subscribed already, unsubscribe it instead +(@code{gnus-group-unsubscribe-group}). + +@item S k +@itemx C-k +@kindex S k (Group) +@kindex C-k (Group) +@findex gnus-group-kill-group +@c @icon{gnus-group-kill-group} +Kill the current group (@code{gnus-group-kill-group}). + +@item S y +@itemx C-y +@kindex S y (Group) +@kindex C-y (Group) +@findex gnus-group-yank-group +Yank the last killed group (@code{gnus-group-yank-group}). + +@item C-x C-t +@kindex C-x C-t (Group) +@findex gnus-group-transpose-groups +Transpose two groups (@code{gnus-group-transpose-groups}). This isn't +really a subscription command, but you can use it instead of a +kill-and-yank sequence sometimes. + +@item S w +@itemx C-w +@kindex S w (Group) +@kindex C-w (Group) +@findex gnus-group-kill-region +Kill all groups in the region (@code{gnus-group-kill-region}). + +@item S z +@kindex S z (Group) +@findex gnus-group-kill-all-zombies +Kill all zombie groups (@code{gnus-group-kill-all-zombies}). + +@item S C-k +@kindex S C-k (Group) +@findex gnus-group-kill-level +Kill all groups on a certain level (@code{gnus-group-kill-level}). +These groups can't be yanked back after killing, so this command should +be used with some caution. The only time where this command comes in +really handy is when you have a @file{.newsrc} with lots of unsubscribed +groups that you want to get rid off. @kbd{S C-k} on level 7 will +kill off all unsubscribed groups that do not have message numbers in the +@file{.newsrc} file. + +@end table + +Also @pxref{Group Levels}. + + +@node Group Data +@section Group Data + +@table @kbd + +@item c +@kindex c (Group) +@findex gnus-group-catchup-current +@vindex gnus-group-catchup-group-hook +@c @icon{gnus-group-catchup-current} +Mark all unticked articles in this group as read +(@code{gnus-group-catchup-current}). +@code{gnus-group-catchup-group-hook} is called when catching up a group +from the group buffer. + +@item C +@kindex C (Group) +@findex gnus-group-catchup-current-all +Mark all articles in this group, even the ticked ones, as read +(@code{gnus-group-catchup-current-all}). + +@item M-c +@kindex M-c (Group) +@findex gnus-group-clear-data +Clear the data from the current group---nix out marks and the list of +read articles (@code{gnus-group-clear-data}). + +@item M-x gnus-group-clear-data-on-native-groups +@kindex M-x gnus-group-clear-data-on-native-groups +@findex gnus-group-clear-data-on-native-groups +If you have switched from one @sc{nntp} server to another, all your marks +and read ranges have become worthless. You can use this command to +clear out all data that you have on your native groups. Use with +caution. + +@end table + + +@node Group Levels +@section Group Levels +@cindex group level +@cindex level + +All groups have a level of @dfn{subscribedness}. For instance, if a +group is on level 2, it is more subscribed than a group on level 5. You +can ask gnus to just list groups on a given level or lower +(@pxref{Listing Groups}), or to just check for new articles in groups on +a given level or lower (@pxref{Scanning New Messages}). + +Remember: The higher the level of the group, the less important it is. + +@table @kbd + +@item S l +@kindex S l (Group) +@findex gnus-group-set-current-level +Set the level of the current group. If a numeric prefix is given, the +next @var{n} groups will have their levels set. The user will be +prompted for a level. +@end table + +@vindex gnus-level-killed +@vindex gnus-level-zombie +@vindex gnus-level-unsubscribed +@vindex gnus-level-subscribed +Gnus considers groups from levels 1 to +@code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed, +@code{gnus-level-subscribed} (exclusive) and +@code{gnus-level-unsubscribed} (inclusive) (default 7) to be +unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead) +(default 8) and @code{gnus-level-killed} to be killed (completely dead) +(default 9). Gnus treats subscribed and unsubscribed groups exactly the +same, but zombie and killed groups have no information on what articles +you have read, etc, stored. This distinction between dead and living +groups isn't done because it is nice or clever, it is done purely for +reasons of efficiency. + +It is recommended that you keep all your mail groups (if any) on quite +low levels (e.g. 1 or 2). + +If you want to play with the level variables, you should show some care. +Set them once, and don't touch them ever again. Better yet, don't touch +them at all unless you know exactly what you're doing. + +@vindex gnus-level-default-unsubscribed +@vindex gnus-level-default-subscribed +Two closely related variables are @code{gnus-level-default-subscribed} +(default 3) and @code{gnus-level-default-unsubscribed} (default 6), +which are the levels that new groups will be put on if they are +(un)subscribed. These two variables should, of course, be inside the +relevant valid ranges. + +@vindex gnus-keep-same-level +If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands +will only move to groups of the same level (or lower). In +particular, going from the last article in one group to the next group +will go to the next group of the same level (or lower). This might be +handy if you want to read the most important groups before you read the +rest. + +@vindex gnus-group-default-list-level +All groups with a level less than or equal to +@code{gnus-group-default-list-level} will be listed in the group buffer +by default. + +@vindex gnus-group-list-inactive-groups +If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active +groups will be listed along with the unread groups. This variable is +@code{t} by default. If it is @code{nil}, inactive groups won't be +listed. + +@vindex gnus-group-use-permanent-levels +If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you +give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will +use this level as the ``work'' level. + +@vindex gnus-activate-level +Gnus will normally just activate (i. e., query the server about) groups +on level @code{gnus-activate-level} or less. If you don't want to +activate unsubscribed groups, for instance, you might set this variable +to 5. The default is 6. + + +@node Group Score +@section Group Score +@cindex group score +@cindex group rank +@cindex rank + +You would normally keep important groups on high levels, but that scheme +is somewhat restrictive. Don't you wish you could have Gnus sort the +group buffer according to how often you read groups, perhaps? Within +reason? + +This is what @dfn{group score} is for. You can assign a score to each +group. You can then sort the group buffer based on this score. +Alternatively, you can sort on score and then level. (Taken together, +the level and the score is called the @dfn{rank} of the group. A group +that is on level 4 and has a score of 1 has a higher rank than a group +on level 5 that has a score of 300. (The level is the most significant +part and the score is the least significant part.)) + +@findex gnus-summary-bubble-group +If you want groups you read often to get higher scores than groups you +read seldom you can add the @code{gnus-summary-bubble-group} function to +the @code{gnus-summary-exit-hook} hook. This will result (after +sorting) in a bubbling sort of action. If you want to see that in +action after each summary exit, you can add +@code{gnus-group-sort-groups-by-rank} or +@code{gnus-group-sort-groups-by-score} to the same hook, but that will +slow things down somewhat. + + +@node Marking Groups +@section Marking Groups +@cindex marking groups + +If you want to perform some command on several groups, and they appear +subsequently in the group buffer, you would normally just give a +numerical prefix to the command. Most group commands will then do your +bidding on those groups. + +However, if the groups are not in sequential order, you can still +perform a command on several groups. You simply mark the groups first +with the process mark and then execute the command. + +@table @kbd + +@item # +@kindex # (Group) +@itemx M m +@kindex M m (Group) +@findex gnus-group-mark-group +Set the mark on the current group (@code{gnus-group-mark-group}). + +@item M-# +@kindex M-# (Group) +@itemx M u +@kindex M u (Group) +@findex gnus-group-unmark-group +Remove the mark from the current group +(@code{gnus-group-unmark-group}). + +@item M U +@kindex M U (Group) +@findex gnus-group-unmark-all-groups +Remove the mark from all groups (@code{gnus-group-unmark-all-groups}). + +@item M w +@kindex M w (Group) +@findex gnus-group-mark-region +Mark all groups between point and mark (@code{gnus-group-mark-region}). + +@item M b +@kindex M b (Group) +@findex gnus-group-mark-buffer +Mark all groups in the buffer (@code{gnus-group-mark-buffer}). + +@item M r +@kindex M r (Group) +@findex gnus-group-mark-regexp +Mark all groups that match some regular expression +(@code{gnus-group-mark-regexp}). +@end table + +Also @pxref{Process/Prefix}. + +@findex gnus-group-universal-argument +If you want to execute some command on all groups that have been marked +with the process mark, you can use the @kbd{M-&} +(@code{gnus-group-universal-argument}) command. It will prompt you for +the command to be executed. + + +@node Foreign Groups +@section Foreign Groups +@cindex foreign groups + +Below are some group mode commands for making and editing general foreign +groups, as well as commands to ease the creation of a few +special-purpose groups. All these commands insert the newly created +groups under point---@code{gnus-subscribe-newsgroup-method} is not +consulted. + +@table @kbd + +@item G m +@kindex G m (Group) +@findex gnus-group-make-group +@cindex making groups +Make a new group (@code{gnus-group-make-group}). Gnus will prompt you +for a name, a method and possibly an @dfn{address}. For an easier way +to subscribe to @sc{nntp} groups, @pxref{Browse Foreign Server}. + +@item G r +@kindex G r (Group) +@findex gnus-group-rename-group +@cindex renaming groups +Rename the current group to something else +(@code{gnus-group-rename-group}). This is valid only on some +groups---mail groups mostly. This command might very well be quite slow +on some backends. + +@item G c +@kindex G c (Group) +@cindex customizing +@findex gnus-group-customize +Customize the group parameters (@code{gnus-group-customize}). + +@item G e +@kindex G e (Group) +@findex gnus-group-edit-group-method +@cindex renaming groups +Enter a buffer where you can edit the select method of the current +group (@code{gnus-group-edit-group-method}). + +@item G p +@kindex G p (Group) +@findex gnus-group-edit-group-parameters +Enter a buffer where you can edit the group parameters +(@code{gnus-group-edit-group-parameters}). + +@item G E +@kindex G E (Group) +@findex gnus-group-edit-group +Enter a buffer where you can edit the group info +(@code{gnus-group-edit-group}). + +@item G d +@kindex G d (Group) +@findex gnus-group-make-directory-group +@cindex nndir +Make a directory group (@pxref{Directory Groups}). You will be prompted +for a directory name (@code{gnus-group-make-directory-group}). + +@item G h +@kindex G h (Group) +@cindex help group +@findex gnus-group-make-help-group +Make the gnus help group (@code{gnus-group-make-help-group}). + +@item G a +@kindex G a (Group) +@cindex (ding) archive +@cindex archive group +@findex gnus-group-make-archive-group +@vindex gnus-group-archive-directory +@vindex gnus-group-recent-archive-directory +Make a gnus archive group (@code{gnus-group-make-archive-group}). By +default a group pointing to the most recent articles will be created +(@code{gnus-group-recent-archive-directory}), but given a prefix, a full +group will be created from @code{gnus-group-archive-directory}. + +@item G k +@kindex G k (Group) +@findex gnus-group-make-kiboze-group +@cindex nnkiboze +Make a kiboze group. You will be prompted for a name, for a regexp to +match groups to be ``included'' in the kiboze group, and a series of +strings to match on headers (@code{gnus-group-make-kiboze-group}). +@xref{Kibozed Groups}. + +@item G D +@kindex G D (Group) +@findex gnus-group-enter-directory +@cindex nneething +Read an arbitrary directory as if it were a newsgroup with the +@code{nneething} backend (@code{gnus-group-enter-directory}). +@xref{Anything Groups}. + +@item G f +@kindex G f (Group) +@findex gnus-group-make-doc-group +@cindex ClariNet Briefs +@cindex nndoc +Make a group based on some file or other +(@code{gnus-group-make-doc-group}). If you give a prefix to this +command, you will be prompted for a file name and a file type. +Currently supported types are @code{babyl}, @code{mbox}, @code{digest}, +@code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs}, +@code{rfc934}, @code{rfc822-forward}, and @code{forward}. If you run +this command without a prefix, gnus will guess at the file type. +@xref{Document Groups}. + +@item G u +@kindex G u (Group) +@vindex gnus-useful-groups +@findex gnus-group-make-useful-group +Create one of the groups mentioned in @code{gnus-useful-groups} +(@code{gnus-group-make-useful-group}). + +@item G w +@kindex G w (Group) +@findex gnus-group-make-web-group +@cindex DejaNews +@cindex Alta Vista +@cindex InReference +@cindex nnweb +Make an ephemeral group based on a web search +(@code{gnus-group-make-web-group}). If you give a prefix to this +command, make a solid group instead. You will be prompted for the +search engine type and the search string. Valid search engine types +include @code{dejanews}, @code{altavista} and @code{reference}. +@xref{Web Searches}. + +If you use the @code{dejanews} search engine, you can limit the search +to a particular group by using a match string like +@samp{~g alt.sysadmin.recovery shaving}. + +@item G DEL +@kindex G DEL (Group) +@findex gnus-group-delete-group +This function will delete the current group +(@code{gnus-group-delete-group}). If given a prefix, this function will +actually delete all the articles in the group, and forcibly remove the +group itself from the face of the Earth. Use a prefix only if you are +absolutely sure of what you are doing. This command can't be used on +read-only groups (like @code{nntp} group), though. + +@item G V +@kindex G V (Group) +@findex gnus-group-make-empty-virtual +Make a new, fresh, empty @code{nnvirtual} group +(@code{gnus-group-make-empty-virtual}). @xref{Virtual Groups}. + +@item G v +@kindex G v (Group) +@findex gnus-group-add-to-virtual +Add the current group to an @code{nnvirtual} group +(@code{gnus-group-add-to-virtual}). Uses the process/prefix convention. +@end table + +@xref{Select Methods} for more information on the various select +methods. + +@vindex gnus-activate-foreign-newsgroups +If @code{gnus-activate-foreign-newsgroups} is a positive number, +gnus will check all foreign groups with this level or lower at startup. +This might take quite a while, especially if you subscribe to lots of +groups from different @sc{nntp} servers. Also @pxref{Group Levels}; +@code{gnus-activate-level} also affects activation of foreign +newsgroups. + + +@node Group Parameters +@section Group Parameters +@cindex group parameters + +The group parameters store information local to a particular group. +Here's an example group parameter list: + +@example +((to-address . "ding@@gnus.org") + (auto-expire . t)) +@end example + +We see that each element consists of a ``dotted pair''---the thing +before the dot is the key, while the thing after the dot is the value. +All the parameters have this form @emph{except} local variable specs, +which are not dotted pairs, but proper lists. + +The following group parameters can be used: + +@table @code +@item to-address +@cindex to-address +Address used by when doing followups and new posts. + +@example +(to-address . "some@@where.com") +@end example + +This is primarily useful in mail groups that represent closed mailing +lists---mailing lists where it's expected that everybody that writes to +the mailing list is subscribed to it. Since using this parameter +ensures that the mail only goes to the mailing list itself, it means +that members won't receive two copies of your followups. + +Using @code{to-address} will actually work whether the group is foreign +or not. Let's say there's a group on the server that is called +@samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten +the articles from a mail-to-news gateway. Posting directly to this +group is therefore impossible---you have to send mail to the mailing +list address instead. + +@item to-list +@cindex to-list +Address used when doing a @kbd{a} in that group. + +@example +(to-list . "some@@where.com") +@end example + +It is totally ignored +when doing a followup---except that if it is present in a news group, +you'll get mail group semantics when doing @kbd{f}. + +If you do an @kbd{a} command in a mail group and you have neither a +@code{to-list} group parameter nor a @code{to-address} group parameter, +then a @code{to-list} group parameter will be added automatically upon +sending the message if @code{gnus-add-to-list} is set to @code{t}. +@vindex gnus-add-to-list + +If you do an @kbd{a} command in a mail group and you don't have a +@code{to-list} group parameter, one will be added automatically upon +sending the message. + +@item visible +@cindex visible +If the group parameter list has the element @code{(visible . t)}, +that group will always be visible in the Group buffer, regardless +of whether it has any unread articles. + +@item broken-reply-to +@cindex broken-reply-to +Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To} +headers in this group are to be ignored. This can be useful if you're +reading a mailing list group where the listserv has inserted +@code{Reply-To} headers that point back to the listserv itself. This is +broken behavior. So there! + +@item to-group +@cindex to-group +Elements like @code{(to-group . "some.group.name")} means that all +posts in that group will be sent to @code{some.group.name}. + +@item newsgroup +@cindex newsgroup +If you have @code{(newsgroup . t)} in the group parameter list, gnus +will treat all responses as if they were responses to news articles. +This can be useful if you have a mail group that's really a mirror of a +news group. + +@item gcc-self +@cindex gcc-self +If @code{(gcc-self . t)} is present in the group parameter list, newly +composed messages will be @code{Gcc}'d to the current group. If +@code{(gcc-self . none)} is present, no @code{Gcc:} header will be +generated, if @code{(gcc-self . "string")} is present, this string will +be inserted literally as a @code{gcc} header. This parameter takes +precedence over any default @code{Gcc} rules as described later +(@pxref{Archived Messages}). + +@item auto-expire +@cindex auto-expire +If the group parameter has an element that looks like @code{(auto-expire +. t)}, all articles read will be marked as expirable. For an +alternative approach, @pxref{Expiring Mail}. + +@item total-expire +@cindex total-expire +If the group parameter has an element that looks like +@code{(total-expire . t)}, all read articles will be put through the +expiry process, even if they are not marked as expirable. Use with +caution. Unread, ticked and dormant articles are not eligible for +expiry. + +@item expiry-wait +@cindex expiry-wait +@vindex nnmail-expiry-wait-function +If the group parameter has an element that looks like @code{(expiry-wait +. 10)}, this value will override any @code{nnmail-expiry-wait} and +@code{nnmail-expiry-wait-function} when expiring expirable messages. +The value can either be a number of days (not necessarily an integer) or +the symbols @code{never} or @code{immediate}. + +@item score-file +@cindex score file group parameter +Elements that look like @code{(score-file . "file")} will make +@file{file} into the current score file for the group in question. All +interactive score entries will be put into this file. + +@item adapt-file +@cindex adapt file group parameter +Elements that look like @code{(adapt-file . "file")} will make +@file{file} into the current adaptive file for the group in question. +All adaptive score entries will be put into this file. + +@item admin-address +When unsubscribing from a mailing list you should never send the +unsubscription notice to the mailing list itself. Instead, you'd send +messages to the administrative address. This parameter allows you to +put the admin address somewhere convenient. + +@item display +Elements that look like @code{(display . MODE)} say which articles to +display on entering the group. Valid values are: + +@table @code +@item all +Display all articles, both read and unread. + +@item default +Display the default visible articles, which normally includes unread and +ticked articles. +@end table + +@item comment +Elements that look like @code{(comment . "This is a comment")} are +arbitrary comments on the group. They are currently ignored by gnus, +but provide a place for you to store information on particular groups. + +@item charset +Elements that look like @code{(charset . iso-8859-1)} will make +@code{iso-8859-1} the default charset; that is, the charset that will be +used for all articles that do not specify a charset. + +@item @var{(variable form)} +You can use the group parameters to set variables local to the group you +are entering. If you want to turn threading off in @samp{news.answers}, +you could put @code{(gnus-show-threads nil)} in the group parameters of +that group. @code{gnus-show-threads} will be made into a local variable +in the summary buffer you enter, and the form @code{nil} will be +@code{eval}ed there. + +This can also be used as a group-specific hook function, if you'd like. +If you want to hear a beep when you enter a group, you could put +something like @code{(dummy-variable (ding))} in the parameters of that +group. @code{dummy-variable} will be set to the result of the +@code{(ding)} form, but who cares? + +@end table + +Use the @kbd{G p} command to edit group parameters of a group. You +might also be interested in reading about topic parameters (@pxref{Topic +Parameters}). + + +@node Listing Groups +@section Listing Groups +@cindex group listing + +These commands all list various slices of the groups available. + +@table @kbd + +@item l +@itemx A s +@kindex A s (Group) +@kindex l (Group) +@findex gnus-group-list-groups +List all groups that have unread articles +(@code{gnus-group-list-groups}). If the numeric prefix is used, this +command will list only groups of level ARG and lower. By default, it +only lists groups of level five (i. e., +@code{gnus-group-default-list-level}) or lower (i.e., just subscribed +groups). + +@item L +@itemx A u +@kindex A u (Group) +@kindex L (Group) +@findex gnus-group-list-all-groups +List all groups, whether they have unread articles or not +(@code{gnus-group-list-all-groups}). If the numeric prefix is used, +this command will list only groups of level ARG and lower. By default, +it lists groups of level seven or lower (i.e., just subscribed and +unsubscribed groups). + +@item A l +@kindex A l (Group) +@findex gnus-group-list-level +List all unread groups on a specific level +(@code{gnus-group-list-level}). If given a prefix, also list the groups +with no unread articles. + +@item A k +@kindex A k (Group) +@findex gnus-group-list-killed +List all killed groups (@code{gnus-group-list-killed}). If given a +prefix argument, really list all groups that are available, but aren't +currently (un)subscribed. This could entail reading the active file +from the server. + +@item A z +@kindex A z (Group) +@findex gnus-group-list-zombies +List all zombie groups (@code{gnus-group-list-zombies}). + +@item A m +@kindex A m (Group) +@findex gnus-group-list-matching +List all unread, subscribed groups with names that match a regexp +(@code{gnus-group-list-matching}). + +@item A M +@kindex A M (Group) +@findex gnus-group-list-all-matching +List groups that match a regexp (@code{gnus-group-list-all-matching}). + +@item A A +@kindex A A (Group) +@findex gnus-group-list-active +List absolutely all groups in the active file(s) of the +server(s) you are connected to (@code{gnus-group-list-active}). This +might very well take quite a while. It might actually be a better idea +to do a @kbd{A M} to list all matching, and just give @samp{.} as the +thing to match on. Also note that this command may list groups that +don't exist (yet)---these will be listed as if they were killed groups. +Take the output with some grains of salt. + +@item A a +@kindex A a (Group) +@findex gnus-group-apropos +List all groups that have names that match a regexp +(@code{gnus-group-apropos}). + +@item A d +@kindex A d (Group) +@findex gnus-group-description-apropos +List all groups that have names or descriptions that match a regexp +(@code{gnus-group-description-apropos}). + +@end table + +@vindex gnus-permanently-visible-groups +@cindex visible group parameter +Groups that match the @code{gnus-permanently-visible-groups} regexp will +always be shown, whether they have unread articles or not. You can also +add the @code{visible} element to the group parameters in question to +get the same effect. + +@vindex gnus-list-groups-with-ticked-articles +Groups that have just ticked articles in it are normally listed in the +group buffer. If @code{gnus-list-groups-with-ticked-articles} is +@code{nil}, these groups will be treated just like totally empty +groups. It is @code{t} by default. + + +@node Sorting Groups +@section Sorting Groups +@cindex sorting groups + +@kindex C-c C-s (Group) +@findex gnus-group-sort-groups +@vindex gnus-group-sort-function +The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the +group buffer according to the function(s) given by the +@code{gnus-group-sort-function} variable. Available sorting functions +include: + +@table @code + +@item gnus-group-sort-by-alphabet +@findex gnus-group-sort-by-alphabet +Sort the group names alphabetically. This is the default. + +@item gnus-group-sort-by-real-name +@findex gnus-group-sort-by-real-name +Sort the group alphabetically on the real (unprefixed) group names. + +@item gnus-group-sort-by-level +@findex gnus-group-sort-by-level +Sort by group level. + +@item gnus-group-sort-by-score +@findex gnus-group-sort-by-score +Sort by group score. @xref{Group Score}. + +@item gnus-group-sort-by-rank +@findex gnus-group-sort-by-rank +Sort by group score and then the group level. The level and the score +are, when taken together, the group's @dfn{rank}. @xref{Group Score}. + +@item gnus-group-sort-by-unread +@findex gnus-group-sort-by-unread +Sort by number of unread articles. + +@item gnus-group-sort-by-method +@findex gnus-group-sort-by-method +Sort alphabetically on the select method. + + +@end table + +@code{gnus-group-sort-function} can also be a list of sorting +functions. In that case, the most significant sort key function must be +the last one. + + +There are also a number of commands for sorting directly according to +some sorting criteria: + +@table @kbd +@item G S a +@kindex G S a (Group) +@findex gnus-group-sort-groups-by-alphabet +Sort the group buffer alphabetically by group name +(@code{gnus-group-sort-groups-by-alphabet}). + +@item G S u +@kindex G S u (Group) +@findex gnus-group-sort-groups-by-unread +Sort the group buffer by the number of unread articles +(@code{gnus-group-sort-groups-by-unread}). + +@item G S l +@kindex G S l (Group) +@findex gnus-group-sort-groups-by-level +Sort the group buffer by group level +(@code{gnus-group-sort-groups-by-level}). + +@item G S v +@kindex G S v (Group) +@findex gnus-group-sort-groups-by-score +Sort the group buffer by group score +(@code{gnus-group-sort-groups-by-score}). @xref{Group Score}. + +@item G S r +@kindex G S r (Group) +@findex gnus-group-sort-groups-by-rank +Sort the group buffer by group rank +(@code{gnus-group-sort-groups-by-rank}). @xref{Group Score}. + +@item G S m +@kindex G S m (Group) +@findex gnus-group-sort-groups-by-method +Sort the group buffer alphabetically by backend name +(@code{gnus-group-sort-groups-by-method}). + +@end table + +All the commands below obeys the process/prefix convention +(@pxref{Process/Prefix}). + +When given a symbolic prefix (@pxref{Symbolic Prefixes}), all these +commands will sort in reverse order. + +You can also sort a subset of the groups: + +@table @kbd +@item G P a +@kindex G P a (Group) +@findex gnus-group-sort-selected-groups-by-alphabet +Sort the groups alphabetically by group name +(@code{gnus-group-sort-selected-groups-by-alphabet}). + +@item G P u +@kindex G P u (Group) +@findex gnus-group-sort-selected-groups-by-unread +Sort the groups by the number of unread articles +(@code{gnus-group-sort-selected-groups-by-unread}). + +@item G P l +@kindex G P l (Group) +@findex gnus-group-sort-selected-groups-by-level +Sort the groups by group level +(@code{gnus-group-sort-selected-groups-by-level}). + +@item G P v +@kindex G P v (Group) +@findex gnus-group-sort-selected-groups-by-score +Sort the groups by group score +(@code{gnus-group-sort-selected-groups-by-score}). @xref{Group Score}. + +@item G P r +@kindex G P r (Group) +@findex gnus-group-sort-selected-groups-by-rank +Sort the groups by group rank +(@code{gnus-group-sort-selected-groups-by-rank}). @xref{Group Score}. + +@item G P m +@kindex G P m (Group) +@findex gnus-group-sort-selected-groups-by-method +Sort the groups alphabetically by backend name +(@code{gnus-group-sort-selected-groups-by-method}). + +@end table + + + +@node Group Maintenance +@section Group Maintenance +@cindex bogus groups + +@table @kbd +@item b +@kindex b (Group) +@findex gnus-group-check-bogus-groups +Find bogus groups and delete them +(@code{gnus-group-check-bogus-groups}). + +@item F +@kindex F (Group) +@findex gnus-group-find-new-groups +Find new groups and process them (@code{gnus-group-find-new-groups}). +With 1 @kbd{C-u}, use the @code{ask-server} method to query the server +for new groups. With 2 @kbd{C-u}'s, use most complete method possible +to query the server for new groups, and subscribe the new groups as +zombies. + +@item C-c C-x +@kindex C-c C-x (Group) +@findex gnus-group-expire-articles +Run all expirable articles in the current group through the expiry +process (if any) (@code{gnus-group-expire-articles}). + +@item C-c M-C-x +@kindex C-c M-C-x (Group) +@findex gnus-group-expire-all-groups +Run all articles in all groups through the expiry process +(@code{gnus-group-expire-all-groups}). + +@end table + + +@node Browse Foreign Server +@section Browse Foreign Server +@cindex foreign servers +@cindex browsing servers + +@table @kbd +@item B +@kindex B (Group) +@findex gnus-group-browse-foreign-server +You will be queried for a select method and a server name. Gnus will +then attempt to contact this server and let you browse the groups there +(@code{gnus-group-browse-foreign-server}). +@end table + +@findex gnus-browse-mode +A new buffer with a list of available groups will appear. This buffer +will use the @code{gnus-browse-mode}. This buffer looks a bit (well, +a lot) like a normal group buffer. + +Here's a list of keystrokes available in the browse mode: + +@table @kbd +@item n +@kindex n (Browse) +@findex gnus-group-next-group +Go to the next group (@code{gnus-group-next-group}). + +@item p +@kindex p (Browse) +@findex gnus-group-prev-group +Go to the previous group (@code{gnus-group-prev-group}). + +@item SPACE +@kindex SPACE (Browse) +@findex gnus-browse-read-group +Enter the current group and display the first article +(@code{gnus-browse-read-group}). + +@item RET +@kindex RET (Browse) +@findex gnus-browse-select-group +Enter the current group (@code{gnus-browse-select-group}). + +@item u +@kindex u (Browse) +@findex gnus-browse-unsubscribe-current-group +Unsubscribe to the current group, or, as will be the case here, +subscribe to it (@code{gnus-browse-unsubscribe-current-group}). + +@item l +@itemx q +@kindex q (Browse) +@kindex l (Browse) +@findex gnus-browse-exit +Exit browse mode (@code{gnus-browse-exit}). + +@item ? +@kindex ? (Browse) +@findex gnus-browse-describe-briefly +Describe browse mode briefly (well, there's not much to describe, is +there) (@code{gnus-browse-describe-briefly}). +@end table + + +@node Exiting Gnus +@section Exiting gnus +@cindex exiting gnus + +Yes, gnus is ex(c)iting. + +@table @kbd +@item z +@kindex z (Group) +@findex gnus-group-suspend +Suspend gnus (@code{gnus-group-suspend}). This doesn't really exit +gnus, but it kills all buffers except the Group buffer. I'm not sure +why this is a gain, but then who am I to judge? + +@item q +@kindex q (Group) +@findex gnus-group-exit +@c @icon{gnus-group-exit} +Quit gnus (@code{gnus-group-exit}). + +@item Q +@kindex Q (Group) +@findex gnus-group-quit +Quit gnus without saving the @file{.newsrc} files +(@code{gnus-group-quit}). The dribble file will be saved, though +(@pxref{Auto Save}). +@end table + +@vindex gnus-exit-gnus-hook +@vindex gnus-suspend-gnus-hook +@code{gnus-suspend-gnus-hook} is called when you suspend gnus and +@code{gnus-exit-gnus-hook} is called when you quit gnus, while +@code{gnus-after-exiting-gnus-hook} is called as the final item when +exiting gnus. + +@findex gnus-unload +@cindex unloading +If you wish to completely unload gnus and all its adherents, you can use +the @code{gnus-unload} command. This command is also very handy when +trying to customize meta-variables. + +Note: + +@quotation +Miss Lisa Cannifax, while sitting in English class, felt her feet go +numbly heavy and herself fall into a hazy trance as the boy sitting +behind her drew repeated lines with his pencil across the back of her +plastic chair. +@end quotation + + +@node Group Topics +@section Group Topics +@cindex topics + +If you read lots and lots of groups, it might be convenient to group +them hierarchically according to topics. You put your Emacs groups over +here, your sex groups over there, and the rest (what, two groups or so?) +you put in some misc section that you never bother with anyway. You can +even group the Emacs sex groups as a sub-topic to either the Emacs +groups or the sex groups---or both! Go wild! + +@iftex +@iflatex +\gnusfigure{Group Topics}{400}{ +\put(75,50){\epsfig{figure=tmp/group-topic.ps,height=9cm}} +} +@end iflatex +@end iftex + +Here's an example: + +@example +Gnus + Emacs -- I wuw it! + 3: comp.emacs + 2: alt.religion.emacs + Naughty Emacs + 452: alt.sex.emacs + 0: comp.talk.emacs.recovery + Misc + 8: comp.binaries.fractals + 13: comp.sources.unix +@end example + +@findex gnus-topic-mode +@kindex t (Group) +To get this @emph{fab} functionality you simply turn on (ooh!) the +@code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This +is a toggling command.) + +Go ahead, just try it. I'll still be here when you get back. La de +dum... Nice tune, that... la la la... What, you're back? Yes, and now +press @kbd{l}. There. All your groups are now listed under +@samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and +bothered? + +If you want this permanently enabled, you should add that minor mode to +the hook for the group mode: + +@lisp +(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) +@end lisp + +@menu +* Topic Variables:: How to customize the topics the Lisp Way. +* Topic Commands:: Interactive E-Z commands. +* Topic Sorting:: Sorting each topic individually. +* Topic Topology:: A map of the world. +* Topic Parameters:: Parameters that apply to all groups in a topic. +@end menu + + +@node Topic Variables +@subsection Topic Variables +@cindex topic variables + +Now, if you select a topic, it will fold/unfold that topic, which is +really neat, I think. + +@vindex gnus-topic-line-format +The topic lines themselves are created according to the +@code{gnus-topic-line-format} variable (@pxref{Formatting Variables}). +Valid elements are: + +@table @samp +@item i +Indentation. +@item n +Topic name. +@item v +Visibility. +@item l +Level. +@item g +Number of groups in the topic. +@item a +Number of unread articles in the topic. +@item A +Number of unread articles in the topic and all its subtopics. +@end table + +@vindex gnus-topic-indent-level +Each sub-topic (and the groups in the sub-topics) will be indented with +@code{gnus-topic-indent-level} times the topic level number of spaces. +The default is 2. + +@vindex gnus-topic-mode-hook +@code{gnus-topic-mode-hook} is called in topic minor mode buffers. + +@vindex gnus-topic-display-empty-topics +The @code{gnus-topic-display-empty-topics} says whether to display even +topics that have no unread articles in them. The default is @code{t}. + + +@node Topic Commands +@subsection Topic Commands +@cindex topic commands + +When the topic minor mode is turned on, a new @kbd{T} submap will be +available. In addition, a few of the standard keys change their +definitions slightly. + +@table @kbd + +@item T n +@kindex T n (Topic) +@findex gnus-topic-create-topic +Prompt for a new topic name and create it +(@code{gnus-topic-create-topic}). + +@item T m +@kindex T m (Topic) +@findex gnus-topic-move-group +Move the current group to some other topic +(@code{gnus-topic-move-group}). This command uses the process/prefix +convention (@pxref{Process/Prefix}). + +@item T c +@kindex T c (Topic) +@findex gnus-topic-copy-group +Copy the current group to some other topic +(@code{gnus-topic-copy-group}). This command uses the process/prefix +convention (@pxref{Process/Prefix}). + +@item T D +@kindex T D (Topic) +@findex gnus-topic-remove-group +Remove a group from the current topic (@code{gnus-topic-remove-group}). +This command is mainly useful if you have the same group in several +topics and wish to remove it from one of the topics. You may also +remove a group from all topics, but in that case, Gnus will add it to +the root topic the next time you start Gnus. In fact, all new groups +(which, naturally, don't belong to any topic) will show up in the root +topic. + +This command uses the process/prefix convention +(@pxref{Process/Prefix}). + +@item T M +@kindex T M (Topic) +@findex gnus-topic-move-matching +Move all groups that match some regular expression to a topic +(@code{gnus-topic-move-matching}). + +@item T C +@kindex T C (Topic) +@findex gnus-topic-copy-matching +Copy all groups that match some regular expression to a topic +(@code{gnus-topic-copy-matching}). + +@item T H +@kindex T H (Topic) +@findex gnus-topic-toggle-display-empty-topics +Toggle hiding empty topics +(@code{gnus-topic-toggle-display-empty-topics}). + +@item T # +@kindex T # (Topic) +@findex gnus-topic-mark-topic +Mark all groups in the current topic with the process mark +(@code{gnus-topic-mark-topic}). + +@item T M-# +@kindex T M-# (Topic) +@findex gnus-topic-unmark-topic +Remove the process mark from all groups in the current topic +(@code{gnus-topic-unmark-topic}). + +@item RET +@kindex RET (Topic) +@findex gnus-topic-select-group +@itemx SPACE +Either select a group or fold a topic (@code{gnus-topic-select-group}). +When you perform this command on a group, you'll enter the group, as +usual. When done on a topic line, the topic will be folded (if it was +visible) or unfolded (if it was folded already). So it's basically a +toggling command on topics. In addition, if you give a numerical +prefix, group on that level (and lower) will be displayed. + +@item T TAB +@itemx TAB +@kindex T TAB (Topic) +@kindex TAB (Topic) +@findex gnus-topic-indent +``Indent'' the current topic so that it becomes a sub-topic of the +previous topic (@code{gnus-topic-indent}). If given a prefix, +``un-indent'' the topic instead. + +@item M-TAB +@kindex M-TAB (Topic) +@findex gnus-topic-unindent +``Un-indent'' the current topic so that it becomes a sub-topic of the +parent of its current parent (@code{gnus-topic-unindent}). + +@item C-k +@kindex C-k (Topic) +@findex gnus-topic-kill-group +Kill a group or topic (@code{gnus-topic-kill-group}). All groups in the +topic will be removed along with the topic. + +@item C-y +@kindex C-y (Topic) +@findex gnus-topic-yank-group +Yank the previously killed group or topic +(@code{gnus-topic-yank-group}). Note that all topics will be yanked +before all groups. + +@item T r +@kindex T r (Topic) +@findex gnus-topic-rename +Rename a topic (@code{gnus-topic-rename}). + +@item T DEL +@kindex T DEL (Topic) +@findex gnus-topic-delete +Delete an empty topic (@code{gnus-topic-delete}). + +@item A T +@kindex A T (Topic) +@findex gnus-topic-list-active +List all groups that gnus knows about in a topics-ified way +(@code{gnus-topic-list-active}). + +@item G p +@kindex G p (Topic) +@findex gnus-topic-edit-parameters +@cindex group parameters +@cindex topic parameters +@cindex parameters +Edit the topic parameters (@code{gnus-topic-edit-parameters}). +@xref{Topic Parameters}. + +@end table + + +@node Topic Sorting +@subsection Topic Sorting +@cindex topic sorting + +You can sort the groups in each topic individually with the following +commands: + + +@table @kbd +@item T S a +@kindex T S a (Topic) +@findex gnus-topic-sort-groups-by-alphabet +Sort the current topic alphabetically by group name +(@code{gnus-topic-sort-groups-by-alphabet}). + +@item T S u +@kindex T S u (Topic) +@findex gnus-topic-sort-groups-by-unread +Sort the current topic by the number of unread articles +(@code{gnus-topic-sort-groups-by-unread}). + +@item T S l +@kindex T S l (Topic) +@findex gnus-topic-sort-groups-by-level +Sort the current topic by group level +(@code{gnus-topic-sort-groups-by-level}). + +@item T S v +@kindex T S v (Topic) +@findex gnus-topic-sort-groups-by-score +Sort the current topic by group score +(@code{gnus-topic-sort-groups-by-score}). @xref{Group Score}. + +@item T S r +@kindex T S r (Topic) +@findex gnus-topic-sort-groups-by-rank +Sort the current topic by group rank +(@code{gnus-topic-sort-groups-by-rank}). @xref{Group Score}. + +@item T S m +@kindex T S m (Topic) +@findex gnus-topic-sort-groups-by-method +Sort the current topic alphabetically by backend name +(@code{gnus-topic-sort-groups-by-method}). + +@end table + +@xref{Sorting Groups} for more information about group sorting. + + +@node Topic Topology +@subsection Topic Topology +@cindex topic topology +@cindex topology + +So, let's have a look at an example group buffer: + +@example +Gnus + Emacs -- I wuw it! + 3: comp.emacs + 2: alt.religion.emacs + Naughty Emacs + 452: alt.sex.emacs + 0: comp.talk.emacs.recovery + Misc + 8: comp.binaries.fractals + 13: comp.sources.unix +@end example + +So, here we have one top-level topic (@samp{Gnus}), two topics under +that, and one sub-topic under one of the sub-topics. (There is always +just one (1) top-level topic). This topology can be expressed as +follows: + +@lisp +(("Gnus" visible) + (("Emacs -- I wuw it!" visible) + (("Naughty Emacs" visible))) + (("Misc" visible))) +@end lisp + +@vindex gnus-topic-topology +This is in fact how the variable @code{gnus-topic-topology} would look +for the display above. That variable is saved in the @file{.newsrc.eld} +file, and shouldn't be messed with manually---unless you really want +to. Since this variable is read from the @file{.newsrc.eld} file, +setting it in any other startup files will have no effect. + +This topology shows what topics are sub-topics of what topics (right), +and which topics are visible. Two settings are currently +allowed---@code{visible} and @code{invisible}. + + +@node Topic Parameters +@subsection Topic Parameters +@cindex topic parameters + +All groups in a topic will inherit group parameters from the parent (and +ancestor) topic parameters. All valid group parameters are valid topic +parameters (@pxref{Group Parameters}). + +Group parameters (of course) override topic parameters, and topic +parameters in sub-topics override topic parameters in super-topics. You +know. Normal inheritance rules. (@dfn{Rules} is here a noun, not a +verb, although you may feel free to disagree with me here.) + +@example +Gnus + Emacs + 3: comp.emacs + 2: alt.religion.emacs + 452: alt.sex.emacs + Relief + 452: alt.sex.emacs + 0: comp.talk.emacs.recovery + Misc + 8: comp.binaries.fractals + 13: comp.sources.unix + 452: alt.sex.emacs +@end example + +The @samp{Emacs} topic has the topic parameter @code{(score-file +. "emacs.SCORE")}; the @samp{Relief} topic has the topic parameter +@code{(score-file . "relief.SCORE")}; and the @samp{Misc} topic has the +topic parameter @code{(score-file . "emacs.SCORE")}. In addition, +@* @samp{alt.religion.emacs} has the group parameter @code{(score-file +. "religion.SCORE")}. + +Now, when you enter @samp{alt.sex.emacs} in the @samp{Relief} topic, you +will get the @file{relief.SCORE} home score file. If you enter the same +group in the @samp{Emacs} topic, you'll get the @file{emacs.SCORE} home +score file. If you enter the group @samp{alt.religion.emacs}, you'll +get the @file{religion.SCORE} home score file. + +This seems rather simple and self-evident, doesn't it? Well, yes. But +there are some problems, especially with the @code{total-expiry} +parameter. Say you have a mail group in two topics; one with +@code{total-expiry} and one without. What happens when you do @kbd{M-x +gnus-expire-all-expirable-groups}? Gnus has no way of telling which one +of these topics you mean to expire articles from, so anything may +happen. In fact, I hereby declare that it is @dfn{undefined} what +happens. You just have to be careful if you do stuff like that. + + +@node Misc Group Stuff +@section Misc Group Stuff + +@menu +* 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. +@end menu + +@table @kbd + +@item ^ +@kindex ^ (Group) +@findex gnus-group-enter-server-mode +Enter the server buffer (@code{gnus-group-enter-server-mode}). +@xref{The Server Buffer}. + +@item a +@kindex a (Group) +@findex gnus-group-post-news +Post an article to a group (@code{gnus-group-post-news}). If given a +prefix, the current group name will be used as the default. + +@item m +@kindex m (Group) +@findex gnus-group-mail +Mail a message somewhere (@code{gnus-group-mail}). + +@end table + +Variables for the group buffer: + +@table @code + +@item gnus-group-mode-hook +@vindex gnus-group-mode-hook +is called after the group buffer has been +created. + +@item gnus-group-prepare-hook +@vindex gnus-group-prepare-hook +is called after the group buffer is +generated. It may be used to modify the buffer in some strange, +unnatural way. + +@item gnus-group-prepared-hook +@vindex gnus-group-prepare-hook +is called as the very last thing after the group buffer has been +generated. It may be used to move point around, for instance. + +@item gnus-permanently-visible-groups +@vindex gnus-permanently-visible-groups +Groups matching this regexp will always be listed in the group buffer, +whether they are empty or not. + +@end table + + +@node Scanning New Messages +@subsection Scanning New Messages +@cindex new messages +@cindex scanning new news + +@table @kbd + +@item g +@kindex g (Group) +@findex gnus-group-get-new-news +@c @icon{gnus-group-get-new-news} +Check the server(s) for new articles. If the numerical prefix is used, +this command will check only groups of level @var{arg} and lower +(@code{gnus-group-get-new-news}). If given a non-numerical prefix, this +command will force a total re-reading of the active file(s) from the +backend(s). + +@item M-g +@kindex M-g (Group) +@findex gnus-group-get-new-news-this-group +@vindex gnus-goto-next-group-when-activating +@c @icon{gnus-group-get-new-news-this-group} +Check whether new articles have arrived in the current group +(@code{gnus-group-get-new-news-this-group}). +@code{gnus-goto-next-group-when-activating} says whether this command is +to move point to the next group or not. It is @code{t} by default. + +@findex gnus-activate-all-groups +@cindex activating groups +@item C-c M-g +@kindex C-c M-g (Group) +Activate absolutely all groups (@code{gnus-activate-all-groups}). + +@item R +@kindex R (Group) +@cindex restarting +@findex gnus-group-restart +Restart gnus (@code{gnus-group-restart}). This saves the @file{.newsrc} +file(s), closes the connection to all servers, clears up all run-time +gnus variables, and then starts gnus all over again. + +@end table + +@vindex gnus-get-new-news-hook +@code{gnus-get-new-news-hook} is run just before checking for new news. + +@vindex gnus-after-getting-new-news-hook +@code{gnus-after-getting-new-news-hook} is run after checking for new +news. + + +@node Group Information +@subsection Group Information +@cindex group information +@cindex information on groups + +@table @kbd + + +@item H f +@kindex H f (Group) +@findex gnus-group-fetch-faq +@vindex gnus-group-faq-directory +@cindex FAQ +@cindex ange-ftp +Try to fetch the FAQ for the current group +(@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from +@code{gnus-group-faq-directory}, which is usually a directory on a +remote machine. This variable can also be a list of directories. In +that case, giving a prefix to this command will allow you to choose +between the various sites. @code{ange-ftp} (or @code{efs}) will be used +for fetching the file. + +If fetching from the first site is unsuccessful, gnus will attempt to go +through @code{gnus-group-faq-directory} and try to open them one by one. + +@item H d +@itemx C-c C-d +@c @icon{gnus-group-describe-group} +@kindex H d (Group) +@kindex C-c C-d (Group) +@cindex describing groups +@cindex group description +@findex gnus-group-describe-group +Describe the current group (@code{gnus-group-describe-group}). If given +a prefix, force Gnus to re-read the description from the server. + +@item M-d +@kindex M-d (Group) +@findex gnus-group-describe-all-groups +Describe all groups (@code{gnus-group-describe-all-groups}). If given a +prefix, force gnus to re-read the description file from the server. + +@item H v +@itemx V +@kindex V (Group) +@kindex H v (Group) +@cindex version +@findex gnus-version +Display current gnus version numbers (@code{gnus-version}). + +@item ? +@kindex ? (Group) +@findex gnus-group-describe-briefly +Give a very short help message (@code{gnus-group-describe-briefly}). + +@item C-c C-i +@kindex C-c C-i (Group) +@cindex info +@cindex manual +@findex gnus-info-find-node +Go to the gnus info node (@code{gnus-info-find-node}). +@end table + + +@node Group Timestamp +@subsection Group Timestamp +@cindex timestamps +@cindex group timestamps + +It can be convenient to let gnus keep track of when you last read a +group. To set the ball rolling, you should add +@code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}: + +@lisp +(add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp) +@end lisp + +After doing this, each time you enter a group, it'll be recorded. + +This information can be displayed in various ways---the easiest is to +use the @samp{%d} spec in the group line format: + +@lisp +(setq gnus-group-line-format + "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n") +@end lisp + +This will result in lines looking like: + +@example +* 0: mail.ding 19961002T012943 + 0: custom 19961002T012713 +@end example + +As you can see, the date is displayed in compact ISO 8601 format. This +may be a bit too much, so to just display the date, you could say +something like: + +@lisp +(setq gnus-group-line-format + "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n") +@end lisp + + +@node File Commands +@subsection File Commands +@cindex file commands + +@table @kbd + +@item r +@kindex r (Group) +@findex gnus-group-read-init-file +@vindex gnus-init-file +@cindex reading init file +Re-read the init file (@code{gnus-init-file}, which defaults to +@file{~/.gnus}) (@code{gnus-group-read-init-file}). + +@item s +@kindex s (Group) +@findex gnus-group-save-newsrc +@cindex saving .newsrc +Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted) +(@code{gnus-group-save-newsrc}). If given a prefix, force saving the +file(s) whether Gnus thinks it is necessary or not. + +@c @item Z +@c @kindex Z (Group) +@c @findex gnus-group-clear-dribble +@c Clear the dribble buffer (@code{gnus-group-clear-dribble}). + +@end table + + +@node The Summary Buffer +@chapter The Summary Buffer +@cindex summary buffer + +A line for each article is displayed in the summary buffer. You can +move around, read articles, post articles and reply to articles. + +The most common way to a summary buffer is to select a group from the +group buffer (@pxref{Selecting a Group}). + +You can have as many summary buffers open as you wish. + +@menu +* 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. +* Canceling and Superseding:: ``Whoops, I shouldn't have called him that.'' +* Marking Articles:: Marking articles as read, expirable, etc. +* Limiting:: You can limit the summary buffer. +* Threading:: How threads are made. +* Sorting:: How articles and threads are sorted. +* 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. +* 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. +* Exiting the Summary Buffer:: Returning to the Group buffer. +* Crosspost Handling:: How crossposted articles are dealt with. +* Duplicate Suppression:: An alternative when crosspost handling fails. +@end menu + + +@node Summary Buffer Format +@section Summary Buffer Format +@cindex summary buffer format + +@iftex +@iflatex +\gnusfigure{The Summary Buffer}{180}{ +\put(0,0){\epsfig{figure=tmp/summary.ps,width=7.5cm}} +\put(445,0){\makebox(0,0)[br]{\epsfig{figure=tmp/summary-article.ps,width=7.5cm}}} +} +@end iflatex +@end iftex + +@menu +* Summary Buffer Lines:: You can specify how summary lines should look. +* Summary Buffer Mode Line:: You can say how the mode line should look. +* Summary Highlighting:: Making the summary buffer all pretty and nice. +@end menu + +@findex mail-extract-address-components +@findex gnus-extract-address-components +@vindex gnus-extract-address-components +Gnus will use the value of the @code{gnus-extract-address-components} +variable as a function for getting the name and address parts of a +@code{From} header. Three pre-defined functions exist: +@code{gnus-extract-address-components}, which is the default, quite +fast, and too simplistic solution; +@code{mail-extract-address-components}, which works nicely, but is +slower; and @code{std11-extract-address-components}, which works very +nicely, but is slower. The default function will return the wrong +answer in 5% of the cases. If this is unacceptable to you, use the +other function instead. + +@vindex gnus-summary-same-subject +@code{gnus-summary-same-subject} is a string indicating that the current +article has the same subject as the previous. This string will be used +with those specs that require it. The default is @code{""}. + + +@node Summary Buffer Lines +@subsection Summary Buffer Lines + +@vindex gnus-summary-line-format +You can change the format of the lines in the summary buffer by changing +the @code{gnus-summary-line-format} variable. It works along the same +lines as a normal @code{format} string, with some extensions +(@pxref{Formatting Variables}). + +The default string is @samp{%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n}. + +The following format specification characters are understood: + +@table @samp +@item N +Article number. +@item S +Subject string. +@item s +Subject if the article is the root of the thread or the previous article +had a different subject, @code{gnus-summary-same-subject} otherwise. +(@code{gnus-summary-same-subject} defaults to @code{""}.) +@item F +Full @code{From} header. +@item n +The name (from the @code{From} header). +@item a +The name (from the @code{From} header). This differs from the @code{n} +spec in that it uses the function designated by the +@code{gnus-extract-address-components} variable, which is slower, but +may be more thorough. +@item A +The address (from the @code{From} header). This works the same way as +the @code{a} spec. +@item L +Number of lines in the article. +@item c +Number of characters in the article. +@item I +Indentation based on thread level (@pxref{Customizing Threading}). +@item T +Nothing if the article is a root and lots of spaces if it isn't (it +pushes everything after it off the screen). +@item [ +Opening bracket, which is normally @samp{[}, but can also be @samp{<} +for adopted articles (@pxref{Customizing Threading}). +@item ] +Closing bracket, which is normally @samp{]}, but can also be @samp{>} +for adopted articles. +@item > +One space for each thread level. +@item < +Twenty minus thread level spaces. +@item U +Unread. + +@item R +This misleadingly named specifier is the @dfn{secondary mark}. This +mark will say whether the article has been replied to, has been cached, +or has been saved. + +@item i +Score as a number (@pxref{Scoring}). +@item z +@vindex gnus-summary-zcore-fuzz +Zcore, @samp{+} if above the default level and @samp{-} if below the +default level. If the difference between +@code{gnus-summary-default-score} and the score is less than +@code{gnus-summary-zcore-fuzz}, this spec will not be used. +@item V +Total thread score. +@item x +@code{Xref}. +@item D +@code{Date}. +@item d +The @code{Date} in @code{DD-MMM} format. +@item o +The @code{Date} in @var{YYYYMMDD}@code{T}@var{HHMMSS} format. +@item M +@code{Message-ID}. +@item r +@code{References}. +@item t +Number of articles in the current sub-thread. Using this spec will slow +down summary buffer generation somewhat. +@item e +An @samp{=} (@code{gnus-not-empty-thread-mark}) will be displayed if the +article has any children. +@item P +The line number. +@item O +Download mark. +@item u +User defined specifier. The next character in the format string should +be a letter. Gnus will call the function +@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter +following @samp{%u}. The function will be passed the current header as +argument. The function should return a string, which will be inserted +into the summary just like information from any other summary specifier. +@end table + +The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs +have to be handled with care. For reasons of efficiency, gnus will +compute what column these characters will end up in, and ``hard-code'' +that. This means that it is invalid to have these specs after a +variable-length spec. Well, you might not be arrested, but your summary +buffer will look strange, which is bad enough. + +The smart choice is to have these specs as far to the left as possible. +(Isn't that the case with everything, though? But I digress.) + +This restriction may disappear in later versions of gnus. + + +@node Summary Buffer Mode Line +@subsection Summary Buffer Mode Line + +@vindex gnus-summary-mode-line-format +You can also change the format of the summary mode bar (@pxref{Mode Line +Formatting}). Set @code{gnus-summary-mode-line-format} to whatever you +like. The default is @samp{Gnus: %%b [%A] %Z}. + +Here are the elements you can play with: + +@table @samp +@item G +Group name. +@item p +Unprefixed group name. +@item A +Current article number. +@item z +Current article score. +@item V +Gnus version. +@item U +Number of unread articles in this group. +@item e +Number of unread articles in this group that aren't displayed in the +summary buffer. +@item Z +A string with the number of unread and unselected articles represented +either as @samp{<%U(+%e) more>} if there are both unread and unselected +articles, and just as @samp{<%U more>} if there are just unread articles +and no unselected ones. +@item g +Shortish group name. For instance, @samp{rec.arts.anime} will be +shortened to @samp{r.a.anime}. +@item S +Subject of the current article. +@item u +User-defined spec (@pxref{User-Defined Specs}). +@item s +Name of the current score file (@pxref{Scoring}). +@item d +Number of dormant articles (@pxref{Unread Articles}). +@item t +Number of ticked articles (@pxref{Unread Articles}). +@item r +Number of articles that have been marked as read in this session. +@item E +Number of articles expunged by the score files. +@end table + + +@node Summary Highlighting +@subsection Summary Highlighting + +@table @code + +@item gnus-visual-mark-article-hook +@vindex gnus-visual-mark-article-hook +This hook is run after selecting an article. It is meant to be used for +highlighting the article in some way. It is not run if +@code{gnus-visual} is @code{nil}. + +@item gnus-summary-update-hook +@vindex gnus-summary-update-hook +This hook is called when a summary line is changed. It is not run if +@code{gnus-visual} is @code{nil}. + +@item gnus-summary-selected-face +@vindex gnus-summary-selected-face +This is the face (or @dfn{font} as some people call it) used to +highlight the current article in the summary buffer. + +@item gnus-summary-highlight +@vindex gnus-summary-highlight +Summary lines are highlighted according to this variable, which is a +list where the elements are of the format @var{(FORM . FACE)}. If you +would, for instance, like ticked articles to be italic and high-scored +articles to be bold, you could set this variable to something like +@lisp +(((eq mark gnus-ticked-mark) . italic) + ((> score default) . bold)) +@end lisp +As you may have guessed, if @var{FORM} returns a non-@code{nil} value, +@var{FACE} will be applied to the line. +@end table + + +@node Summary Maneuvering +@section Summary Maneuvering +@cindex summary movement + +All the straight movement commands understand the numeric prefix and +behave pretty much as you'd expect. + +None of these commands select articles. + +@table @kbd +@item G M-n +@itemx M-n +@kindex M-n (Summary) +@kindex G M-n (Summary) +@findex gnus-summary-next-unread-subject +Go to the next summary line of an unread article +(@code{gnus-summary-next-unread-subject}). + +@item G M-p +@itemx M-p +@kindex M-p (Summary) +@kindex G M-p (Summary) +@findex gnus-summary-prev-unread-subject +Go to the previous summary line of an unread article +(@code{gnus-summary-prev-unread-subject}). + +@item G j +@itemx j +@kindex j (Summary) +@kindex G j (Summary) +@findex gnus-summary-goto-article +Ask for an article number or @code{Message-ID}, and then go to that +article (@code{gnus-summary-goto-article}). + +@item G g +@kindex G g (Summary) +@findex gnus-summary-goto-subject +Ask for an article number and then go to the summary line of that article +without displaying the article (@code{gnus-summary-goto-subject}). +@end table + +If gnus asks you to press a key to confirm going to the next group, you +can use the @kbd{C-n} and @kbd{C-p} keys to move around the group +buffer, searching for the next group to read without actually returning +to the group buffer. + +Variables related to summary movement: + +@table @code + +@vindex gnus-auto-select-next +@item gnus-auto-select-next +If you issue one of the movement commands (like @kbd{n}) and there are +no more unread articles after the current one, gnus will offer to go to +the next group. If this variable is @code{t} and the next group is +empty, gnus will exit summary mode and return to the group buffer. If +this variable is neither @code{t} nor @code{nil}, gnus will select the +next group, no matter whether it has any unread articles or not. As a +special case, if this variable is @code{quietly}, gnus will select the +next group without asking for confirmation. If this variable is +@code{almost-quietly}, the same will happen only if you are located on +the last article in the group. Finally, if this variable is +@code{slightly-quietly}, the @kbd{Z n} command will go to the next group +without confirmation. Also @pxref{Group Levels}. + +@item gnus-auto-select-same +@vindex gnus-auto-select-same +If non-@code{nil}, all the movement commands will try to go to the next +article with the same subject as the current. (@dfn{Same} here might +mean @dfn{roughly equal}. See @code{gnus-summary-gather-subject-limit} +for details (@pxref{Customizing Threading}).) If there are no more +articles with the same subject, go to the first unread article. + +This variable is not particularly useful if you use a threaded display. + +@item gnus-summary-check-current +@vindex gnus-summary-check-current +If non-@code{nil}, all the ``unread'' movement commands will not proceed +to the next (or previous) article if the current article is unread. +Instead, they will choose the current article. + +@item gnus-auto-center-summary +@vindex gnus-auto-center-summary +If non-@code{nil}, gnus will keep the point in the summary buffer +centered at all times. This makes things quite tidy, but if you have a +slow network connection, or simply do not like this un-Emacsism, you can +set this variable to @code{nil} to get the normal Emacs scrolling +action. This will also inhibit horizontal re-centering of the summary +buffer, which might make it more inconvenient to read extremely long +threads. + +@end table + + +@node Choosing Articles +@section Choosing Articles +@cindex selecting articles + +@menu +* Choosing Commands:: Commands for choosing articles. +* Choosing Variables:: Variables that influence these commands. +@end menu + + +@node Choosing Commands +@subsection Choosing Commands + +None of the following movement commands understand the numeric prefix, +and they all select and display an article. + +@table @kbd +@item SPACE +@kindex SPACE (Summary) +@findex gnus-summary-next-page +Select the current article, or, if that one's read already, the next +unread article (@code{gnus-summary-next-page}). + +@item G n +@itemx n +@kindex n (Summary) +@kindex G n (Summary) +@findex gnus-summary-next-unread-article +@c @icon{gnus-summary-next-unread} +Go to next unread article (@code{gnus-summary-next-unread-article}). + +@item G p +@itemx p +@kindex p (Summary) +@findex gnus-summary-prev-unread-article +@c @icon{gnus-summary-prev-unread} +Go to previous unread article (@code{gnus-summary-prev-unread-article}). + +@item G N +@itemx N +@kindex N (Summary) +@kindex G N (Summary) +@findex gnus-summary-next-article +Go to the next article (@code{gnus-summary-next-article}). + +@item G P +@itemx P +@kindex P (Summary) +@kindex G P (Summary) +@findex gnus-summary-prev-article +Go to the previous article (@code{gnus-summary-prev-article}). + +@item G C-n +@kindex G C-n (Summary) +@findex gnus-summary-next-same-subject +Go to the next article with the same subject +(@code{gnus-summary-next-same-subject}). + +@item G C-p +@kindex G C-p (Summary) +@findex gnus-summary-prev-same-subject +Go to the previous article with the same subject +(@code{gnus-summary-prev-same-subject}). + +@item G f +@itemx . +@kindex G f (Summary) +@kindex . (Summary) +@findex gnus-summary-first-unread-article +Go to the first unread article +(@code{gnus-summary-first-unread-article}). + +@item G b +@itemx , +@kindex G b (Summary) +@kindex , (Summary) +@findex gnus-summary-best-unread-article +Go to the article with the highest score +(@code{gnus-summary-best-unread-article}). + +@item G l +@itemx l +@kindex l (Summary) +@kindex G l (Summary) +@findex gnus-summary-goto-last-article +Go to the previous article read (@code{gnus-summary-goto-last-article}). + +@item G o +@kindex G o (Summary) +@findex gnus-summary-pop-article +@cindex history +@cindex article history +Pop an article off the summary history and go to this article +(@code{gnus-summary-pop-article}). This command differs from the +command above in that you can pop as many previous articles off the +history as you like, while @kbd{l} toggles the two last read articles. +For a somewhat related issue (if you use these commands a lot), +@pxref{Article Backlog}. +@end table + + +@node Choosing Variables +@subsection Choosing Variables + +Some variables relevant for moving and selecting articles: + +@table @code +@item gnus-auto-extend-newsgroup +@vindex gnus-auto-extend-newsgroup +All the movement commands will try to go to the previous (or next) +article, even if that article isn't displayed in the Summary buffer if +this variable is non-@code{nil}. Gnus will then fetch the article from +the server and display it in the article buffer. + +@item gnus-select-article-hook +@vindex gnus-select-article-hook +This hook is called whenever an article is selected. By default it +exposes any threads hidden under the selected article. + +@item gnus-mark-article-hook +@vindex gnus-mark-article-hook +@findex gnus-summary-mark-unread-as-read +@findex gnus-summary-mark-read-and-unread-as-read +@findex gnus-unread-mark +This hook is called whenever an article is selected. It is intended to +be used for marking articles as read. The default value is +@code{gnus-summary-mark-read-and-unread-as-read}, and will change the +mark of almost any article you read to @code{gnus-unread-mark}. The +only articles not affected by this function are ticked, dormant, and +expirable articles. If you'd instead like to just have unread articles +marked as read, you can use @code{gnus-summary-mark-unread-as-read} +instead. It will leave marks like @code{gnus-low-score-mark}, +@code{gnus-del-mark} (and so on) alone. + +@end table + + +@node Paging the Article +@section Scrolling the Article +@cindex article scrolling + +@table @kbd + +@item SPACE +@kindex SPACE (Summary) +@findex gnus-summary-next-page +Pressing @kbd{SPACE} will scroll the current article forward one page, +or, if you have come to the end of the current article, will choose the +next article (@code{gnus-summary-next-page}). + +@item DEL +@kindex DEL (Summary) +@findex gnus-summary-prev-page +Scroll the current article back one page (@code{gnus-summary-prev-page}). + +@item RET +@kindex RET (Summary) +@findex gnus-summary-scroll-up +Scroll the current article one line forward +(@code{gnus-summary-scroll-up}). + +@item M-RET +@kindex M-RET (Summary) +@findex gnus-summary-scroll-down +Scroll the current article one line backward +(@code{gnus-summary-scroll-down}). + +@item A g +@itemx g +@kindex A g (Summary) +@kindex g (Summary) +@findex gnus-summary-show-article +(Re)fetch the current article (@code{gnus-summary-show-article}). If +given a prefix, fetch the current article, but don't run any of the +article treatment functions. This will give you a ``raw'' article, just +the way it came from the server. + +@item A < +@itemx < +@kindex < (Summary) +@kindex A < (Summary) +@findex gnus-summary-beginning-of-article +Scroll to the beginning of the article +(@code{gnus-summary-beginning-of-article}). + +@item A > +@itemx > +@kindex > (Summary) +@kindex A > (Summary) +@findex gnus-summary-end-of-article +Scroll to the end of the article (@code{gnus-summary-end-of-article}). + +@item A s +@itemx s +@kindex A s (Summary) +@kindex s (Summary) +@findex gnus-summary-isearch-article +Perform an isearch in the article buffer +(@code{gnus-summary-isearch-article}). + +@item h +@kindex h (Summary) +@findex gnus-summary-select-article-buffer +Select the article buffer (@code{gnus-summary-select-article-buffer}). + +@end table + + +@node Reply Followup and Post +@section Reply, Followup and Post + +@menu +* Summary Mail Commands:: Sending mail. +* Summary Post Commands:: Sending news. +@end menu + + +@node Summary Mail Commands +@subsection Summary Mail Commands +@cindex mail +@cindex composing mail + +Commands for composing a mail message: + +@table @kbd + +@item S r +@itemx r +@kindex S r (Summary) +@kindex r (Summary) +@findex gnus-summary-reply +@c @icon{gnus-summary-mail-reply} +@c @icon{gnus-summary-reply} +Mail a reply to the author of the current article +(@code{gnus-summary-reply}). + +@item S R +@itemx R +@kindex R (Summary) +@kindex S R (Summary) +@findex gnus-summary-reply-with-original +@c @icon{gnus-summary-reply-with-original} +Mail a reply to the author of the current article and include the +original message (@code{gnus-summary-reply-with-original}). This +command uses the process/prefix convention. + +@item S w +@kindex S w (Summary) +@findex gnus-summary-wide-reply +Mail a wide reply to the author of the current article +(@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that +goes out to all people listed in the @code{To}, @code{From} (or +@code{Reply-to}) and @code{Cc} headers. + +@item S W +@kindex S W (Summary) +@findex gnus-summary-wide-reply-with-original +Mail a wide reply to the current article and include the original +message (@code{gnus-summary-reply-with-original}). This command uses +the process/prefix convention. + +@item S o m +@kindex S o m (Summary) +@findex gnus-summary-mail-forward +@c @icon{gnus-summary-mail-forward} +Forward the current article to some other person +(@code{gnus-summary-mail-forward}). If given a prefix, include the full +headers of the forwarded article. + +@item S m +@itemx m +@kindex m (Summary) +@kindex S m (Summary) +@findex gnus-summary-mail-other-window +@c @icon{gnus-summary-mail-originate} +Send a mail to some other person +(@code{gnus-summary-mail-other-window}). + +@item S D b +@kindex S D b (Summary) +@findex gnus-summary-resend-bounced-mail +@cindex bouncing mail +If you have sent a mail, but the mail was bounced back to you for some +reason (wrong address, transient failure), you can use this command to +resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You +will be popped into a mail buffer where you can edit the headers before +sending the mail off again. If you give a prefix to this command, and +the bounced mail is a reply to some other mail, gnus will try to fetch +that mail and display it for easy perusal of its headers. This might +very well fail, though. + +@item S D r +@kindex S D r (Summary) +@findex gnus-summary-resend-message +Not to be confused with the previous command, +@code{gnus-summary-resend-message} will prompt you for an address to +send the current message off to, and then send it to that place. The +headers of the message won't be altered---but lots of headers that say +@code{Resent-To}, @code{Resent-From} and so on will be added. This +means that you actually send a mail to someone that has a @code{To} +header that (probably) points to yourself. This will confuse people. +So, natcherly you'll only do that if you're really eVIl. + +This command is mainly used if you have several accounts and want to +ship a mail to a different account of yours. (If you're both +@code{root} and @code{postmaster} and get a mail for @code{postmaster} +to the @code{root} account, you may want to resend it to +@code{postmaster}. Ordnung mu,A_(B sein! + +This command understands the process/prefix convention +(@pxref{Process/Prefix}). + +@item S O m +@kindex S O m (Summary) +@findex gnus-uu-digest-mail-forward +Digest the current series (@pxref{Decoding Articles}) and forward the +result using mail (@code{gnus-uu-digest-mail-forward}). This command +uses the process/prefix convention (@pxref{Process/Prefix}). + +@item S M-c +@kindex S M-c (Summary) +@findex gnus-summary-mail-crosspost-complaint +@cindex crossposting +@cindex excessive crossposting +Send a complaint about excessive crossposting to the author of the +current article (@code{gnus-summary-mail-crosspost-complaint}). + +@findex gnus-crosspost-complaint +This command is provided as a way to fight back against the current +crossposting pandemic that's sweeping Usenet. It will compose a reply +using the @code{gnus-crosspost-complaint} variable as a preamble. This +command understands the process/prefix convention +(@pxref{Process/Prefix}) and will prompt you before sending each mail. + +@end table + +Also @pxref{(message)Header Commands} for more information. + + +@node Summary Post Commands +@subsection Summary Post Commands +@cindex post +@cindex composing news + +Commands for posting a news article: + +@table @kbd +@item S p +@itemx a +@kindex a (Summary) +@kindex S p (Summary) +@findex gnus-summary-post-news +@c @icon{gnus-summary-post-news} +Post an article to the current group +(@code{gnus-summary-post-news}). + +@item S f +@itemx f +@kindex f (Summary) +@kindex S f (Summary) +@findex gnus-summary-followup +@c @icon{gnus-summary-followup} +Post a followup to the current article (@code{gnus-summary-followup}). + +@item S F +@itemx F +@kindex S F (Summary) +@kindex F (Summary) +@c @icon{gnus-summary-followup-with-original} +@findex gnus-summary-followup-with-original +Post a followup to the current article and include the original message +(@code{gnus-summary-followup-with-original}). This command uses the +process/prefix convention. + +@item S n +@kindex S n (Summary) +@findex gnus-summary-followup-to-mail +Post a followup to the current article via news, even if you got the +message through mail (@code{gnus-summary-followup-to-mail}). + +@item S N +@kindex S N (Summary) +@findex gnus-summary-followup-to-mail-with-original +Post a followup to the current article via news, even if you got the +message through mail and include the original message +(@code{gnus-summary-followup-to-mail-with-original}). This command uses +the process/prefix convention. + +@item S o p +@kindex S o p (Summary) +@findex gnus-summary-post-forward +Forward the current article to a newsgroup +(@code{gnus-summary-post-forward}). If given a prefix, include the full +headers of the forwarded article. + +@item S O p +@kindex S O p (Summary) +@findex gnus-uu-digest-post-forward +@cindex digests +@cindex making digests +Digest the current series and forward the result to a newsgroup +(@code{gnus-uu-digest-mail-forward}). This command uses the +process/prefix convention. + +@item S u +@kindex S u (Summary) +@findex gnus-uu-post-news +@c @icon{gnus-uu-post-news} +Uuencode a file, split it into parts, and post it as a series +(@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}). +@end table + +Also @pxref{(message)Header Commands} for more information. + + +@node Canceling and Superseding +@section Canceling Articles +@cindex canceling articles +@cindex superseding articles + +Have you ever written something, and then decided that you really, +really, really wish you hadn't posted that? + +Well, you can't cancel mail, but you can cancel posts. + +@findex gnus-summary-cancel-article +@kindex C (Summary) +@c @icon{gnus-summary-cancel-article} +Find the article you wish to cancel (you can only cancel your own +articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S +c} (@code{gnus-summary-cancel-article}). Your article will be +canceled---machines all over the world will be deleting your article. +This command uses the process/prefix convention (@pxref{Process/Prefix}). + +Be aware, however, that not all sites honor cancels, so your article may +live on here and there, while most sites will delete the article in +question. + +Gnus will use the ``current'' select method when canceling. If you +want to use the standard posting method, use the @samp{a} symbolic +prefix (@pxref{Symbolic Prefixes}). + +If you discover that you have made some mistakes and want to do some +corrections, you can post a @dfn{superseding} article that will replace +your original article. + +@findex gnus-summary-supersede-article +@kindex S (Summary) +Go to the original article and press @kbd{S s} +(@code{gnus-summary-supersede-article}). You will be put in a buffer +where you can edit the article all you want before sending it off the +usual way. + +The same goes for superseding as for canceling, only more so: Some +sites do not honor superseding. On those sites, it will appear that you +have posted almost the same article twice. + +If you have just posted the article, and change your mind right away, +there is a trick you can use to cancel/supersede the article without +waiting for the article to appear on your site first. You simply return +to the post buffer (which is called @code{*sent ...*}). There you will +find the article you just posted, with all the headers intact. Change +the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes} +header by substituting one of those words for the word +@code{Message-ID}. Then just press @kbd{C-c C-c} to send the article as +you would do normally. The previous article will be +canceled/superseded. + +Just remember, kids: There is no `c' in `supersede'. + + +@node Marking Articles +@section Marking Articles +@cindex article marking +@cindex article ticking +@cindex marks + +There are several marks you can set on an article. + +You have marks that decide the @dfn{readedness} (whoo, neato-keano +neologism ohoy!) of the article. Alphabetic marks generally mean +@dfn{read}, while non-alphabetic characters generally mean @dfn{unread}. + +In addition, you also have marks that do not affect readedness. + +@menu +* Unread Articles:: Marks for unread articles. +* Read Articles:: Marks for read articles. +* Other Marks:: Marks that do not affect readedness. +@end menu + +@ifinfo +There's a plethora of commands for manipulating these marks: +@end ifinfo + +@menu +* Setting Marks:: How to set and remove marks. +* Setting Process Marks:: How to mark articles for later processing. +@end menu + + +@node Unread Articles +@subsection Unread Articles + +The following marks mark articles as (kinda) unread, in one form or +other. + +@table @samp +@item ! +@vindex gnus-ticked-mark +Marked as ticked (@code{gnus-ticked-mark}). + +@dfn{Ticked articles} are articles that will remain visible always. If +you see an article that you find interesting, or you want to put off +reading it, or replying to it, until sometime later, you'd typically +tick it. However, articles can be expired, so if you want to keep an +article forever, you'll have to make it persistent (@pxref{Persistent +Articles}). + +@item ? +@vindex gnus-dormant-mark +Marked as dormant (@code{gnus-dormant-mark}). + +@dfn{Dormant articles} will only appear in the summary buffer if there +are followups to it. If you want to see them even if they don't have +followups, you can use the @kbd{/ D} command (@pxref{Limiting}). + +@item SPACE +@vindex gnus-unread-mark +Marked as unread (@code{gnus-unread-mark}). + +@dfn{Unread articles} are articles that haven't been read at all yet. +@end table + + +@node Read Articles +@subsection Read Articles +@cindex expirable mark + +All the following marks mark articles as read. + +@table @samp + +@item r +@vindex gnus-del-mark +These are articles that the user has marked as read with the @kbd{d} +command manually, more or less (@code{gnus-del-mark}). + +@item R +@vindex gnus-read-mark +Articles that have actually been read (@code{gnus-read-mark}). + +@item O +@vindex gnus-ancient-mark +Articles that were marked as read in previous sessions and are now +@dfn{old} (@code{gnus-ancient-mark}). + +@item K +@vindex gnus-killed-mark +Marked as killed (@code{gnus-killed-mark}). + +@item X +@vindex gnus-kill-file-mark +Marked as killed by kill files (@code{gnus-kill-file-mark}). + +@item Y +@vindex gnus-low-score-mark +Marked as read by having too low a score (@code{gnus-low-score-mark}). + +@item C +@vindex gnus-catchup-mark +Marked as read by a catchup (@code{gnus-catchup-mark}). + +@item G +@vindex gnus-canceled-mark +Canceled article (@code{gnus-canceled-mark}) + +@item F +@vindex gnus-souped-mark +@sc{SOUP}ed article (@code{gnus-souped-mark}). @xref{SOUP}. + +@item Q +@vindex gnus-sparse-mark +Sparsely reffed article (@code{gnus-sparse-mark}). @xref{Customizing +Threading}. + +@item M +@vindex gnus-duplicate-mark +Article marked as read by duplicate suppression +(@code{gnus-duplicated-mark}). @xref{Duplicate Suppression}. + +@end table + +All these marks just mean that the article is marked as read, really. +They are interpreted differently when doing adaptive scoring, though. + +One more special mark, though: + +@table @samp +@item E +@vindex gnus-expirable-mark +Marked as expirable (@code{gnus-expirable-mark}). + +Marking articles as @dfn{expirable} (or have them marked as such +automatically) doesn't make much sense in normal groups---a user doesn't +control expiring of news articles, but in mail groups, for instance, +articles marked as @dfn{expirable} can be deleted by gnus at any time. +@end table + + +@node Other Marks +@subsection Other Marks +@cindex process mark +@cindex bookmarks + +There are some marks that have nothing to do with whether the article is +read or not. + +@itemize @bullet + +@item +You can set a bookmark in the current article. Say you are reading a +long thesis on cats' urinary tracts, and have to go home for dinner +before you've finished reading the thesis. You can then set a bookmark +in the article, and gnus will jump to this bookmark the next time it +encounters the article. @xref{Setting Marks} + +@item +@vindex gnus-replied-mark +All articles that you have replied to or made a followup to (i.e., have +answered) will be marked with an @samp{A} in the second column +(@code{gnus-replied-mark}). + +@item +@vindex gnus-cached-mark +Articles stored in the article cache will be marked with an @samp{*} in +the second column (@code{gnus-cached-mark}). @xref{Article Caching} + +@item +@vindex gnus-saved-mark +Articles ``saved'' (in some manner or other; not necessarily +religiously) are marked with an @samp{S} in the second column +(@code{gnus-saved-mark}). + +@item +@vindex gnus-not-empty-thread-mark +@vindex gnus-empty-thread-mark +If the @samp{%e} spec is used, the presence of threads or not will be +marked with @code{gnus-not-empty-thread-mark} and +@code{gnus-empty-thread-mark} in the third column, respectively. + +@item +@vindex gnus-process-mark +Finally we have the @dfn{process mark} (@code{gnus-process-mark}). A +variety of commands react to the presence of the process mark. For +instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view +all articles that have been marked with the process mark. Articles +marked with the process mark have a @samp{#} in the second column. + +@end itemize + +You might have noticed that most of these ``non-readedness'' marks +appear in the second column by default. So if you have a cached, saved, +replied article that you have process-marked, what will that look like? + +Nothing much. The precedence rules go as follows: process -> cache -> +replied -> saved. So if the article is in the cache and is replied, +you'll only see the cache mark and not the replied mark. + + +@node Setting Marks +@subsection Setting Marks +@cindex setting marks + +All the marking commands understand the numeric prefix. + +@table @kbd +@item M c +@itemx M-u +@kindex M c (Summary) +@kindex M-u (Summary) +@findex gnus-summary-clear-mark-forward +@cindex mark as unread +Clear all readedness-marks from the current article +(@code{gnus-summary-clear-mark-forward}). In other words, mark the +article as unread. + +@item M t +@itemx ! +@kindex ! (Summary) +@kindex M t (Summary) +@findex gnus-summary-tick-article-forward +Tick the current article (@code{gnus-summary-tick-article-forward}). +@xref{Article Caching} + +@item M ? +@itemx ? +@kindex ? (Summary) +@kindex M ? (Summary) +@findex gnus-summary-mark-as-dormant +Mark the current article as dormant +(@code{gnus-summary-mark-as-dormant}). @xref{Article Caching} + +@item M d +@itemx d +@kindex M d (Summary) +@kindex d (Summary) +@findex gnus-summary-mark-as-read-forward +Mark the current article as read +(@code{gnus-summary-mark-as-read-forward}). + +@item D +@kindex D (Summary) +@findex gnus-summary-mark-as-read-backward +Mark the current article as read and move point to the previous line +(@code{gnus-summary-mark-as-read-backward}). + +@item M k +@itemx k +@kindex k (Summary) +@kindex M k (Summary) +@findex gnus-summary-kill-same-subject-and-select +Mark all articles that have the same subject as the current one as read, +and then select the next unread article +(@code{gnus-summary-kill-same-subject-and-select}). + +@item M K +@itemx C-k +@kindex M K (Summary) +@kindex C-k (Summary) +@findex gnus-summary-kill-same-subject +Mark all articles that have the same subject as the current one as read +(@code{gnus-summary-kill-same-subject}). + +@item M C +@kindex M C (Summary) +@findex gnus-summary-catchup +@c @icon{gnus-summary-catchup} +Mark all unread articles as read (@code{gnus-summary-catchup}). + +@item M C-c +@kindex M C-c (Summary) +@findex gnus-summary-catchup-all +Mark all articles in the group as read---even the ticked and dormant +articles (@code{gnus-summary-catchup-all}). + +@item M H +@kindex M H (Summary) +@findex gnus-summary-catchup-to-here +Catchup the current group to point +(@code{gnus-summary-catchup-to-here}). + +@item C-w +@kindex C-w (Summary) +@findex gnus-summary-mark-region-as-read +Mark all articles between point and mark as read +(@code{gnus-summary-mark-region-as-read}). + +@item M V k +@kindex M V k (Summary) +@findex gnus-summary-kill-below +Kill all articles with scores below the default score (or below the +numeric prefix) (@code{gnus-summary-kill-below}). + +@item M e +@itemx E +@kindex M e (Summary) +@kindex E (Summary) +@findex gnus-summary-mark-as-expirable +Mark the current article as expirable +(@code{gnus-summary-mark-as-expirable}). + +@item M b +@kindex M b (Summary) +@findex gnus-summary-set-bookmark +Set a bookmark in the current article +(@code{gnus-summary-set-bookmark}). + +@item M B +@kindex M B (Summary) +@findex gnus-summary-remove-bookmark +Remove the bookmark from the current article +(@code{gnus-summary-remove-bookmark}). + +@item M V c +@kindex M V c (Summary) +@findex gnus-summary-clear-above +Clear all marks from articles with scores over the default score (or +over the numeric prefix) (@code{gnus-summary-clear-above}). + +@item M V u +@kindex M V u (Summary) +@findex gnus-summary-tick-above +Tick all articles with scores over the default score (or over the +numeric prefix) (@code{gnus-summary-tick-above}). + +@item M V m +@kindex M V m (Summary) +@findex gnus-summary-mark-above +Prompt for a mark, and mark all articles with scores over the default +score (or over the numeric prefix) with this mark +(@code{gnus-summary-clear-above}). +@end table + +@vindex gnus-summary-goto-unread +The @code{gnus-summary-goto-unread} variable controls what action should +be taken after setting a mark. If non-@code{nil}, point will move to +the next/previous unread article. If @code{nil}, point will just move +one line up or down. As a special case, if this variable is +@code{never}, all the marking commands as well as other commands (like +@kbd{SPACE}) will move to the next article, whether it is unread or not. +The default is @code{t}. + + +@node Setting Process Marks +@subsection Setting Process Marks +@cindex setting process marks + +@table @kbd + +@item M P p +@itemx # +@kindex # (Summary) +@kindex M P p (Summary) +@findex gnus-summary-mark-as-processable +Mark the current article with the process mark +(@code{gnus-summary-mark-as-processable}). +@findex gnus-summary-unmark-as-processable + +@item M P u +@itemx M-# +@kindex M P u (Summary) +@kindex M-# (Summary) +Remove the process mark, if any, from the current article +(@code{gnus-summary-unmark-as-processable}). + +@item M P U +@kindex M P U (Summary) +@findex gnus-summary-unmark-all-processable +Remove the process mark from all articles +(@code{gnus-summary-unmark-all-processable}). + +@item M P i +@kindex M P i (Summary) +@findex gnus-uu-invert-processable +Invert the list of process marked articles +(@code{gnus-uu-invert-processable}). + +@item M P R +@kindex M P R (Summary) +@findex gnus-uu-mark-by-regexp +Mark articles that have a @code{Subject} header that matches a regular +expression (@code{gnus-uu-mark-by-regexp}). + +@item M P r +@kindex M P r (Summary) +@findex gnus-uu-mark-region +Mark articles in region (@code{gnus-uu-mark-region}). + +@item M P t +@kindex M P t (Summary) +@findex gnus-uu-mark-thread +Mark all articles in the current (sub)thread +(@code{gnus-uu-mark-thread}). + +@item M P T +@kindex M P T (Summary) +@findex gnus-uu-unmark-thread +Unmark all articles in the current (sub)thread +(@code{gnus-uu-unmark-thread}). + +@item M P v +@kindex M P v (Summary) +@findex gnus-uu-mark-over +Mark all articles that have a score above the prefix argument +(@code{gnus-uu-mark-over}). + +@item M P s +@kindex M P s (Summary) +@findex gnus-uu-mark-series +Mark all articles in the current series (@code{gnus-uu-mark-series}). + +@item M P S +@kindex M P S (Summary) +@findex gnus-uu-mark-sparse +Mark all series that have already had some articles marked +(@code{gnus-uu-mark-sparse}). + +@item M P a +@kindex M P a (Summary) +@findex gnus-uu-mark-all +Mark all articles in series order (@code{gnus-uu-mark-series}). + +@item M P b +@kindex M P b (Summary) +@findex gnus-uu-mark-buffer +Mark all articles in the buffer in the order they appear +(@code{gnus-uu-mark-buffer}). + +@item M P k +@kindex M P k (Summary) +@findex gnus-summary-kill-process-mark +Push the current process mark set onto the stack and unmark all articles +(@code{gnus-summary-kill-process-mark}). + +@item M P y +@kindex M P y (Summary) +@findex gnus-summary-yank-process-mark +Pop the previous process mark set from the stack and restore it +(@code{gnus-summary-yank-process-mark}). + +@item M P w +@kindex M P w (Summary) +@findex gnus-summary-save-process-mark +Push the current process mark set onto the stack +(@code{gnus-summary-save-process-mark}). + +@end table + + +@node Limiting +@section Limiting +@cindex limiting + +It can be convenient to limit the summary buffer to just show some +subset of the articles currently in the group. The effect most limit +commands have is to remove a few (or many) articles from the summary +buffer. + +All limiting commands work on subsets of the articles already fetched +from the servers. None of these commands query the server for +additional articles. + +@table @kbd + +@item / / +@itemx / s +@kindex / / (Summary) +@findex gnus-summary-limit-to-subject +Limit the summary buffer to articles that match some subject +(@code{gnus-summary-limit-to-subject}). + +@item / a +@kindex / a (Summary) +@findex gnus-summary-limit-to-author +Limit the summary buffer to articles that match some author +(@code{gnus-summary-limit-to-author}). + +@item / u +@itemx x +@kindex / u (Summary) +@kindex x (Summary) +@findex gnus-summary-limit-to-unread +Limit the summary buffer to articles not marked as read +(@code{gnus-summary-limit-to-unread}). If given a prefix, limit the +buffer to articles strictly unread. This means that ticked and +dormant articles will also be excluded. + +@item / m +@kindex / m (Summary) +@findex gnus-summary-limit-to-marks +Ask for a mark and then limit to all articles that have been marked +with that mark (@code{gnus-summary-limit-to-marks}). + +@item / t +@kindex / t (Summary) +@findex gnus-summary-limit-to-age +Ask for a number and then limit the summary buffer to articles older than (or equal to) that number of days +(@code{gnus-summary-limit-to-marks}). If given a prefix, limit to +articles younger than that number of days. + +@item / n +@kindex / n (Summary) +@findex gnus-summary-limit-to-articles +Limit the summary buffer to the current article +(@code{gnus-summary-limit-to-articles}). Uses the process/prefix +convention (@pxref{Process/Prefix}). + +@item / w +@kindex / w (Summary) +@findex gnus-summary-pop-limit +Pop the previous limit off the stack and restore it +(@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off +the stack. + +@item / v +@kindex / v (Summary) +@findex gnus-summary-limit-to-score +Limit the summary buffer to articles that have a score at or above some +score (@code{gnus-summary-limit-to-score}). + +@item / E +@itemx M S +@kindex M S (Summary) +@kindex / E (Summary) +@findex gnus-summary-limit-include-expunged +Include all expunged articles in the limit +(@code{gnus-summary-limit-include-expunged}). + +@item / D +@kindex / D (Summary) +@findex gnus-summary-limit-include-dormant +Include all dormant articles in the limit +(@code{gnus-summary-limit-include-dormant}). + +@item / * +@kindex / * (Summary) +@findex gnus-summary-limit-include-cached +Include all cached articles in the limit +(@code{gnus-summary-limit-include-cached}). + +@item / d +@kindex / d (Summary) +@findex gnus-summary-limit-exclude-dormant +Exclude all dormant articles from the limit +(@code{gnus-summary-limit-exclude-dormant}). + +@item / T +@kindex / T (Summary) +@findex gnus-summary-limit-include-thread +Include all the articles in the current thread in the limit. + +@item / c +@kindex / c (Summary) +@findex gnus-summary-limit-exclude-childless-dormant +Exclude all dormant articles that have no children from the limit +(@code{gnus-summary-limit-exclude-childless-dormant}). + +@item / C +@kindex / C (Summary) +@findex gnus-summary-limit-mark-excluded-as-read +Mark all excluded unread articles as read +(@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix, +also mark excluded ticked and dormant articles as read. + +@end table + + +@node Threading +@section Threading +@cindex threading +@cindex article threading + +Gnus threads articles by default. @dfn{To thread} is to put responses +to articles directly after the articles they respond to---in a +hierarchical fashion. + +Threading is done by looking at the @code{References} headers of the +articles. In a perfect world, this would be enough to build pretty +trees, but unfortunately, the @code{References} header is often broken +or simply missing. Weird news propagation excarcerbates the problem, +so one has to employ other heuristics to get pleasing results. A +plethora of approaches exists, as detailed in horrible detail in +@pxref{Customizing Threading}. + +First, a quick overview of the concepts: + +@table @dfn +@item root +The top-most article in a thread; the first article in the thread. + +@item thread +A tree-like article structure. + +@item sub-thread +A small(er) section of this tree-like structure. + +@item loose threads +Threads often lose their roots due to article expiry, or due to the root +already having been read in a previous session, and not displayed in the +summary buffer. We then typically have many sub-threads that really +belong to one thread, but are without connecting roots. These are +called loose threads. + +@item thread gathering +An attempt to gather loose threads into bigger threads. + +@item sparse threads +A thread where the missing articles have been ``guessed'' at, and are +displayed as empty lines in the summary buffer. + +@end table + + +@menu +* Customizing Threading:: Variables you can change to affect the threading. +* Thread Commands:: Thread based commands in the summary buffer. +@end menu + + +@node Customizing Threading +@subsection Customizing Threading +@cindex customizing threading + +@menu +* 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... but you were wrong! +@end menu + + +@node Loose Threads +@subsubsection Loose Threads +@cindex < +@cindex > +@cindex loose threads + +@table @code +@item gnus-summary-make-false-root +@vindex gnus-summary-make-false-root +If non-@code{nil}, gnus will gather all loose subtrees into one big tree +and create a dummy root at the top. (Wait a minute. Root at the top? +Yup.) Loose subtrees occur when the real root has expired, or you've +read or killed the root in a previous session. + +When there is no real root of a thread, gnus will have to fudge +something. This variable says what fudging method gnus should use. +There are four possible values: + +@iftex +@iflatex +\gnusfigure{The Summary Buffer}{390}{ +\put(0,0){\epsfig{figure=tmp/summary-adopt.ps,width=7.5cm}} +\put(445,0){\makebox(0,0)[br]{\epsfig{figure=tmp/summary-empty.ps,width=7.5cm}}} +\put(0,400){\makebox(0,0)[tl]{\epsfig{figure=tmp/summary-none.ps,width=7.5cm}}} +\put(445,400){\makebox(0,0)[tr]{\epsfig{figure=tmp/summary-dummy.ps,width=7.5cm}}} +} +@end iflatex +@end iftex + +@cindex adopting articles + +@table @code + +@item adopt +Gnus will make the first of the orphaned articles the parent. This +parent will adopt all the other articles. The adopted articles will be +marked as such by pointy brackets (@samp{<>}) instead of the standard +square brackets (@samp{[]}). This is the default method. + +@item dummy +@vindex gnus-summary-dummy-line-format +Gnus will create a dummy summary line that will pretend to be the +parent. This dummy line does not correspond to any real article, so +selecting it will just select the first real article after the dummy +article. @code{gnus-summary-dummy-line-format} is used to specify the +format of the dummy roots. It accepts only one format spec: @samp{S}, +which is the subject of the article. @xref{Formatting Variables}. + +@item empty +Gnus won't actually make any article the parent, but simply leave the +subject field of all orphans except the first empty. (Actually, it will +use @code{gnus-summary-same-subject} as the subject (@pxref{Summary +Buffer Format}).) + +@item none +Don't make any article parent at all. Just gather the threads and +display them after one another. + +@item nil +Don't gather loose threads. +@end table + +@item gnus-summary-gather-subject-limit +@vindex gnus-summary-gather-subject-limit +Loose threads are gathered by comparing subjects of articles. If this +variable is @code{nil}, gnus requires an exact match between the +subjects of the loose threads before gathering them into one big +super-thread. This might be too strict a requirement, what with the +presence of stupid newsreaders that chop off long subject lines. If +you think so, set this variable to, say, 20 to require that only the +first 20 characters of the subjects have to match. If you set this +variable to a really low number, you'll find that gnus will gather +everything in sight into one thread, which isn't very helpful. + +@cindex fuzzy article gathering +If you set this variable to the special value @code{fuzzy}, gnus will +use a fuzzy string comparison algorithm on the subjects (@pxref{Fuzzy +Matching}). + +@item gnus-simplify-subject-fuzzy-regexp +@vindex gnus-simplify-subject-fuzzy-regexp +This can either be a regular expression or list of regular expressions +that match strings that will be removed from subjects if fuzzy subject +simplification is used. + +@item gnus-simplify-ignored-prefixes +@vindex gnus-simplify-ignored-prefixes +If you set @code{gnus-summary-gather-subject-limit} to something as low +as 10, you might consider setting this variable to something sensible: + +@c Written by Michael Ernst +@lisp +(setq gnus-simplify-ignored-prefixes + (concat + "\\`\\[?\\(" + (mapconcat + 'identity + '("looking" + "wanted" "followup" "summary\\( of\\)?" + "help" "query" "problem" "question" + "answer" "reference" "announce" + "How can I" "How to" "Comparison of" + ;; ... + ) + "\\|") + "\\)\\s *\\(" + (mapconcat 'identity + '("for" "for reference" "with" "about") + "\\|") + "\\)?\\]?:?[ \t]*")) +@end lisp + +All words that match this regexp will be removed before comparing two +subjects. + +@item gnus-simplify-subject-functions +@vindex gnus-simplify-subject-functions +If non-@code{nil}, this variable overrides +@code{gnus-summary-gather-subject-limit}. This variable should be a +list of functions to apply to the @code{Subject} string iteratively to +arrive at the simplified version of the string. + +Useful functions to put in this list include: + +@table @code +@item gnus-simplify-subject-re +@findex gnus-simplify-subject-re +Strip the leading @samp{Re:}. + +@item gnus-simplify-subject-fuzzy +@findex gnus-simplify-subject-fuzzy +Simplify fuzzily. + +@item gnus-simplify-whitespace +@findex gnus-simplify-whitespace +Remove excessive whitespace. +@end table + +You may also write your own functions, of course. + + +@item gnus-summary-gather-exclude-subject +@vindex gnus-summary-gather-exclude-subject +Since loose thread gathering is done on subjects only, that might lead +to many false hits, especially with certain common subjects like +@samp{} and @samp{(none)}. To make the situation slightly better, +you can use the regexp @code{gnus-summary-gather-exclude-subject} to say +what subjects should be excluded from the gathering process.@* +The default is @samp{^ *$\\|^(none)$}. + +@item gnus-summary-thread-gathering-function +@vindex gnus-summary-thread-gathering-function +Gnus gathers threads by looking at @code{Subject} headers. This means +that totally unrelated articles may end up in the same ``thread'', which +is confusing. An alternate approach is to look at all the +@code{Message-ID}s in all the @code{References} headers to find matches. +This will ensure that no gathered threads ever include unrelated +articles, but it also means that people who have posted with broken +newsreaders won't be gathered properly. The choice is yours---plague or +cholera: + +@table @code +@item gnus-gather-threads-by-subject +@findex gnus-gather-threads-by-subject +This function is the default gathering function and looks at +@code{Subject}s exclusively. + +@item gnus-gather-threads-by-references +@findex gnus-gather-threads-by-references +This function looks at @code{References} headers exclusively. +@end table + +If you want to test gathering by @code{References}, you could say +something like: + +@lisp +(setq gnus-summary-thread-gathering-function + 'gnus-gather-threads-by-references) +@end lisp + +@end table + + +@node Filling In Threads +@subsubsection Filling In Threads + +@table @code +@item gnus-fetch-old-headers +@vindex gnus-fetch-old-headers +If non-@code{nil}, gnus will attempt to build old threads by fetching +more old headers---headers to articles marked as read. If you would +like to display as few summary lines as possible, but still connect as +many loose threads as possible, you should set this variable to +@code{some} or a number. If you set it to a number, no more than that +number of extra old headers will be fetched. In either case, fetching +old headers only works if the backend you are using carries overview +files---this would normally be @code{nntp}, @code{nnspool} and +@code{nnml}. Also remember that if the root of the thread has been +expired by the server, there's not much gnus can do about that. + +This variable can also be set to @code{invisible}. This won't have any +visible effects, but is useful if you use the @kbd{A T} command a lot +(@pxref{Finding the Parent}). + +@item gnus-build-sparse-threads +@vindex gnus-build-sparse-threads +Fetching old headers can be slow. A low-rent similar effect can be +gotten by setting this variable to @code{some}. Gnus will then look at +the complete @code{References} headers of all articles and try to string +together articles that belong in the same thread. This will leave +@dfn{gaps} in the threading display where gnus guesses that an article +is missing from the thread. (These gaps appear like normal summary +lines. If you select a gap, gnus will try to fetch the article in +question.) If this variable is @code{t}, gnus will display all these +``gaps'' without regard for whether they are useful for completing the +thread or not. Finally, if this variable is @code{more}, gnus won't cut +off sparse leaf nodes that don't lead anywhere. This variable is +@code{nil} by default. + +@end table + + +@node More Threading +@subsubsection More Threading + +@table @code +@item gnus-show-threads +@vindex gnus-show-threads +If this variable is @code{nil}, no threading will be done, and all of +the rest of the variables here will have no effect. Turning threading +off will speed group selection up a bit, but it is sure to make reading +slower and more awkward. + +@item gnus-thread-hide-subtree +@vindex gnus-thread-hide-subtree +If non-@code{nil}, all threads will be hidden when the summary buffer is +generated. + +@item gnus-thread-expunge-below +@vindex gnus-thread-expunge-below +All threads that have a total score (as defined by +@code{gnus-thread-score-function}) less than this number will be +expunged. This variable is @code{nil} by default, which means that no +threads are expunged. + +@item gnus-thread-hide-killed +@vindex gnus-thread-hide-killed +if you kill a thread and this variable is non-@code{nil}, the subtree +will be hidden. + +@item gnus-thread-ignore-subject +@vindex gnus-thread-ignore-subject +Sometimes somebody changes the subject in the middle of a thread. If +this variable is non-@code{nil}, the subject change is ignored. If it +is @code{nil}, which is the default, a change in the subject will result +in a new thread. + +@item gnus-thread-indent-level +@vindex gnus-thread-indent-level +This is a number that says how much each sub-thread should be indented. +The default is 4. + +@end table + + +@node Low-Level Threading +@subsubsection Low-Level Threading + +@table @code + +@item gnus-parse-headers-hook +@vindex gnus-parse-headers-hook +Hook run before parsing any headers. The default value is +@code{(gnus-set-summary-default-charset)}, which sets up local value of +@code{default-mime-charset} in summary buffer based on variable +@code{gnus-newsgroup-default-charset-alist}. + +@item gnus-alter-header-function +@vindex gnus-alter-header-function +If non-@code{nil}, this function will be called to allow alteration of +article header structures. The function is called with one parameter, +the article header vector, which it may alter in any way. For instance, +if you have a mail-to-news gateway which alters the @code{Message-ID}s +in systematic ways (by adding prefixes and such), you can use this +variable to un-scramble the @code{Message-ID}s so that they are more +meaningful. Here's one example: + +@lisp +(setq gnus-alter-header-function 'my-alter-message-id) + +(defun my-alter-message-id (header) + (let ((id (mail-header-id header))) + (when (string-match + "\\(<[^<>@@]*\\)\\.?cygnus\\..*@@\\([^<>@@]*>\\)" id) + (mail-header-set-id + (concat (match-string 1 id) "@@" (match-string 2 id)) + header)))) +@end lisp + +@end table + + +@node Thread Commands +@subsection Thread Commands +@cindex thread commands + +@table @kbd + +@item T k +@itemx M-C-k +@kindex T k (Summary) +@kindex M-C-k (Summary) +@findex gnus-summary-kill-thread +Mark all articles in the current (sub-)thread as read +(@code{gnus-summary-kill-thread}). If the prefix argument is positive, +remove all marks instead. If the prefix argument is negative, tick +articles instead. + +@item T l +@itemx M-C-l +@kindex T l (Summary) +@kindex M-C-l (Summary) +@findex gnus-summary-lower-thread +Lower the score of the current (sub-)thread +(@code{gnus-summary-lower-thread}). + +@item T i +@kindex T i (Summary) +@findex gnus-summary-raise-thread +Increase the score of the current (sub-)thread +(@code{gnus-summary-raise-thread}). + +@item T # +@kindex T # (Summary) +@findex gnus-uu-mark-thread +Set the process mark on the current (sub-)thread +(@code{gnus-uu-mark-thread}). + +@item T M-# +@kindex T M-# (Summary) +@findex gnus-uu-unmark-thread +Remove the process mark from the current (sub-)thread +(@code{gnus-uu-unmark-thread}). + +@item T T +@kindex T T (Summary) +@findex gnus-summary-toggle-threads +Toggle threading (@code{gnus-summary-toggle-threads}). + +@item T s +@kindex T s (Summary) +@findex gnus-summary-show-thread +Expose the (sub-)thread hidden under the current article, if any +(@code{gnus-summary-show-thread}). + +@item T h +@kindex T h (Summary) +@findex gnus-summary-hide-thread +Hide the current (sub-)thread (@code{gnus-summary-hide-thread}). + +@item T S +@kindex T S (Summary) +@findex gnus-summary-show-all-threads +Expose all hidden threads (@code{gnus-summary-show-all-threads}). + +@item T H +@kindex T H (Summary) +@findex gnus-summary-hide-all-threads +Hide all threads (@code{gnus-summary-hide-all-threads}). + +@item T t +@kindex T t (Summary) +@findex gnus-summary-rethread-current +Re-thread the current article's thread +(@code{gnus-summary-rethread-current}). This works even when the +summary buffer is otherwise unthreaded. + +@item T ^ +@kindex T ^ (Summary) +@findex gnus-summary-reparent-thread +Make the current article the child of the marked (or previous) article +(@code{gnus-summary-reparent-thread}). + +@end table + +The following commands are thread movement commands. They all +understand the numeric prefix. + +@table @kbd + +@item T n +@kindex T n (Summary) +@findex gnus-summary-next-thread +Go to the next thread (@code{gnus-summary-next-thread}). + +@item T p +@kindex T p (Summary) +@findex gnus-summary-prev-thread +Go to the previous thread (@code{gnus-summary-prev-thread}). + +@item T d +@kindex T d (Summary) +@findex gnus-summary-down-thread +Descend the thread (@code{gnus-summary-down-thread}). + +@item T u +@kindex T u (Summary) +@findex gnus-summary-up-thread +Ascend the thread (@code{gnus-summary-up-thread}). + +@item T o +@kindex T o (Summary) +@findex gnus-summary-top-thread +Go to the top of the thread (@code{gnus-summary-top-thread}). +@end table + +@vindex gnus-thread-operation-ignore-subject +If you ignore subject while threading, you'll naturally end up with +threads that have several different subjects in them. If you then issue +a command like `T k' (@code{gnus-summary-kill-thread}) you might not +wish to kill the entire thread, but just those parts of the thread that +have the same subject as the current article. If you like this idea, +you can fiddle with @code{gnus-thread-operation-ignore-subject}. If it +is non-@code{nil} (which it is by default), subjects will be ignored +when doing thread commands. If this variable is @code{nil}, articles in +the same thread with different subjects will not be included in the +operation in question. If this variable is @code{fuzzy}, only articles +that have subjects fuzzily equal will be included (@pxref{Fuzzy +Matching}). + + +@node Sorting +@section Sorting + +@findex gnus-thread-sort-by-total-score +@findex gnus-thread-sort-by-date +@findex gnus-thread-sort-by-score +@findex gnus-thread-sort-by-subject +@findex gnus-thread-sort-by-author +@findex gnus-thread-sort-by-number +@vindex gnus-thread-sort-functions +If you are using a threaded summary display, you can sort the threads by +setting @code{gnus-thread-sort-functions}, which is a list of functions. +By default, sorting is done on article numbers. Ready-made sorting +predicate functions include @code{gnus-thread-sort-by-number}, +@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject}, +@code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and +@code{gnus-thread-sort-by-total-score}. + +Each function takes two threads and returns non-@code{nil} if the first +thread should be sorted before the other. Note that sorting really is +normally done by looking only at the roots of each thread. If you use +more than one function, the primary sort key should be the last function +in the list. You should probably always include +@code{gnus-thread-sort-by-number} in the list of sorting +functions---preferably first. This will ensure that threads that are +equal with respect to the other sort criteria will be displayed in +ascending article order. + +If you would like to sort by score, then by subject, and finally by +number, you could do something like: + +@lisp +(setq gnus-thread-sort-functions + '(gnus-thread-sort-by-number + gnus-thread-sort-by-subject + gnus-thread-sort-by-total-score)) +@end lisp + +The threads that have highest score will be displayed first in the +summary buffer. When threads have the same score, they will be sorted +alphabetically. The threads that have the same score and the same +subject will be sorted by number, which is (normally) the sequence in +which the articles arrived. + +If you want to sort by score and then reverse arrival order, you could +say something like: + +@lisp +(setq gnus-thread-sort-functions + '((lambda (t1 t2) + (not (gnus-thread-sort-by-number t1 t2))) + gnus-thread-sort-by-score)) +@end lisp + +@vindex gnus-thread-score-function +The function in the @code{gnus-thread-score-function} variable (default +@code{+}) is used for calculating the total score of a thread. Useful +functions might be @code{max}, @code{min}, or squared means, or whatever +tickles your fancy. + +@findex gnus-article-sort-functions +@findex gnus-article-sort-by-date +@findex gnus-article-sort-by-score +@findex gnus-article-sort-by-subject +@findex gnus-article-sort-by-author +@findex gnus-article-sort-by-number +If you are using an unthreaded display for some strange reason or other, +you have to fiddle with the @code{gnus-article-sort-functions} variable. +It is very similar to the @code{gnus-thread-sort-functions}, except that +it uses slightly different functions for article comparison. Available +sorting predicate functions are @code{gnus-article-sort-by-number}, +@code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject}, +@code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}. + +If you want to sort an unthreaded summary display by subject, you could +say something like: + +@lisp +(setq gnus-article-sort-functions + '(gnus-article-sort-by-number + gnus-article-sort-by-subject)) +@end lisp + + + +@node Asynchronous Fetching +@section Asynchronous Article Fetching +@cindex asynchronous article fetching +@cindex article pre-fetch +@cindex pre-fetch + +If you read your news from an @sc{nntp} server that's far away, the +network latencies may make reading articles a chore. You have to wait +for a while after pressing @kbd{n} to go to the next article before the +article appears. Why can't gnus just go ahead and fetch the article +while you are reading the previous one? Why not, indeed. + +First, some caveats. There are some pitfalls to using asynchronous +article fetching, especially the way gnus does it. + +Let's say you are reading article 1, which is short, and article 2 is +quite long, and you are not interested in reading that. Gnus does not +know this, so it goes ahead and fetches article 2. You decide to read +article 3, but since gnus is in the process of fetching article 2, the +connection is blocked. + +To avoid these situations, gnus will open two (count 'em two) +connections to the server. Some people may think this isn't a very nice +thing to do, but I don't see any real alternatives. Setting up that +extra connection takes some time, so gnus startup will be slower. + +Gnus will fetch more articles than you will read. This will mean that +the link between your machine and the @sc{nntp} server will become more +loaded than if you didn't use article pre-fetch. The server itself will +also become more loaded---both with the extra article requests, and the +extra connection. + +Ok, so now you know that you shouldn't really use this thing... unless +you really want to. + +@vindex gnus-asynchronous +Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should +happen automatically. + +@vindex gnus-use-article-prefetch +You can control how many articles are to be pre-fetched by setting +@code{gnus-use-article-prefetch}. This is 30 by default, which means +that when you read an article in the group, the backend will pre-fetch +the next 30 articles. If this variable is @code{t}, the backend will +pre-fetch all the articles it can without bound. If it is +@code{nil}, no pre-fetching will be done. + +@vindex gnus-async-prefetch-article-p +@findex gnus-async-read-p +There are probably some articles that you don't want to pre-fetch---read +articles, for instance. The @code{gnus-async-prefetch-article-p} variable controls whether an article is to be pre-fetched. This function should +return non-@code{nil} when the article in question is to be +pre-fetched. The default is @code{gnus-async-read-p}, which returns +@code{nil} on read articles. The function is called with an article +data structure as the only parameter. + +If, for instance, you wish to pre-fetch only unread articles shorter +than 100 lines, you could say something like: + +@lisp +(defun my-async-short-unread-p (data) + "Return non-nil for short, unread articles." + (and (gnus-data-unread-p data) + (< (mail-header-lines (gnus-data-header data)) + 100))) + +(setq gnus-async-prefetch-article-p 'my-async-short-unread-p) +@end lisp + +These functions will be called many, many times, so they should +preferably be short and sweet to avoid slowing down gnus too much. It's +probably a good idea to byte-compile things like this. + +@vindex gnus-prefetched-article-deletion-strategy +Articles have to be removed from the asynch buffer sooner or later. The +@code{gnus-prefetched-article-deletion-strategy} says when to remove +articles. This is a list that may contain the following elements: + +@table @code +@item read +Remove articles when they are read. + +@item exit +Remove articles when exiting the group. +@end table + +The default value is @code{(read exit)}. + +@c @vindex gnus-use-header-prefetch +@c If @code{gnus-use-header-prefetch} is non-@code{nil}, prefetch articles +@c from the next group. + + +@node Article Caching +@section Article Caching +@cindex article caching +@cindex caching + +If you have an @emph{extremely} slow @sc{nntp} connection, you may +consider turning article caching on. Each article will then be stored +locally under your home directory. As you may surmise, this could +potentially use @emph{huge} amounts of disk space, as well as eat up all +your inodes so fast it will make your head swim. In vodka. + +Used carefully, though, it could be just an easier way to save articles. + +@vindex gnus-use-long-file-name +@vindex gnus-cache-directory +@vindex gnus-use-cache +To turn caching on, set @code{gnus-use-cache} to @code{t}. By default, +all articles ticked or marked as dormant will then be copied +over to your local cache (@code{gnus-cache-directory}). Whether this +cache is flat or hierarchal is controlled by the +@code{gnus-use-long-file-name} variable, as usual. + +When re-selecting a ticked or dormant article, it will be fetched from the +cache instead of from the server. As articles in your cache will never +expire, this might serve as a method of saving articles while still +keeping them where they belong. Just mark all articles you want to save +as dormant, and don't worry. + +When an article is marked as read, is it removed from the cache. + +@vindex gnus-cache-remove-articles +@vindex gnus-cache-enter-articles +The entering/removal of articles from the cache is controlled by the +@code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles} +variables. Both are lists of symbols. The first is @code{(ticked +dormant)} by default, meaning that ticked and dormant articles will be +put in the cache. The latter is @code{(read)} by default, meaning that +articles marked as read are removed from the cache. Possibly +symbols in these two lists are @code{ticked}, @code{dormant}, +@code{unread} and @code{read}. + +@findex gnus-jog-cache +So where does the massive article-fetching and storing come into the +picture? The @code{gnus-jog-cache} command will go through all +subscribed newsgroups, request all unread articles, score them, and +store them in the cache. You should only ever, ever ever ever, use this +command if 1) your connection to the @sc{nntp} server is really, really, +really slow and 2) you have a really, really, really huge disk. +Seriously. One way to cut down on the number of articles downloaded is +to score unwanted articles down and have them marked as read. They will +not then be downloaded by this command. + +@vindex gnus-uncacheable-groups +@vindex gnus-cacheable-groups +It is likely that you do not want caching on all groups. For instance, +if your @code{nnml} mail is located under your home directory, it makes no +sense to cache it somewhere else under your home directory. Unless you +feel that it's neat to use twice as much space. + +To limit the caching, you could set @code{gnus-cacheable-groups} to a +regexp of groups to cache, @samp{^nntp} for instance, or set the +@code{gnus-uncacheable-groups} regexp to @samp{^nnml}, for instance. +Both variables are @code{nil} by default. If a group matches both +variables, the group is not cached. + +@findex gnus-cache-generate-nov-databases +@findex gnus-cache-generate-active +@vindex gnus-cache-active-file +The cache stores information on what articles it contains in its active +file (@code{gnus-cache-active-file}). If this file (or any other parts +of the cache) becomes all messed up for some reason or other, gnus +offers two functions that will try to set things right. @kbd{M-x +gnus-cache-generate-nov-databases} will (re)build all the @sc{nov} +files, and @kbd{gnus-cache-generate-active} will (re)generate the active +file. + + +@node Persistent Articles +@section Persistent Articles +@cindex persistent articles + +Closely related to article caching, we have @dfn{persistent articles}. +In fact, it's just a different way of looking at caching, and much more +useful in my opinion. + +Say you're reading a newsgroup, and you happen on to some valuable gem +that you want to keep and treasure forever. You'd normally just save it +(using one of the many saving commands) in some file. The problem with +that is that it's just, well, yucky. Ideally you'd prefer just having +the article remain in the group where you found it forever; untouched by +the expiry going on at the news server. + +This is what a @dfn{persistent article} is---an article that just won't +be deleted. It's implemented using the normal cache functions, but +you use two explicit commands for managing persistent articles: + +@table @kbd + +@item * +@kindex * (Summary) +@findex gnus-cache-enter-article +Make the current article persistent (@code{gnus-cache-enter-article}). + +@item M-* +@kindex M-* (Summary) +@findex gnus-cache-remove-article +Remove the current article from the persistent articles +(@code{gnus-cache-remove-article}). This will normally delete the +article. +@end table + +Both these commands understand the process/prefix convention. + +To avoid having all ticked articles (and stuff) entered into the cache, +you should set @code{gnus-use-cache} to @code{passive} if you're just +interested in persistent articles: + +@lisp +(setq gnus-use-cache 'passive) +@end lisp + + +@node Article Backlog +@section Article Backlog +@cindex backlog +@cindex article backlog + +If you have a slow connection, but the idea of using caching seems +unappealing to you (and it is, really), you can help the situation some +by switching on the @dfn{backlog}. This is where gnus will buffer +already read articles so that it doesn't have to re-fetch articles +you've already read. This only helps if you are in the habit of +re-selecting articles you've recently read, of course. If you never do +that, turning the backlog on will slow gnus down a little bit, and +increase memory usage some. + +@vindex gnus-keep-backlog +If you set @code{gnus-keep-backlog} to a number @var{n}, gnus will store +at most @var{n} old articles in a buffer for later re-fetching. If this +variable is non-@code{nil} and is not a number, gnus will store +@emph{all} read articles, which means that your Emacs will grow without +bound before exploding and taking your machine down with you. I put +that in there just to keep y'all on your toes. + +This variable is @code{nil} by default. + + +@node Saving Articles +@section Saving Articles +@cindex saving articles + +Gnus can save articles in a number of ways. Below is the documentation +for saving articles in a fairly straight-forward fashion (i.e., little +processing of the article is done before it is saved). For a different +approach (uudecoding, unsharing) you should use @code{gnus-uu} +(@pxref{Decoding Articles}). + +@vindex gnus-save-all-headers +If @code{gnus-save-all-headers} is non-@code{nil}, gnus will not delete +unwanted headers before saving the article. + +@vindex gnus-saved-headers +If the preceding variable is @code{nil}, all headers that match the +@code{gnus-saved-headers} regexp will be kept, while the rest will be +deleted before saving. + +@table @kbd + +@item O o +@itemx o +@kindex O o (Summary) +@kindex o (Summary) +@findex gnus-summary-save-article +@c @icon{gnus-summary-save-article} +Save the current article using the default article saver +(@code{gnus-summary-save-article}). + +@item O m +@kindex O m (Summary) +@findex gnus-summary-save-article-mail +Save the current article in mail format +(@code{gnus-summary-save-article-mail}). + +@item O r +@kindex O r (Summary) +@findex gnus-summary-save-article-rmail +Save the current article in rmail format +(@code{gnus-summary-save-article-rmail}). + +@item O f +@kindex O f (Summary) +@findex gnus-summary-save-article-file +@c @icon{gnus-summary-save-article-file} +Save the current article in plain file format +(@code{gnus-summary-save-article-file}). + +@item O F +@kindex O F (Summary) +@findex gnus-summary-write-article-file +Write the current article in plain file format, overwriting any previous +file contents (@code{gnus-summary-write-article-file}). + +@item O b +@kindex O b (Summary) +@findex gnus-summary-save-article-body-file +Save the current article body in plain file format +(@code{gnus-summary-save-article-body-file}). + +@item O h +@kindex O h (Summary) +@findex gnus-summary-save-article-folder +Save the current article in mh folder format +(@code{gnus-summary-save-article-folder}). + +@item O v +@kindex O v (Summary) +@findex gnus-summary-save-article-vm +Save the current article in a VM folder +(@code{gnus-summary-save-article-vm}). + +@item O p +@kindex O p (Summary) +@findex gnus-summary-pipe-output +Save the current article in a pipe. Uhm, like, what I mean is---Pipe +the current article to a process (@code{gnus-summary-pipe-output}). +@end table + +@vindex gnus-prompt-before-saving +All these commands use the process/prefix convention +(@pxref{Process/Prefix}). If you save bunches of articles using these +functions, you might get tired of being prompted for files to save each +and every article in. The prompting action is controlled by +the @code{gnus-prompt-before-saving} variable, which is @code{always} by +default, giving you that excessive prompting action you know and +loathe. If you set this variable to @code{t} instead, you'll be prompted +just once for each series of articles you save. If you like to really +have Gnus do all your thinking for you, you can even set this variable +to @code{nil}, which means that you will never be prompted for files to +save articles in. Gnus will simply save all the articles in the default +files. + + +@vindex gnus-default-article-saver +You can customize the @code{gnus-default-article-saver} variable to make +gnus do what you want it to. You can use any of the four ready-made +functions below, or you can create your own. + +@table @code + +@item gnus-summary-save-in-rmail +@findex gnus-summary-save-in-rmail +@vindex gnus-rmail-save-name +@findex gnus-plain-save-name +This is the default format, @dfn{babyl}. Uses the function in the +@code{gnus-rmail-save-name} variable to get a file name to save the +article in. The default is @code{gnus-plain-save-name}. + +@item gnus-summary-save-in-mail +@findex gnus-summary-save-in-mail +@vindex gnus-mail-save-name +Save in a Unix mail (mbox) file. Uses the function in the +@code{gnus-mail-save-name} variable to get a file name to save the +article in. The default is @code{gnus-plain-save-name}. + +@item gnus-summary-save-in-file +@findex gnus-summary-save-in-file +@vindex gnus-file-save-name +@findex gnus-numeric-save-name +Append the article straight to an ordinary file. Uses the function in +the @code{gnus-file-save-name} variable to get a file name to save the +article in. The default is @code{gnus-numeric-save-name}. + +@item gnus-summary-save-body-in-file +@findex gnus-summary-save-body-in-file +Append the article body to an ordinary file. Uses the function in the +@code{gnus-file-save-name} variable to get a file name to save the +article in. The default is @code{gnus-numeric-save-name}. + +@item gnus-summary-save-in-folder +@findex gnus-summary-save-in-folder +@findex gnus-folder-save-name +@findex gnus-Folder-save-name +@vindex gnus-folder-save-name +@cindex rcvstore +@cindex MH folders +Save the article to an MH folder using @code{rcvstore} from the MH +library. Uses the function in the @code{gnus-folder-save-name} variable +to get a file name to save the article in. The default is +@code{gnus-folder-save-name}, but you can also use +@code{gnus-Folder-save-name}, which creates capitalized names. + +@item gnus-summary-save-in-vm +@findex gnus-summary-save-in-vm +Save the article in a VM folder. You have to have the VM mail +reader to use this setting. +@end table + +@vindex gnus-article-save-directory +All of these functions, except for the last one, will save the article +in the @code{gnus-article-save-directory}, which is initialized from the +@code{SAVEDIR} environment variable. This is @file{~/News/} by +default. + +As you can see above, the functions use different functions to find a +suitable name of a file to save the article in. Below is a list of +available functions that generate names: + +@table @code + +@item gnus-Numeric-save-name +@findex gnus-Numeric-save-name +File names like @file{~/News/Alt.andrea-dworkin/45}. + +@item gnus-numeric-save-name +@findex gnus-numeric-save-name +File names like @file{~/News/alt.andrea-dworkin/45}. + +@item gnus-Plain-save-name +@findex gnus-Plain-save-name +File names like @file{~/News/Alt.andrea-dworkin}. + +@item gnus-plain-save-name +@findex gnus-plain-save-name +File names like @file{~/News/alt.andrea-dworkin}. +@end table + +@vindex gnus-split-methods +You can have gnus suggest where to save articles by plonking a regexp +into the @code{gnus-split-methods} alist. For instance, if you would +like to save articles related to gnus in the file @file{gnus-stuff}, and +articles related to VM in @code{vm-stuff}, you could set this variable +to something like: + +@lisp +(("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff") + ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff") + (my-choosing-function "../other-dir/my-stuff") + ((equal gnus-newsgroup-name "mail.misc") "mail-stuff")) +@end lisp + +We see that this is a list where each element is a list that has two +elements---the @dfn{match} and the @dfn{file}. The match can either be +a string (in which case it is used as a regexp to match on the article +head); it can be a symbol (which will be called as a function with the +group name as a parameter); or it can be a list (which will be +@code{eval}ed). If any of these actions have a non-@code{nil} result, +the @dfn{file} will be used as a default prompt. In addition, the +result of the operation itself will be used if the function or form +called returns a string or a list of strings. + +You basically end up with a list of file names that might be used when +saving the current article. (All ``matches'' will be used.) You will +then be prompted for what you really want to use as a name, with file +name completion over the results from applying this variable. + +This variable is @code{((gnus-article-archive-name))} by default, which +means that gnus will look at the articles it saves for an +@code{Archive-name} line and use that as a suggestion for the file name. + +Here's an example function to clean up file names somewhat. If you have +lots of mail groups called things like +@samp{nnml:mail.whatever}, you may want to chop off the beginning of +these group names before creating the file name to save to. The +following will do just that: + +@lisp +(defun my-save-name (group) + (when (string-match "^nnml:mail." group) + (substring group (match-end 0)))) + +(setq gnus-split-methods + '((gnus-article-archive-name) + (my-save-name))) +@end lisp + + +@vindex gnus-use-long-file-name +Finally, you have the @code{gnus-use-long-file-name} variable. If it is +@code{nil}, all the preceding functions will replace all periods +(@samp{.}) in the group names with slashes (@samp{/})---which means that +the functions will generate hierarchies of directories instead of having +all the files in the top level directory +(@file{~/News/alt/andrea-dworkin} instead of +@file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default +on most systems. However, for historical reasons, this is @code{nil} on +Xenix and usg-unix-v machines by default. + +This function also affects kill and score file names. If this variable +is a list, and the list contains the element @code{not-score}, long file +names will not be used for score files, if it contains the element +@code{not-save}, long file names will not be used for saving, and if it +contains the element @code{not-kill}, long file names will not be used +for kill files. + +If you'd like to save articles in a hierarchy that looks something like +a spool, you could + +@lisp +(setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy +(setq gnus-default-article-saver 'gnus-summary-save-in-file) ; no encoding +@end lisp + +Then just save with @kbd{o}. You'd then read this hierarchy with +ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and +the top level directory as the argument (@file{~/News/}). Then just walk +around to the groups/directories with @code{nneething}. + + +@node Decoding Articles +@section Decoding Articles +@cindex decoding articles + +Sometime users post articles (or series of articles) that have been +encoded in some way or other. Gnus can decode them for you. + +@menu +* 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? +@end menu + +@cindex series +@cindex article series +All these functions use the process/prefix convention +(@pxref{Process/Prefix}) for finding out what articles to work on, with +the extension that a ``single article'' means ``a single series''. Gnus +can find out by itself what articles belong to a series, decode all the +articles and unpack/view/save the resulting file(s). + +Gnus guesses what articles are in the series according to the following +simplish rule: The subjects must be (nearly) identical, except for the +last two numbers of the line. (Spaces are largely ignored, however.) + +For example: If you choose a subject called @samp{cat.gif (2/3)}, gnus +will find all the articles that match the regexp @samp{^cat.gif +([0-9]+/[0-9]+).*$}. + +Subjects that are non-standard, like @samp{cat.gif (2/3) Part 6 of a +series}, will not be properly recognized by any of the automatic viewing +commands, and you have to mark the articles manually with @kbd{#}. + + +@node Uuencoded Articles +@subsection Uuencoded Articles +@cindex uudecode +@cindex uuencoded articles + +@table @kbd + +@item X u +@kindex X u (Summary) +@findex gnus-uu-decode-uu +@c @icon{gnus-uu-decode-uu} +Uudecodes the current series (@code{gnus-uu-decode-uu}). + +@item X U +@kindex X U (Summary) +@findex gnus-uu-decode-uu-and-save +Uudecodes and saves the current series +(@code{gnus-uu-decode-uu-and-save}). + +@item X v u +@kindex X v u (Summary) +@findex gnus-uu-decode-uu-view +Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}). + +@item X v U +@kindex X v U (Summary) +@findex gnus-uu-decode-uu-and-save-view +Uudecodes, views and saves the current series +(@code{gnus-uu-decode-uu-and-save-view}). + +@end table + +Remember that these all react to the presence of articles marked with +the process mark. If, for instance, you'd like to decode and save an +entire newsgroup, you'd typically do @kbd{M P a} +(@code{gnus-uu-mark-all}) and then @kbd{X U} +(@code{gnus-uu-decode-uu-and-save}). + +All this is very much different from how @code{gnus-uu} worked with +@sc{GNUS 4.1}, where you had explicit keystrokes for everything under +the sun. This version of @code{gnus-uu} generally assumes that you mark +articles in some way (@pxref{Setting Process Marks}) and then press +@kbd{X u}. + +@vindex gnus-uu-notify-files +Note: When trying to decode articles that have names matching +@code{gnus-uu-notify-files}, which is hard-coded to +@samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will +automatically post an article on @samp{comp.unix.wizards} saying that +you have just viewed the file in question. This feature can't be turned +off. + + +@node Shell Archives +@subsection Shell Archives +@cindex unshar +@cindex shell archives +@cindex shared articles + +Shell archives (``shar files'') used to be a popular way to distribute +sources, but it isn't used all that much today. In any case, we have +some commands to deal with these: + +@table @kbd + +@item X s +@kindex X s (Summary) +@findex gnus-uu-decode-unshar +Unshars the current series (@code{gnus-uu-decode-unshar}). + +@item X S +@kindex X S (Summary) +@findex gnus-uu-decode-unshar-and-save +Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}). + +@item X v s +@kindex X v s (Summary) +@findex gnus-uu-decode-unshar-view +Unshars and views the current series (@code{gnus-uu-decode-unshar-view}). + +@item X v S +@kindex X v S (Summary) +@findex gnus-uu-decode-unshar-and-save-view +Unshars, views and saves the current series +(@code{gnus-uu-decode-unshar-and-save-view}). +@end table + + +@node PostScript Files +@subsection PostScript Files +@cindex PostScript + +@table @kbd + +@item X p +@kindex X p (Summary) +@findex gnus-uu-decode-postscript +Unpack the current PostScript series (@code{gnus-uu-decode-postscript}). + +@item X P +@kindex X P (Summary) +@findex gnus-uu-decode-postscript-and-save +Unpack and save the current PostScript series +(@code{gnus-uu-decode-postscript-and-save}). + +@item X v p +@kindex X v p (Summary) +@findex gnus-uu-decode-postscript-view +View the current PostScript series +(@code{gnus-uu-decode-postscript-view}). + +@item X v P +@kindex X v P (Summary) +@findex gnus-uu-decode-postscript-and-save-view +View and save the current PostScript series +(@code{gnus-uu-decode-postscript-and-save-view}). +@end table + + +@node Other Files +@subsection Other Files + +@table @kbd +@item X o +@kindex X o (Summary) +@findex gnus-uu-decode-save +Save the current series +(@code{gnus-uu-decode-save}). + +@item X b +@kindex X b (Summary) +@findex gnus-uu-decode-binhex +Unbinhex the current series (@code{gnus-uu-decode-binhex}). This +doesn't really work yet. +@end table + + +@node Decoding Variables +@subsection Decoding Variables + +Adjective, not verb. + +@menu +* 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. +@end menu + + +@node Rule Variables +@subsubsection Rule Variables +@cindex rule variables + +Gnus uses @dfn{rule variables} to decide how to view a file. All these +variables are of the form + +@lisp + (list '(regexp1 command2) + '(regexp2 command2) + ...) +@end lisp + +@table @code + +@item gnus-uu-user-view-rules +@vindex gnus-uu-user-view-rules +@cindex sox +This variable is consulted first when viewing files. If you wish to use, +for instance, @code{sox} to convert an @samp{.au} sound file, you could +say something like: +@lisp +(setq gnus-uu-user-view-rules + (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\"))) +@end lisp + +@item gnus-uu-user-view-rules-end +@vindex gnus-uu-user-view-rules-end +This variable is consulted if gnus couldn't make any matches from the +user and default view rules. + +@item gnus-uu-user-archive-rules +@vindex gnus-uu-user-archive-rules +This variable can be used to say what commands should be used to unpack +archives. +@end table + + +@node Other Decode Variables +@subsubsection Other Decode Variables + +@table @code +@vindex gnus-uu-grabbed-file-functions + +@item gnus-uu-grabbed-file-functions +All functions in this list will be called right after each file has been +successfully decoded---so that you can move or view files right away, +and don't have to wait for all files to be decoded before you can do +anything. Ready-made functions you can put in this list are: + +@table @code + +@item gnus-uu-grab-view +@findex gnus-uu-grab-view +View the file. + +@item gnus-uu-grab-move +@findex gnus-uu-grab-move +Move the file (if you're using a saving function.) +@end table + +@item gnus-uu-be-dangerous +@vindex gnus-uu-be-dangerous +Specifies what to do if unusual situations arise during decoding. If +@code{nil}, be as conservative as possible. If @code{t}, ignore things +that didn't work, and overwrite existing files. Otherwise, ask each +time. + +@item gnus-uu-ignore-files-by-name +@vindex gnus-uu-ignore-files-by-name +Files with name matching this regular expression won't be viewed. + +@item gnus-uu-ignore-files-by-type +@vindex gnus-uu-ignore-files-by-type +Files with a @sc{mime} type matching this variable won't be viewed. +Note that Gnus tries to guess what type the file is based on the name. +@code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly +kludgey. + +@item gnus-uu-tmp-dir +@vindex gnus-uu-tmp-dir +Where @code{gnus-uu} does its work. + +@item gnus-uu-do-not-unpack-archives +@vindex gnus-uu-do-not-unpack-archives +Non-@code{nil} means that @code{gnus-uu} won't peek inside archives +looking for files to display. + +@item gnus-uu-view-and-save +@vindex gnus-uu-view-and-save +Non-@code{nil} means that the user will always be asked to save a file +after viewing it. + +@item gnus-uu-ignore-default-view-rules +@vindex gnus-uu-ignore-default-view-rules +Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing +rules. + +@item gnus-uu-ignore-default-archive-rules +@vindex gnus-uu-ignore-default-archive-rules +Non-@code{nil} means that @code{gnus-uu} will ignore the default archive +unpacking commands. + +@item gnus-uu-kill-carriage-return +@vindex gnus-uu-kill-carriage-return +Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns +from articles. + +@item gnus-uu-unmark-articles-not-decoded +@vindex gnus-uu-unmark-articles-not-decoded +Non-@code{nil} means that @code{gnus-uu} will mark unsuccessfully +decoded articles as unread. + +@item gnus-uu-correct-stripped-uucode +@vindex gnus-uu-correct-stripped-uucode +Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix +uuencoded files that have had trailing spaces deleted. + +@item gnus-uu-pre-uudecode-hook +@vindex gnus-uu-pre-uudecode-hook +Hook run before sending a message to @code{uudecode}. + +@item gnus-uu-view-with-metamail +@vindex gnus-uu-view-with-metamail +@cindex metamail +Non-@code{nil} means that @code{gnus-uu} will ignore the viewing +commands defined by the rule variables and just fudge a @sc{mime} +content type based on the file name. The result will be fed to +@code{metamail} for viewing. + +@item gnus-uu-save-in-digest +@vindex gnus-uu-save-in-digest +Non-@code{nil} means that @code{gnus-uu}, when asked to save without +decoding, will save in digests. If this variable is @code{nil}, +@code{gnus-uu} will just save everything in a file without any +embellishments. The digesting almost conforms to RFC1153---no easy way +to specify any meaningful volume and issue numbers were found, so I +simply dropped them. + +@end table + + +@node Uuencoding and Posting +@subsubsection Uuencoding and Posting + +@table @code + +@item gnus-uu-post-include-before-composing +@vindex gnus-uu-post-include-before-composing +Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode +before you compose the article. If this variable is @code{t}, you can +either include an encoded file with @kbd{C-c C-i} or have one included +for you when you post the article. + +@item gnus-uu-post-length +@vindex gnus-uu-post-length +Maximum length of an article. The encoded file will be split into how +many articles it takes to post the entire file. + +@item gnus-uu-post-threaded +@vindex gnus-uu-post-threaded +Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a +thread. This may not be smart, as no other decoder I have seen is able +to follow threads when collecting uuencoded articles. (Well, I have +seen one package that does that---@code{gnus-uu}, but somehow, I don't +think that counts...) Default is @code{nil}. + +@item gnus-uu-post-separate-description +@vindex gnus-uu-post-separate-description +Non-@code{nil} means that the description will be posted in a separate +article. The first article will typically be numbered (0/x). If this +variable is @code{nil}, the description the user enters will be included +at the beginning of the first article, which will be numbered (1/x). +Default is @code{t}. + +@end table + + +@node Viewing Files +@subsection Viewing Files +@cindex viewing files +@cindex pseudo-articles + +After decoding, if the file is some sort of archive, gnus will attempt +to unpack the archive and see if any of the files in the archive can be +viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz} +containing the files @file{pic1.jpg} and @file{pic2.gif}, gnus will +uncompress and de-tar the main file, and then view the two pictures. +This unpacking process is recursive, so if the archive contains archives +of archives, it'll all be unpacked. + +Finally, gnus will normally insert a @dfn{pseudo-article} for each +extracted file into the summary buffer. If you go to these +``articles'', you will be prompted for a command to run (usually Gnus +will make a suggestion), and then the command will be run. + +@vindex gnus-view-pseudo-asynchronously +If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait +until the viewing is done before proceeding. + +@vindex gnus-view-pseudos +If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert +the pseudo-articles into the summary buffer, but view them +immediately. If this variable is @code{not-confirm}, the user won't even +be asked for a confirmation before viewing is done. + +@vindex gnus-view-pseudos-separately +If @code{gnus-view-pseudos-separately} is non-@code{nil}, one +pseudo-article will be created for each file to be viewed. If +@code{nil}, all files that use the same viewing command will be given as +a list of parameters to that command. + +@vindex gnus-insert-pseudo-articles +If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert +pseudo-articles when decoding. It is @code{t} by default. + +So; there you are, reading your @emph{pseudo-articles} in your +@emph{virtual newsgroup} from the @emph{virtual server}; and you think: +Why isn't anything real anymore? How did we get here? + + +@node Article Treatment +@section Article Treatment + +Reading through this huge manual, you may have quite forgotten that the +object of newsreaders is to actually, like, read what people have +written. Reading articles. Unfortunately, people are quite bad at +writing, so there are tons of functions and variables to make reading +these articles easier. + +@menu +* 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 Buttons:: Click on URLs, Message-IDs, addresses and the like. +* Article Date:: Grumble, UT! +* Article Signature:: What is a signature? +@end menu + + +@node Article Highlighting +@subsection Article Highlighting +@cindex highlighting + +Not only do you want your article buffer to look like fruit salad, but +you want it to look like technicolor fruit salad. + +@table @kbd + +@item W H a +@kindex W H a (Summary) +@findex gnus-article-highlight +@findex gnus-article-maybe-highlight +Do much highlighting of the current article +(@code{gnus-article-highlight}). This function highlights header, cited +text, the signature, and adds buttons to the body and the head. + +Most users would prefer using @code{gnus-article-maybe-highlight} in +@code{gnus-article-display-hook} (@pxref{Customizing Articles}) instead. +This is a bit less agressive---it highlights only the headers, the +signature and adds buttons. + +@item W H h +@kindex W H h (Summary) +@findex gnus-article-highlight-headers +@vindex gnus-header-face-alist +Highlight the headers (@code{gnus-article-highlight-headers}). The +highlighting will be done according to the @code{gnus-header-face-alist} +variable, which is a list where each element has the form @var{(regexp +name content)}. @var{regexp} is a regular expression for matching the +header, @var{name} is the face used for highlighting the header name +(@pxref{Faces and Fonts}) and @var{content} is the face for highlighting +the header value. The first match made will be used. Note that +@var{regexp} shouldn't have @samp{^} prepended---Gnus will add one. + +@item W H c +@kindex W H c (Summary) +@findex gnus-article-highlight-citation +Highlight cited text (@code{gnus-article-highlight-citation}). + +Some variables to customize the citation highlights: + +@table @code +@vindex gnus-cite-parse-max-size + +@item gnus-cite-parse-max-size +If the article size if bigger than this variable (which is 25000 by +default), no citation highlighting will be performed. + +@item gnus-cite-prefix-regexp +@vindex gnus-cite-prefix-regexp +Regexp matching the longest possible citation prefix on a line. + +@item gnus-cite-max-prefix +@vindex gnus-cite-max-prefix +Maximum possible length for a citation prefix (default 20). + +@item gnus-cite-face-list +@vindex gnus-cite-face-list +List of faces used for highlighting citations (@pxref{Faces and Fonts}). +When there are citations from multiple articles in the same message, +gnus will try to give each citation from each article its own face. +This should make it easier to see who wrote what. + +@item gnus-supercite-regexp +@vindex gnus-supercite-regexp +Regexp matching normal Supercite attribution lines. + +@item gnus-supercite-secondary-regexp +@vindex gnus-supercite-secondary-regexp +Regexp matching mangled Supercite attribution lines. + +@item gnus-cite-minimum-match-count +@vindex gnus-cite-minimum-match-count +Minimum number of identical prefixes we have to see before we believe +that it's a citation. + +@item gnus-cite-attribution-prefix +@vindex gnus-cite-attribution-prefix +Regexp matching the beginning of an attribution line. + +@item gnus-cite-attribution-suffix +@vindex gnus-cite-attribution-suffix +Regexp matching the end of an attribution line. + +@item gnus-cite-attribution-face +@vindex gnus-cite-attribution-face +Face used for attribution lines. It is merged with the face for the +cited text belonging to the attribution. + +@end table + + +@item W H s +@kindex W H s (Summary) +@vindex gnus-signature-separator +@vindex gnus-signature-face +@findex gnus-article-highlight-signature +Highlight the signature (@code{gnus-article-highlight-signature}). +Everything after @code{gnus-signature-separator} (@pxref{Article +Signature}) in an article will be considered a signature and will be +highlighted with @code{gnus-signature-face}, which is @code{italic} by +default. + +@end table + +@xref{Customizing Articles} for how to highlight articles automatically. + + +@node Article Fontisizing +@subsection Article Fontisizing +@cindex emphasis +@cindex article emphasis + +@findex gnus-article-emphasize +@kindex W e (Summary) +People commonly add emphasis to words in news articles by writing things +like @samp{_this_} or @samp{*this*}. Gnus can make this look nicer by +running the article through the @kbd{W e} +(@code{gnus-article-emphasize}) command. + +@vindex gnus-emphasis-alist +How the emphasis is computed is controlled by the +@code{gnus-emphasis-alist} variable. This is an alist where the first +element is a regular expression to be matched. The second is a number +that says what regular expression grouping is used to find the entire +emphasized word. The third is a number that says what regexp grouping +should be displayed and highlighted. (The text between these two +groupings will be hidden.) The fourth is the face used for +highlighting. + +@lisp +(setq gnus-article-emphasis + '(("_\\(\\w+\\)_" 0 1 gnus-emphasis-underline) + ("\\*\\(\\w+\\)\\*" 0 1 gnus-emphasis-bold))) +@end lisp + +@vindex gnus-emphasis-underline +@vindex gnus-emphasis-bold +@vindex gnus-emphasis-italic +@vindex gnus-emphasis-underline-bold +@vindex gnus-emphasis-underline-italic +@vindex gnus-emphasis-bold-italic +@vindex gnus-emphasis-underline-bold-italic +By default, there are seven rules, and they use the following faces: +@code{gnus-emphasis-bold}, @code{gnus-emphasis-italic}, +@code{gnus-emphasis-underline}, @code{gnus-emphasis-bold-italic}, +@code{gnus-emphasis-underline-italic}, +@code{gnus-emphasis-underline-bold}, and +@code{gnus-emphasis-underline-bold-italic}. + +If you want to change these faces, you can either use @kbd{M-x +customize}, or you can use @code{copy-face}. For instance, if you want +to make @code{gnus-emphasis-italic} use a red face instead, you could +say something like: + +@lisp +(copy-face 'red 'gnus-emphasis-italic) +@end lisp + +@xref{Customizing Articles} for how to fontize articles automatically. + + +@node Article Hiding +@subsection Article Hiding +@cindex article hiding + +Or rather, hiding certain things in each article. There usually is much +too much cruft in most articles. + +@table @kbd + +@item W W a +@kindex W W a (Summary) +@findex gnus-article-hide +Do quite a lot of hiding on the article buffer +(@kbd{gnus-article-hide}). In particular, this function will hide +headers, PGP, cited text and the signature. + +@item W W h +@kindex W W h (Summary) +@findex gnus-article-hide-headers +Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding +Headers}. + +@item W W b +@kindex W W b (Summary) +@findex gnus-article-hide-boring-headers +Hide headers that aren't particularly interesting +(@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}. + +@item W W s +@kindex W W s (Summary) +@findex gnus-article-hide-signature +Hide signature (@code{gnus-article-hide-signature}). @xref{Article +Signature}. + +@item W W p +@kindex W W p (Summary) +@findex gnus-article-hide-pgp +@vindex gnus-article-hide-pgp-hook +Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}). The +@code{gnus-article-hide-pgp-hook} hook will be run after a @sc{pgp} +signature has been hidden. For example, to automatically verify +articles that have signatures in them do: +@lisp +;;; Hide pgp cruft if any. + +(add-hook 'gnus-article-display-hook 'gnus-article-hide-pgp) + +;;; After hiding pgp, verify the message; +;;; only happens if pgp signature is found. + +(add-hook 'gnus-article-hide-pgp-hook + (lambda () + (save-excursion + (set-buffer gnus-original-article-buffer) + (mc-verify)))) +@end lisp + +@item W W P +@kindex W W P (Summary) +@findex gnus-article-hide-pem +Hide @sc{pem} (privacy enhanced messages) cruft +(@code{gnus-article-hide-pem}). + +@item W W c +@kindex W W c (Summary) +@findex gnus-article-hide-citation +Hide citation (@code{gnus-article-hide-citation}). Some variables for +customizing the hiding: + +@table @code + +@item gnus-cited-opened-text-button-line-format +@itemx gnus-cited-closed-text-button-line-format +@vindex gnus-cited-closed-text-button-line-format +@vindex gnus-cited-opened-text-button-line-format +Gnus adds buttons to show where the cited text has been hidden, and to +allow toggle hiding the text. The format of the variable is specified +by these format-like variable (@pxref{Formatting Variables}). These +specs are valid: + +@table @samp +@item b +Starting point of the hidden text. +@item e +Ending point of the hidden text. +@item l +Number of characters in the hidden region. +@item n +Number of lines of hidden text. +@end table + +@item gnus-cited-lines-visible +@vindex gnus-cited-lines-visible +The number of lines at the beginning of the cited text to leave shown. + +@end table + +@item W W C-c +@kindex W W C-c (Summary) +@findex gnus-article-hide-citation-maybe + +Hide citation (@code{gnus-article-hide-citation-maybe}) depending on the +following two variables: + +@table @code +@item gnus-cite-hide-percentage +@vindex gnus-cite-hide-percentage +If the cited text is of a bigger percentage than this variable (default +50), hide the cited text. + +@item gnus-cite-hide-absolute +@vindex gnus-cite-hide-absolute +The cited text must have at least this length (default 10) before it +is hidden. +@end table + +@item W W C +@kindex W W C (Summary) +@findex gnus-article-hide-citation-in-followups +Hide cited text in articles that aren't roots +(@code{gnus-article-hide-citation-in-followups}). This isn't very +useful as an interactive command, but might be a handy function to stick +in @code{gnus-article-display-hook} (@pxref{Customizing Articles}). + +@end table + +All these ``hiding'' commands are toggles, but if you give a negative +prefix to these commands, they will show what they have previously +hidden. If you give a positive prefix, they will always hide. + +Also @pxref{Article Highlighting} for further variables for +citation customization. + +@xref{Customizing Articles} for how to hide article elements +automatically. + + +@node Article Washing +@subsection Article Washing +@cindex washing +@cindex article washing + +We call this ``article washing'' for a really good reason. Namely, the +@kbd{A} key was taken, so we had to use the @kbd{W} key instead. + +@dfn{Washing} is defined by us as ``changing something from something to +something else'', but normally results in something looking better. +Cleaner, perhaps. + +@table @kbd + +@item W l +@kindex W l (Summary) +@findex gnus-summary-stop-page-breaking +Remove page breaks from the current article +(@code{gnus-summary-stop-page-breaking}). @xref{Misc Article} for page +delimiters. + +@item W r +@kindex W r (Summary) +@findex gnus-summary-caesar-message +@c @icon{gnus-summary-caesar-message} +Do a Caesar rotate (rot13) on the article buffer +(@code{gnus-summary-caesar-message}). +Unreadable articles that tell you to read them with Caesar rotate or rot13. +(Typically offensive jokes and such.) + +It's commonly called ``rot13'' because each letter is rotated 13 +positions in the alphabet, e. g. @samp{B} (letter #2) -> @samp{O} (letter +#15). It is sometimes referred to as ``Caesar rotate'' because Caesar +is rumored to have employed this form of, uh, somewhat weak encryption. + +@item W t +@kindex W t (Summary) +@findex gnus-summary-toggle-header +Toggle whether to display all headers in the article buffer +(@code{gnus-summary-toggle-header}). + +@item W v +@kindex W v (Summary) +@findex gnus-summary-verbose-header +Toggle whether to display all headers in the article buffer permanently +(@code{gnus-summary-verbose-header}). + +@item W m +@kindex W m (Summary) +@findex gnus-summary-toggle-mime +Toggle whether to display the article as @sc{mime} message +(@code{gnus-summary-toggle-mime}). + +@item W o +@kindex W o (Summary) +@findex gnus-article-treat-overstrike +Treat overstrike (@code{gnus-article-treat-overstrike}). + +@item W d +@kindex W d (Summary) +@findex gnus-article-treat-dumbquotes +Treat M******** sm*rtq**t*s (@code{gnus-article-treat-dumbquotes}). + +@item W w +@kindex W w (Summary) +@findex gnus-article-fill-cited-article +Do word wrap (@code{gnus-article-fill-cited-article}). If you use this +function in @code{gnus-article-display-hook}, it should be run fairly +late and certainly after any highlighting. + +You can give the command a numerical prefix to specify the width to use +when filling. + +@item W c +@kindex W c (Summary) +@findex gnus-article-remove-cr +Remove CR (i. e., @samp{^M}s on the end of the lines) +(@code{gnus-article-remove-cr}). + +@item W f +@kindex W f (Summary) +@cindex x-face +@findex gnus-article-display-x-face +@findex gnus-article-x-face-command +@vindex gnus-article-x-face-command +@vindex gnus-article-x-face-too-ugly +@iftex +@iflatex +\include{xface} +@end iflatex +@end iftex +Look for and display any X-Face headers +(@code{gnus-article-display-x-face}). The command executed by this +function is given by the @code{gnus-article-x-face-command} variable. +If this variable is a string, this string will be executed in a +sub-shell. If it is a function, this function will be called with the +face as the argument. If the @code{gnus-article-x-face-too-ugly} (which +is a regexp) matches the @code{From} header, the face will not be shown. +The default action under Emacs is to fork off an @code{xv} to view the +face; under XEmacs the default action is to display the face before the +@code{From} header. (It's nicer if XEmacs has been compiled with X-Face +support---that will make display somewhat faster. If there's no native +X-Face support, Gnus will try to convert the @code{X-Face} header using +external programs from the @code{pbmplus} package and friends.) If you +want to have this function in the display hook, it should probably come +last. + +@item W b +@kindex W b (Summary) +@findex gnus-article-add-buttons +Add clickable buttons to the article (@code{gnus-article-add-buttons}). +@xref{Article Buttons} + +@item W B +@kindex W B (Summary) +@findex gnus-article-add-buttons-to-head +Add clickable buttons to the article headers +(@code{gnus-article-add-buttons-to-head}). + +@item W E l +@kindex W E l (Summary) +@findex gnus-article-strip-leading-blank-lines +Remove all blank lines from the beginning of the article +(@code{gnus-article-strip-leading-blank-lines}). + +@item W E m +@kindex W E m (Summary) +@findex gnus-article-strip-multiple-blank-lines +Replace all blank lines with empty lines and then all multiple empty +lines with a single empty line. +(@code{gnus-article-strip-multiple-blank-lines}). + +@item W E t +@kindex W E t (Summary) +@findex gnus-article-remove-trailing-blank-lines +Remove all blank lines at the end of the article +(@code{gnus-article-remove-trailing-blank-lines}). + +@item W E a +@kindex W E a (Summary) +@findex gnus-article-strip-blank-lines +Do all the three commands above +(@code{gnus-article-strip-blank-lines}). + +@item W E A +@kindex W E A (Summary) +@findex gnus-article-strip-all-blank-lines +Remove all blank lines +(@code{gnus-article-strip-all-blank-lines}). + +@item W E s +@kindex W E s (Summary) +@findex gnus-article-strip-leading-space +Remove all white space from the beginning of all lines of the article +body (@code{gnus-article-strip-leading-space}). + +@end table + +@xref{Customizing Articles} for how to wash articles automatically. + + +@node Article Buttons +@subsection Article Buttons +@cindex buttons + +People often include references to other stuff in articles, and it would +be nice if Gnus could just fetch whatever it is that people talk about +with the minimum of fuzz when you hit @kbd{RET} or use the middle mouse +button on these references. + +Gnus adds @dfn{buttons} to certain standard references by default: +Well-formed URLs, mail addresses and Message-IDs. This is controlled by +two variables, one that handles article bodies and one that handles +article heads: + +@table @code + +@item gnus-button-alist +@vindex gnus-button-alist +This is an alist where each entry has this form: + +@lisp +(REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR) +@end lisp + +@table @var + +@item regexp +All text that match this regular expression will be considered an +external reference. Here's a typical regexp that matches embedded URLs: +@samp{]*\\)>}. + +@item button-par +Gnus has to know which parts of the matches is to be highlighted. This +is a number that says what sub-expression of the regexp is to be +highlighted. If you want it all highlighted, you use 0 here. + +@item use-p +This form will be @code{eval}ed, and if the result is non-@code{nil}, +this is considered a match. This is useful if you want extra sifting to +avoid false matches. + +@item function +This function will be called when you click on this button. + +@item data-par +As with @var{button-par}, this is a sub-expression number, but this one +says which part of the match is to be sent as data to @var{function}. + +@end table + +So the full entry for buttonizing URLs is then + +@lisp +("]*\\)>" 0 t gnus-button-url 1) +@end lisp + +@item gnus-header-button-alist +@vindex gnus-header-button-alist +This is just like the other alist, except that it is applied to the +article head only, and that each entry has an additional element that is +used to say what headers to apply the buttonize coding to: + +@lisp +(HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR) +@end lisp + +@var{HEADER} is a regular expression. + +@item gnus-button-url-regexp +@vindex gnus-button-url-regexp +A regular expression that matches embedded URLs. It is used in the +default values of the variables above. + +@item gnus-article-button-face +@vindex gnus-article-button-face +Face used on buttons. + +@item gnus-article-mouse-face +@vindex gnus-article-mouse-face +Face used when the mouse cursor is over a button. + +@end table + +@xref{Customizing Articles} for how to buttonize articles automatically. + + +@node Article Date +@subsection Article Date + +The date is most likely generated in some obscure timezone you've never +heard of, so it's quite nice to be able to find out what the time was +when the article was sent. + +@table @kbd + +@item W T u +@kindex W T u (Summary) +@findex gnus-article-date-ut +Display the date in UT (aka. GMT, aka ZULU) +(@code{gnus-article-date-ut}). + +@item W T i +@kindex W T i (Summary) +@findex gnus-article-date-iso8601 +@cindex ISO 8601 +Display the date in international format, aka. ISO 8601 +(@code{gnus-article-date-iso8601}). + +@item W T l +@kindex W T l (Summary) +@findex gnus-article-date-local +Display the date in the local timezone (@code{gnus-article-date-local}). + +@item W T s +@kindex W T s (Summary) +@vindex gnus-article-time-format +@findex gnus-article-date-user +@findex format-time-string +Display the date using a user-defined format +(@code{gnus-article-date-user}). The format is specified by the +@code{gnus-article-time-format} variable, and is a string that's passed +to @code{format-time-string}. See the documentation of that variable +for a list of possible format specs. + +@item W T e +@kindex W T e (Summary) +@findex gnus-article-date-lapsed +@findex gnus-start-date-timer +@findex gnus-stop-date-timer +Say how much time has elapsed between the article was posted and now +(@code{gnus-article-date-lapsed}). If you want to have this line +updated continually, you can put + +@lisp +(gnus-start-date-timer) +@end lisp + +in your @file{.gnus.el} file, or you can run it off of some hook. If +you want to stop the timer, you can use the @code{gnus-stop-date-timer} +command. + +@item W T o +@kindex W T o (Summary) +@findex gnus-article-date-original +Display the original date (@code{gnus-article-date-original}). This can +be useful if you normally use some other conversion function and are +worried that it might be doing something totally wrong. Say, claiming +that the article was posted in 1854. Although something like that is +@emph{totally} impossible. Don't you trust me? *titter* + +@end table + +@xref{Customizing Articles} for how to display the date in your +preferred format automatically. + + +@node Article Signature +@subsection Article Signature +@cindex signatures +@cindex article signature + +@vindex gnus-signature-separator +Each article is divided into two parts---the head and the body. The +body can be divided into a signature part and a text part. The variable +that says what is to be considered a signature is +@code{gnus-signature-separator}. This is normally the standard +@samp{^-- $} as mandated by son-of-RFC 1036. However, many people use +non-standard signature separators, so this variable can also be a list +of regular expressions to be tested, one by one. (Searches are done +from the end of the body towards the beginning.) One likely value is: + +@lisp +(setq gnus-signature-separator + '("^-- $" ; The standard + "^-- *$" ; A common mangling + "^-------*$" ; Many people just use a looong + ; line of dashes. Shame! + "^ *--------*$" ; Double-shame! + "^________*$" ; Underscores are also popular + "^========*$")) ; Pervert! +@end lisp + +The more permissive you are, the more likely it is that you'll get false +positives. + +@vindex gnus-signature-limit +@code{gnus-signature-limit} provides a limit to what is considered a +signature. + +@enumerate +@item +If it is an integer, no signature may be longer (in characters) than +that integer. +@item +If it is a floating point number, no signature may be longer (in lines) +than that number. +@item +If it is a function, the function will be called without any parameters, +and if it returns @code{nil}, there is no signature in the buffer. +@item +If it is a string, it will be used as a regexp. If it matches, the text +in question is not a signature. +@end enumerate + +This variable can also be a list where the elements may be of the types +listed above. Here's an example: + +@lisp +(setq gnus-signature-limit + '(200.0 "^---*Forwarded article")) +@end lisp + +This means that if there are more than 200 lines after the signature +separator, or the text after the signature separator is matched by +the regular expression @samp{^---*Forwarded article}, then it isn't a +signature after all. + + +@node MIME Commands +@section MIME Commands +@cindex MIME decoding + +@table @kbd +@item W M w +@kindex W M w (Summary) +Decode RFC2047-encoded words in the article headers +(@code{gnus-article-decode-mime-words}). + +@item W M c +@kindex W M c (Summary) +Decode encoded article bodies as well as charsets +(@code{gnus-article-decode-charset}). + +This command looks in the @code{Content-Type} header to determine the +charset. If there is no such header in the article, you can give it a +prefix, which will prompt for the charset to decode as. In regional +groups where people post using some common encoding (but do not include +MIME headers), you can set the @code{charset} group/topic parameter to +the required charset (@pxref{Group Parameters}). + +@end table + + +@node Article Commands +@section Article Commands + +@table @kbd + +@item A P +@cindex PostScript +@cindex printing +@kindex A P (Summary) +@vindex gnus-ps-print-hook +@findex gnus-summary-print-article +Generate and print a PostScript image of the article buffer +(@code{gnus-summary-print-article}). @code{gnus-ps-print-hook} will be +run just before printing the buffer. + +@end table + + +@node Summary Sorting +@section Summary Sorting +@cindex summary sorting + +You can have the summary buffer sorted in various ways, even though I +can't really see why you'd want that. + +@table @kbd + +@item C-c C-s C-n +@kindex C-c C-s C-n (Summary) +@findex gnus-summary-sort-by-number +Sort by article number (@code{gnus-summary-sort-by-number}). + +@item C-c C-s C-a +@kindex C-c C-s C-a (Summary) +@findex gnus-summary-sort-by-author +Sort by author (@code{gnus-summary-sort-by-author}). + +@item C-c C-s C-s +@kindex C-c C-s C-s (Summary) +@findex gnus-summary-sort-by-subject +Sort by subject (@code{gnus-summary-sort-by-subject}). + +@item C-c C-s C-d +@kindex C-c C-s C-d (Summary) +@findex gnus-summary-sort-by-date +Sort by date (@code{gnus-summary-sort-by-date}). + +@item C-c C-s C-l +@kindex C-c C-s C-l (Summary) +@findex gnus-summary-sort-by-lines +Sort by lines (@code{gnus-summary-sort-by-lines}). + +@item C-c C-s C-i +@kindex C-c C-s C-i (Summary) +@findex gnus-summary-sort-by-score +Sort by score (@code{gnus-summary-sort-by-score}). +@end table + +These functions will work both when you use threading and when you don't +use threading. In the latter case, all summary lines will be sorted, +line by line. In the former case, sorting will be done on a +root-by-root basis, which might not be what you were looking for. To +toggle whether to use threading, type @kbd{T T} (@pxref{Thread +Commands}). + + +@node Finding the Parent +@section Finding the Parent +@cindex parent articles +@cindex referring articles + +@table @kbd +@item ^ +@kindex ^ (Summary) +@findex gnus-summary-refer-parent-article +If you'd like to read the parent of the current article, and it is not +displayed in the summary buffer, you might still be able to. That is, +if the current group is fetched by @sc{nntp}, the parent hasn't expired +and the @code{References} in the current article are not mangled, you +can just press @kbd{^} or @kbd{A r} +(@code{gnus-summary-refer-parent-article}). If everything goes well, +you'll get the parent. If the parent is already displayed in the +summary buffer, point will just move to this article. + +If given a positive numerical prefix, fetch that many articles back into +the ancestry. If given a negative numerical prefix, fetch just that +ancestor. So if you say @kbd{3 ^}, gnus will fetch the parent, the +grandparent and the grandgrandparent of the current article. If you say +@kbd{-3 ^}, gnus will only fetch the grandgrandparent of the current +article. + +@item A R (Summary) +@findex gnus-summary-refer-references +@kindex A R (Summary) +Fetch all articles mentioned in the @code{References} header of the +article (@code{gnus-summary-refer-references}). + +@item A T (Summary) +@findex gnus-summary-refer-thread +@kindex A T (Summary) +Display the full thread where the current article appears +(@code{gnus-summary-refer-thread}). This command has to fetch all the +headers in the current group to work, so it usually takes a while. If +you do it often, you may consider setting @code{gnus-fetch-old-headers} +to @code{invisible} (@pxref{Filling In Threads}). This won't have any +visible effects normally, but it'll make this command work a whole lot +faster. Of course, it'll make group entry somewhat slow. + +@vindex gnus-refer-thread-limit +The @code{gnus-refer-thread-limit} variable says how many old (i. e., +articles before the first displayed in the current group) headers to +fetch when doing this command. The default is 200. If @code{t}, all +the available headers will be fetched. This variable can be overridden +by giving the @kbd{A T} command a numerical prefix. + +@item M-^ (Summary) +@findex gnus-summary-refer-article +@kindex M-^ (Summary) +@cindex Message-ID +@cindex fetching by Message-ID +You can also ask the @sc{nntp} server for an arbitrary article, no +matter what group it belongs to. @kbd{M-^} +(@code{gnus-summary-refer-article}) will ask you for a +@code{Message-ID}, which is one of those long, hard-to-read thingies +that look something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You +have to get it all exactly right. No fuzzy searches, I'm afraid. +@end table + +The current select method will be used when fetching by +@code{Message-ID} from non-news select method, but you can override this +by giving this command a prefix. + +@vindex gnus-refer-article-method +If the group you are reading is located on a backend that does not +support fetching by @code{Message-ID} very well (like @code{nnspool}), +you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It +would, perhaps, be best if the @sc{nntp} server you consult is the one +updating the spool you are reading from, but that's not really +necessary. + +Most of the mail backends support fetching by @code{Message-ID}, but do +not do a particularly excellent job at it. That is, @code{nnmbox} and +@code{nnbabyl} are able to locate articles from any groups, while +@code{nnml} and @code{nnfolder} are only able to locate articles that +have been posted to the current group. (Anything else would be too time +consuming.) @code{nnmh} does not support this at all. + + +@node Alternative Approaches +@section Alternative Approaches + +Different people like to read news using different methods. This being +gnus, we offer a small selection of minor modes for the summary buffers. + +@menu +* Pick and Read:: First mark articles and then read them. +* Binary Groups:: Auto-decode all articles. +@end menu + + +@node Pick and Read +@subsection Pick and Read +@cindex pick and read + +Some newsreaders (like @code{nn} and, uhm, @code{Netnews} on VM/CMS) use +a two-phased reading interface. The user first marks in a summary +buffer the articles she wants to read. Then she starts reading the +articles with just an article buffer displayed. + +@findex gnus-pick-mode +@kindex M-x gnus-pick-mode +Gnus provides a summary buffer minor mode that allows +this---@code{gnus-pick-mode}. This basically means that a few process +mark commands become one-keystroke commands to allow easy marking, and +it provides one additional command for switching to the summary buffer. + +Here are the available keystrokes when using pick mode: + +@table @kbd +@item . +@kindex . (Pick) +@findex gnus-pick-article-or-thread +Pick the article or thread on the current line +(@code{gnus-pick-article-or-thread}). If the variable +@code{gnus-thread-hide-subtree} is true, then this key selects the +entire thread when used at the first article of the thread. Otherwise, +it selects just the article. If given a numerical prefix, go to that +thread or article and pick it. (The line number is normally displayed +at the beginning of the summary pick lines.) + +@item SPACE +@kindex SPACE (Pick) +@findex gnus-pick-next-page +Scroll the summary buffer up one page (@code{gnus-pick-next-page}). If +at the end of the buffer, start reading the picked articles. + +@item u +@kindex u (Pick) +@findex gnus-pick-unmark-article-or-thread. +Unpick the thread or article +(@code{gnus-pick-unmark-article-or-thread}). If the variable +@code{gnus-thread-hide-subtree} is true, then this key unpicks the +thread if used at the first article of the thread. Otherwise it unpicks +just the article. You can give this key a numerical prefix to unpick +the thread or article at that line. + +@item RET +@kindex RET (Pick) +@findex gnus-pick-start-reading +@vindex gnus-pick-display-summary +Start reading the picked articles (@code{gnus-pick-start-reading}). If +given a prefix, mark all unpicked articles as read first. If +@code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer +will still be visible when you are reading. + +@end table + +All the normal summary mode commands are still available in the +pick-mode, with the exception of @kbd{u}. However @kbd{!} is available +which is mapped to the same function +@code{gnus-summary-tick-article-forward}. + +If this sounds like a good idea to you, you could say: + +@lisp +(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) +@end lisp + +@vindex gnus-pick-mode-hook +@code{gnus-pick-mode-hook} is run in pick minor mode buffers. + +@vindex gnus-mark-unpicked-articles-as-read +If @code{gnus-mark-unpicked-articles-as-read} is non-@code{nil}, mark +all unpicked articles as read. The default is @code{nil}. + +@vindex gnus-summary-pick-line-format +The summary line format in pick mode is slightly different from the +standard format. At the beginning of each line the line number is +displayed. The pick mode line format is controlled by the +@code{gnus-summary-pick-line-format} variable (@pxref{Formatting +Variables}). It accepts the same format specs that +@code{gnus-summary-line-format} does (@pxref{Summary Buffer Lines}). + + +@node Binary Groups +@subsection Binary Groups +@cindex binary groups + +@findex gnus-binary-mode +@kindex M-x gnus-binary-mode +If you spend much time in binary groups, you may grow tired of hitting +@kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode} +is a minor mode for summary buffers that makes all ordinary Gnus article +selection functions uudecode series of articles and display the result +instead of just displaying the articles the normal way. + +@kindex g (Binary) +@findex gnus-binary-show-article +The only way, in fact, to see the actual articles is the @kbd{g} +command, when you have turned on this mode +(@code{gnus-binary-show-article}). + +@vindex gnus-binary-mode-hook +@code{gnus-binary-mode-hook} is called in binary minor mode buffers. + + +@node Tree Display +@section Tree Display +@cindex trees + +@vindex gnus-use-trees +If you don't like the normal gnus summary display, you might try setting +@code{gnus-use-trees} to @code{t}. This will create (by default) an +additional @dfn{tree buffer}. You can execute all summary mode commands +in the tree buffer. + +There are a few variables to customize the tree display, of course: + +@table @code +@item gnus-tree-mode-hook +@vindex gnus-tree-mode-hook +A hook called in all tree mode buffers. + +@item gnus-tree-mode-line-format +@vindex gnus-tree-mode-line-format +A format string for the mode bar in the tree mode buffers (@pxref{Mode +Line Formatting}). The default is @samp{Gnus: %%b %S %Z}. For a list +of valid specs, @pxref{Summary Buffer Mode Line}. + +@item gnus-selected-tree-face +@vindex gnus-selected-tree-face +Face used for highlighting the selected article in the tree buffer. The +default is @code{modeline}. + +@item gnus-tree-line-format +@vindex gnus-tree-line-format +A format string for the tree nodes. The name is a bit of a misnomer, +though---it doesn't define a line, but just the node. The default value +is @samp{%(%[%3,3n%]%)}, which displays the first three characters of +the name of the poster. It is vital that all nodes are of the same +length, so you @emph{must} use @samp{%4,4n}-like specifiers. + +Valid specs are: + +@table @samp +@item n +The name of the poster. +@item f +The @code{From} header. +@item N +The number of the article. +@item [ +The opening bracket. +@item ] +The closing bracket. +@item s +The subject. +@end table + +@xref{Formatting Variables}. + +Variables related to the display are: + +@table @code +@item gnus-tree-brackets +@vindex gnus-tree-brackets +This is used for differentiating between ``real'' articles and +``sparse'' articles. The format is @var{((real-open . real-close) +(sparse-open . sparse-close) (dummy-open . dummy-close))}, and the +default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}) (?< . ?>))}. + +@item gnus-tree-parent-child-edges +@vindex gnus-tree-parent-child-edges +This is a list that contains the characters used for connecting parent +nodes to their children. The default is @code{(?- ?\\ ?|)}. + +@end table + +@item gnus-tree-minimize-window +@vindex gnus-tree-minimize-window +If this variable is non-@code{nil}, gnus will try to keep the tree +buffer as small as possible to allow more room for the other gnus +windows. If this variable is a number, the tree buffer will never be +higher than that number. The default is @code{t}. Note that if you +have several windows displayed side-by-side in a frame and the tree +buffer is one of these, minimizing the tree window will also resize all +other windows displayed next to it. + +@item gnus-generate-tree-function +@vindex gnus-generate-tree-function +@findex gnus-generate-horizontal-tree +@findex gnus-generate-vertical-tree +The function that actually generates the thread tree. Two predefined +functions are available: @code{gnus-generate-horizontal-tree} and +@code{gnus-generate-vertical-tree} (which is the default). + +@end table + +Here's an example from a horizontal tree buffer: + +@example +@{***@}-(***)-[odd]-[Gun] + | \[Jan] + | \[odd]-[Eri] + | \(***)-[Eri] + | \[odd]-[Paa] + \[Bjo] + \[Gun] + \[Gun]-[Jor] +@end example + +Here's the same thread displayed in a vertical tree buffer: + +@example +@{***@} + |--------------------------\-----\-----\ +(***) [Bjo] [Gun] [Gun] + |--\-----\-----\ | +[odd] [Jan] [odd] (***) [Jor] + | | |--\ +[Gun] [Eri] [Eri] [odd] + | + [Paa] +@end example + +If you're using horizontal trees, it might be nice to display the trees +side-by-side with the summary buffer. You could add something like the +following to your @file{.gnus.el} file: + +@lisp +(setq gnus-use-trees t + gnus-generate-tree-function 'gnus-generate-horizontal-tree + gnus-tree-minimize-window nil) +(gnus-add-configuration + '(article + (vertical 1.0 + (horizontal 0.25 + (summary 0.75 point) + (tree 1.0)) + (article 1.0)))) +@end lisp + +@xref{Windows Configuration}. + + +@node Mail Group Commands +@section Mail Group Commands +@cindex mail group commands + +Some commands only make sense in mail groups. If these commands are +invalid in the current group, they will raise a hell and let you know. + +All these commands (except the expiry and edit commands) use the +process/prefix convention (@pxref{Process/Prefix}). + +@table @kbd + +@item B e +@kindex B e (Summary) +@findex gnus-summary-expire-articles +Expire all expirable articles in the group +(@code{gnus-summary-expire-articles}). + +@item B M-C-e +@kindex B M-C-e (Summary) +@findex gnus-summary-expire-articles-now +Delete all the expirable articles in the group +(@code{gnus-summary-expire-articles-now}). This means that @strong{all} +articles eligible for expiry in the current group will +disappear forever into that big @file{/dev/null} in the sky. + +@item B DEL +@kindex B DEL (Summary) +@findex gnus-summary-delete-article +@c @icon{gnus-summary-mail-delete} +Delete the mail article. This is ``delete'' as in ``delete it from your +disk forever and ever, never to return again.'' Use with caution. +(@code{gnus-summary-delete-article}). + +@item B m +@kindex B m (Summary) +@cindex move mail +@findex gnus-summary-move-article +Move the article from one mail group to another +(@code{gnus-summary-move-article}). + +@item B c +@kindex B c (Summary) +@cindex copy mail +@findex gnus-summary-copy-article +@c @icon{gnus-summary-mail-copy} +Copy the article from one group (mail group or not) to a mail group +(@code{gnus-summary-copy-article}). + +@item B B +@kindex B B (Summary) +@cindex crosspost mail +@findex gnus-summary-crosspost-article +Crosspost the current article to some other group +(@code{gnus-summary-crosspost-article}). This will create a new copy of +the article in the other group, and the Xref headers of the article will +be properly updated. + +@item B i +@kindex B i (Summary) +@findex gnus-summary-import-article +Import an arbitrary file into the current mail newsgroup +(@code{gnus-summary-import-article}). You will be prompted for a file +name, a @code{From} header and a @code{Subject} header. + +@item B r +@kindex B r (Summary) +@findex gnus-summary-respool-article +Respool the mail article (@code{gnus-summary-respool-article}). +@code{gnus-summary-respool-default-method} will be used as the default +select method when respooling. This variable is @code{nil} by default, +which means that the current group select method will be used instead. + +@item B w +@itemx e +@kindex B w (Summary) +@kindex e (Summary) +@findex gnus-summary-edit-article +@kindex C-c C-c (Article) +Edit the current article (@code{gnus-summary-edit-article}). To finish +editing and make the changes permanent, type @kbd{C-c C-c} +(@kbd{gnus-summary-edit-article-done}). If you give a prefix to the +@kbd{C-c C-c} command, gnus won't re-highlight the article. + +@item B q +@kindex B q (Summary) +@findex gnus-summary-respool-query +If you want to re-spool an article, you might be curious as to what group +the article will end up in before you do the re-spooling. This command +will tell you (@code{gnus-summary-respool-query}). + +@item B t +@kindex B t (Summary) +@findex gnus-summary-respool-trace +Similarly, this command will display all fancy splitting patterns used +when repooling, if any (@code{gnus-summary-respool-trace}). + +@item B p +@kindex B p (Summary) +@findex gnus-summary-article-posted-p +Some people have a tendency to send you "courtesy" copies when they +follow up to articles you have posted. These usually have a +@code{Newsgroups} header in them, but not always. This command +(@code{gnus-summary-article-posted-p}) will try to fetch the current +article from your news server (or rather, from +@code{gnus-refer-article-method} or @code{gnus-select-method}) and will +report back whether it found the article or not. Even if it says that +it didn't find the article, it may have been posted anyway---mail +propagation is much faster than news propagation, and the news copy may +just not have arrived yet. + +@end table + +@vindex gnus-move-split-methods +@cindex moving articles +If you move (or copy) articles regularly, you might wish to have gnus +suggest where to put the articles. @code{gnus-move-split-methods} is a +variable that uses the same syntax as @code{gnus-split-methods} +(@pxref{Saving Articles}). You may customize that variable to create +suggestions you find reasonable. + +@lisp +(setq gnus-move-split-methods + '(("^From:.*Lars Magne" "nnml:junk") + ("^Subject:.*gnus" "nnfolder:important") + (".*" "nnml:misc"))) +@end lisp + + +@node Various Summary Stuff +@section Various Summary Stuff + +@menu +* Summary Group Information:: Information oriented commands. +* Searching for Articles:: Multiple article commands. +* Summary Generation Commands:: (Re)generating the summary buffer. +* Really Various Summary Commands:: Those pesky non-conformant commands. +@end menu + +@table @code +@vindex gnus-summary-mode-hook +@item gnus-summary-mode-hook +This hook is called when creating a summary mode buffer. + +@vindex gnus-summary-generate-hook +@item gnus-summary-generate-hook +This is called as the last thing before doing the threading and the +generation of the summary buffer. It's quite convenient for customizing +the threading variables based on what data the newsgroup has. This hook +is called from the summary buffer after most summary buffer variables +have been set. + +@vindex gnus-summary-prepare-hook +@item gnus-summary-prepare-hook +It is called after the summary buffer has been generated. You might use +it to, for instance, highlight lines or modify the look of the buffer in +some other ungodly manner. I don't care. + +@vindex gnus-summary-prepared-hook +@item gnus-summary-prepared-hook +A hook called as the very last thing after the summary buffer has been +generated. + +@vindex gnus-summary-ignore-duplicates +@item gnus-summary-ignore-duplicates +When gnus discovers two articles that have the same @code{Message-ID}, +it has to do something drastic. No articles are allowed to have the +same @code{Message-ID}, but this may happen when reading mail from some +sources. Gnus allows you to customize what happens with this variable. +If it is @code{nil} (which is the default), gnus will rename the +@code{Message-ID} (for display purposes only) and display the article as +any other article. If this variable is @code{t}, it won't display the +article---it'll be as if it never existed. + +@end table + + +@node Summary Group Information +@subsection Summary Group Information + +@table @kbd + +@item H f +@kindex H f (Summary) +@findex gnus-summary-fetch-faq +@vindex gnus-group-faq-directory +Try to fetch the FAQ (list of frequently asked questions) for the +current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the +FAQ from @code{gnus-group-faq-directory}, which is usually a directory +on a remote machine. This variable can also be a list of directories. +In that case, giving a prefix to this command will allow you to choose +between the various sites. @code{ange-ftp} or @code{efs} will probably +be used for fetching the file. + +@item H d +@kindex H d (Summary) +@findex gnus-summary-describe-group +Give a brief description of the current group +(@code{gnus-summary-describe-group}). If given a prefix, force +rereading the description from the server. + +@item H h +@kindex H h (Summary) +@findex gnus-summary-describe-briefly +Give an extremely brief description of the most important summary +keystrokes (@code{gnus-summary-describe-briefly}). + +@item H i +@kindex H i (Summary) +@findex gnus-info-find-node +Go to the gnus info node (@code{gnus-info-find-node}). +@end table + + +@node Searching for Articles +@subsection Searching for Articles + +@table @kbd + +@item M-s +@kindex M-s (Summary) +@findex gnus-summary-search-article-forward +Search through all subsequent articles for a regexp +(@code{gnus-summary-search-article-forward}). + +@item M-r +@kindex M-r (Summary) +@findex gnus-summary-search-article-backward +Search through all previous articles for a regexp +(@code{gnus-summary-search-article-backward}). + +@item & +@kindex & (Summary) +@findex gnus-summary-execute-command +This command will prompt you for a header field, a regular expression to +match on this field, and a command to be executed if the match is made +(@code{gnus-summary-execute-command}). If given a prefix, search +backward instead. + +@item M-& +@kindex M-& (Summary) +@findex gnus-summary-universal-argument +Perform any operation on all articles that have been marked with +the process mark (@code{gnus-summary-universal-argument}). +@end table + +@node Summary Generation Commands +@subsection Summary Generation Commands + +@table @kbd + +@item Y g +@kindex Y g (Summary) +@findex gnus-summary-prepare +Regenerate the current summary buffer (@code{gnus-summary-prepare}). + +@item Y c +@kindex Y c (Summary) +@findex gnus-summary-insert-cached-articles +Pull all cached articles (for the current group) into the summary buffer +(@code{gnus-summary-insert-cached-articles}). + +@end table + + +@node Really Various Summary Commands +@subsection Really Various Summary Commands + +@table @kbd + +@item C-d +@kindex C-d (Summary) +@findex gnus-summary-enter-digest-group +If the current article is a collection of other articles (for instance, +a digest), you might use this command to enter a group based on the that +article (@code{gnus-summary-enter-digest-group}). Gnus will try to +guess what article type is currently displayed unless you give a prefix +to this command, which forces a ``digest'' interpretation. Basically, +whenever you see a message that is a collection of other messages of +some format, you @kbd{C-d} and read these messages in a more convenient +fashion. + +@item M-C-d +@kindex M-C-d (Summary) +@findex gnus-summary-read-document +This command is very similar to the one above, but lets you gather +several documents into one biiig group +(@code{gnus-summary-read-document}). It does this by opening several +@code{nndoc} groups for each document, and then opening an +@code{nnvirtual} group on top of these @code{nndoc} groups. This +command understands the process/prefix convention +(@pxref{Process/Prefix}). + +@item C-t +@kindex C-t (Summary) +@findex gnus-summary-toggle-truncation +Toggle truncation of summary lines +(@code{gnus-summary-toggle-truncation}). This will probably confuse the +line centering function in the summary buffer, so it's not a good idea +to have truncation switched off while reading articles. + +@item = +@kindex = (Summary) +@findex gnus-summary-expand-window +Expand the summary buffer window (@code{gnus-summary-expand-window}). +If given a prefix, force an @code{article} window configuration. + +@item M-C-e +@kindex M-C-e (Summary) +@findex gnus-summary-edit-parameters +Edit the group parameters (@pxref{Group Parameters}) of the current +group (@code{gnus-summary-edit-parameters}). + +@end table + + +@node Exiting the Summary Buffer +@section Exiting the Summary Buffer +@cindex summary exit +@cindex exiting groups + +Exiting from the summary buffer will normally update all info on the +group and return you to the group buffer. + +@table @kbd + +@item Z Z +@itemx q +@kindex Z Z (Summary) +@kindex q (Summary) +@findex gnus-summary-exit +@vindex gnus-summary-exit-hook +@vindex gnus-summary-prepare-exit-hook +@c @icon{gnus-summary-exit} +Exit the current group and update all information on the group +(@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is +called before doing much of the exiting, which calls +@code{gnus-summary-expire-articles} by default. +@code{gnus-summary-exit-hook} is called after finishing the exit +process. @code{gnus-group-no-more-groups-hook} is run when returning to +group mode having no more (unread) groups. + +@item Z E +@itemx Q +@kindex Z E (Summary) +@kindex Q (Summary) +@findex gnus-summary-exit-no-update +Exit the current group without updating any information on the group +(@code{gnus-summary-exit-no-update}). + +@item Z c +@itemx c +@kindex Z c (Summary) +@kindex c (Summary) +@findex gnus-summary-catchup-and-exit +@c @icon{gnus-summary-catchup-and-exit} +Mark all unticked articles in the group as read and then exit +(@code{gnus-summary-catchup-and-exit}). + +@item Z C +@kindex Z C (Summary) +@findex gnus-summary-catchup-all-and-exit +Mark all articles, even the ticked ones, as read and then exit +(@code{gnus-summary-catchup-all-and-exit}). + +@item Z n +@kindex Z n (Summary) +@findex gnus-summary-catchup-and-goto-next-group +Mark all articles as read and go to the next group +(@code{gnus-summary-catchup-and-goto-next-group}). + +@item Z R +@kindex Z R (Summary) +@findex gnus-summary-reselect-current-group +Exit this group, and then enter it again +(@code{gnus-summary-reselect-current-group}). If given a prefix, select +all articles, both read and unread. + +@item Z G +@itemx M-g +@kindex Z G (Summary) +@kindex M-g (Summary) +@findex gnus-summary-rescan-group +@c @icon{gnus-summary-mail-get} +Exit the group, check for new articles in the group, and select the +group (@code{gnus-summary-rescan-group}). If given a prefix, select all +articles, both read and unread. + +@item Z N +@kindex Z N (Summary) +@findex gnus-summary-next-group +Exit the group and go to the next group +(@code{gnus-summary-next-group}). + +@item Z P +@kindex Z P (Summary) +@findex gnus-summary-prev-group +Exit the group and go to the previous group +(@code{gnus-summary-prev-group}). + +@item Z s +@kindex Z s (Summary) +@findex gnus-summary-save-newsrc +Save the current number of read/marked articles in the dribble buffer +and then save the dribble buffer (@code{gnus-summary-save-newsrc}). If +given a prefix, also save the @file{.newsrc} file(s). Using this +command will make exit without updating (the @kbd{Q} command) worthless. +@end table + +@vindex gnus-exit-group-hook +@code{gnus-exit-group-hook} is called when you exit the current +group. + +@findex gnus-summary-wake-up-the-dead +@findex gnus-dead-summary-mode +@vindex gnus-kill-summary-on-exit +If you're in the habit of exiting groups, and then changing your mind +about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}. +If you do that, gnus won't kill the summary buffer when you exit it. +(Quelle surprise!) Instead it will change the name of the buffer to +something like @samp{*Dead Summary ... *} and install a minor mode +called @code{gnus-dead-summary-mode}. Now, if you switch back to this +buffer, you'll find that all keys are mapped to a function called +@code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead +summary buffer will result in a live, normal summary buffer. + +There will never be more than one dead summary buffer at any one time. + +@vindex gnus-use-cross-reference +The data on the current group will be updated (which articles you have +read, which articles you have replied to, etc.) when you exit the +summary buffer. If the @code{gnus-use-cross-reference} variable is +@code{t} (which is the default), articles that are cross-referenced to +this group and are marked as read, will also be marked as read in the +other subscribed groups they were cross-posted to. If this variable is +neither @code{nil} nor @code{t}, the article will be marked as read in +both subscribed and unsubscribed groups (@pxref{Crosspost Handling}). + + +@node Crosspost Handling +@section Crosspost Handling + +@cindex velveeta +@cindex spamming +Marking cross-posted articles as read ensures that you'll never have to +read the same article more than once. Unless, of course, somebody has +posted it to several groups separately. Posting the same article to +several groups (not cross-posting) is called @dfn{spamming}, and you are +by law required to send nasty-grams to anyone who perpetrates such a +heinous crime. You may want to try NoCeM handling to filter out spam +(@pxref{NoCeM}). + +Remember: Cross-posting is kinda ok, but posting the same article +separately to several groups is not. Massive cross-posting (aka. +@dfn{velveeta}) is to be avoided at all costs, and you can even use the +@code{gnus-summary-mail-crosspost-complaint} command to complain about +excessive crossposting (@pxref{Summary Mail Commands}). + +@cindex cross-posting +@cindex Xref +@cindex @sc{nov} +One thing that may cause Gnus to not do the cross-posting thing +correctly is if you use an @sc{nntp} server that supports @sc{xover} +(which is very nice, because it speeds things up considerably) which +does not include the @code{Xref} header in its @sc{nov} lines. This is +Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing +even with @sc{xover} by registering the @code{Xref} lines of all +articles you actually read, but if you kill the articles, or just mark +them as read without reading them, Gnus will not get a chance to snoop +the @code{Xref} lines out of these articles, and will be unable to use +the cross reference mechanism. + +@cindex LIST overview.fmt +@cindex overview.fmt +To check whether your @sc{nntp} server includes the @code{Xref} header +in its overview files, try @samp{telnet your.nntp.server nntp}, +@samp{MODE READER} on @code{inn} servers, and then say @samp{LIST +overview.fmt}. This may not work, but if it does, and the last line you +get does not read @samp{Xref:full}, then you should shout and whine at +your news admin until she includes the @code{Xref} header in the +overview files. + +@vindex gnus-nov-is-evil +If you want Gnus to get the @code{Xref}s right all the time, you have to +set @code{gnus-nov-is-evil} to @code{t}, which slows things down +considerably. + +C'est la vie. + +For an alternative approach, @pxref{Duplicate Suppression}. + + +@node Duplicate Suppression +@section Duplicate Suppression + +By default, gnus tries to make sure that you don't have to read the same +article more than once by utilizing the crossposting mechanism +(@pxref{Crosspost Handling}). However, that simple and efficient +approach may not work satisfactory for some users for various reasons. + +@enumerate +@item +The @sc{nntp} server may fail to generate the @code{Xref} header. This +is evil and not very common. + +@item +The @sc{nntp} server may fail to include the @code{Xref} header in the +@file{.overview} data bases. This is evil and all too common, alas. + +@item +You may be reading the same group (or several related groups) from +different @sc{nntp} servers. + +@item +You may be getting mail that duplicates articles posted to groups. +@end enumerate + +I'm sure there are other situations where @code{Xref} handling fails as +well, but these four are the most common situations. + +If, and only if, @code{Xref} handling fails for you, then you may +consider switching on @dfn{duplicate suppression}. If you do so, Gnus +will remember the @code{Message-ID}s of all articles you have read or +otherwise marked as read, and then, as if by magic, mark them as read +all subsequent times you see them---in @emph{all} groups. Using this +mechanism is quite likely to be somewhat inefficient, but not overly +so. It's certainly preferable to reading the same articles more than +once. + +Duplicate suppression is not a very subtle instrument. It's more like a +sledge hammer than anything else. It works in a very simple +fashion---if you have marked an article as read, it adds this Message-ID +to a cache. The next time it sees this Message-ID, it will mark the +article as read with the @samp{M} mark. It doesn't care what group it +saw the article in. + +@table @code +@item gnus-suppress-duplicates +@vindex gnus-suppress-duplicates +If non-@code{nil}, suppress duplicates. + +@item gnus-save-duplicate-list +@vindex gnus-save-duplicate-list +If non-@code{nil}, save the list of duplicates to a file. This will +make startup and shutdown take longer, so the default is @code{nil}. +However, this means that only duplicate articles read in a single gnus +session are suppressed. + +@item gnus-duplicate-list-length +@vindex gnus-duplicate-list-length +This variable says how many @code{Message-ID}s to keep in the duplicate +suppression list. The default is 10000. + +@item gnus-duplicate-file +@vindex gnus-duplicate-file +The name of the file to store the duplicate suppression list in. The +default is @file{~/News/suppression}. +@end table + +If you have a tendency to stop and start gnus often, setting +@code{gnus-save-duplicate-list} to @code{t} is probably a good idea. If +you leave gnus running for weeks on end, you may have it @code{nil}. On +the other hand, saving the list makes startup and shutdown much slower, +so that means that if you stop and start gnus often, you should set +@code{gnus-save-duplicate-list} to @code{nil}. Uhm. I'll leave this up +to you to figure out, I think. + + +@node The Article Buffer +@chapter The Article Buffer +@cindex article buffer + +The articles are displayed in the article buffer, of which there is only +one. All the summary buffers share the same article buffer unless you +tell gnus otherwise. + +@menu +* Hiding Headers:: Deciding what headers should be displayed. +* Using MIME:: Pushing to mime articles as @sc{mime} messages. +* Customizing Articles:: Tailoring the look of the articles. +* Article Keymap:: Keystrokes available in the article buffer. +* Misc Article:: Other stuff. +@end menu + + +@node Hiding Headers +@section Hiding Headers +@cindex hiding headers +@cindex deleting headers + +The top section of each article is the @dfn{head}. (The rest is the +@dfn{body}, but you may have guessed that already.) + +@vindex gnus-show-all-headers +There is a lot of useful information in the head: the name of the person +who wrote the article, the date it was written and the subject of the +article. That's well and nice, but there's also lots of information +most people do not want to see---what systems the article has passed +through before reaching you, the @code{Message-ID}, the +@code{References}, etc. ad nauseum---and you'll probably want to get rid +of some of those lines. If you want to keep all those lines in the +article buffer, you can set @code{gnus-show-all-headers} to @code{t}. + +Gnus provides you with two variables for sifting headers: + +@table @code + +@item gnus-visible-headers +@vindex gnus-visible-headers +If this variable is non-@code{nil}, it should be a regular expression +that says what headers you wish to keep in the article buffer. All +headers that do not match this variable will be hidden. + +For instance, if you only want to see the name of the person who wrote +the article and the subject, you'd say: + +@lisp +(setq gnus-visible-headers "^From:\\|^Subject:") +@end lisp + +This variable can also be a list of regexps to match headers to +remain visible. + +@item gnus-ignored-headers +@vindex gnus-ignored-headers +This variable is the reverse of @code{gnus-visible-headers}. If this +variable is set (and @code{gnus-visible-headers} is @code{nil}), it +should be a regular expression that matches all lines that you want to +hide. All lines that do not match this variable will remain visible. + +For instance, if you just want to get rid of the @code{References} field +and the @code{Xref} field, you might say: + +@lisp +(setq gnus-ignored-headers "^References:\\|^Xref:") +@end lisp + +This variable can also be a list of regexps to match headers to +be removed. + +Note that if @code{gnus-visible-headers} is non-@code{nil}, this +variable will have no effect. + +@end table + +@vindex gnus-sorted-header-list +Gnus can also sort the headers for you. (It does this by default.) You +can control the sorting by setting the @code{gnus-sorted-header-list} +variable. It is a list of regular expressions that says in what order +the headers are to be displayed. + +For instance, if you want the name of the author of the article first, +and then the subject, you might say something like: + +@lisp +(setq gnus-sorted-header-list '("^From:" "^Subject:")) +@end lisp + +Any headers that are to remain visible, but are not listed in this +variable, will be displayed in random order after all the headers listed +in this variable. + +@findex gnus-article-hide-boring-headers +@vindex gnus-article-display-hook +@vindex gnus-boring-article-headers +You can hide further boring headers by entering +@code{gnus-article-hide-boring-headers} into +@code{gnus-article-display-hook}. What this function does depends on +the @code{gnus-boring-article-headers} variable. It's a list, but this +list doesn't actually contain header names. Instead is lists various +@dfn{boring conditions} that gnus can check and remove from sight. + +These conditions are: +@table @code +@item empty +Remove all empty headers. +@item followup-to +Remove the @code{Followup-To} header if it is identical to the +@code{Newsgroups} header. +@item reply-to +Remove the @code{Reply-To} header if it lists the same address as the +@code{From} header. +@item newsgroups +Remove the @code{Newsgroups} header if it only contains the current group +name. +@item date +Remove the @code{Date} header if the article is less than three days +old. +@item long-to +Remove the @code{To} header if it is very long. +@item many-to +Remove all @code{To} headers if there are more than one. +@end table + +To include the four three elements, you could say something like; + +@lisp +(setq gnus-boring-article-headers + '(empty followup-to reply-to)) +@end lisp + +This is also the default value for this variable. + + +@node Using MIME +@section Using @sc{mime} +@cindex @sc{mime} + +Mime is a standard for waving your hands through the air, aimlessly, +while people stand around yawning. + +@sc{mime}, however, is a standard for encoding your articles, aimlessly, +while all newsreaders die of fear. + +@sc{mime} may specify what character set the article uses, the encoding +of the characters, and it also makes it possible to embed pictures and +other naughty stuff in innocent-looking articles. + +@vindex gnus-show-mime +@vindex gnus-article-display-method-for-mime +@vindex gnus-strict-mime +@findex gnus-article-display-mime-message +Gnus handles @sc{mime} by pushing the articles through +@code{gnus-article-display-method-for-mime}, which is +@code{gnus-article-display-mime-message} by default. This function +calls the SEMI MIME-View program to actually do the work. For more +information on SEMI MIME-View, see its manual page (however it is not +existed yet, sorry). + +Set @code{gnus-show-mime} to @code{t} if you want to use +@sc{mime} all the time. However, if @code{gnus-strict-mime} is +non-@code{nil}, the @sc{mime} method will only be used if there are +@sc{mime} headers in the article. If you have @code{gnus-show-mime} +set, then you'll see some unfortunate display glitches in the article +buffer. These can't be avoided. + +In GNUS or Gnus, it might be best to just use the toggling functions +from the summary buffer to avoid getting nasty surprises. (For instance, +you enter the group @samp{alt.sing-a-long} and, before you know it, +@sc{mime} has decoded the sound file in the article and some horrible +sing-a-long song comes screaming out your speakers, and you can't find +the volume button, because there isn't one, and people are starting to +look at you, and you try to stop the program, but you can't, and you +can't find the program to control the volume, and everybody else in the +room suddenly decides to look at you disdainfully, and you'll feel +rather stupid.) + +Any similarity to real events and people is purely coincidental. Ahem. + +To avoid such kind of situation, gnus stops to use +@code{metamail-buffer}. So now, you can set @code{gnus-show-mime} to +non-@code{nil} every-time, then you can push button in the article +buffer when there are nobody else. + + +@node Customizing Articles +@section Customizing Articles +@cindex article customization + +@vindex gnus-article-display-hook +The @code{gnus-article-display-hook} is called after the article has +been inserted into the article buffer. It is meant to handle all +treatment of the article before it is displayed. + +@findex gnus-article-maybe-highlight +@findex gnus-article-maybe-hide-headers +By default this hook just contains +@code{gnus-article-maybe-hide-headers}, +@code{gnus-hide-boring-headers}, @code{gnus-article-treat-overstrike}, +and @code{gnus-article-maybe-highlight} (and under XEmacs, +@code{gnus-article-display-x-face}), but there are thousands, nay +millions, of functions you can put in this hook. For an overview of +functions @pxref{Article Highlighting}, @pxref{Article Hiding}, +@pxref{Article Washing}, @pxref{Article Buttons} and @pxref{Article +Date}. Note that the order of functions in this hook might affect +things, so you may have to fiddle a bit to get the desired results. + +You can, of course, write your own functions. The functions are called +from the article buffer, and you can do anything you like, pretty much. +There is no information that you have to keep in the buffer---you can +change everything. However, you shouldn't delete any headers. Instead +make them invisible if you want to make them go away. + + +@node Article Keymap +@section Article Keymap + +Most of the keystrokes in the summary buffer can also be used in the +article buffer. They should behave as if you typed them in the summary +buffer, which means that you don't actually have to have a summary +buffer displayed while reading. You can do it all from the article +buffer. + +A few additional keystrokes are available: + +@table @kbd + +@item SPACE +@kindex SPACE (Article) +@findex gnus-article-next-page +Scroll forwards one page (@code{gnus-article-next-page}). + +@item DEL +@kindex DEL (Article) +@findex gnus-article-prev-page +Scroll backwards one page (@code{gnus-article-prev-page}). + +@item C-c ^ +@kindex C-c ^ (Article) +@findex gnus-article-refer-article +If point is in the neighborhood of a @code{Message-ID} and you press +@kbd{C-c ^}, Gnus will try to get that article from the server +(@code{gnus-article-refer-article}). + +@item C-c C-m +@kindex C-c C-m (Article) +@findex gnus-article-mail +Send a reply to the address near point (@code{gnus-article-mail}). If +given a prefix, include the mail. + +@item s +@kindex s (Article) +@findex gnus-article-show-summary +Reconfigure the buffers so that the summary buffer becomes visible +(@code{gnus-article-show-summary}). + +@item ? +@kindex ? (Article) +@findex gnus-article-describe-briefly +Give a very brief description of the available keystrokes +(@code{gnus-article-describe-briefly}). + +@item TAB +@kindex TAB (Article) +@findex gnus-article-next-button +Go to the next button, if any (@code{gnus-article-next-button}). This +only makes sense if you have buttonizing turned on. + +@item M-TAB +@kindex M-TAB (Article) +@findex gnus-article-prev-button +Go to the previous button, if any (@code{gnus-article-prev-button}). + +@end table + + +@node Misc Article +@section Misc Article + +@table @code + +@item gnus-single-article-buffer +@vindex gnus-single-article-buffer +If non-@code{nil}, use the same article buffer for all the groups. +(This is the default.) If @code{nil}, each group will have its own +article buffer. + +@vindex gnus-article-decode-hook +@item gnus-article-decode-hook +@cindex MIME +Hook used to decode @sc{mime} articles. The default value is +@code{(article-decode-charset article-decode-encoded-words)} + +@vindex gnus-article-prepare-hook +@item gnus-article-prepare-hook +This hook is called right after the article has been inserted into the +article buffer. It is mainly intended for functions that do something +depending on the contents; it should probably not be used for changing +the contents of the article buffer. + +@vindex gnus-article-display-hook +@item gnus-article-display-hook +This hook is called as the last thing when displaying an article, and is +intended for modifying the contents of the buffer, doing highlights, +hiding headers, and the like. + +@item gnus-article-mode-hook +@vindex gnus-article-mode-hook +Hook called in article mode buffers. + +@item gnus-article-mode-syntax-table +@vindex gnus-article-mode-syntax-table +Syntax table used in article buffers. It is initialized from +@code{text-mode-syntax-table}. + +@vindex gnus-article-mode-line-format +@item gnus-article-mode-line-format +This variable is a format string along the same lines as +@code{gnus-summary-mode-line-format} (@pxref{Mode Line Formatting}). It +accepts the same format specifications as that variable, with one +extension: + +@table @samp +@item w +The @dfn{wash status} of the article. This is a short string with one +character for each possible article wash operation that may have been +performed. +@end table + +@vindex gnus-break-pages + +@item gnus-break-pages +Controls whether @dfn{page breaking} is to take place. If this variable +is non-@code{nil}, the articles will be divided into pages whenever a +page delimiter appears in the article. If this variable is @code{nil}, +paging will not be done. + +@item gnus-page-delimiter +@vindex gnus-page-delimiter +This is the delimiter mentioned above. By default, it is @samp{^L} +(formfeed). +@end table + + +@node Composing Messages +@chapter Composing Messages +@cindex composing messages +@cindex messages +@cindex mail +@cindex sending mail +@cindex reply +@cindex followup +@cindex post + +@kindex C-c C-c (Post) +All commands for posting and mailing will put you in a message buffer +where you can edit the article all you like, before you send the article +by pressing @kbd{C-c C-c}. @xref{Top, , Top, message, The Message +Manual}. If you are in a foreign news group, and you wish to post the +article using the foreign server, you can give a prefix to @kbd{C-c C-c} +to make gnus try to post using the foreign server. + +@menu +* Mail:: Mailing and replying. +* Post:: Posting and following up. +* Posting Server:: What server should you post via? +* 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? +@end menu + +Also see @pxref{Canceling and Superseding} for information on how to +remove articles you shouldn't have posted. + + +@node Mail +@section Mail + +Variables for customizing outgoing mail: + +@table @code +@item gnus-uu-digest-headers +@vindex gnus-uu-digest-headers +List of regexps to match headers included in digested messages. The +headers will be included in the sequence they are matched. + +@item gnus-add-to-list +@vindex gnus-add-to-list +If non-@code{nil}, add a @code{to-list} group parameter to mail groups +that have none when you do a @kbd{a}. + +@end table + + +@node Post +@section Post + +Variables for composing news articles: + +@table @code +@item gnus-sent-message-ids-file +@vindex gnus-sent-message-ids-file +Gnus will keep a @code{Message-ID} history file of all the mails it has +sent. If it discovers that it has already sent a mail, it will ask the +user whether to re-send the mail. (This is primarily useful when +dealing with @sc{soup} packets and the like where one is apt to send the +same packet multiple times.) This variable says what the name of this +history file is. It is @file{~/News/Sent-Message-IDs} by default. Set +this variable to @code{nil} if you don't want gnus to keep a history +file. + +@item gnus-sent-message-ids-length +@vindex gnus-sent-message-ids-length +This variable says how many @code{Message-ID}s to keep in the history +file. It is 1000 by default. + +@end table + + +@node Posting Server +@section Posting Server + +When you press those magical @kbd{C-c C-c} keys to ship off your latest +(extremely intelligent, of course) article, where does it go? + +Thank you for asking. I hate you. + +@vindex gnus-post-method + +It can be quite complicated. Normally, gnus will use the same native +server. However. If your native server doesn't allow posting, just +reading, you probably want to use some other server to post your +(extremely intelligent and fabulously interesting) articles. You can +then set the @code{gnus-post-method} to some other method: + +@lisp +(setq gnus-post-method '(nnspool "")) +@end lisp + +Now, if you've done this, and then this server rejects your article, or +this server is down, what do you do then? To override this variable you +can use a non-zero prefix to the @kbd{C-c C-c} command to force using +the ``current'' server for posting. + +If you give a zero prefix (i.e., @kbd{C-u 0 C-c C-c}) to that command, +gnus will prompt you for what method to use for posting. + +You can also set @code{gnus-post-method} to a list of select methods. +If that's the case, gnus will always prompt you for what method to use +for posting. + +Finally, if you want to always post using the same select method as +you're reading from (which might be convenient if you're reading lots of +groups from different private servers), you can set this variable to +@code{current}. + + +@node Mail and Post +@section Mail and Post + +Here's a list of variables relevant to both mailing and +posting: + +@table @code +@item gnus-mailing-list-groups +@findex gnus-mailing-list-groups +@cindex mailing lists + +If your news server offers groups that are really mailing lists +gatewayed to the @sc{nntp} server, you can read those groups without +problems, but you can't post/followup to them without some difficulty. +One solution is to add a @code{to-address} to the group parameters +(@pxref{Group Parameters}). An easier thing to do is set the +@code{gnus-mailing-list-groups} to a regexp that matches the groups that +really are mailing lists. Then, at least, followups to the mailing +lists will work most of the time. Posting to these groups (@kbd{a}) is +still a pain, though. + +@end table + +You may want to do spell-checking on messages that you send out. Or, if +you don't want to spell-check by hand, you could add automatic +spell-checking via the @code{ispell} package: + +@cindex ispell +@findex ispell-message +@lisp +(add-hook 'message-send-hook 'ispell-message) +@end lisp + + +@node Archived Messages +@section Archived Messages +@cindex archived messages +@cindex sent messages + +Gnus provides a few different methods for storing the mail and news you +send. The default method is to use the @dfn{archive virtual server} to +store the messages. If you want to disable this completely, the +@code{gnus-message-archive-group} variable should be @code{nil}, which +is the default. + +@vindex gnus-message-archive-method +@code{gnus-message-archive-method} says what virtual server gnus is to +use to store sent messages. The default is: + +@lisp +(nnfolder "archive" + (nnfolder-directory "~/Mail/archive") + (nnfolder-active-file "~/Mail/archive/active") + (nnfolder-get-new-mail nil) + (nnfolder-inhibit-expiry t)) +@end lisp + +You can, however, use any mail select method (@code{nnml}, +@code{nnmbox}, etc.). @code{nnfolder} is a quite likeable select method +for doing this sort of thing, though. If you don't like the default +directory chosen, you could say something like: + +@lisp +(setq gnus-message-archive-method + '(nnfolder "archive" + (nnfolder-inhibit-expiry t) + (nnfolder-active-file "~/News/sent-mail/active") + (nnfolder-directory "~/News/sent-mail/"))) +@end lisp + +@vindex gnus-message-archive-group +@cindex Gcc +Gnus will insert @code{Gcc} headers in all outgoing messages that point +to one or more group(s) on that server. Which group to use is +determined by the @code{gnus-message-archive-group} variable. + +This variable can be used to do the following: + +@itemize @bullet +@item a string +Messages will be saved in that group. +@item a list of strings +Messages will be saved in all those groups. +@item an alist of regexps, functions and forms +When a key ``matches'', the result is used. +@item @code{nil} +No message archiving will take place. This is the default. +@end itemize + +Let's illustrate: + +Just saving to a single group called @samp{MisK}: +@lisp +(setq gnus-message-archive-group "MisK") +@end lisp + +Saving to two groups, @samp{MisK} and @samp{safe}: +@lisp +(setq gnus-message-archive-group '("MisK" "safe")) +@end lisp + +Save to different groups based on what group you are in: +@lisp +(setq gnus-message-archive-group + '(("^alt" "sent-to-alt") + ("mail" "sent-to-mail") + (".*" "sent-to-misc"))) +@end lisp + +More complex stuff: +@lisp +(setq gnus-message-archive-group + '((if (message-news-p) + "misc-news" + "misc-mail"))) +@end lisp + +How about storing all news messages in one file, but storing all mail +messages in one file per month: + +@lisp +(setq gnus-message-archive-group + '((if (message-news-p) + "misc-news" + (concat "mail." (format-time-string + "%Y-%m" (current-time)))))) +@end lisp + +(XEmacs 19.13 doesn't have @code{format-time-string}, so you'll have to +use a different value for @code{gnus-message-archive-group} there.) + +Now, when you send a message off, it will be stored in the appropriate +group. (If you want to disable storing for just one particular message, +you can just remove the @code{Gcc} header that has been inserted.) The +archive group will appear in the group buffer the next time you start +gnus, or the next time you press @kbd{F} in the group buffer. You can +enter it and read the articles in it just like you'd read any other +group. If the group gets really big and annoying, you can simply rename +if (using @kbd{G r} in the group buffer) to something +nice---@samp{misc-mail-september-1995}, or whatever. New messages will +continue to be stored in the old (now empty) group. + +That's the default method of archiving sent messages. Gnus offers a +different way for the people who don't like the default method. In that +case you should set @code{gnus-message-archive-group} to @code{nil}; +this will disable archiving. + +@table @code +@item gnus-outgoing-message-group +@vindex gnus-outgoing-message-group +All outgoing messages will be put in this group. If you want to store +all your outgoing mail and articles in the group @samp{nnml:archive}, +you set this variable to that value. This variable can also be a list of +group names. + +If you want to have greater control over what group to put each +message in, you can set this variable to a function that checks the +current newsgroup name and then returns a suitable group name (or list +of names). + +This variable can be used instead of @code{gnus-message-archive-group}, +but the latter is the preferred method. +@end table + + +@node Posting Styles +@section Posting Styles +@cindex posting styles +@cindex styles + +All them variables, they make my head swim. + +So what if you want a different @code{Organization} and signature based +on what groups you post to? And you post both from your home machine +and your work machine, and you want different @code{From} lines, and so +on? + +@vindex gnus-posting-styles +One way to do stuff like that is to write clever hooks that change the +variables you need to have changed. That's a bit boring, so somebody +came up with the bright idea of letting the user specify these things in +a handy alist. Here's an example of a @code{gnus-posting-styles} +variable: + +@lisp +((".*" + (signature "Peace and happiness") + (organization "What me?")) + ("^comp" + (signature "Death to everybody")) + ("comp.emacs.i-love-it" + (organization "Emacs is it"))) +@end lisp + +As you might surmise from this example, this alist consists of several +@dfn{styles}. Each style will be applicable if the first element +``matches'', in some form or other. The entire alist will be iterated +over, from the beginning towards the end, and each match will be +applied, which means that attributes in later styles that match override +the same attributes in earlier matching styles. So +@samp{comp.programming.literate} will have the @samp{Death to everybody} +signature and the @samp{What me?} @code{Organization} header. + +The first element in each style is called the @code{match}. If it's a +string, then Gnus will try to regexp match it against the group name. +If it's a function symbol, that function will be called with no +arguments. If it's a variable symbol, then the variable will be +referenced. If it's a list, then that list will be @code{eval}ed. In +any case, if this returns a non-@code{nil} value, then the style is said +to @dfn{match}. + +Each style may contain a arbitrary amount of @dfn{attributes}. Each +attribute consists of a @var{(name . value)} pair. The attribute name +can be one of @code{signature}, @code{signature-file}, +@code{organization}, @code{address}, @code{name} or @code{body}. The +attribute name can also be a string. In that case, this will be used as +a header name, and the value will be inserted in the headers of the +article. + +The attribute value can be a string (used verbatim), a function (the +return value will be used), a variable (its value will be used) or a +list (it will be @code{eval}ed and the return value will be used). + +If you wish to check whether the message you are about to compose is +meant to be a news article or a mail message, you can check the values +of the two dynamically bound variables @code{message-this-is-news} and +@code{message-this-is-mail}. + +@vindex message-this-is-mail +@vindex message-this-is-news + +So here's a new example: + +@lisp +(setq gnus-posting-styles + '((".*" + (signature-file "~/.signature") + (name "User Name") + ("X-Home-Page" (getenv "WWW_HOME")) + (organization "People's Front Against MWM")) + ("^rec.humor" + (signature my-funny-signature-randomizer)) + ((equal (system-name) "gnarly") + (signature my-quote-randomizer)) + (message-this-is-news + (signature my-news-signature)) + (posting-from-work-p + (signature-file "~/.work-signature") + (address "user@@bar.foo") + (body "You are fired.\n\nSincerely, your boss.") + (organization "Important Work, Inc")) + ("^nn.+:" + (signature-file "~/.mail-signature")))) +@end lisp + + +@node Drafts +@section Drafts +@cindex drafts + +If you are writing a message (mail or news) and suddenly remember that +you have a steak in the oven (or some pesto in the food processor, you +craaazy vegetarians), you'll probably wish there was a method to save +the message you are writing so that you can continue editing it some +other day, and send it when you feel its finished. + +Well, don't worry about it. Whenever you start composing a message of +some sort using the gnus mail and post commands, the buffer you get will +automatically associate to an article in a special @dfn{draft} group. +If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the +article will be saved there. (Auto-save files also go to the draft +group.) + +@cindex nndraft +@vindex nndraft-directory +The draft group is a special group (which is implemented as an +@code{nndraft} group, if you absolutely have to know) called +@samp{nndraft:drafts}. The variable @code{nndraft-directory} says where +@code{nndraft} is to store its files. What makes this group special is +that you can't tick any articles in it or mark any articles as +read---all articles in the group are permanently unread. + +If the group doesn't exist, it will be created and you'll be subscribed +to it. The only way to make it disappear from the Group buffer is to +unsubscribe it. + +@c @findex gnus-dissociate-buffer-from-draft +@c @kindex C-c M-d (Mail) +@c @kindex C-c M-d (Post) +@c @findex gnus-associate-buffer-with-draft +@c @kindex C-c C-d (Mail) +@c @kindex C-c C-d (Post) +@c If you're writing some super-secret message that you later want to +@c encode with PGP before sending, you may wish to turn the auto-saving +@c (and association with the draft group) off. You never know who might be +@c interested in reading all your extremely valuable and terribly horrible +@c and interesting secrets. The @kbd{C-c M-d} +@c (@code{gnus-dissociate-buffer-from-draft}) command does that for you. +@c If you change your mind and want to turn the auto-saving back on again, +@c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that. +@c +@c @vindex gnus-use-draft +@c To leave association with the draft group off by default, set +@c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default. + +@findex gnus-draft-edit-message +@kindex D e (Draft) +When you want to continue editing the article, you simply enter the +draft group and push @kbd{D e} (@code{gnus-draft-edit-message}) to do +that. You will be placed in a buffer where you left off. + +Rejected articles will also be put in this draft group (@pxref{Rejected +Articles}). + +@findex gnus-draft-send-all-messages +@findex gnus-draft-send-message +If you have lots of rejected messages you want to post (or mail) without +doing further editing, you can use the @kbd{D s} command +(@code{gnus-draft-send-message}). This command understands the +process/prefix convention (@pxref{Process/Prefix}). The @kbd{D S} +command (@code{gnus-draft-send-all-messages}) will ship off all messages +in the buffer. + +If you have some messages that you wish not to send, you can use the +@kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message +as unsendable. This is a toggling command. + + +@node Rejected Articles +@section Rejected Articles +@cindex rejected articles + +Sometimes a news server will reject an article. Perhaps the server +doesn't like your face. Perhaps it just feels miserable. Perhaps +@emph{there be demons}. Perhaps you have included too much cited text. +Perhaps the disk is full. Perhaps the server is down. + +These situations are, of course, totally beyond the control of gnus. +(Gnus, of course, loves the way you look, always feels great, has angels +fluttering around inside of it, doesn't care about how much cited text +you include, never runs full and never goes down.) So gnus saves these +articles until some later time when the server feels better. + +The rejected articles will automatically be put in a special draft group +(@pxref{Drafts}). When the server comes back up again, you'd then +typically enter that group and send all the articles off. + + +@node Select Methods +@chapter Select Methods +@cindex foreign groups +@cindex select methods + +A @dfn{foreign group} is a group not read by the usual (or +default) means. It could be, for instance, a group from a different +@sc{nntp} server, it could be a virtual group, or it could be your own +personal mail group. + +A foreign group (or any group, really) is specified by a @dfn{name} and +a @dfn{select method}. To take the latter first, a select method is a +list where the first element says what backend to use (e.g. @code{nntp}, +@code{nnspool}, @code{nnml}) and the second element is the @dfn{server +name}. There may be additional elements in the select method, where the +value may have special meaning for the backend in question. + +One could say that a select method defines a @dfn{virtual server}---so +we do just that (@pxref{The Server Buffer}). + +The @dfn{name} of the group is the name the backend will recognize the +group as. + +For instance, the group @samp{soc.motss} on the @sc{nntp} server +@samp{some.where.edu} will have the name @samp{soc.motss} and select +method @code{(nntp "some.where.edu")}. Gnus will call this group +@samp{nntp+some.where.edu:soc.motss}, even though the @code{nntp} +backend just knows this group as @samp{soc.motss}. + +The different methods all have their peculiarities, of course. + +@menu +* The Server Buffer:: Making and editing virtual servers. +* Getting News:: Reading USENET news with Gnus. +* Getting Mail:: Reading your personal mail with Gnus. +* Other Sources:: Reading directories, files, SOUP packets. +* Combined Groups:: Combining groups into one group. +* Gnus Unplugged:: Reading news and mail offline. +@end menu + + +@node The Server Buffer +@section The Server Buffer + +Traditionally, a @dfn{server} is a machine or a piece of software that +one connects to, and then requests information from. Gnus does not +connect directly to any real servers, but does all transactions through +one backend or other. But that's just putting one layer more between +the actual media and Gnus, so we might just as well say that each +backend represents a virtual server. + +For instance, the @code{nntp} backend may be used to connect to several +different actual @sc{nntp} servers, or, perhaps, to many different ports +on the same actual @sc{nntp} server. You tell Gnus which backend to +use, and what parameters to set by specifying a @dfn{select method}. + +These select method specifications can sometimes become quite +complicated---say, for instance, that you want to read from the +@sc{nntp} server @samp{news.funet.fi} on port number 13, which +hangs if queried for @sc{nov} headers and has a buggy select. Ahem. +Anyways, if you had to specify that for each group that used this +server, that would be too much work, so Gnus offers a way of naming +select methods, which is what you do in the server buffer. + +To enter the server buffer, use the @kbd{^} +(@code{gnus-group-enter-server-mode}) command in the group buffer. + +@menu +* 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. +@end menu + +@vindex gnus-server-mode-hook +@code{gnus-server-mode-hook} is run when creating the server buffer. + + +@node Server Buffer Format +@subsection Server Buffer Format +@cindex server buffer format + +@vindex gnus-server-line-format +You can change the look of the server buffer lines by changing the +@code{gnus-server-line-format} variable. This is a @code{format}-like +variable, with some simple extensions: + +@table @samp + +@item h +How the news is fetched---the backend name. + +@item n +The name of this server. + +@item w +Where the news is to be fetched from---the address. + +@item s +The opened/closed/denied status of the server. +@end table + +@vindex gnus-server-mode-line-format +The mode line can also be customized by using the +@code{gnus-server-mode-line-format} variable (@pxref{Mode Line +Formatting}). The following specs are understood: + +@table @samp +@item S +Server name. + +@item M +Server method. +@end table + +Also @pxref{Formatting Variables}. + + +@node Server Commands +@subsection Server Commands +@cindex server commands + +@table @kbd + +@item a +@kindex a (Server) +@findex gnus-server-add-server +Add a new server (@code{gnus-server-add-server}). + +@item e +@kindex e (Server) +@findex gnus-server-edit-server +Edit a server (@code{gnus-server-edit-server}). + +@item SPACE +@kindex SPACE (Server) +@findex gnus-server-read-server +Browse the current server (@code{gnus-server-read-server}). + +@item q +@kindex q (Server) +@findex gnus-server-exit +Return to the group buffer (@code{gnus-server-exit}). + +@item k +@kindex k (Server) +@findex gnus-server-kill-server +Kill the current server (@code{gnus-server-kill-server}). + +@item y +@kindex y (Server) +@findex gnus-server-yank-server +Yank the previously killed server (@code{gnus-server-yank-server}). + +@item c +@kindex c (Server) +@findex gnus-server-copy-server +Copy the current server (@code{gnus-server-copy-server}). + +@item l +@kindex l (Server) +@findex gnus-server-list-servers +List all servers (@code{gnus-server-list-servers}). + +@item s +@kindex s (Server) +@findex gnus-server-scan-server +Request that the server scan its sources for new articles +(@code{gnus-server-scan-server}). This is mainly sensible with mail +servers. + +@item g +@kindex g (Server) +@findex gnus-server-regenerate-server +Request that the server regenerate all its data structures +(@code{gnus-server-regenerate-server}). This can be useful if you have +a mail backend that has gotten out of synch. + +@end table + + +@node Example Methods +@subsection Example Methods + +Most select methods are pretty simple and self-explanatory: + +@lisp +(nntp "news.funet.fi") +@end lisp + +Reading directly from the spool is even simpler: + +@lisp +(nnspool "") +@end lisp + +As you can see, the first element in a select method is the name of the +backend, and the second is the @dfn{address}, or @dfn{name}, if you +will. + +After these two elements, there may be an arbitrary number of +@var{(variable form)} pairs. + +To go back to the first example---imagine that you want to read from +port 15 on that machine. This is what the select method should +look like then: + +@lisp +(nntp "news.funet.fi" (nntp-port-number 15)) +@end lisp + +You should read the documentation to each backend to find out what +variables are relevant, but here's an @code{nnmh} example: + +@code{nnmh} is a mail backend that reads a spool-like structure. Say +you have two structures that you wish to access: One is your private +mail spool, and the other is a public one. Here's the possible spec for +your private mail: + +@lisp +(nnmh "private" (nnmh-directory "~/private/mail/")) +@end lisp + +(This server is then called @samp{private}, but you may have guessed +that.) + +Here's the method for a public spool: + +@lisp +(nnmh "public" + (nnmh-directory "/usr/information/spool/") + (nnmh-get-new-mail nil)) +@end lisp + +If you are behind a firewall and only have access to the @sc{nntp} +server from the firewall machine, you can instruct Gnus to @code{rlogin} +on the firewall machine and telnet from there to the @sc{nntp} server. +Doing this can be rather fiddly, but your virtual server definition +should probably look something like this: + +@lisp +(nntp "firewall" + (nntp-address "the.firewall.machine") + (nntp-open-connection-function nntp-open-rlogin) + (nntp-end-of-line "\n") + (nntp-rlogin-parameters + ("telnet" "the.real.nntp.host" "nntp"))) +@end lisp + +If you want to use the wonderful @code{ssh} program to provide a +compressed connection over the modem line, you could create a virtual +server that would look something like this: + +@lisp +(nntp "news" + (nntp-address "copper.uio.no") + (nntp-rlogin-program "ssh") + (nntp-open-connection-function nntp-open-rlogin) + (nntp-end-of-line "\n") + (nntp-rlogin-parameters + ("telnet" "news.uio.no" "nntp"))) +@end lisp + +This means that you have to have set up @code{ssh-agent} correctly to +provide automatic authorization, of course. And to get a compressed +connection, you have to have the @samp{Compression} option in the +@code{ssh} @file{config} file. + + +@node Creating a Virtual Server +@subsection Creating a Virtual Server + +If you're saving lots of articles in the cache by using persistent +articles, you may want to create a virtual server to read the cache. + +First you need to add a new server. The @kbd{a} command does that. It +would probably be best to use @code{nnspool} to read the cache. You +could also use @code{nnml} or @code{nnmh}, though. + +Type @kbd{a nnspool RET cache RET}. + +You should now have a brand new @code{nnspool} virtual server called +@samp{cache}. You now need to edit it to have the right definitions. +Type @kbd{e} to edit the server. You'll be entered into a buffer that +will contain the following: + +@lisp +(nnspool "cache") +@end lisp + +Change that to: + +@lisp +(nnspool "cache" + (nnspool-spool-directory "~/News/cache/") + (nnspool-nov-directory "~/News/cache/") + (nnspool-active-file "~/News/cache/active")) +@end lisp + +Type @kbd{C-c C-c} to return to the server buffer. If you now press +@kbd{RET} over this virtual server, you should be entered into a browse +buffer, and you should be able to enter any of the groups displayed. + + +@node Server Variables +@subsection Server Variables + +One sticky point when defining variables (both on backends and in Emacs +in general) is that some variables are typically initialized from other +variables when the definition of the variables is being loaded. If you +change the "base" variable after the variables have been loaded, you +won't change the "derived" variables. + +This typically affects directory and file variables. For instance, +@code{nnml-directory} is @file{~/Mail/} by default, and all @code{nnml} +directory variables are initialized from that variable, so +@code{nnml-active-file} will be @file{~/Mail/active}. If you define a +new virtual @code{nnml} server, it will @emph{not} suffice to set just +@code{nnml-directory}---you have to explicitly set all the file +variables to be what you want them to be. For a complete list of +variables for each backend, see each backend's section later in this +manual, but here's an example @code{nnml} definition: + +@lisp +(nnml "public" + (nnml-directory "~/my-mail/") + (nnml-active-file "~/my-mail/active") + (nnml-newsgroups-file "~/my-mail/newsgroups")) +@end lisp + + +@node Servers and Methods +@subsection Servers and Methods + +Wherever you would normally use a select method +(e.g. @code{gnus-secondary-select-method}, in the group select method, +when browsing a foreign server) you can use a virtual server name +instead. This could potentially save lots of typing. And it's nice all +over. + + +@node Unavailable Servers +@subsection Unavailable Servers + +If a server seems to be unreachable, Gnus will mark that server as +@code{denied}. That means that any subsequent attempt to make contact +with that server will just be ignored. ``It can't be opened,'' Gnus +will tell you, without making the least effort to see whether that is +actually the case or not. + +That might seem quite naughty, but it does make sense most of the time. +Let's say you have 10 groups subscribed to on server +@samp{nephelococcygia.com}. This server is located somewhere quite far +away from you and the machine is quite slow, so it takes 1 minute just +to find out that it refuses connection to you today. If Gnus were to +attempt to do that 10 times, you'd be quite annoyed, so Gnus won't +attempt to do that. Once it has gotten a single ``connection refused'', +it will regard that server as ``down''. + +So, what happens if the machine was only feeling unwell temporarily? +How do you test to see whether the machine has come up again? + +You jump to the server buffer (@pxref{The Server Buffer}) and poke it +with the following commands: + +@table @kbd + +@item O +@kindex O (Server) +@findex gnus-server-open-server +Try to establish connection to the server on the current line +(@code{gnus-server-open-server}). + +@item C +@kindex C (Server) +@findex gnus-server-close-server +Close the connection (if any) to the server +(@code{gnus-server-close-server}). + +@item D +@kindex D (Server) +@findex gnus-server-deny-server +Mark the current server as unreachable +(@code{gnus-server-deny-server}). + +@item M-o +@kindex M-o (Server) +@findex gnus-server-open-all-servers +Open the connections to all servers in the buffer +(@code{gnus-server-open-all-servers}). + +@item M-c +@kindex M-c (Server) +@findex gnus-server-close-all-servers +Close the connections to all servers in the buffer +(@code{gnus-server-close-all-servers}). + +@item R +@kindex R (Server) +@findex gnus-server-remove-denials +Remove all marks to whether Gnus was denied connection from any servers +(@code{gnus-server-remove-denials}). + +@end table + + +@node Getting News +@section Getting News +@cindex reading news +@cindex news backends + +A newsreader is normally used for reading news. Gnus currently provides +only two methods of getting news---it can read from an @sc{nntp} server, +or it can read from a local spool. + +@menu +* NNTP:: Reading news from an @sc{nntp} server. +* News Spool:: Reading news from the local spool. +@end menu + + +@node NNTP +@subsection @sc{nntp} +@cindex nntp + +Subscribing to a foreign group from an @sc{nntp} server is rather easy. +You just specify @code{nntp} as method and the address of the @sc{nntp} +server as the, uhm, address. + +If the @sc{nntp} server is located at a non-standard port, setting the +third element of the select method to this port number should allow you +to connect to the right port. You'll have to edit the group info for +that (@pxref{Foreign Groups}). + +The name of the foreign group can be the same as a native group. In +fact, you can subscribe to the same group from as many different servers +you feel like. There will be no name collisions. + +The following variables can be used to create a virtual @code{nntp} +server: + +@table @code + +@item nntp-server-opened-hook +@vindex nntp-server-opened-hook +@cindex @sc{mode reader} +@cindex authinfo +@cindex authentification +@cindex nntp authentification +@findex nntp-send-authinfo +@findex nntp-send-mode-reader +is run after a connection has been made. It can be used to send +commands to the @sc{nntp} server after it has been contacted. By +default it sends the command @code{MODE READER} to the server with the +@code{nntp-send-mode-reader} function. This function should always be +present in this hook. + +@item nntp-authinfo-function +@vindex nntp-authinfo-function +@findex nntp-send-authinfo +@vindex nntp-authinfo-file +This function will be used to send @samp{AUTHINFO} to the @sc{nntp} +server. The default function is @code{nntp-send-authinfo}, which looks +through your @file{~/.authinfo} (or whatever you've set the +@code{nntp-authinfo-file} variable to) for applicable entries. If none +are found, it will prompt you for a login name and a password. The +format of the @file{~/.authinfo} file is (almost) the same as the +@code{ftp} @file{~/.netrc} file, which is defined in the @code{ftp} +manual page, but here are the salient facts: + +@enumerate +@item +The file contains one or more line, each of which define one server. + +@item +Each line may contain an arbitrary number of token/value pairs. The +valid tokens include @samp{machine}, @samp{login}, @samp{password}, +@samp{default} and @samp{force}. (The latter is not a valid +@file{.netrc}/@code{ftp} token, which is the only way the +@file{.authinfo} file format deviates from the @file{.netrc} file +format.) + +@end enumerate + +Here's an example file: + +@example +machine news.uio.no login larsi password geheimnis +machine nntp.ifi.uio.no login larsi force yes +@end example + +The token/value pairs may appear in any order; @samp{machine} doesn't +have to be first, for instance. + +In this example, both login name and password have been supplied for the +former server, while the latter has only the login name listed, and the +user will be prompted for the password. The latter also has the +@samp{force} tag, which means that the authinfo will be sent to the +@var{nntp} server upon connection; the default (i.e., when there is not +@samp{force} tag) is to not send authinfo to the @var{nntp} server +until the @var{nntp} server asks for it. + +You can also add @samp{default} lines that will apply to all servers +that don't have matching @samp{machine} lines. + +@example +default force yes +@end example + +This will force sending @samp{AUTHINFO} commands to all servers not +previously mentioned. + +Remember to not leave the @file{~/.authinfo} file world-readable. + +@item nntp-server-action-alist +@vindex nntp-server-action-alist +This is a list of regexps to match on server types and actions to be +taken when matches are made. For instance, if you want Gnus to beep +every time you connect to innd, you could say something like: + +@lisp +(setq nntp-server-action-alist + '(("innd" (ding)))) +@end lisp + +You probably don't want to do that, though. + +The default value is + +@lisp +'(("nntpd 1\\.5\\.11t" + (remove-hook 'nntp-server-opened-hook 'nntp-send-mode-reader))) +@end lisp + +This ensures that Gnus doesn't send the @code{MODE READER} command to +nntpd 1.5.11t, since that command chokes that server, I've been told. + +@item nntp-maximum-request +@vindex nntp-maximum-request +If the @sc{nntp} server doesn't support @sc{nov} headers, this backend +will collect headers by sending a series of @code{head} commands. To +speed things up, the backend sends lots of these commands without +waiting for reply, and then reads all the replies. This is controlled +by the @code{nntp-maximum-request} variable, and is 400 by default. If +your network is buggy, you should set this to 1. + +@item nntp-connection-timeout +@vindex nntp-connection-timeout +If you have lots of foreign @code{nntp} groups that you connect to +regularly, you're sure to have problems with @sc{nntp} servers not +responding properly, or being too loaded to reply within reasonable +time. This is can lead to awkward problems, which can be helped +somewhat by setting @code{nntp-connection-timeout}. This is an integer +that says how many seconds the @code{nntp} backend should wait for a +connection before giving up. If it is @code{nil}, which is the default, +no timeouts are done. + +@c @item nntp-command-timeout +@c @vindex nntp-command-timeout +@c @cindex PPP connections +@c @cindex dynamic IP addresses +@c If you're running Gnus on a machine that has a dynamically assigned +@c address, Gnus may become confused. If the address of your machine +@c changes after connecting to the @sc{nntp} server, Gnus will simply sit +@c waiting forever for replies from the server. To help with this +@c unfortunate problem, you can set this command to a number. Gnus will +@c then, if it sits waiting for a reply from the server longer than that +@c number of seconds, shut down the connection, start a new one, and resend +@c the command. This should hopefully be transparent to the user. A +@c likely number is 30 seconds. +@c +@c @item nntp-retry-on-break +@c @vindex nntp-retry-on-break +@c If this variable is non-@code{nil}, you can also @kbd{C-g} if Gnus +@c hangs. This will have much the same effect as the command timeout +@c described above. + +@item nntp-server-hook +@vindex nntp-server-hook +This hook is run as the last step when connecting to an @sc{nntp} +server. + +@findex nntp-open-rlogin +@findex nntp-open-telnet +@findex nntp-open-network-stream +@item nntp-open-connection-function +@vindex nntp-open-connection-function +This function is used to connect to the remote system. Four pre-made +functions are supplied: + +@table @code +@item nntp-open-network-stream +This is the default, and simply connects to some port or other on the +remote system. + +@item nntp-open-rlogin +Does an @samp{rlogin} on the +remote system, and then does a @samp{telnet} to the @sc{nntp} server +available there. + +@code{nntp-open-rlogin}-related variables: + +@table @code + +@item nntp-rlogin-program +@vindex nntp-rlogin-program +Program used to log in on remote machines. The default is @samp{rsh}, +but @samp{ssh} is a popular alternative. + +@item nntp-rlogin-parameters +@vindex nntp-rlogin-parameters +This list will be used as the parameter list given to @code{rsh}. + +@item nntp-rlogin-user-name +@vindex nntp-rlogin-user-name +User name on the remote system. + +@end table + +@item nntp-open-telnet +Does a @samp{telnet} to the remote system and then another @samp{telnet} +to get to the @sc{nntp} server. + +@code{nntp-open-telnet}-related variables: + +@table @code +@item nntp-telnet-command +@vindex nntp-telnet-command +Command used to start @code{telnet}. + +@item nntp-telnet-switches +@vindex nntp-telnet-switches +List of strings to be used as the switches to the @code{telnet} command. + +@item nntp-telnet-user-name +@vindex nntp-telnet-user-name +User name for log in on the remote system. + +@item nntp-telnet-passwd +@vindex nntp-telnet-passwd +Password to use when logging in. + +@item nntp-telnet-parameters +@vindex nntp-telnet-parameters +A list of strings executed as a command after logging in +via @code{telnet}. + +@item nntp-telnet-shell-prompt +@vindex nntp-telnet-shell-prompt +Regexp matching the shell prompt on the remote machine. The default is +@samp{bash\\|\$ *\r?$\\|> *\r?}. + +@item nntp-open-telnet-envuser +@vindex nntp-open-telnet-envuser +If non-@code{nil}, the @code{telnet} session (client and server both) +will support the @code{ENVIRON} option and not prompt for login name. +This works for Solaris @code{telnet}, for instance. + +@end table + +@findex nntp-open-ssl-stream +@item nntp-open-ssl-stream +Opens a connection to a server over a @dfn{secure} channel. To use this +you must have SSLay installed +(@file{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL}, and you also need +@file{ssl.el} (from the W3 distributeion, for instance). You then +define a server as follows: + +@lisp +;; Type `C-c C-c' after you've finished editing. +;; +;; "snews" is port 563 and is predefined in our /etc/services +;; +(nntp "snews.bar.com" + (nntp-open-connection-function nntp-open-ssl-stream) + (nntp-port-number "snews") + (nntp-address "snews.bar.com")) +@end lisp + +@end table + +@item nntp-end-of-line +@vindex nntp-end-of-line +String to use as end-of-line marker when talking to the @sc{nntp} +server. This is @samp{\r\n} by default, but should be @samp{\n} when +using @code{rlogin} to talk to the server. + +@item nntp-rlogin-user-name +@vindex nntp-rlogin-user-name +User name on the remote system when using the @code{rlogin} connect +function. + +@item nntp-address +@vindex nntp-address +The address of the remote system running the @sc{nntp} server. + +@item nntp-port-number +@vindex nntp-port-number +Port number to connect to when using the @code{nntp-open-network-stream} +connect function. + +@item nntp-buggy-select +@vindex nntp-buggy-select +Set this to non-@code{nil} if your select routine is buggy. + +@item nntp-nov-is-evil +@vindex nntp-nov-is-evil +If the @sc{nntp} server does not support @sc{nov}, you could set this +variable to @code{t}, but @code{nntp} usually checks automatically whether @sc{nov} +can be used. + +@item nntp-xover-commands +@vindex nntp-xover-commands +@cindex nov +@cindex XOVER +List of strings used as commands to fetch @sc{nov} lines from a +server. The default value of this variable is @code{("XOVER" +"XOVERVIEW")}. + +@item nntp-nov-gap +@vindex nntp-nov-gap +@code{nntp} normally sends just one big request for @sc{nov} lines to +the server. The server responds with one huge list of lines. However, +if you have read articles 2-5000 in the group, and only want to read +article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov} +lines that you will not need. This variable says how +big a gap between two consecutive articles is allowed to be before the +@code{XOVER} request is split into several request. Note that if your +network is fast, setting this variable to a really small number means +that fetching will probably be slower. If this variable is @code{nil}, +@code{nntp} will never split requests. The default is 5. + +@item nntp-prepare-server-hook +@vindex nntp-prepare-server-hook +A hook run before attempting to connect to an @sc{nntp} server. + +@item nntp-warn-about-losing-connection +@vindex nntp-warn-about-losing-connection +If this variable is non-@code{nil}, some noise will be made when a +server closes connection. + +@item nntp-record-commands +@vindex nntp-record-commands +If non-@code{nil}, @code{nntp} will log all commands it sends to the +@sc{nntp} server (along with a timestep) in the @samp{*nntp-log*} +buffer. This is useful if you are debugging a Gnus/@sc{nntp} connection +that doesn't seem to work. + +@end table + + +@node News Spool +@subsection News Spool +@cindex nnspool +@cindex news spool + +Subscribing to a foreign group from the local spool is extremely easy, +and might be useful, for instance, to speed up reading groups that +contain very big articles---@samp{alt.binaries.pictures.furniture}, for +instance. + +Anyways, you just specify @code{nnspool} as the method and @code{""} (or +anything else) as the address. + +If you have access to a local spool, you should probably use that as the +native select method (@pxref{Finding the News}). It is normally faster +than using an @code{nntp} select method, but might not be. It depends. +You just have to try to find out what's best at your site. + +@table @code + +@item nnspool-inews-program +@vindex nnspool-inews-program +Program used to post an article. + +@item nnspool-inews-switches +@vindex nnspool-inews-switches +Parameters given to the inews program when posting an article. + +@item nnspool-spool-directory +@vindex nnspool-spool-directory +Where @code{nnspool} looks for the articles. This is normally +@file{/usr/spool/news/}. + +@item nnspool-nov-directory +@vindex nnspool-nov-directory +Where @code{nnspool} will look for @sc{nov} files. This is normally +@file{/usr/spool/news/over.view/}. + +@item nnspool-lib-dir +@vindex nnspool-lib-dir +Where the news lib dir is (@file{/usr/lib/news/} by default). + +@item nnspool-active-file +@vindex nnspool-active-file +The path to the active file. + +@item nnspool-newsgroups-file +@vindex nnspool-newsgroups-file +The path to the group descriptions file. + +@item nnspool-history-file +@vindex nnspool-history-file +The path to the news history file. + +@item nnspool-active-times-file +@vindex nnspool-active-times-file +The path to the active date file. + +@item nnspool-nov-is-evil +@vindex nnspool-nov-is-evil +If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files +that it finds. + +@item nnspool-sift-nov-with-sed +@vindex nnspool-sift-nov-with-sed +@cindex sed +If non-@code{nil}, which is the default, use @code{sed} to get the +relevant portion from the overview file. If nil, @code{nnspool} will +load the entire file into a buffer and process it there. + +@end table + + +@node Getting Mail +@section Getting Mail +@cindex reading mail +@cindex mail + +Reading mail with a newsreader---isn't that just plain WeIrD? But of +course. + +@menu +* Getting Started Reading Mail:: A simple cookbook example. +* Splitting Mail:: How to create mail groups. +* Mail Backend Variables:: Variables for customizing mail handling. +* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. +* Mail and Procmail:: Reading mail groups that procmail create. +* Incorporating Old Mail:: What about the old mail you have? +* Expiring Mail:: Getting rid of unwanted mail. +* Washing Mail:: Removing gruft from the mail you get. +* Duplicates:: Dealing with duplicated mail. +* Not Reading Mail:: Using mail backends for reading other files. +* Choosing a Mail Backend:: Gnus can read a variety of mail formats. +@end menu + + +@node Getting Started Reading Mail +@subsection Getting Started Reading Mail + +It's quite easy to use Gnus to read your new mail. You just plonk the +mail backend of your choice into @code{gnus-secondary-select-methods}, +and things will happen automatically. + +For instance, if you want to use @code{nnml} (which is a "one file per +mail" backend), you could put the following in your @file{.gnus} file: + +@lisp +(setq gnus-secondary-select-methods + '((nnml "private"))) +@end lisp + +Now, the next time you start Gnus, this backend will be queried for new +articles, and it will move all the messages in your spool file to its +directory, which is @code{~/Mail/} by default. The new group that will +be created (@samp{mail.misc}) will be subscribed, and you can read it +like any other group. + +You will probably want to split the mail into several groups, though: + +@lisp +(setq nnmail-split-methods + '(("junk" "^From:.*Lars Ingebrigtsen") + ("crazy" "^Subject:.*die\\|^Organization:.*flabby") + ("other" ""))) +@end lisp + +This will result in three new @code{nnml} mail groups being created: +@samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the +mail that doesn't fit into the first two groups will be placed in the +last group. + +This should be sufficient for reading mail with Gnus. You might want to +give the other sections in this part of the manual a perusal, though. +Especially @pxref{Choosing a Mail Backend} and @pxref{Expiring Mail}. + + +@node Splitting Mail +@subsection Splitting Mail +@cindex splitting mail +@cindex mail splitting + +@vindex nnmail-split-methods +The @code{nnmail-split-methods} variable says how the incoming mail is +to be split into groups. + +@lisp +(setq nnmail-split-methods + '(("mail.junk" "^From:.*Lars Ingebrigtsen") + ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby") + ("mail.other" ""))) +@end lisp + +This variable is a list of lists, where the first element of each of +these lists is the name of the mail group (they do not have to be called +something beginning with @samp{mail}, by the way), and the second +element is a regular expression used on the header of each mail to +determine if it belongs in this mail group. The first string may +contain @samp{\\1} forms, like the ones used by @code{replace-match} to +insert sub-expressions from the matched text. For instance: + +@lisp +("list.\\1" "From:.*\\(.*\\)-list@@majordomo.com") +@end lisp + +The second element can also be a function. In that case, it will be +called narrowed to the headers with the first element of the rule as the +argument. It should return a non-@code{nil} value if it thinks that the +mail belongs in that group. + +The last of these groups should always be a general one, and the regular +expression should @emph{always} be @samp{} so that it matches any mails +that haven't been matched by any of the other regexps. (These rules are +processed from the beginning of the alist toward the end. The first +rule to make a match will "win", unless you have crossposting enabled. +In that case, all matching rules will "win".) + +If you like to tinker with this yourself, you can set this variable to a +function of your choice. This function will be called without any +arguments in a buffer narrowed to the headers of an incoming mail +message. The function should return a list of group names that it +thinks should carry this mail message. + +Note that the mail backends are free to maul the poor, innocent, +incoming headers all they want to. They all add @code{Lines} headers; +some add @code{X-Gnus-Group} headers; most rename the Unix mbox +@code{From} line to something else. + +@vindex nnmail-crosspost +The mail backends all support cross-posting. If several regexps match, +the mail will be ``cross-posted'' to all those groups. +@code{nnmail-crosspost} says whether to use this mechanism or not. Note +that no articles are crossposted to the general (@samp{}) group. + +@vindex nnmail-crosspost-link-function +@cindex crosspost +@cindex links +@code{nnmh} and @code{nnml} makes crossposts by creating hard links to +the crossposted articles. However, not all file systems support hard +links. If that's the case for you, set +@code{nnmail-crosspost-link-function} to @code{copy-file}. (This +variable is @code{add-name-to-file} by default.) + +@kindex M-x nnmail-split-history +@kindex nnmail-split-history +If you wish to see where the previous mail split put the messages, you +can use the @kbd{M-x nnmail-split-history} command. + +Gnus gives you all the opportunity you could possibly want for shooting +yourself in the foot. Let's say you create a group that will contain +all the mail you get from your boss. And then you accidentally +unsubscribe from the group. Gnus will still put all the mail from your +boss in the unsubscribed group, and so, when your boss mails you ``Have +that report ready by Monday or you're fired!'', you'll never see it and, +come Tuesday, you'll still believe that you're gainfully employed while +you really should be out collecting empty bottles to save up for next +month's rent money. + + +@node Mail Backend Variables +@subsection Mail Backend Variables + +These variables are (for the most part) pertinent to all the various +mail backends. + +@table @code +@vindex nnmail-read-incoming-hook +@item nnmail-read-incoming-hook +The mail backends all call this hook after reading new mail. You can +use this hook to notify any mail watch programs, if you want to. + +@vindex nnmail-spool-file +@item nnmail-spool-file +@cindex POP mail +@cindex MAILHOST +@cindex movemail +@vindex nnmail-pop-password +@vindex nnmail-pop-password-required +The backends will look for new mail in this file. If this variable is +@code{nil}, the mail backends will never attempt to fetch mail by +themselves. If you are using a POP mail server and your name is +@samp{larsi}, you should set this variable to @samp{po:larsi}. If +your name is not @samp{larsi}, you should probably modify that +slightly, but you may have guessed that already, you smart & handsome +devil! You can also set this variable to @code{pop}, and Gnus will try +to figure out the POP mail string by itself. In any case, Gnus will +call @code{movemail} which will contact the POP server named in the +@code{MAILHOST} environment variable. If the POP server needs a +password, you can either set @code{nnmail-pop-password-required} to +@code{t} and be prompted for the password, or set +@code{nnmail-pop-password} to the password itself. + +@code{nnmail-spool-file} can also be a list of mailboxes. + +Your Emacs has to have been configured with @samp{--with-pop} before +compilation. This is the default, but some installations have it +switched off. + +When you use a mail backend, Gnus will slurp all your mail from your +inbox and plonk it down in your home directory. Gnus doesn't move any +mail if you're not using a mail backend---you have to do a lot of magic +invocations first. At the time when you have finished drawing the +pentagram, lightened the candles, and sacrificed the goat, you really +shouldn't be too surprised when Gnus moves your mail. + +@vindex nnmail-use-procmail +@vindex nnmail-procmail-suffix +@item nnmail-use-procmail +If non-@code{nil}, the mail backends will look in +@code{nnmail-procmail-directory} for incoming mail. All the files in +that directory that have names ending in @code{nnmail-procmail-suffix} +will be considered incoming mailboxes, and will be searched for new +mail. + +@vindex nnmail-crash-box +@item nnmail-crash-box +When a mail backend reads a spool file, mail is first moved to this +file, which is @file{~/.gnus-crash-box} by default. If this file +already exists, it will always be read (and incorporated) before any +other spool files. + +@vindex nnmail-prepare-incoming-hook +@item nnmail-prepare-incoming-hook +This is run in a buffer that holds all the new incoming mail, and can be +used for, well, anything, really. + +@vindex nnmail-split-hook +@item nnmail-split-hook +@findex article-decode-encoded-words +@findex RFC1522 decoding +@findex RFC2047 decoding +Hook run in the buffer where the mail headers of each message is kept +just before the splitting based on these headers is done. The hook is +free to modify the buffer contents in any way it sees fit---the buffer +is discarded after the splitting has been done, and no changes performed +in the buffer will show up in any files. +@code{gnus-article-decode-encoded-words} is one likely function to add +to this hook. + +@vindex nnmail-pre-get-new-mail-hook +@vindex nnmail-post-get-new-mail-hook +@item nnmail-pre-get-new-mail-hook +@itemx nnmail-post-get-new-mail-hook +These are two useful hooks executed when treating new incoming +mail---@code{nnmail-pre-get-new-mail-hook} (is called just before +starting to handle the new mail) and +@code{nnmail-post-get-new-mail-hook} (is called when the mail handling +is done). Here's and example of using these two hooks to change the +default file modes the new mail files get: + +@lisp +(add-hook 'gnus-pre-get-new-mail-hook + (lambda () (set-default-file-modes 511))) + +(add-hook 'gnus-post-get-new-mail-hook + (lambda () (set-default-file-modes 551))) +@end lisp + +@item nnmail-tmp-directory +@vindex nnmail-tmp-directory +This variable says where to move incoming mail to -- while processing +it. This is usually done in the same directory that the mail backend +inhabits (e.g., @file{~/Mail/}), but if this variable is non-@code{nil}, +it will be used instead. + +@item nnmail-movemail-program +@vindex nnmail-movemail-program +This program is executed to move mail from the user's inbox to her home +directory. The default is @samp{movemail}. + +This can also be a function. In that case, the function will be called +with two parameters -- the name of the inbox, and the file to be moved +to. + +@item nnmail-delete-incoming +@vindex nnmail-delete-incoming +@cindex incoming mail files +@cindex deleting incoming files +If non-@code{nil}, the mail backends will delete the temporary incoming +file after splitting mail into the proper groups. This is @code{t} by +default. + +@c This is @code{nil} by +@c default for reasons of security. + +@c Since Red Gnus is an alpha release, it is to be expected to lose mail. +(No Gnus release since (ding) Gnus 0.10 (or something like that) have +lost mail, I think, but that's not the point. (Except certain versions +of Red Gnus.)) By not deleting the Incoming* files, one can be sure not +to lose mail -- if Gnus totally whacks out, one can always recover what +was lost. + +You may delete the @file{Incoming*} files at will. + +@item nnmail-use-long-file-names +@vindex nnmail-use-long-file-names +If non-@code{nil}, the mail backends will use long file and directory +names. Groups like @samp{mail.misc} will end up in directories +(assuming use of @code{nnml} backend) or files (assuming use of +@code{nnfolder} backend) like @file{mail.misc}. If it is @code{nil}, +the same group will end up in @file{mail/misc}. + +@item nnmail-delete-file-function +@vindex nnmail-delete-file-function +@findex delete-file +Function called to delete files. It is @code{delete-file} by default. + +@item nnmail-cache-accepted-message-ids +@vindex nnmail-cache-accepted-message-ids +If non-@code{nil}, put the @code{Message-ID}s of articles imported into +the backend (via @code{Gcc}, for instance) into the mail duplication +discovery cache. The default is @code{nil}. + +@end table + + +@node Fancy Mail Splitting +@subsection Fancy Mail Splitting +@cindex mail splitting +@cindex fancy mail splitting + +@vindex nnmail-split-fancy +@findex nnmail-split-fancy +If the rather simple, standard method for specifying how to split mail +doesn't allow you to do what you want, you can set +@code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can +play with the @code{nnmail-split-fancy} variable. + +Let's look at an example value of this variable first: + +@lisp +;; Messages from the mailer daemon are not crossposted to any of +;; the ordinary groups. Warnings are put in a separate group +;; from real errors. +(| ("from" mail (| ("subject" "warn.*" "mail.warning") + "mail.misc")) + ;; Non-error messages are crossposted to all relevant + ;; groups, but we don't crosspost between the group for the + ;; (ding) list and the group for other (ding) related mail. + (& (| (any "ding@@ifi\\.uio\\.no" "ding.list") + ("subject" "ding" "ding.misc")) + ;; Other mailing lists... + (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list") + (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list") + ;; People... + (any "larsi@@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen")) + ;; Unmatched mail goes to the catch all group. + "misc.misc") +@end lisp + +This variable has the format of a @dfn{split}. A split is a (possibly) +recursive structure where each split may contain other splits. Here are +the five possible split syntaxes: + +@enumerate + +@item +@samp{group}: If the split is a string, that will be taken as a group +name. Normal regexp match expansion will be done. See below for +examples. + +@item +@var{(FIELD VALUE SPLIT)}: If the split is a list, the first element of +which is a string, then store the message as specified by SPLIT, if +header FIELD (a regexp) contains VALUE (also a regexp). + +@item +@var{(| SPLIT...)}: If the split is a list, and the first element is +@code{|} (vertical bar), then process each SPLIT until one of them +matches. A SPLIT is said to match if it will cause the mail message to +be stored in one or more groups. + +@item +@var{(& SPLIT...)}: If the split is a list, and the first element is +@code{&}, then process all SPLITs in the list. + +@item +@code{junk}: If the split is the symbol @code{junk}, then don't save +this message. Use with extreme caution. + +@item +@var{(: function arg1 arg2 ...)}: If the split is a list, and the first +element is @code{:}, then the second element will be called as a +function with @var{args} given as arguments. The function should return +a SPLIT. + +@item +@code{nil}: If the split is @code{nil}, it is ignored. + +@end enumerate + +In these splits, @var{FIELD} must match a complete field name. +@var{VALUE} must match a complete word according to the fundamental mode +syntax table. You can use @code{.*} in the regexps to match partial +field names or words. In other words, all @var{VALUE}'s are wrapped in +@samp{\<} and @samp{\>} pairs. + +@vindex nnmail-split-abbrev-alist +@var{FIELD} and @var{VALUE} can also be lisp symbols, in that case they +are expanded as specified by the variable +@code{nnmail-split-abbrev-alist}. This is an alist of cons cells, where +the @code{car} of a cell contains the key, and the @code{cdr} contains the associated +value. + +@vindex nnmail-split-fancy-syntax-table +@code{nnmail-split-fancy-syntax-table} is the syntax table in effect +when all this splitting is performed. + +If you want to have Gnus create groups dynamically based on some +information in the headers (i.e., do @code{replace-match}-like +substitutions in the group names), you can say things like: + +@example +(any "debian-\\b\\(\\w+\\)@@lists.debian.org" "mail.debian.\\1") +@end example + +If the string contains the element @samp{\&}, then the previously +matched string will be substituted. Similarly, the elements @samp{\\1} +up to @samp{\\9} will be substituted with the text matched by the +groupings 1 through 9. + + +@node Mail and Procmail +@subsection Mail and Procmail +@cindex procmail + +@cindex slocal +@cindex elm +Many people use @code{procmail} (or some other mail filter program or +external delivery agent---@code{slocal}, @code{elm}, etc) to split +incoming mail into groups. If you do that, you should set +@code{nnmail-spool-file} to @code{procmail} to ensure that the mail +backends never ever try to fetch mail by themselves. + +If you have a combined @code{procmail}/POP/mailbox setup, you can do +something like the following: + +@vindex nnmail-use-procmail +@lisp +(setq nnmail-use-procmail t) +(setq nnmail-spool-file + '("/usr/spool/mail/my-name" "po:my-name")) +@end lisp + +This also means that you probably don't want to set +@code{nnmail-split-methods} either, which has some, perhaps, unexpected +side effects. + +When a mail backend is queried for what groups it carries, it replies +with the contents of that variable, along with any groups it has figured +out that it carries by other means. None of the backends, except +@code{nnmh}, actually go out to the disk and check what groups actually +exist. (It's not trivial to distinguish between what the user thinks is +a basis for a newsgroup and what is just a plain old file or directory.) + +This means that you have to tell Gnus (and the backends) by hand what +groups exist. + +Let's take the @code{nnmh} backend as an example: + +The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}. +There are three folders, @file{foo}, @file{bar} and @file{mail.baz}. + +Go to the group buffer and type @kbd{G m}. When prompted, answer +@samp{foo} for the name and @samp{nnmh} for the method. Repeat +twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure +to include all your mail groups. + +That's it. You are now set to read your mail. An active file for this +method will be created automatically. + +@vindex nnmail-procmail-suffix +@vindex nnmail-procmail-directory +If you use @code{nnfolder} or any other backend that store more than a +single article in each file, you should never have procmail add mails to +the file that Gnus sees. Instead, procmail should put all incoming mail +in @code{nnmail-procmail-directory}. To arrive at the file name to put +the incoming mail in, append @code{nnmail-procmail-suffix} to the group +name. The mail backends will read the mail from these files. + +@vindex nnmail-resplit-incoming +When Gnus reads a file called @file{mail.misc.spool}, this mail will be +put in the @code{mail.misc}, as one would expect. However, if you want +Gnus to split the mail the normal way, you could set +@code{nnmail-resplit-incoming} to @code{t}. + +@vindex nnmail-keep-last-article +If you use @code{procmail} to split things directly into an @code{nnmh} +directory (which you shouldn't do), you should set +@code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from +ever expiring the final article (i.e., the article with the highest +article number) in a mail newsgroup. This is quite, quite important. + +Here's an example setup: The incoming spools are located in +@file{~/incoming/} and have @samp{""} as suffixes (i.e., the incoming +spool files have the same names as the equivalent groups). The +@code{nnfolder} backend is to be used as the mail interface, and the +@code{nnfolder} directory is @file{~/fMail/}. + +@lisp +(setq nnfolder-directory "~/fMail/") +(setq nnmail-spool-file 'procmail) +(setq nnmail-procmail-directory "~/incoming/") +(setq gnus-secondary-select-methods '((nnfolder ""))) +(setq nnmail-procmail-suffix "") +@end lisp + + +@node Incorporating Old Mail +@subsection Incorporating Old Mail + +Most people have lots of old mail stored in various file formats. If +you have set up Gnus to read mail using one of the spiffy Gnus mail +backends, you'll probably wish to have that old mail incorporated into +your mail groups. + +Doing so can be quite easy. + +To take an example: You're reading mail using @code{nnml} +(@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a +satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox +file filled with important, but old, mail. You want to move it into +your @code{nnml} groups. + +Here's how: + +@enumerate +@item +Go to the group buffer. + +@item +Type `G f' and give the path to the mbox file when prompted to create an +@code{nndoc} group from the mbox file (@pxref{Foreign Groups}). + +@item +Type `SPACE' to enter the newly created group. + +@item +Type `M P b' to process-mark all articles in this group's buffer +(@pxref{Setting Process Marks}). + +@item +Type `B r' to respool all the process-marked articles, and answer +@samp{nnml} when prompted (@pxref{Mail Group Commands}). +@end enumerate + +All the mail messages in the mbox file will now also be spread out over +all your @code{nnml} groups. Try entering them and check whether things +have gone without a glitch. If things look ok, you may consider +deleting the mbox file, but I wouldn't do that unless I was absolutely +sure that all the mail has ended up where it should be. + +Respooling is also a handy thing to do if you're switching from one mail +backend to another. Just respool all the mail in the old mail groups +using the new mail backend. + + +@node Expiring Mail +@subsection Expiring Mail +@cindex article expiry + +Traditional mail readers have a tendency to remove mail articles when +you mark them as read, in some way. Gnus takes a fundamentally +different approach to mail reading. + +Gnus basically considers mail just to be news that has been received in +a rather peculiar manner. It does not think that it has the power to +actually change the mail, or delete any mail messages. If you enter a +mail group, and mark articles as ``read'', or kill them in some other +fashion, the mail articles will still exist on the system. I repeat: +Gnus will not delete your old, read mail. Unless you ask it to, of +course. + +To make Gnus get rid of your unwanted mail, you have to mark the +articles as @dfn{expirable}. This does not mean that the articles will +disappear right away, however. In general, a mail article will be +deleted from your system if, 1) it is marked as expirable, AND 2) it is +more than one week old. If you do not mark an article as expirable, it +will remain on your system until hell freezes over. This bears +repeating one more time, with some spurious capitalizations: IF you do +NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES. + +@vindex gnus-auto-expirable-newsgroups +You do not have to mark articles as expirable by hand. Groups that +match the regular expression @code{gnus-auto-expirable-newsgroups} will +have all articles that you read marked as expirable automatically. All +articles marked as expirable have an @samp{E} in the first +column in the summary buffer. + +By default, if you have auto expiry switched on, Gnus will mark all the +articles you read as expirable, no matter if they were read or unread +before. To avoid having articles marked as read marked as expirable +automatically, you can put something like the following in your +@file{.gnus} file: + +@vindex gnus-mark-article-hook +@lisp +(remove-hook 'gnus-mark-article-hook + 'gnus-summary-mark-read-and-unread-as-read) +(add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read) +@end lisp + +Note that making a group auto-expirable doesn't mean that all read +articles are expired---only the articles marked as expirable +will be expired. Also note that using the @kbd{d} command won't make +groups expirable---only semi-automatic marking of articles as read will +mark the articles as expirable in auto-expirable groups. + +Let's say you subscribe to a couple of mailing lists, and you want the +articles you have read to disappear after a while: + +@lisp +(setq gnus-auto-expirable-newsgroups + "mail.nonsense-list\\|mail.nice-list") +@end lisp + +Another way to have auto-expiry happen is to have the element +@code{auto-expire} in the group parameters of the group. + +If you use adaptive scoring (@pxref{Adaptive Scoring}) and +auto-expiring, you'll have problems. Auto-expiring and adaptive scoring +don't really mix very well. + +@vindex nnmail-expiry-wait +The @code{nnmail-expiry-wait} variable supplies the default time an +expirable article has to live. Gnus starts counting days from when the +message @emph{arrived}, not from when it was sent. The default is seven +days. + +Gnus also supplies a function that lets you fine-tune how long articles +are to live, based on what group they are in. Let's say you want to +have one month expiry period in the @samp{mail.private} group, a one day +expiry period in the @samp{mail.junk} group, and a six day expiry period +everywhere else: + +@vindex nnmail-expiry-wait-function +@lisp +(setq nnmail-expiry-wait-function + (lambda (group) + (cond ((string= group "mail.private") + 31) + ((string= group "mail.junk") + 1) + ((string= group "important") + 'never) + (t + 6)))) +@end lisp + +The group names this function is fed are ``unadorned'' group +names---no @samp{nnml:} prefixes and the like. + +The @code{nnmail-expiry-wait} variable and +@code{nnmail-expiry-wait-function} function can either be a number (not +necessarily an integer) or one of the symbols @code{immediate} or +@code{never}. + +You can also use the @code{expiry-wait} group parameter to selectively +change the expiry period (@pxref{Group Parameters}). + +@vindex nnmail-keep-last-article +If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never +expire the final article in a mail newsgroup. This is to make life +easier for procmail users. + +@vindex gnus-total-expirable-newsgroups +By the way: That line up there, about Gnus never expiring non-expirable +articles, is a lie. If you put @code{total-expire} in the group +parameters, articles will not be marked as expirable, but all read +articles will be put through the expiry process. Use with extreme +caution. Even more dangerous is the +@code{gnus-total-expirable-newsgroups} variable. All groups that match +this regexp will have all read articles put through the expiry process, +which means that @emph{all} old mail articles in the groups in question +will be deleted after a while. Use with extreme caution, and don't come +crying to me when you discover that the regexp you used matched the +wrong group and all your important mail has disappeared. Be a +@emph{man}! Or a @emph{woman}! Whatever you feel more comfortable +with! So there! + +Most people make most of their mail groups total-expirable, though. + + +@node Washing Mail +@subsection Washing Mail +@cindex mail washing +@cindex list server brain damage +@cindex incoming mail treatment + +Mailers and list servers are notorious for doing all sorts of really, +really stupid things with mail. ``Hey, RFC822 doesn't explicitly +prohibit us from adding the string @code{wE aRe ElItE!!!!!1!!} to the +end of all lines passing through our server, so let's do that!!!!1!'' +Yes, but RFC822 wasn't designed to be read by morons. Things that were +considered to be self-evident were not discussed. So. Here we are. + +Case in point: The German version of Microsoft Exchange adds @samp{AW: +} to the subjects of replies instead of @samp{Re: }. I could pretend to +be shocked and dismayed by this, but I haven't got the energy. It is to +laugh. + +Gnus provides a plethora of functions for washing articles while +displaying them, but it might be nicer to do the filtering before +storing the mail to disc. For that purpose, we have three hooks and +various functions that can be put in these hooks. + +@table @code +@item nnmail-prepare-incoming-hook +@vindex nnmail-prepare-incoming-hook +This hook is called before doing anything with the mail and is meant for +grand, sweeping gestures. Functions to be used include: + +@table @code +@item nnheader-ms-strip-cr +@findex nnheader-ms-strip-cr +Remove trailing carriage returns from each line. This is default on +Emacs running on MS machines. + +@end table + +@item nnmail-prepare-incoming-header-hook +@vindex nnmail-prepare-incoming-header-hook +This hook is called narrowed to each header. It can be used when +cleaning up the headers. Functions that can be used include: + +@table @code +@item nnmail-remove-leading-whitespace +@findex nnmail-remove-leading-whitespace +Clear leading white space that ``helpful'' listservs have added to the +headers to make them look nice. Aaah. + +@item nnmail-remove-list-identifiers +@findex nnmail-remove-list-identifiers +Some list servers add an identifier---for example, @samp{(idm)}---to the +beginning of all @code{Subject} headers. I'm sure that's nice for +people who use stone age mail readers. This function will remove +strings that match the @code{nnmail-list-identifiers} regexp, which can +also be a list of regexp. + +For instance, if you want to remove the @samp{(idm)} and the +@samp{nagnagnag} identifiers: + +@lisp +(setq nnmail-list-identifiers + '("(idm)" "nagnagnag")) +@end lisp + +@item nnmail-remove-tabs +@findex nnmail-remove-tabs +Translate all @samp{TAB} characters into @samp{SPACE} characters. + +@end table + +@item nnmail-prepare-incoming-message-hook +@vindex nnmail-prepare-incoming-message-hook +This hook is called narrowed to each message. Functions to be used +include: + +@table @code +@item article-de-quoted-unreadable +@findex article-de-quoted-unreadable +Decode Quoted Readable encoding. + +@end table +@end table + + +@node Duplicates +@subsection Duplicates + +@vindex nnmail-treat-duplicates +@vindex nnmail-message-id-cache-length +@vindex nnmail-message-id-cache-file +@cindex duplicate mails +If you are a member of a couple of mailing lists, you will sometimes +receive two copies of the same mail. This can be quite annoying, so +@code{nnmail} checks for and treats any duplicates it might find. To do +this, it keeps a cache of old @code{Message-ID}s--- +@code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by +default. The approximate maximum number of @code{Message-ID}s stored +there is controlled by the @code{nnmail-message-id-cache-length} +variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be +stored.) If all this sounds scary to you, you can set +@code{nnmail-treat-duplicates} to @code{warn} (which is what it is by +default), and @code{nnmail} won't delete duplicate mails. Instead it +will insert a warning into the head of the mail saying that it thinks +that this is a duplicate of a different message. + +This variable can also be a function. If that's the case, the function +will be called from a buffer narrowed to the message in question with +the @code{Message-ID} as a parameter. The function must return either +@code{nil}, @code{warn}, or @code{delete}. + +You can turn this feature off completely by setting the variable to +@code{nil}. + +If you want all the duplicate mails to be put into a special +@dfn{duplicates} group, you could do that using the normal mail split +methods: + +@lisp +(setq nnmail-split-fancy + '(| ;; Messages duplicates go to a separate group. + ("gnus-warning" "duplication of message" "duplicate") + ;; Message from daemons, postmaster, and the like to another. + (any mail "mail.misc") + ;; Other rules. + [ ... ] )) +@end lisp + +Or something like: +@lisp +(setq nnmail-split-methods + '(("duplicates" "^Gnus-Warning:") + ;; Other rules. + [...])) +@end lisp + +Here's a neat feature: If you know that the recipient reads her mail +with Gnus, and that she has @code{nnmail-treat-duplicates} set to +@code{delete}, you can send her as many insults as you like, just by +using a @code{Message-ID} of a mail that you know that she's already +received. Think of all the fun! She'll never see any of it! Whee! + + +@node Not Reading Mail +@subsection Not Reading Mail + +If you start using any of the mail backends, they have the annoying +habit of assuming that you want to read mail with them. This might not +be unreasonable, but it might not be what you want. + +If you set @code{nnmail-spool-file} to @code{nil}, none of the backends +will ever attempt to read incoming mail, which should help. + +@vindex nnbabyl-get-new-mail +@vindex nnmbox-get-new-mail +@vindex nnml-get-new-mail +@vindex nnmh-get-new-mail +@vindex nnfolder-get-new-mail +This might be too much, if, for instance, you are reading mail quite +happily with @code{nnml} and just want to peek at some old @sc{rmail} +file you have stashed away with @code{nnbabyl}. All backends have +variables called backend-@code{get-new-mail}. If you want to disable +the @code{nnbabyl} mail reading, you edit the virtual server for the +group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}. + +All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook} +narrowed to the article to be saved before saving it when reading +incoming mail. + + +@node Choosing a Mail Backend +@subsection Choosing a Mail Backend + +Gnus will read the mail spool when you activate a mail group. The mail +file is first copied to your home directory. What happens after that +depends on what format you want to store your mail in. + +@menu +* Unix Mail Box:: Using the (quite) standard Un*x mbox. +* Rmail Babyl:: Emacs programs use the rmail babyl format. +* Mail Spool:: Store your mail in a private spool? +* MH Spool:: An mhspool-like backend. +* Mail Folders:: Having one file for each group. +@end menu + + +@node Unix Mail Box +@subsubsection Unix Mail Box +@cindex nnmbox +@cindex unix mail box + +@vindex nnmbox-active-file +@vindex nnmbox-mbox-file +The @dfn{nnmbox} backend will use the standard Un*x mbox file to store +mail. @code{nnmbox} will add extra headers to each mail article to say +which group it belongs in. + +Virtual server settings: + +@table @code +@item nnmbox-mbox-file +@vindex nnmbox-mbox-file +The name of the mail box in the user's home directory. + +@item nnmbox-active-file +@vindex nnmbox-active-file +The name of the active file for the mail box. + +@item nnmbox-get-new-mail +@vindex nnmbox-get-new-mail +If non-@code{nil}, @code{nnmbox} will read incoming mail and split it +into groups. +@end table + + +@node Rmail Babyl +@subsubsection Rmail Babyl +@cindex nnbabyl +@cindex rmail mbox + +@vindex nnbabyl-active-file +@vindex nnbabyl-mbox-file +The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail +mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail +article to say which group it belongs in. + +Virtual server settings: + +@table @code +@item nnbabyl-mbox-file +@vindex nnbabyl-mbox-file +The name of the rmail mbox file. + +@item nnbabyl-active-file +@vindex nnbabyl-active-file +The name of the active file for the rmail box. + +@item nnbabyl-get-new-mail +@vindex nnbabyl-get-new-mail +If non-@code{nil}, @code{nnbabyl} will read incoming mail. +@end table + + +@node Mail Spool +@subsubsection Mail Spool +@cindex nnml +@cindex mail @sc{nov} spool + +The @dfn{nnml} spool mail format isn't compatible with any other known +format. It should be used with some caution. + +@vindex nnml-directory +If you use this backend, Gnus will split all incoming mail into files, +one file for each mail, and put the articles into the corresponding +directories under the directory specified by the @code{nnml-directory} +variable. The default value is @file{~/Mail/}. + +You do not have to create any directories beforehand; Gnus will take +care of all that. + +If you have a strict limit as to how many files you are allowed to store +in your account, you should not use this backend. As each mail gets its +own file, you might very well occupy thousands of inodes within a few +weeks. If this is no problem for you, and it isn't a problem for you +having your friendly systems administrator walking around, madly, +shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should +know that this is probably the fastest format to use. You do not have +to trudge through a big mbox file just to read your new mail. + +@code{nnml} is probably the slowest backend when it comes to article +splitting. It has to create lots of files, and it also generates +@sc{nov} databases for the incoming mails. This makes it the fastest +backend when it comes to reading mail. + +Virtual server settings: + +@table @code +@item nnml-directory +@vindex nnml-directory +All @code{nnml} directories will be placed under this directory. + +@item nnml-active-file +@vindex nnml-active-file +The active file for the @code{nnml} server. + +@item nnml-newsgroups-file +@vindex nnml-newsgroups-file +The @code{nnml} group descriptions file. @xref{Newsgroups File +Format}. + +@item nnml-get-new-mail +@vindex nnml-get-new-mail +If non-@code{nil}, @code{nnml} will read incoming mail. + +@item nnml-nov-is-evil +@vindex nnml-nov-is-evil +If non-@code{nil}, this backend will ignore any @sc{nov} files. + +@item nnml-nov-file-name +@vindex nnml-nov-file-name +The name of the @sc{nov} files. The default is @file{.overview}. + +@item nnml-prepare-save-mail-hook +@vindex nnml-prepare-save-mail-hook +Hook run narrowed to an article before saving. + +@end table + +@findex nnml-generate-nov-databases +If your @code{nnml} groups and @sc{nov} files get totally out of whack, +you can do a complete update by typing @kbd{M-x +nnml-generate-nov-databases}. This command will trawl through the +entire @code{nnml} hierarchy, looking at each and every article, so it +might take a while to complete. A better interface to this +functionality can be found in the server buffer (@pxref{Server +Commands}). + + +@node MH Spool +@subsubsection MH Spool +@cindex nnmh +@cindex mh-e mail spool + +@code{nnmh} is just like @code{nnml}, except that is doesn't generate +@sc{nov} databases and it doesn't keep an active file. This makes +@code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also +makes it easier to write procmail scripts for. + +Virtual server settings: + +@table @code +@item nnmh-directory +@vindex nnmh-directory +All @code{nnmh} directories will be located under this directory. + +@item nnmh-get-new-mail +@vindex nnmh-get-new-mail +If non-@code{nil}, @code{nnmh} will read incoming mail. + +@item nnmh-be-safe +@vindex nnmh-be-safe +If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make +sure that the articles in the folder are actually what Gnus thinks they +are. It will check date stamps and stat everything in sight, so +setting this to @code{t} will mean a serious slow-down. If you never +use anything but Gnus to read the @code{nnmh} articles, you do not have +to set this variable to @code{t}. +@end table + + +@node Mail Folders +@subsubsection Mail Folders +@cindex nnfolder +@cindex mbox folders +@cindex mail folders + +@code{nnfolder} is a backend for storing each mail group in a separate +file. Each file is in the standard Un*x mbox format. @code{nnfolder} +will add extra headers to keep track of article numbers and arrival +dates. + +Virtual server settings: + +@table @code +@item nnfolder-directory +@vindex nnfolder-directory +All the @code{nnfolder} mail boxes will be stored under this directory. + +@item nnfolder-active-file +@vindex nnfolder-active-file +The name of the active file. + +@item nnfolder-newsgroups-file +@vindex nnfolder-newsgroups-file +The name of the group descriptions file. @xref{Newsgroups File Format}. + +@item nnfolder-get-new-mail +@vindex nnfolder-get-new-mail +If non-@code{nil}, @code{nnfolder} will read incoming mail. + +@item nnfolder-save-buffer-hook +@vindex nnfolder-save-buffer-hook +@cindex backup files +Hook run before saving the folders. Note that Emacs does the normal +backup renaming of files even with the @code{nnfolder} buffers. If you +wish to switch this off, you could say something like the following in +your @file{.emacs} file: + +@lisp +(defun turn-off-backup () + (set (make-local-variable 'backup-inhibited) t)) + +(add-hook 'nnfolder-save-buffer-hook 'turn-off-backup) +@end lisp + +@item nnfolder-delete-mail-hook +@vindex nnfolder-delete-mail-hook +Hook run in a buffer narrowed to the message that is to be deleted. +This function can be used to copy the message to somewhere else, or to +extract some information from it before removing it. + +@end table + + +@findex nnfolder-generate-active-file +@kindex M-x nnfolder-generate-active-file +If you have lots of @code{nnfolder}-like files you'd like to read with +@code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file} +command to make @code{nnfolder} aware of all likely files in +@code{nnfolder-directory}. + + +@node Other Sources +@section Other Sources + +Gnus can do more than just read news or mail. The methods described +below allow Gnus to view directories and files as if they were +newsgroups. + +@menu +* 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''. +* Web Searches:: Creating groups from articles that match a string. +* Mail-To-News Gateways:: Posting articles via mail-to-news gateways. +@end menu + + +@node Directory Groups +@subsection Directory Groups +@cindex nndir +@cindex directory groups + +If you have a directory that has lots of articles in separate files in +it, you might treat it as a newsgroup. The files have to have numerical +names, of course. + +This might be an opportune moment to mention @code{ange-ftp} (and its +successor @code{efs}), that most wonderful of all wonderful Emacs +packages. When I wrote @code{nndir}, I didn't think much about it---a +backend to read directories. Big deal. + +@code{ange-ftp} changes that picture dramatically. For instance, if you +enter the @code{ange-ftp} file name +@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name, +@code{ange-ftp} or @code{efs} will actually allow you to read this +directory over at @samp{sina} as a newsgroup. Distributed news ahoy! + +@code{nndir} will use @sc{nov} files if they are present. + +@code{nndir} is a ``read-only'' backend---you can't delete or expire +articles with this method. You can use @code{nnmh} or @code{nnml} for +whatever you use @code{nndir} for, so you could switch to any of those +methods if you feel the need to have a non-read-only @code{nndir}. + + +@node Anything Groups +@subsection Anything Groups +@cindex nneething + +From the @code{nndir} backend (which reads a single spool-like +directory), it's just a hop and a skip to @code{nneething}, which +pretends that any arbitrary directory is a newsgroup. Strange, but +true. + +When @code{nneething} is presented with a directory, it will scan this +directory and assign article numbers to each file. When you enter such +a group, @code{nneething} must create ``headers'' that Gnus can use. +After all, Gnus is a newsreader, in case you're +forgetting. @code{nneething} does this in a two-step process. First, it +snoops each file in question. If the file looks like an article (i.e., +the first few lines look like headers), it will use this as the head. +If this is just some arbitrary file without a head (e.g. a C source +file), @code{nneething} will cobble up a header out of thin air. It +will use file ownership, name and date and do whatever it can with these +elements. + +All this should happen automatically for you, and you will be presented +with something that looks very much like a newsgroup. Totally like a +newsgroup, to be precise. If you select an article, it will be displayed +in the article buffer, just as usual. + +If you select a line that represents a directory, Gnus will pop you into +a new summary buffer for this @code{nneething} group. And so on. You can +traverse the entire disk this way, if you feel like, but remember that +Gnus is not dired, really, and does not intend to be, either. + +There are two overall modes to this action---ephemeral or solid. When +doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus +will not store information on what files you have read, and what files +are new, and so on. If you create a solid @code{nneething} group the +normal way with @kbd{G m}, Gnus will store a mapping table between +article numbers and file names, and you can treat this group like any +other groups. When you activate a solid @code{nneething} group, you will +be told how many unread articles it contains, etc., etc. + +Some variables: + +@table @code +@item nneething-map-file-directory +@vindex nneething-map-file-directory +All the mapping files for solid @code{nneething} groups will be stored +in this directory, which defaults to @file{~/.nneething/}. + +@item nneething-exclude-files +@vindex nneething-exclude-files +All files that match this regexp will be ignored. Nice to use to exclude +auto-save files and the like, which is what it does by default. + +@item nneething-map-file +@vindex nneething-map-file +Name of the map files. +@end table + + +@node Document Groups +@subsection Document Groups +@cindex nndoc +@cindex documentation group +@cindex help group + +@code{nndoc} is a cute little thing that will let you read a single file +as a newsgroup. Several files types are supported: + +@table @code +@cindex babyl +@cindex rmail mbox + +@item babyl +The babyl (rmail) mail box. +@cindex mbox +@cindex Unix mbox + +@item mbox +The standard Unix mbox file. + +@cindex MMDF mail box +@item mmdf +The MMDF mail box format. + +@item news +Several news articles appended into a file. + +@item rnews +@cindex rnews batch files +The rnews batch transport format. +@cindex forwarded messages + +@item forward +Forwarded articles. + +@item mime-parts +MIME multipart messages, besides digests. + +@item mime-digest +@cindex digest +@cindex MIME digest +@cindex 1153 digest +@cindex RFC 1153 digest +@cindex RFC 341 digest +MIME (RFC 1341) digest format. + +@item standard-digest +The standard (RFC 1153) digest format. + +@item slack-digest +Non-standard digest format---matches most things, but does it badly. +@end table + +You can also use the special ``file type'' @code{guess}, which means +that @code{nndoc} will try to guess what file type it is looking at. +@code{digest} means that @code{nndoc} should guess what digest type the +file is. + +@code{nndoc} will not try to change the file or insert any extra headers into +it---it will simply, like, let you use the file as the basis for a +group. And that's it. + +If you have some old archived articles that you want to insert into your +new & spiffy Gnus mail backend, @code{nndoc} can probably help you with +that. Say you have an old @file{RMAIL} file with mail that you now want +to split into your new @code{nnml} groups. You look at that file using +@code{nndoc} (using the @kbd{G f} command in the group buffer +(@pxref{Foreign Groups})), set the process mark on all the articles in +the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r}) +using @code{nnml}. If all goes well, all the mail in the @file{RMAIL} +file is now also stored in lots of @code{nnml} directories, and you can +delete that pesky @file{RMAIL} file. If you have the guts! + +Virtual server variables: + +@table @code +@item nndoc-article-type +@vindex nndoc-article-type +This should be one of @code{mbox}, @code{babyl}, @code{digest}, +@code{news}, @code{rnews}, @code{mmdf}, @code{forward}, @code{rfc934}, +@code{rfc822-forward}, @code{mime-parts}, @code{mime-digest}, +@code{standard-digest}, @code{slack-digest}, @code{clari-briefs} or +@code{guess}. + +@item nndoc-post-type +@vindex nndoc-post-type +This variable says whether Gnus is to consider the group a news group or +a mail group. There are two valid values: @code{mail} (the default) +and @code{news}. +@end table + +@menu +* Document Server Internals:: How to add your own document types. +@end menu + + +@node Document Server Internals +@subsubsection Document Server Internals + +Adding new document types to be recognized by @code{nndoc} isn't +difficult. You just have to whip up a definition of what the document +looks like, write a predicate function to recognize that document type, +and then hook into @code{nndoc}. + +First, here's an example document type definition: + +@example +(mmdf + (article-begin . "^\^A\^A\^A\^A\n") + (body-end . "^\^A\^A\^A\^A\n")) +@end example + +The definition is simply a unique @dfn{name} followed by a series of +regexp pseudo-variable settings. Below are the possible +variables---don't be daunted by the number of variables; most document +types can be defined with very few settings: + +@table @code +@item first-article +If present, @code{nndoc} will skip past all text until it finds +something that match this regexp. All text before this will be +totally ignored. + +@item article-begin +This setting has to be present in all document type definitions. It +says what the beginning of each article looks like. + +@item head-begin-function +If present, this should be a function that moves point to the head of +the article. + +@item nndoc-head-begin +If present, this should be a regexp that matches the head of the +article. + +@item nndoc-head-end +This should match the end of the head of the article. It defaults to +@samp{^$}---the empty line. + +@item body-begin-function +If present, this function should move point to the beginning of the body +of the article. + +@item body-begin +This should match the beginning of the body of the article. It defaults +to @samp{^\n}. + +@item body-end-function +If present, this function should move point to the end of the body of +the article. + +@item body-end +If present, this should match the end of the body of the article. + +@item file-end +If present, this should match the end of the file. All text after this +regexp will be totally ignored. + +@end table + +So, using these variables @code{nndoc} is able to dissect a document +file into a series of articles, each with a head and a body. However, a +few more variables are needed since not all document types are all that +news-like---variables needed to transform the head or the body into +something that's palatable for Gnus: + +@table @code +@item prepare-body-function +If present, this function will be called when requesting an article. It +will be called with point at the start of the body, and is useful if the +document has encoded some parts of its contents. + +@item article-transform-function +If present, this function is called when requesting an article. It's +meant to be used for more wide-ranging transformation of both head and +body of the article. + +@item generate-head-function +If present, this function is called to generate a head that Gnus can +understand. It is called with the article number as a parameter, and is +expected to generate a nice head for the article in question. It is +called when requesting the headers of all articles. + +@end table + +Let's look at the most complicated example I can come up with---standard +digests: + +@example +(standard-digest + (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+")) + (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+")) + (prepare-body-function . nndoc-unquote-dashes) + (body-end-function . nndoc-digest-body-end) + (head-end . "^ ?$") + (body-begin . "^ ?\n") + (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$") + (subtype digest guess)) +@end example + +We see that all text before a 70-width line of dashes is ignored; all +text after a line that starts with that @samp{^End of} is also ignored; +each article begins with a 30-width line of dashes; the line separating +the head from the body may contain a single space; and that the body is +run through @code{nndoc-unquote-dashes} before being delivered. + +To hook your own document definition into @code{nndoc}, use the +@code{nndoc-add-type} function. It takes two parameters---the first is +the definition itself and the second (optional) parameter says where in +the document type definition alist to put this definition. The alist is +traversed sequentially, and @code{nndoc-TYPE-type-p} is called for a given type @code{TYPE}. So @code{nndoc-mmdf-type-p} is called to see whether a document +is of @code{mmdf} type, and so on. These type predicates should return +@code{nil} if the document is not of the correct type; @code{t} if it is +of the correct type; and a number if the document might be of the +correct type. A high number means high probability; a low number means +low probability with @samp{0} being the lowest valid number. + + +@node SOUP +@subsection SOUP +@cindex SOUP +@cindex offline + +In the PC world people often talk about ``offline'' newsreaders. These +are thingies that are combined reader/news transport monstrosities. +With built-in modem programs. Yecchh! + +Of course, us Unix Weenie types of human beans use things like +@code{uucp} and, like, @code{nntpd} and set up proper news and mail +transport things like Ghod intended. And then we just use normal +newsreaders. + +However, it can sometimes be convenient to do something a that's a bit +easier on the brain if you have a very slow modem, and you're not really +that interested in doing things properly. + +A file format called @sc{soup} has been developed for transporting news +and mail from servers to home machines and back again. It can be a bit +fiddly. + +First some terminology: + +@table @dfn + +@item server +This is the machine that is connected to the outside world and where you +get news and/or mail from. + +@item home machine +This is the machine that you want to do the actual reading and responding +on. It is typically not connected to the rest of the world in any way. + +@item packet +Something that contains messages and/or commands. There are two kinds +of packets: + +@table @dfn +@item message packets +These are packets made at the server, and typically contain lots of +messages for you to read. These are called @file{SoupoutX.tgz} by +default, where @var{X} is a number. + +@item response packets +These are packets made at the home machine, and typically contains +replies that you've written. These are called @file{SoupinX.tgz} by +default, where @var{X} is a number. + +@end table + +@end table + + +@enumerate + +@item +You log in on the server and create a @sc{soup} packet. You can either +use a dedicated @sc{soup} thingie (like the @code{awk} program), or you +can use Gnus to create the packet with its @sc{soup} commands (@kbd{O +s} and/or @kbd{G s b}; and then @kbd{G s p}) (@pxref{SOUP Commands}). + +@item +You transfer the packet home. Rail, boat, car or modem will do fine. + +@item +You put the packet in your home directory. + +@item +You fire up Gnus on your home machine using the @code{nnsoup} backend as +the native or secondary server. + +@item +You read articles and mail and answer and followup to the things you +want (@pxref{SOUP Replies}). + +@item +You do the @kbd{G s r} command to pack these replies into a @sc{soup} +packet. + +@item +You transfer this packet to the server. + +@item +You use Gnus to mail this packet out with the @kbd{G s s} command. + +@item +You then repeat until you die. + +@end enumerate + +So you basically have a bipartite system---you use @code{nnsoup} for +reading and Gnus for packing/sending these @sc{soup} packets. + +@menu +* SOUP Commands:: Commands for creating and sending @sc{soup} packets +* SOUP Groups:: A backend for reading @sc{soup} packets. +* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news. +@end menu + + +@node SOUP Commands +@subsubsection SOUP Commands + +These are commands for creating and manipulating @sc{soup} packets. + +@table @kbd +@item G s b +@kindex G s b (Group) +@findex gnus-group-brew-soup +Pack all unread articles in the current group +(@code{gnus-group-brew-soup}). This command understands the +process/prefix convention. + +@item G s w +@kindex G s w (Group) +@findex gnus-soup-save-areas +Save all @sc{soup} data files (@code{gnus-soup-save-areas}). + +@item G s s +@kindex G s s (Group) +@findex gnus-soup-send-replies +Send all replies from the replies packet +(@code{gnus-soup-send-replies}). + +@item G s p +@kindex G s p (Group) +@findex gnus-soup-pack-packet +Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}). + +@item G s r +@kindex G s r (Group) +@findex nnsoup-pack-replies +Pack all replies into a replies packet (@code{nnsoup-pack-replies}). + +@item O s +@kindex O s (Summary) +@findex gnus-soup-add-article +This summary-mode command adds the current article to a @sc{soup} packet +(@code{gnus-soup-add-article}). It understands the process/prefix +convention (@pxref{Process/Prefix}). + +@end table + + +There are a few variables to customize where Gnus will put all these +thingies: + +@table @code + +@item gnus-soup-directory +@vindex gnus-soup-directory +Directory where Gnus will save intermediate files while composing +@sc{soup} packets. The default is @file{~/SoupBrew/}. + +@item gnus-soup-replies-directory +@vindex gnus-soup-replies-directory +This is what Gnus will use as a temporary directory while sending our +reply packets. @file{~/SoupBrew/SoupReplies/} is the default. + +@item gnus-soup-prefix-file +@vindex gnus-soup-prefix-file +Name of the file where Gnus stores the last used prefix. The default is +@samp{gnus-prefix}. + +@item gnus-soup-packer +@vindex gnus-soup-packer +A format string command for packing a @sc{soup} packet. The default is +@samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}. + +@item gnus-soup-unpacker +@vindex gnus-soup-unpacker +Format string command for unpacking a @sc{soup} packet. The default is +@samp{gunzip -c %s | tar xvf -}. + +@item gnus-soup-packet-directory +@vindex gnus-soup-packet-directory +Where Gnus will look for reply packets. The default is @file{~/}. + +@item gnus-soup-packet-regexp +@vindex gnus-soup-packet-regexp +Regular expression matching @sc{soup} reply packets in +@code{gnus-soup-packet-directory}. + +@end table + + +@node SOUP Groups +@subsubsection @sc{soup} Groups +@cindex nnsoup + +@code{nnsoup} is the backend for reading @sc{soup} packets. It will +read incoming packets, unpack them, and put them in a directory where +you can read them at leisure. + +These are the variables you can use to customize its behavior: + +@table @code + +@item nnsoup-tmp-directory +@vindex nnsoup-tmp-directory +When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this +directory. (@file{/tmp/} by default.) + +@item nnsoup-directory +@vindex nnsoup-directory +@code{nnsoup} then moves each message and index file to this directory. +The default is @file{~/SOUP/}. + +@item nnsoup-replies-directory +@vindex nnsoup-replies-directory +All replies will be stored in this directory before being packed into a +reply packet. The default is @file{~/SOUP/replies/"}. + +@item nnsoup-replies-format-type +@vindex nnsoup-replies-format-type +The @sc{soup} format of the replies packets. The default is @samp{?n} +(rnews), and I don't think you should touch that variable. I probably +shouldn't even have documented it. Drats! Too late! + +@item nnsoup-replies-index-type +@vindex nnsoup-replies-index-type +The index type of the replies packet. The default is @samp{?n}, which +means ``none''. Don't fiddle with this one either! + +@item nnsoup-active-file +@vindex nnsoup-active-file +Where @code{nnsoup} stores lots of information. This is not an ``active +file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose +this file or mess it up in any way, you're dead. The default is +@file{~/SOUP/active}. + +@item nnsoup-packer +@vindex nnsoup-packer +Format string command for packing a reply @sc{soup} packet. The default +is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}. + +@item nnsoup-unpacker +@vindex nnsoup-unpacker +Format string command for unpacking incoming @sc{soup} packets. The +default is @samp{gunzip -c %s | tar xvf -}. + +@item nnsoup-packet-directory +@vindex nnsoup-packet-directory +Where @code{nnsoup} will look for incoming packets. The default is +@file{~/}. + +@item nnsoup-packet-regexp +@vindex nnsoup-packet-regexp +Regular expression matching incoming @sc{soup} packets. The default is +@samp{Soupout}. + +@item nnsoup-always-save +@vindex nnsoup-always-save +If non-@code{nil}, save the replies buffer after each posted message. + +@end table + + +@node SOUP Replies +@subsubsection SOUP Replies + +Just using @code{nnsoup} won't mean that your postings and mailings end +up in @sc{soup} reply packets automagically. You have to work a bit +more for that to happen. + +@findex nnsoup-set-variables +The @code{nnsoup-set-variables} command will set the appropriate +variables to ensure that all your followups and replies end up in the +@sc{soup} system. + +In specific, this is what it does: + +@lisp +(setq message-send-news-function 'nnsoup-request-post) +(setq message-send-mail-function 'nnsoup-request-mail) +@end lisp + +And that's it, really. If you only want news to go into the @sc{soup} +system you just use the first line. If you only want mail to be +@sc{soup}ed you use the second. + + +@node Web Searches +@subsection Web Searches +@cindex nnweb +@cindex DejaNews +@cindex Alta Vista +@cindex InReference +@cindex Usenet searches +@cindex searching the Usenet + +It's, like, too neat to search the Usenet for articles that match a +string, but it, like, totally @emph{sucks}, like, totally, to use one of +those, like, Web browsers, and you, like, have to, rilly, like, look at +the commercials, so, like, with Gnus you can do @emph{rad}, rilly, +searches without having to use a browser. + +The @code{nnweb} backend allows an easy interface to the mighty search +engine. You create an @code{nnweb} group, enter a search pattern, and +then enter the group and read the articles like you would any normal +group. The @kbd{G w} command in the group buffer (@pxref{Foreign +Groups}) will do this in an easy-to-use fashion. + +@code{nnweb} groups don't really lend themselves to being solid +groups---they have a very fleeting idea of article numbers. In fact, +each time you enter an @code{nnweb} group (not even changing the search +pattern), you are likely to get the articles ordered in a different +manner. Not even using duplicate suppression (@pxref{Duplicate +Suppression}) will help, since @code{nnweb} doesn't even know the +@code{Message-ID} of the articles before reading them using some search +engines (DejaNews, for instance). The only possible way to keep track +of which articles you've read is by scoring on the @code{Date} +header---mark all articles posted before the last date you read the +group as read. + +If the search engine changes its output substantially, @code{nnweb} +won't be able to parse it and will fail. One could hardly fault the Web +providers if they were to do this---their @emph{raison d',Aj(Btre} is to +make money off of advertisements, not to provide services to the +community. Since @code{nnweb} washes the ads off all the articles, one +might think that the providers might be somewhat miffed. We'll see. + +You must have the @code{url} and @code{w3} package installed to be able +to use @code{nnweb}. + +Virtual server variables: + +@table @code +@item nnweb-type +@vindex nnweb-type +What search engine type is being used. The currently supported types +are @code{dejanews}, @code{dejanewsold}, @code{altavista} and +@code{reference}. + +@item nnweb-search +@vindex nnweb-search +The search string to feed to the search engine. + +@item nnweb-max-hits +@vindex nnweb-max-hits +Advisory maximum number of hits per search to display. The default is +100. + +@item nnweb-type-definition +@vindex nnweb-type-definition +Type-to-definition alist. This alist says what @code{nnweb} should do +with the various search engine types. The following elements must be +present: + +@table @code +@item article +Function to decode the article and provide something that Gnus +understands. + +@item map +Function to create an article number to message header and URL alist. + +@item search +Function to send the search string to the search engine. + +@item address +The address the aforementioned function should send the search string +to. + +@item id +Format string URL to fetch an article by @code{Message-ID}. +@end table + +@end table + + + +@node Mail-To-News Gateways +@subsection Mail-To-News Gateways +@cindex mail-to-news gateways +@cindex gateways + +If your local @code{nntp} server doesn't allow posting, for some reason +or other, you can post using one of the numerous mail-to-news gateways. +The @code{nngateway} backend provides the interface. + +Note that you can't read anything from this backend---it can only be +used to post with. + +Server variables: + +@table @code +@item nngateway-address +@vindex nngateway-address +This is the address of the mail-to-news gateway. + +@item nngateway-header-transformation +@vindex nngateway-header-transformation +News headers often have to be transformed in some odd way or other +for the mail-to-news gateway to accept it. This variable says what +transformation should be called, and defaults to +@code{nngateway-simple-header-transformation}. The function is called +narrowed to the headers to be transformed and with one parameter---the +gateway address. + +This default function just inserts a new @code{To} header based on the +@code{Newsgroups} header and the gateway address. +For instance, an article with this @code{Newsgroups} header: + +@example +Newsgroups: alt.religion.emacs +@end example + +will get this @code{From} header inserted: + +@example +To: alt-religion-emacs@@GATEWAY +@end example + +The following pre-defined functions exist: + +@findex nngateway-simple-header-transformation +@table @code + +@item nngateway-simple-header-transformation +Creates a @code{To} header that looks like +@var{newsgroup}@@@code{nngateway-address}. + +@findex nngateway-mail2news-header-transformation + +@item nngateway-mail2news-header-transformation +Creates a @code{To} header that looks like +@code{nngateway-address}. + +Here's an example: + +@lisp +(setq gnus-post-method + '(nngateway "mail2news@@replay.com" + (nngateway-header-transformation + nngateway-mail2news-header-transformation))) +@end lisp + +@end table + + +@end table + +So, to use this, simply say something like: + +@lisp +(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS")) +@end lisp + + +@node Combined Groups +@section Combined Groups + +Gnus allows combining a mixture of all the other group types into bigger +groups. + +@menu +* Virtual Groups:: Combining articles from many groups. +* Kibozed Groups:: Looking through parts of the newsfeed for articles. +@end menu + + +@node Virtual Groups +@subsection Virtual Groups +@cindex nnvirtual +@cindex virtual groups +@cindex merging groups + +An @dfn{nnvirtual group} is really nothing more than a collection of +other groups. + +For instance, if you are tired of reading many small groups, you can +put them all in one big group, and then grow tired of reading one +big, unwieldy group. The joys of computing! + +You specify @code{nnvirtual} as the method. The address should be a +regexp to match component groups. + +All marks in the virtual group will stick to the articles in the +component groups. So if you tick an article in a virtual group, the +article will also be ticked in the component group from whence it came. +(And vice versa---marks from the component groups will also be shown in +the virtual group.) + +Here's an example @code{nnvirtual} method that collects all Andrea Dworkin +newsgroups into one, big, happy newsgroup: + +@lisp +(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*") +@end lisp + +The component groups can be native or foreign; everything should work +smoothly, but if your computer explodes, it was probably my fault. + +Collecting the same group from several servers might actually be a good +idea if users have set the Distribution header to limit distribution. +If you would like to read @samp{soc.motss} both from a server in Japan +and a server in Norway, you could use the following as the group regexp: + +@example +"^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$" +@end example + +(Remember, though, that if you're creating the group with @kbd{G m}, you +shouldn't double the backslashes, and you should leave off the quote +characters at the beginning and the end of the string.) + +This should work kinda smoothly---all articles from both groups should +end up in this one, and there should be no duplicates. Threading (and +the rest) will still work as usual, but there might be problems with the +sequence of articles. Sorting on date might be an option here +(@pxref{Selecting a Group}). + +One limitation, however---all groups included in a virtual +group have to be alive (i.e., subscribed or unsubscribed). Killed or +zombie groups can't be component groups for @code{nnvirtual} groups. + +@vindex nnvirtual-always-rescan +If the @code{nnvirtual-always-rescan} is non-@code{nil}, +@code{nnvirtual} will always scan groups for unread articles when +entering a virtual group. If this variable is @code{nil} (which is the +default) and you read articles in a component group after the virtual +group has been activated, the read articles from the component group +will show up when you enter the virtual group. You'll also see this +effect if you have two virtual groups that have a component group in +common. If that's the case, you should set this variable to @code{t}. +Or you can just tap @code{M-g} on the virtual group every time before +you enter it---it'll have much the same effect. + +@code{nnvirtual} can have both mail and news groups as component groups. +When responding to articles in @code{nnvirtual} groups, @code{nnvirtual} +has to ask the backend of the component group the article comes from +whether it is a news or mail backend. However, when you do a @kbd{^}, +there is typically no sure way for the component backend to know this, +and in that case @code{nnvirtual} tells Gnus that the article came from a +not-news backend. (Just to be on the safe side.) + +@kbd{C-c C-t} in the message buffer will insert the @code{Newsgroups} +line from the article you respond to in these cases. + + + +@node Kibozed Groups +@subsection Kibozed Groups +@cindex nnkiboze +@cindex kibozing + +@dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of) +the news feed''. @code{nnkiboze} is a backend that will do this for +you. Oh joy! Now you can grind any @sc{nntp} server down to a halt +with useless requests! Oh happiness! + +@kindex G k (Group) +To create a kibozed group, use the @kbd{G k} command in the group +buffer. + +The address field of the @code{nnkiboze} method is, as with +@code{nnvirtual}, a regexp to match groups to be ``included'' in the +@code{nnkiboze} group. That's where most similarities between @code{nnkiboze} +and @code{nnvirtual} end. + +In addition to this regexp detailing component groups, an @code{nnkiboze} group +must have a score file to say what articles are to be included in +the group (@pxref{Scoring}). + +@kindex M-x nnkiboze-generate-groups +@findex nnkiboze-generate-groups +You must run @kbd{M-x nnkiboze-generate-groups} after creating the +@code{nnkiboze} groups you want to have. This command will take time. Lots of +time. Oodles and oodles of time. Gnus has to fetch the headers from +all the articles in all the component groups and run them through the +scoring process to determine if there are any articles in the groups +that are to be part of the @code{nnkiboze} groups. + +Please limit the number of component groups by using restrictive +regexps. Otherwise your sysadmin may become annoyed with you, and the +@sc{nntp} site may throw you off and never let you back in again. +Stranger things have happened. + +@code{nnkiboze} component groups do not have to be alive---they can be dead, +and they can be foreign. No restrictions. + +@vindex nnkiboze-directory +The generation of an @code{nnkiboze} group means writing two files in +@code{nnkiboze-directory}, which is @file{~/News/} by default. One +contains the @sc{nov} header lines for all the articles in the group, +and the other is an additional @file{.newsrc} file to store information +on what groups have been searched through to find component articles. + +Articles marked as read in the @code{nnkiboze} group will have +their @sc{nov} lines removed from the @sc{nov} file. + + +@node Gnus Unplugged +@section Gnus Unplugged +@cindex offline +@cindex unplugged +@cindex Agent +@cindex Gnus Agent +@cindex Gnus Unplugged + +In olden times (ca. February '88), people used to run their newsreaders +on big machines with permanent connections to the net. News transport +was dealt with by news servers, and all the newsreaders had to do was to +read news. Believe it or not. + +Nowadays most people read news and mail at home, and use some sort of +modem to connect to the net. To avoid running up huge phone bills, it +would be nice to have a way to slurp down all the news and mail, hang up +the phone, read for several hours, and then upload any responses you +have to make. And then you repeat the procedure. + +Of course, you can use news servers for doing this as well. I've used +@code{inn} together with @code{slurp}, @code{pop} and @code{sendmail} +for some years, but doing that's a bore. Moving the news server +functionality up to the newsreader makes sense if you're the only person +reading news on a machine. + +Using Gnus as an ``offline'' newsreader is quite simple. + +@itemize @bullet +@item +First, set up Gnus as you would do if you were running it on a machine +that has full connection to the net. Go ahead. I'll still be waiting +here. + +@item +Then, put the following magical incantation at the end of your +@file{.gnus.el} file: + +@lisp +(gnus-agentize) +@end lisp +@end itemize + +That's it. Gnus is now an ``offline'' newsreader. + +Of course, to use it as such, you have to learn a few new commands. + +@menu +* 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 Expiry:: How to make old articles go away. +* 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. +@end menu + + +@node Agent Basics +@subsection Agent Basics + +First, let's get some terminology out of the way. + +The Gnus Agent is said to be @dfn{unplugged} when you have severed the +connection to the net (and notified the Agent that this is the case). +When the connection to the net is up again (and Gnus knows this), the +Agent is @dfn{plugged}. + +The @dfn{local} machine is the one you're running on, and which isn't +connected to the net continuously. + +@dfn{Downloading} means fetching things from the net to your local +machine. @dfn{Uploading} is doing the opposite. + +Let's take a typical Gnus session using the Agent. + +@itemize @bullet + +@item +You start Gnus with @code{gnus-unplugged}. This brings up the Gnus +Agent in a disconnected state. You can read all the news that you have +already fetched while in this mode. + +@item +You then decide to see whether any new news has arrived. You connect +your machine to the net (using PPP or whatever), and then hit @kbd{J j} +to make Gnus become @dfn{plugged}. + +@item +You can then read the new news immediately, or you can download the news +onto your local machine. If you want to do the latter, you press @kbd{J +s} to fetch all the eligible articles in all the groups. (To let Gnus +know which articles you want to download, @pxref{Agent Categories}.) + +@item +After fetching the articles, you press @kbd{J j} to make Gnus become +unplugged again, and you shut down the PPP thing (or whatever). And +then you read the news offline. + +@item +And then you go to step 2. +@end itemize + +Here are some things you should do the first time (or so) that you use +the Agent. + +@itemize @bullet + +@item +Decide which servers should be covered by the Agent. If you have a mail +backend, it would probably be nonsensical to have it covered by the +Agent. Go to the server buffer (@kbd{^} in the group buffer) and press +@kbd{J a} the server (or servers) that you wish to have covered by the +Agent (@pxref{Server Agent Commands}). This will typically be only the +primary select method, which is listed on the bottom in the buffer. + +@item +Decide on download policy. @xref{Agent Categories} + +@item +Uhm... that's it. +@end itemize + + +@node Agent Categories +@subsection Agent Categories + +One of the main reasons to integrate the news transport layer into the +newsreader is to allow greater control over what articles to download. +There's not much point in downloading huge amounts of articles, just to +find out that you're not interested in reading any of them. It's better +to be somewhat more conservative in choosing what to download, and then +mark the articles for downloading manually if it should turn out that +you're interested in the articles anyway. + +The main way to control what is to be downloaded is to create a +@dfn{category} and then assign some (or all) groups to this category. +Gnus has its own buffer for creating and managing categories. + +@menu +* Category Syntax:: What a category looks like. +* The Category Buffer:: A buffer for maintaining categories. +* Category Variables:: Customize'r'Us. +@end menu + + +@node Category Syntax +@subsubsection Category Syntax + +A category consists of two things. + +@enumerate +@item +A predicate which (generally) gives a rough outline of which articles +are eligible for downloading; and + +@item +a score rule which (generally) gives you a finer granularity when +deciding what articles to download. (Note that this @dfn{download +score} is not necessarily related to normal scores.) +@end enumerate + +A predicate in its simplest form can be a single predicate such as +@code{true} or @code{false}. These two will download every available +article or nothing respectively. In the case of these two special +predicates an additional score rule is superfluous. + +Predicates of @code{high} or @code{low} download articles in respect of +their scores in relationship to @code{gnus-agent-high-score} and +@code{gnus-agent-low-score} as descibed below. + +To gain even finer control of what is to be regarded eligible for +download a predicate can consist of a number of predicates with logical +operators sprinkled in between. + +Perhaps some examples are in order. + +Here's a simple predicate. (It's the default predicate, in fact, used +for all groups that don't belong to any other category.) + +@lisp +short +@end lisp + +Quite simple, eh? This predicate is true if and only if the article is +short (for some value of ``short''). + +Here's a more complex predicate: + +@lisp +(or high + (and + (not low) + (not long))) +@end lisp + +This means that an article should be downloaded if it has a high score, +or if the score is not low and the article is not long. You get the +drift. + +The available logical operators are @code{or}, @code{and} and +@code{not}. (If you prefer, you can use the more ``C''-ish operators +@samp{|}, @code{&} and @code{!} instead.) + +The following predicates are pre-defined, but if none of these fit what +you want to do, you can write your own. + +@table @code +@item short +True iff the article is shorter than @code{gnus-agent-short-article} +lines; default 100. + +@item long +True iff the article is longer than @code{gnus-agent-long-article} +lines; default 200. + +@item low +True iff the article has a download score less than +@code{gnus-agent-low-score}; default 0. + +@item high +True iff the article has a download score greater than +@code{gnus-agent-high-score}; default 0. + +@item spam +True iff the Gnus Agent guesses that the article is spam. The +heuristics may change over time, but at present it just computes a +checksum and sees whether articles match. + +@item true +Always true. + +@item false +Always false. +@end table + +If you want to create your own predicate function, here's what you have +to know: The functions are called with no parameters, but the +@code{gnus-headers} and @code{gnus-score} dynamic variables are bound to +useful values. + +For example, you could decide that you don't want to download articles +that were posted more than a certain number of days ago (e.g. posted +more than @code{gnus-agent-expire-days} ago) you might write a function +something along the lines of the following: + +@lisp +(defun my-article-old-p () + "Say whether an article is old." + (< (time-to-day (date-to-time (mail-header-date gnus-headers))) + (- (time-to-day (current-time)) gnus-agent-expire-days))) +@end lisp + +with the predicate then defined as: + +@lisp +(not my-article-old-p) +@end lisp + +or you could append your predicate to the predefined +@code{gnus-category-predicate-alist} in your @file{~/.gnus.el} or +wherever. (Note: this would have to be at a point *after* +@code{gnus-agent} has been loaded via @code{(gnus-agentize)}) + +@lisp +(defvar gnus-category-predicate-alist + (append gnus-category-predicate-alist + '((old . my-article-old-p)))) +@end lisp + +and simply specify your predicate as: + +@lisp +(not old) +@end lisp + +If/when using something like the above, be aware that there are many +misconfigured systems/mailers out there and so an article's date is not +always a reliable indication of when it was posted. Hell, some people +just don't give a damm. + + +The above predicates apply to *all* the groups which belong to the +category. However, if you wish to have a specific predicate for an +individual group within a category, or you're just too lazy to set up a +new category, you can enter a group's individual predicate in it's group +parameters like so: + +@lisp +(agent-predicate . short) +@end lisp + +This is the group parameter equivalent of the agent category +default. Note that when specifying a single word predicate like this, +the @code{agent-predicate} specification must be in dotted pair +notation. + +The equivalent of the longer example from above would be: + +@lisp +(agent-predicate or high (and (not low) (not long))) +@end lisp + +The outer parenthesis required in the category specification are not +entered here as, not being in dotted pair notation, the value of the +predicate is assumed to be a list. + + +Now, the syntax of the download score is the same as the syntax of +normal score files, except that all elements that require actually +seeing the article itself are verboten. This means that only the +following headers can be scored on: @code{Subject}, @code{From}, +@code{Date}, @code{Message-ID}, @code{References}, @code{Chars}, +@code{Lines}, and @code{Xref}. + +As with predicates, the specification of the @code{download score rule} +to use in respect of a group can be in either the category definition if +it's to be applicable to all groups in therein, or a group's parameters +if it's to be specific to that group. + +In both of these places the @code{download score rule} can take one of +three forms: + +@table @code +@enumerate +@item +Score rule + +This has the same syntax as a normal gnus score file except only a +subset of scoring keywords are available as mentioned above. + +example: + +@itemize @bullet +@item +Category specification + +@lisp +(("from" + ("Lars Ingebrigtsen" 1000000 nil s)) +("lines" + (500 -100 nil <))) +@end lisp + +@item +Group Parameter specification + +@lisp +(agent-score ("from" + ("Lars Ingebrigtsen" 1000000 nil s)) + ("lines" + (500 -100 nil <))) +@end lisp + +Again, note the omission of the outermost parenthesis here. +@end itemize + +@item +Agent score file + +These score files must *only* contain the permitted scoring keywords +stated above. + +example: + +@itemize @bullet +@item +Category specification + +@lisp +("~/News/agent.SCORE") +@end lisp + +or perhaps + +@lisp +("~/News/agent.SCORE" "~/News/agent.group.SCORE") +@end lisp + +@item +Group Parameter specification + +@lisp +(agent-score "~/News/agent.SCORE") +@end lisp + +Additional score files can be specified as above. Need I say anything +about parenthesis. +@end itemize + +@item +Use @code{normal} score files + +If you dont want to maintain two sets of scoring rules for a group, and +your desired @code{downloading} criteria for a group are the same as your +@code{reading} criteria then you can tell the agent to refer to your +@code{normal} score files when deciding what to download. + +These directives in either the category definition or a group's +parameters will cause the agent to read in all the applicable score +files for a group, *filtering out* those those sections that do not +relate to one of the permitted subset of scoring keywords. + +@itemize @bullet +@item +Category Specification + +@lisp +file +@end lisp + +@item +Group Parameter specification + +@lisp +(agent-score . file) +@end lisp +@end itemize +@end enumerate +@end table + +@node The Category Buffer +@subsubsection The Category Buffer + +You'd normally do all category maintenance from the category buffer. +When you enter it for the first time (with the @kbd{J c} command from +the group buffer), you'll only see the @code{default} category. + +The following commands are available in this buffer: + +@table @kbd +@item q +@kindex q (Category) +@findex gnus-category-exit +Return to the group buffer (@code{gnus-category-exit}). + +@item k +@kindex k (Category) +@findex gnus-category-kill +Kill the current category (@code{gnus-category-kill}). + +@item c +@kindex c (Category) +@findex gnus-category-copy +Copy the current category (@code{gnus-category-copy}). + +@item a +@kindex a (Category) +@findex gnus-category-add +Add a new category (@code{gnus-category-add}). + +@item p +@kindex p (Category) +@findex gnus-category-edit-predicate +Edit the predicate of the current category +(@code{gnus-category-edit-predicate}). + +@item g +@kindex g (Category) +@findex gnus-category-edit-groups +Edit the list of groups belonging to the current category +(@code{gnus-category-edit-groups}). + +@item s +@kindex s (Category) +@findex gnus-category-edit-score +Edit the download score rule of the current category +(@code{gnus-category-edit-score}). + +@item l +@kindex l (Category) +@findex gnus-category-list +List all the categories (@code{gnus-category-list}). +@end table + + +@node Category Variables +@subsubsection Category Variables + +@table @code +@item gnus-category-mode-hook +@vindex gnus-category-mode-hook +Hook run in category buffers. + +@item gnus-category-line-format +@vindex gnus-category-line-format +Format of the lines in the category buffer (@pxref{Formatting +Variables}). Valid elements are: + +@table @samp +@item c +The name of the category. + +@item g +The number of groups in the category. +@end table + +@item gnus-category-mode-line-format +@vindex gnus-category-mode-line-format +Format of the category mode line (@pxref{Mode Line Formatting}). + +@item gnus-agent-short-article +@vindex gnus-agent-short-article +Articles that have fewer lines than this are short. Default 100. + +@item gnus-agent-long-article +@vindex gnus-agent-long-article +Articles that have more lines than this are long. Default 200. + +@item gnus-agent-low-score +@vindex gnus-agent-low-score +Articles that have a score lower than this have a low score. Default +0. + +@item gnus-agent-high-score +@vindex gnus-agent-high-score +Articles that have a score higher than this have a high score. Default +0. + +@end table + + +@node Agent Commands +@subsection Agent Commands + +All the Gnus Agent commands are on the @kbd{J} submap. The @kbd{J j} +(@code{gnus-agent-toggle-plugged} command works in all modes, and +toggles the plugged/unplugged state of the Gnus Agent. + + +@menu +* Group Agent Commands:: +* Summary Agent Commands:: +* Server Agent Commands:: +@end menu + +You can run a complete batch fetch from the command line with the +following incantation: + +@cindex gnus-agent-batch-fetch +@example +$ emacs -batch -l ~/.gnus.el -f gnus-agent-batch-fetch +@end example + + + +@node Group Agent Commands +@subsubsection Group Agent Commands + +@table @kbd +@item J u +@kindex J u (Agent Group) +@findex gnus-agent-fetch-groups +Fetch all eligible articles in the current group +(@code{gnus-agent-fetch-groups}). + +@item J c +@kindex J c (Agent Group) +@findex gnus-enter-category-buffer +Enter the Agent category buffer (@code{gnus-enter-category-buffer}). + +@item J s +@kindex J s (Agent Group) +@findex gnus-agent-fetch-session +Fetch all eligible articles in all groups +(@code{gnus-agent-fetch-session}). + +@item J S +@kindex J S (Agent Group) +@findex gnus-group-send-drafts +Send all sendable messages in the draft group +(@code{gnus-agent-fetch-session}). @xref{Drafts} + +@item J a +@kindex J a (Agent Group) +@findex gnus-agent-add-group +Add the current group to an Agent category +(@code{gnus-agent-add-group}). + +@end table + + +@node Summary Agent Commands +@subsubsection Summary Agent Commands + +@table @kbd +@item J # +@kindex J # (Agent Summary) +@findex gnus-agent-mark-article +Mark the article for downloading (@code{gnus-agent-mark-article}). + +@item J M-# +@kindex J M-# (Agent Summary) +@findex gnus-agent-unmark-article +Remove the downloading mark from the article +(@code{gnus-agent-unmark-article}). + +@item @@ +@kindex @@ (Agent Summary) +@findex gnus-agent-toggle-mark +Toggle whether to download the article (@code{gnus-agent-toggle-mark}). + +@item J c +@kindex J c (Agent Summary) +@findex gnus-agent-catchup +Mark all undownloaded articles as read (@code{gnus-agent-catchup}). + +@end table + + +@node Server Agent Commands +@subsubsection Server Agent Commands + +@table @kbd +@item J a +@kindex J a (Agent Server) +@findex gnus-agent-add-server +Add the current server to the list of servers covered by the Gnus Agent +(@code{gnus-agent-add-server}). + +@item J r +@kindex J r (Agent Server) +@findex gnus-agent-remove-server +Remove the current server from the list of servers covered by the Gnus +Agent (@code{gnus-agent-remove-server}). + +@end table + + +@node Agent Expiry +@subsection Agent Expiry + +@vindex gnus-agent-expire-days +@findex gnus-agent-expire +@kindex M-x gnus-agent-expire +@cindex Agent expiry +@cindex Gnus Agent expiry +@cindex expiry + +@code{nnagent} doesn't handle expiry. Instead, there's a special +@code{gnus-agent-expire} command that will expire all read articles that +are older than @code{gnus-agent-expire-days} days. It can be run +whenever you feel that you're running out of space. It's not +particularly fast or efficient, and it's not a particularly good idea to +interrupt it (with @kbd{C-g} or anything else) once you've started it. + +@vindex gnus-agent-expire-all +if @code{gnus-agent-expire-all} is non-@code{nil}, this command will +expire all articles---unread, read, ticked and dormant. If @code{nil} +(which is the default), only read articles are eligible for expiry, and +unread, ticked and dormant articles will be kept indefinitely. + + +@node Outgoing Messages +@subsection Outgoing Messages + +When Gnus is unplugged, all outgoing messages (both mail and news) are +stored in the draft groups (@pxref{Drafts}). You can view them there +after posting, and edit them at will. + +When Gnus is plugged again, you can send the messages either from the +draft group with the special commands available there, or you can use +the @kbd{J S} command in the group buffer to send all the sendable +messages in the draft group. + + + +@node Agent Variables +@subsection Agent Variables + +@table @code +@item gnus-agent-directory +@vindex gnus-agent-directory +Where the Gnus Agent will store its files. The default is +@file{~/News/agent/}. + +@item gnus-agent-handle-level +@vindex gnus-agent-handle-level +Groups on levels (@pxref{Group Levels}) higher than this variable will +be ignored by the Agent. The default is @code{gnus-level-subscribed}, +which means that only subscribed group will be considered by the Agent +by default. + +@item gnus-agent-plugged-hook +@vindex gnus-agent-plugged-hook +Hook run when connecting to the network. + +@item gnus-agent-unplugged-hook +@vindex gnus-agent-unplugged-hook +Hook run when disconnecting from the network. + +@end table + + +@node Example Setup +@subsection Example Setup + +If you don't want to read this manual, and you have a fairly standard +setup, you may be able to use something like the following as your +@file{.gnus.el} file to get started. + +@lisp +;;; Define how Gnus is to fetch news. We do this over NNTP +;;; from your ISP's server. +(setq gnus-select-method '(nntp "nntp.your-isp.com")) + +;;; Define how Gnus is to read your mail. We read mail from +;;; your ISP's POP server. +(setenv "MAILHOST" "pop.your-isp.com") +(setq nnmail-spool-file "po:username") + +;;; Say how Gnus is to store the mail. We use nnml groups. +(setq gnus-secondary-select-methods '((nnml ""))) + +;;; Make Gnus into an offline newsreader. +(gnus-agentize) +@end lisp + +That should be it, basically. Put that in your @file{~/.gnus.el} file, +edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x +gnus}. + +If this is the first time you've run Gnus, you will be subscribed +automatically to a few default newsgroups. You'll probably want to +subscribe to more groups, and to do that, you have to query the +@sc{nntp} server for a complete list of groups with the @kbd{A A} +command. This usually takes quite a while, but you only have to do it +once. + +After reading and parsing a while, you'll be presented with a list of +groups. Subscribe to the ones you want to read with the @kbd{u} +command. @kbd{l} to make all the killed groups disappear after you've +subscribe to all the groups you want to read. (@kbd{A k} will bring +back all the killed groups.) + +You can now read the groups at once, or you can download the articles +with the @kbd{J s} command. And then read the rest of this manual to +find out which of the other gazillion things you want to customize. + + +@node Batching Agents +@subsection Batching Agents + +Having the Gnus Agent fetch articles (and post whatever messages you've +written) is quite easy once you've gotten things set up properly. The +following shell script will do everything that is necessary: + +@example +#!/bin/sh +emacs -batch -l ~/.emacs -f gnus-agent-batch >/dev/null +@end example + + + +@node Scoring +@chapter Scoring +@cindex scoring + +Other people use @dfn{kill files}, but we here at Gnus Towers like +scoring better than killing, so we'd rather switch than fight. They do +something completely different as well, so sit up straight and pay +attention! + +@vindex gnus-summary-mark-below +All articles have a default score (@code{gnus-summary-default-score}), +which is 0 by default. This score may be raised or lowered either +interactively or by score files. Articles that have a score lower than +@code{gnus-summary-mark-below} are marked as read. + +Gnus will read any @dfn{score files} that apply to the current group +before generating the summary buffer. + +There are several commands in the summary buffer that insert score +entries based on the current article. You can, for instance, ask Gnus to +lower or increase the score of all articles with a certain subject. + +There are two sorts of scoring entries: Permanent and temporary. +Temporary score entries are self-expiring entries. Any entries that are +temporary and have not been used for, say, a week, will be removed +silently to help keep the sizes of the score files down. + +@menu +* 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 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. +@end menu + + +@node Summary Score Commands +@section Summary Score Commands +@cindex score commands + +The score commands that alter score entries do not actually modify real +score files. That would be too inefficient. Gnus maintains a cache of +previously loaded score files, one of which is considered the +@dfn{current score file alist}. The score commands simply insert +entries into this list, and upon group exit, this list is saved. + +The current score file is by default the group's local score file, even +if no such score file actually exists. To insert score commands into +some other score file (e.g. @file{all.SCORE}), you must first make this +score file the current one. + +General score commands that don't actually change the score file: + +@table @kbd + +@item V s +@kindex V s (Summary) +@findex gnus-summary-set-score +Set the score of the current article (@code{gnus-summary-set-score}). + +@item V S +@kindex V S (Summary) +@findex gnus-summary-current-score +Display the score of the current article +(@code{gnus-summary-current-score}). + +@item V t +@kindex V t (Summary) +@findex gnus-score-find-trace +Display all score rules that have been used on the current article +(@code{gnus-score-find-trace}). + +@item V R +@kindex V R (Summary) +@findex gnus-summary-rescore +Run the current summary through the scoring process +(@code{gnus-summary-rescore}). This might be useful if you're playing +around with your score files behind Gnus' back and want to see the +effect you're having. + +@item V c +@kindex V c (Summary) +@findex gnus-score-change-score-file +Make a different score file the current +(@code{gnus-score-change-score-file}). + +@item V e +@kindex V e (Summary) +@findex gnus-score-edit-current-scores +Edit the current score file (@code{gnus-score-edit-current-scores}). +You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score +File Editing}). + +@item V f +@kindex V f (Summary) +@findex gnus-score-edit-file +Edit a score file and make this score file the current one +(@code{gnus-score-edit-file}). + +@item V F +@kindex V F (Summary) +@findex gnus-score-flush-cache +Flush the score cache (@code{gnus-score-flush-cache}). This is useful +after editing score files. + +@item V C +@kindex V C (Summary) +@findex gnus-score-customize +Customize a score file in a visually pleasing manner +(@code{gnus-score-customize}). + +@end table + +The rest of these commands modify the local score file. + +@table @kbd + +@item V m +@kindex V m (Summary) +@findex gnus-score-set-mark-below +Prompt for a score, and mark all articles with a score below this as +read (@code{gnus-score-set-mark-below}). + +@item V x +@kindex V x (Summary) +@findex gnus-score-set-expunge-below +Prompt for a score, and add a score rule to the current score file to +expunge all articles below this score +(@code{gnus-score-set-expunge-below}). +@end table + +The keystrokes for actually making score entries follow a very regular +pattern, so there's no need to list all the commands. (Hundreds of +them.) + +@findex gnus-summary-increase-score +@findex gnus-summary-lower-score + +@enumerate +@item +The first key is either @kbd{I} (upper case i) for increasing the score +or @kbd{L} for lowering the score. +@item +The second key says what header you want to score on. The following +keys are available: +@table @kbd + +@item a +Score on the author name. + +@item s +Score on the subject line. + +@item x +Score on the Xref line---i.e., the cross-posting line. + +@item r +Score on the References line. + +@item d +Score on the date. + +@item l +Score on the number of lines. + +@item i +Score on the Message-ID. + +@item f +Score on followups. + +@item b +Score on the body. + +@item h +Score on the head. + +@item t +Score on thread. + +@end table + +@item +The third key is the match type. Which match types are valid depends on +what headers you are scoring on. + +@table @code + +@item strings + +@table @kbd + +@item e +Exact matching. + +@item s +Substring matching. + +@item f +Fuzzy matching (@pxref{Fuzzy Matching}). + +@item r +Regexp matching +@end table + +@item date +@table @kbd + +@item b +Before date. + +@item a +After date. + +@item n +This date. +@end table + +@item number +@table @kbd + +@item < +Less than number. + +@item = +Equal to number. + +@item > +Greater than number. +@end table +@end table + +@item +The fourth and final key says whether this is a temporary (i.e., expiring) +score entry, or a permanent (i.e., non-expiring) score entry, or whether +it is to be done immediately, without adding to the score file. +@table @kbd + +@item t +Temporary score entry. + +@item p +Permanent score entry. + +@item i +Immediately scoring. +@end table + +@end enumerate + +So, let's say you want to increase the score on the current author with +exact matching permanently: @kbd{I a e p}. If you want to lower the +score based on the subject line, using substring matching, and make a +temporary score entry: @kbd{L s s t}. Pretty easy. + +To make things a bit more complicated, there are shortcuts. If you use +a capital letter on either the second or third keys, Gnus will use +defaults for the remaining one or two keystrokes. The defaults are +``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s +t}, and @kbd{I a R} is the same as @kbd{I a r t}. + +These functions take both the numerical prefix and the symbolic prefix +(@pxref{Symbolic Prefixes}). A numerical prefix says how much to lower +(or increase) the score of the article. A symbolic prefix of @code{a} +says to use the @file{all.SCORE} file for the command instead of the +current score file. + +@vindex gnus-score-mimic-keymap +The @code{gnus-score-mimic-keymap} says whether these commands will +pretend they are keymaps or not. + + +@node Group Score Commands +@section Group Score Commands +@cindex group score commands + +There aren't many of these as yet, I'm afraid. + +@table @kbd + +@item W f +@kindex W f (Group) +@findex gnus-score-flush-cache +Gnus maintains a cache of score alists to avoid having to reload them +all the time. This command will flush the cache +(@code{gnus-score-flush-cache}). + +@end table + +You can do scoring from the command line by saying something like: + +@findex gnus-batch-score +@cindex batch scoring +@example +$ emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-batch-score +@end example + + +@node Score Variables +@section Score Variables +@cindex score variables + +@table @code + +@item gnus-use-scoring +@vindex gnus-use-scoring +If @code{nil}, Gnus will not check for score files, and will not, in +general, do any score-related work. This is @code{t} by default. + +@item gnus-kill-killed +@vindex gnus-kill-killed +If this variable is @code{nil}, Gnus will never apply score files to +articles that have already been through the kill process. While this +may save you lots of time, it also means that if you apply a kill file +to a group, and then change the kill file and want to run it over you +group again to kill more articles, it won't work. You have to set this +variable to @code{t} to do that. (It is @code{t} by default.) + +@item gnus-kill-files-directory +@vindex gnus-kill-files-directory +All kill and score files will be stored in this directory, which is +initialized from the @code{SAVEDIR} environment variable by default. +This is @file{~/News/} by default. + +@item gnus-score-file-suffix +@vindex gnus-score-file-suffix +Suffix to add to the group name to arrive at the score file name +(@samp{SCORE} by default.) + +@item gnus-score-uncacheable-files +@vindex gnus-score-uncacheable-files +@cindex score cache +All score files are normally cached to avoid excessive re-loading of +score files. However, if this might make you Emacs grow big and +bloated, so this regexp can be used to weed out score files unlikely to be needed again. It would be a bad idea to deny caching of +@file{all.SCORE}, while it might be a good idea to not cache +@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this +variable is @samp{ADAPT$} by default, so no adaptive score files will +be cached. + +@item gnus-save-score +@vindex gnus-save-score +If you have really complicated score files, and do lots of batch +scoring, then you might set this variable to @code{t}. This will make +Gnus save the scores into the @file{.newsrc.eld} file. + +@item gnus-score-interactive-default-score +@vindex gnus-score-interactive-default-score +Score used by all the interactive raise/lower commands to raise/lower +score with. Default is 1000, which may seem excessive, but this is to +ensure that the adaptive scoring scheme gets enough room to play with. +We don't want the small changes from the adaptive scoring to overwrite +manually entered data. + +@item gnus-summary-default-score +@vindex gnus-summary-default-score +Default score of an article, which is 0 by default. + +@item gnus-summary-expunge-below +@vindex gnus-summary-expunge-below +Don't display the summary lines of articles that have scores lower than +this variable. This is @code{nil} by default, which means that no +articles will be hidden. This variable is local to the summary buffers, +and has to be set from @code{gnus-summary-mode-hook}. + +@item gnus-score-over-mark +@vindex gnus-score-over-mark +Mark (in the third column) used for articles with a score over the +default. Default is @samp{+}. + +@item gnus-score-below-mark +@vindex gnus-score-below-mark +Mark (in the third column) used for articles with a score below the +default. Default is @samp{-}. + +@item gnus-score-find-score-files-function +@vindex gnus-score-find-score-files-function +Function used to find score files for the current group. This function +is called with the name of the group as the argument. + +Predefined functions available are: +@table @code + +@item gnus-score-find-single +@findex gnus-score-find-single +Only apply the group's own score file. + +@item gnus-score-find-bnews +@findex gnus-score-find-bnews +Apply all score files that match, using bnews syntax. This is the +default. If the current group is @samp{gnu.emacs.gnus}, for instance, +@file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and +@file{gnu.all.SCORE} would all apply. In short, the instances of +@samp{all} in the score file names are translated into @samp{.*}, and +then a regexp match is done. + +This means that if you have some score entries that you want to apply to +all groups, then you put those entries in the @file{all.SCORE} file. + +The score files are applied in a semi-random order, although Gnus will +try to apply the more general score files before the more specific score +files. It does this by looking at the number of elements in the score +file names---discarding the @samp{all} elements. + +@item gnus-score-find-hierarchical +@findex gnus-score-find-hierarchical +Apply all score files from all the parent groups. This means that you +can't have score files like @file{all.SCORE}, but you can have +@file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE}. + +@end table +This variable can also be a list of functions. In that case, all these +functions will be called, and all the returned lists of score files will +be applied. These functions can also return lists of score alists +directly. In that case, the functions that return these non-file score +alists should probably be placed before the ``real'' score file +functions, to ensure that the last score file returned is the local +score file. Phu. + +@item gnus-score-expiry-days +@vindex gnus-score-expiry-days +This variable says how many days should pass before an unused score file +entry is expired. If this variable is @code{nil}, no score file entries +are expired. It's 7 by default. + +@item gnus-update-score-entry-dates +@vindex gnus-update-score-entry-dates +If this variable is non-@code{nil}, matching score entries will have +their dates updated. (This is how Gnus controls expiry---all +non-matching entries will become too old while matching entries will +stay fresh and young.) However, if you set this variable to @code{nil}, +even matching entries will grow old and will have to face that oh-so +grim reaper. + +@item gnus-score-after-write-file-function +@vindex gnus-score-after-write-file-function +Function called with the name of the score file just written. + +@item gnus-score-thread-simplify +@vindex gnus-score-thread-simplify +If this variable is non-@code{nil}, article subjects will be simplified +for subject scoring purposes in the same manner as with +threading---according to the current value of +gnus-simplify-subject-functions. If the scoring entry uses +@code{substring} or @code{exact} matching, the match will also be +simplified in this manner. + +@end table + + +@node Score File Format +@section Score File Format +@cindex score file format + +A score file is an @code{emacs-lisp} file that normally contains just a +single form. Casual users are not expected to edit these files; +everything can be changed from the summary buffer. + +Anyway, if you'd like to dig into it yourself, here's an example: + +@lisp +(("from" + ("Lars Ingebrigtsen" -10000) + ("Per Abrahamsen") + ("larsi\\|lmi" -50000 nil R)) + ("subject" + ("Ding is Badd" nil 728373)) + ("xref" + ("alt.politics" -1000 728372 s)) + ("lines" + (2 -100 nil <)) + (mark 0) + (expunge -1000) + (mark-and-expunge -10) + (read-only nil) + (orphan -10) + (adapt t) + (files "/hom/larsi/News/gnu.SCORE") + (exclude-files "all.SCORE") + (local (gnus-newsgroup-auto-expire t) + (gnus-summary-make-false-root empty)) + (eval (ding))) +@end lisp + +This example demonstrates most score file elements. For a different +approach, see @pxref{Advanced Scoring}. + +Even though this looks much like lisp code, nothing here is actually +@code{eval}ed. The lisp reader is used to read this form, though, so it +has to be valid syntactically, if not semantically. + +Six keys are supported by this alist: + +@table @code + +@item STRING +If the key is a string, it is the name of the header to perform the +match on. Scoring can only be performed on these eight headers: +@code{From}, @code{Subject}, @code{References}, @code{Message-ID}, +@code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to +these headers, there are three strings to tell Gnus to fetch the entire +article and do the match on larger parts of the article: @code{Body} +will perform the match on the body of the article, @code{Head} will +perform the match on the head of the article, and @code{All} will +perform the match on the entire article. Note that using any of these +last three keys will slow down group entry @emph{considerably}. The +final ``header'' you can score on is @code{Followup}. These score +entries will result in new score entries being added for all follow-ups +to articles that matches these score entries. + +Following this key is a arbitrary number of score entries, where each +score entry has one to four elements. +@enumerate + +@item +The first element is the @dfn{match element}. On most headers this will +be a string, but on the Lines and Chars headers, this must be an +integer. + +@item +If the second element is present, it should be a number---the @dfn{score +element}. This number should be an integer in the neginf to posinf +interval. This number is added to the score of the article if the match +is successful. If this element is not present, the +@code{gnus-score-interactive-default-score} number will be used +instead. This is 1000 by default. + +@item +If the third element is present, it should be a number---the @dfn{date +element}. This date says when the last time this score entry matched, +which provides a mechanism for expiring the score entries. It this +element is not present, the score entry is permanent. The date is +represented by the number of days since December 31, 1 BCE. + +@item +If the fourth element is present, it should be a symbol---the @dfn{type +element}. This element specifies what function should be used to see +whether this score entry matches the article. What match types that can +be used depends on what header you wish to perform the match on. +@table @dfn + +@item From, Subject, References, Xref, Message-ID +For most header types, there are the @code{r} and @code{R} (regexp), as +well as @code{s} and @code{S} (substring) types, and @code{e} and +@code{E} (exact match), and @code{w} (word match) types. If this +element is not present, Gnus will assume that substring matching should +be used. @code{R}, @code{S}, and @code{E} differ from the others in +that the matches will be done in a case-sensitive manner. All these +one-letter types are really just abbreviations for the @code{regexp}, +@code{string}, @code{exact}, and @code{word} types, which you can use +instead, if you feel like. + +@item Lines, Chars +These two headers use different match types: @code{<}, @code{>}, +@code{=}, @code{>=} and @code{<=}. + +These predicates are true if + +@example +(PREDICATE HEADER MATCH) +@end example + +evaluates to non-@code{nil}. For instance, the advanced match +@code{("lines" 4 <)} (@pxref{Advanced Scoring}) will result in the +following form: + +@lisp +(< header-value 4) +@end lisp + +Or to put it another way: When using @code{<} on @code{Lines} with 4 as +the match, we get the score added if the article has less than 4 lines. +(It's easy to get confused and think it's the other way around. But +it's not. I think.) + +When matching on @code{Lines}, be careful because some backends (like +@code{nndir}) do not generate @code{Lines} header, so every article ends +up being marked as having 0 lines. This can lead to strange results if +you happen to lower score of the articles with few lines. + +@item Date +For the Date header we have three kinda silly match types: +@code{before}, @code{at} and @code{after}. I can't really imagine this +ever being useful, but, like, it would feel kinda silly not to provide +this function. Just in case. You never know. Better safe than sorry. +Once burnt, twice shy. Don't judge a book by its cover. Never not have +sex on a first date. (I have been told that at least one person, and I +quote, ``found this function indispensable'', however.) + +@cindex ISO8601 +@cindex date +A more useful match type is @code{regexp}. With it, you can match the +date string using a regular expression. The date is normalized to +ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. If +you want to match all articles that have been posted on April 1st in +every year, you could use @samp{....0401.........} as a match string, +for instance. (Note that the date is kept in its original time zone, so +this will match articles that were posted when it was April 1st where +the article was posted from. Time zones are such wholesome fun for the +whole family, eh?) + +@item Head, Body, All +These three match keys use the same match types as the @code{From} (etc) +header uses. + +@item Followup +This match key is somewhat special, in that it will match the +@code{From} header, and affect the score of not only the matching +articles, but also all followups to the matching articles. This allows +you e.g. increase the score of followups to your own articles, or +decrease the score of followups to the articles of some known +trouble-maker. Uses the same match types as the @code{From} header +uses. (Using this match key will lead to creation of @file{ADAPT} +files.) + +@item Thread +This match key works along the same lines as the @code{Followup} match +key. If you say that you want to score on a (sub-)thread started by an article with a @code{Message-ID} @var{X}, then you add a +@samp{thread} match. This will add a new @samp{thread} match for each +article that has @var{X} in its @code{References} header. (These new +@samp{thread} matches will use the @code{Message-ID}s of these matching +articles.) This will ensure that you can raise/lower the score of an +entire thread, even though some articles in the thread may not have +complete @code{References} headers. Note that using this may lead to +undeterministic scores of the articles in the thread. (Using this match +key will lead to creation of @file{ADAPT} files.) +@end table +@end enumerate + +@cindex Score File Atoms +@item mark +The value of this entry should be a number. Any articles with a score +lower than this number will be marked as read. + +@item expunge +The value of this entry should be a number. Any articles with a score +lower than this number will be removed from the summary buffer. + +@item mark-and-expunge +The value of this entry should be a number. Any articles with a score +lower than this number will be marked as read and removed from the +summary buffer. + +@item thread-mark-and-expunge +The value of this entry should be a number. All articles that belong to +a thread that has a total score below this number will be marked as read +and removed from the summary buffer. @code{gnus-thread-score-function} +says how to compute the total score for a thread. + +@item files +The value of this entry should be any number of file names. These files +are assumed to be score files as well, and will be loaded the same way +this one was. + +@item exclude-files +The clue of this entry should be any number of files. These files will +not be loaded, even though they would normally be so, for some reason or +other. + +@item eval +The value of this entry will be @code{eval}el. This element will be +ignored when handling global score files. + +@item read-only +Read-only score files will not be updated or saved. Global score files +should feature this atom (@pxref{Global Score Files}). (Note: +@dfn{Global} here really means @dfn{global}; not your personal +apply-to-all-groups score files.) + +@item orphan +The value of this entry should be a number. Articles that do not have +parents will get this number added to their scores. Imagine you follow +some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you +will only follow a few of the threads, also want to see any new threads. + +You can do this with the following two score file entries: + +@example + (orphan -500) + (mark-and-expunge -100) +@end example + +When you enter the group the first time, you will only see the new +threads. You then raise the score of the threads that you find +interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the +rest. Next time you enter the group, you will see new articles in the +interesting threads, plus any new threads. + +I.e.---the orphan score atom is for high-volume groups where there +exist a few interesting threads which can't be found automatically by +ordinary scoring rules. + +@item adapt +This entry controls the adaptive scoring. If it is @code{t}, the +default adaptive scoring rules will be used. If it is @code{ignore}, no +adaptive scoring will be performed on this group. If it is a list, this +list will be used as the adaptive scoring rules. If it isn't present, +or is something other than @code{t} or @code{ignore}, the default +adaptive scoring rules will be used. If you want to use adaptive +scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to +@code{t}, and insert an @code{(adapt ignore)} in the groups where you do +not want adaptive scoring. If you only want adaptive scoring in a few +groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and +insert @code{(adapt t)} in the score files of the groups where you want +it. + +@item adapt-file +All adaptive score entries will go to the file named by this entry. It +will also be applied when entering the group. This atom might be handy +if you want to adapt on several groups at once, using the same adaptive +file for a number of groups. + +@item local +@cindex local variables +The value of this entry should be a list of @code{(VAR VALUE)} pairs. +Each @var{var} will be made buffer-local to the current summary buffer, +and set to the value specified. This is a convenient, if somewhat +strange, way of setting variables in some groups if you don't like hooks +much. Note that the @var{value} won't be evaluated. +@end table + + +@node Score File Editing +@section Score File Editing + +You normally enter all scoring commands from the summary buffer, but you +might feel the urge to edit them by hand as well, so we've supplied you +with a mode for that. + +It's simply a slightly customized @code{emacs-lisp} mode, with these +additional commands: + +@table @kbd + +@item C-c C-c +@kindex C-c C-c (Score) +@findex gnus-score-edit-done +Save the changes you have made and return to the summary buffer +(@code{gnus-score-edit-done}). + +@item C-c C-d +@kindex C-c C-d (Score) +@findex gnus-score-edit-insert-date +Insert the current date in numerical format +(@code{gnus-score-edit-insert-date}). This is really the day number, if +you were wondering. + +@item C-c C-p +@kindex C-c C-p (Score) +@findex gnus-score-pretty-print +The adaptive score files are saved in an unformatted fashion. If you +intend to read one of these files, you want to @dfn{pretty print} it +first. This command (@code{gnus-score-pretty-print}) does that for +you. + +@end table + +Type @kbd{M-x gnus-score-mode} to use this mode. + +@vindex gnus-score-mode-hook +@code{gnus-score-menu-hook} is run in score mode buffers. + +In the summary buffer you can use commands like @kbd{V f} and @kbd{V +e} to begin editing score files. + + +@node Adaptive Scoring +@section Adaptive Scoring +@cindex adaptive scoring + +If all this scoring is getting you down, Gnus has a way of making it all +happen automatically---as if by magic. Or rather, as if by artificial +stupidity, to be precise. + +@vindex gnus-use-adaptive-scoring +When you read an article, or mark an article as read, or kill an +article, you leave marks behind. On exit from the group, Gnus can sniff +these marks and add score elements depending on what marks it finds. +You turn on this ability by setting @code{gnus-use-adaptive-scoring} to +@code{t} or @code{(line)}. If you want score adaptively on separate +words appearing in the subjects, you should set this variable to +@code{(word)}. If you want to use both adaptive methods, set this +variable to @code{(word line)}. + +@vindex gnus-default-adaptive-score-alist +To give you complete control over the scoring process, you can customize +the @code{gnus-default-adaptive-score-alist} variable. For instance, it +might look something like this: + +@lisp +(defvar gnus-default-adaptive-score-alist + '((gnus-unread-mark) + (gnus-ticked-mark (from 4)) + (gnus-dormant-mark (from 5)) + (gnus-del-mark (from -4) (subject -1)) + (gnus-read-mark (from 4) (subject 2)) + (gnus-expirable-mark (from -1) (subject -1)) + (gnus-killed-mark (from -1) (subject -3)) + (gnus-kill-file-mark) + (gnus-ancient-mark) + (gnus-low-score-mark) + (gnus-catchup-mark (from -1) (subject -1)))) +@end lisp + +As you see, each element in this alist has a mark as a key (either a +variable name or a ``real'' mark---a character). Following this key is +a arbitrary number of header/score pairs. If there are no header/score +pairs following the key, no adaptive scoring will be done on articles +that have that key as the article mark. For instance, articles with +@code{gnus-unread-mark} in the example above will not get adaptive score +entries. + +Each article can have only one mark, so just a single of these rules +will be applied to each article. + +To take @code{gnus-del-mark} as an example---this alist says that all +articles that have that mark (i.e., are marked with @samp{D}) will have a +score entry added to lower based on the @code{From} header by -4, and +lowered by @code{Subject} by -1. Change this to fit your prejudices. + +If you have marked 10 articles with the same subject with +@code{gnus-del-mark}, the rule for that mark will be applied ten times. +That means that that subject will get a score of ten times -1, which +should be, unless I'm much mistaken, -10. + +If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all +the read articles will be marked with the @samp{E} mark. This'll +probably make adaptive scoring slightly impossible, so auto-expiring and +adaptive scoring doesn't really mix very well. + +The headers you can score on are @code{from}, @code{subject}, +@code{message-id}, @code{references}, @code{xref}, @code{lines}, +@code{chars} and @code{date}. In addition, you can score on +@code{followup}, which will create an adaptive score entry that matches +on the @code{References} header using the @code{Message-ID} of the +current article, thereby matching the following thread. + +You can also score on @code{thread}, which will try to score all +articles that appear in a thread. @code{thread} matches uses a +@code{Message-ID} to match on the @code{References} header of the +article. If the match is made, the @code{Message-ID} of the article is +added to the @code{thread} rule. (Think about it. I'd recommend two +aspirins afterwards.) + +If you use this scheme, you should set the score file atom @code{mark} +to something small---like -300, perhaps, to avoid having small random +changes result in articles getting marked as read. + +After using adaptive scoring for a week or so, Gnus should start to +become properly trained and enhance the authors you like best, and kill +the authors you like least, without you having to say so explicitly. + +You can control what groups the adaptive scoring is to be performed on +by using the score files (@pxref{Score File Format}). This will also +let you use different rules in different groups. + +@vindex gnus-adaptive-file-suffix +The adaptive score entries will be put into a file where the name is the +group name with @code{gnus-adaptive-file-suffix} appended. The default +is @samp{ADAPT}. + +@vindex gnus-score-exact-adapt-limit +When doing adaptive scoring, substring or fuzzy matching would probably +give you the best results in most cases. However, if the header one +matches is short, the possibility for false positives is great, so if +the length of the match is less than +@code{gnus-score-exact-adapt-limit}, exact matching will be used. If +this variable is @code{nil}, exact matching will always be used to avoid +this problem. + +@vindex gnus-default-adaptive-word-score-alist +As mentioned above, you can adapt either on individual words or entire +headers. If you adapt on words, the +@code{gnus-default-adaptive-word-score-alist} variable says what score +each instance of a word should add given a mark. + +@lisp +(setq gnus-default-adaptive-word-score-alist + `((,gnus-read-mark . 30) + (,gnus-catchup-mark . -10) + (,gnus-killed-mark . -20) + (,gnus-del-mark . -15))) +@end lisp + +This is the default value. If you have adaption on words enabled, every +word that appears in subjects of articles marked with +@code{gnus-read-mark} will result in a score rule that increase the +score with 30 points. + +@vindex gnus-default-ignored-adaptive-words +@vindex gnus-ignored-adaptive-words +Words that appear in the @code{gnus-default-ignored-adaptive-words} list +will be ignored. If you wish to add more words to be ignored, use the +@code{gnus-ignored-adaptive-words} list instead. + +@vindex gnus-adaptive-word-syntax-table +When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the +syntax table in effect. It is similar to the standard syntax table, but +it considers numbers to be non-word-constituent characters. + +@vindex gnus-adaptive-word-minimum +If @code{gnus-adaptive-word-minimum} is set to a number, the adaptive +word scoring process will never bring down the score of an article to +below this number. The default is @code{nil}. + +@vindex gnus-adative-word-no-group-words +If @code{gnus-adative-word-no-group-words} is set to t, gnus won't +adaptively word score any of the words in the group name. Useful for +groups like comp.editors.emacs, where most of the subject lines contain +the word "emacs". + +After using this scheme for a while, it might be nice to write a +@code{gnus-psychoanalyze-user} command to go through the rules and see +what words you like and what words you don't like. Or perhaps not. + +Note that the adaptive word scoring thing is highly experimental and is +likely to change in the future. Initial impressions seem to indicate +that it's totally useless as it stands. Some more work (involving more +rigorous statistical methods) will have to be done to make this useful. + + +@node Home Score File +@section Home Score File + +The score file where new score file entries will go is called the +@dfn{home score file}. This is normally (and by default) the score file +for the group itself. For instance, the home score file for +@samp{gnu.emacs.gnus} is @file{gnu.emacs.gnus.SCORE}. + +However, this may not be what you want. It is often convenient to share +a common home score file among many groups---all @samp{emacs} groups +could perhaps use the same home score file. + +@vindex gnus-home-score-file +The variable that controls this is @code{gnus-home-score-file}. It can +be: + +@enumerate +@item +A string. Then this file will be used as the home score file for all +groups. + +@item +A function. The result of this function will be used as the home score +file. The function will be called with the name of the group as the +parameter. + +@item +A list. The elements in this list can be: + +@enumerate +@item +@var{(regexp file-name)}. If the @var{regexp} matches the group name, +the @var{file-name} will will be used as the home score file. + +@item +A function. If the function returns non-nil, the result will be used as +the home score file. + +@item +A string. Use the string as the home score file. +@end enumerate + +The list will be traversed from the beginning towards the end looking +for matches. + +@end enumerate + +So, if you want to use just a single score file, you could say: + +@lisp +(setq gnus-home-score-file + "my-total-score-file.SCORE") +@end lisp + +If you want to use @file{gnu.SCORE} for all @samp{gnu} groups and +@file{rec.SCORE} for all @samp{rec} groups (and so on), you can say: + +@findex gnus-hierarchial-home-score-file +@lisp +(setq gnus-home-score-file + 'gnus-hierarchial-home-score-file) +@end lisp + +This is a ready-made function provided for your convenience. +Other functions include + +@table @code +@item gnus-current-home-score-file +@findex gnus-current-home-score-file +Return the ``current'' regular score file. This will make scoring +commands add entry to the ``innermost'' matching score file. + +@end table + +If you want to have one score file for the @samp{emacs} groups and +another for the @samp{comp} groups, while letting all other groups use +their own home score files: + +@lisp +(setq gnus-home-score-file + ;; All groups that match the regexp "\\.emacs" + '(("\\.emacs" "emacs.SCORE") + ;; All the comp groups in one score file + ("^comp" "comp.SCORE"))) +@end lisp + +@vindex gnus-home-adapt-file +@code{gnus-home-adapt-file} works exactly the same way as +@code{gnus-home-score-file}, but says what the home adaptive score file +is instead. All new adaptive file entries will go into the file +specified by this variable, and the same syntax is allowed. + +In addition to using @code{gnus-home-score-file} and +@code{gnus-home-adapt-file}, you can also use group parameters +(@pxref{Group Parameters}) and topic parameters (@pxref{Topic +Parameters}) to achieve much the same. Group and topic parameters take +precedence over this variable. + + +@node Followups To Yourself +@section Followups To Yourself + +Gnus offers two commands for picking out the @code{Message-ID} header in +the current buffer. Gnus will then add a score rule that scores using +this @code{Message-ID} on the @code{References} header of other +articles. This will, in effect, increase the score of all articles that +respond to the article in the current buffer. Quite useful if you want +to easily note when people answer what you've said. + +@table @code + +@item gnus-score-followup-article +@findex gnus-score-followup-article +This will add a score to articles that directly follow up your own +article. + +@item gnus-score-followup-thread +@findex gnus-score-followup-thread +This will add a score to all articles that appear in a thread ``below'' +your own article. +@end table + +@vindex message-sent-hook +These two functions are both primarily meant to be used in hooks like +@code{message-sent-hook}. + +If you look closely at your own @code{Message-ID}, you'll notice that +the first two or three characters are always the same. Here's two of +mine: + +@example + + +@end example + +So ``my'' ident on this machine is @samp{x6}. This can be +exploited---the following rule will raise the score on all followups to +myself: + +@lisp +("references" + ("" + 1000 nil r)) +@end lisp + +Whether it's the first two or first three characters that are ``yours'' +is system-dependent. + + +@node Scoring Tips +@section Scoring Tips +@cindex scoring tips + +@table @dfn + +@item Crossposts +@cindex crossposts +@cindex scoring crossposts +If you want to lower the score of crossposts, the line to match on is +the @code{Xref} header. +@lisp +("xref" (" talk.politics.misc:" -1000)) +@end lisp + +@item Multiple crossposts +If you want to lower the score of articles that have been crossposted to +more than, say, 3 groups: +@lisp +("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r)) +@end lisp + +@item Matching on the body +This is generally not a very good idea---it takes a very long time. +Gnus actually has to fetch each individual article from the server. But +you might want to anyway, I guess. Even though there are three match +keys (@code{Head}, @code{Body} and @code{All}), you should choose one +and stick with it in each score file. If you use any two, each article +will be fetched @emph{twice}. If you want to match a bit on the +@code{Head} and a bit on the @code{Body}, just use @code{All} for all +the matches. + +@item Marking as read +You will probably want to mark articles that has a score below a certain +number as read. This is most easily achieved by putting the following +in your @file{all.SCORE} file: +@lisp +((mark -100)) +@end lisp +You may also consider doing something similar with @code{expunge}. + +@item Negated character classes +If you say stuff like @code{[^abcd]*}, you may get unexpected results. +That will match newlines, which might lead to, well, The Unknown. Say +@code{[^abcd\n]*} instead. +@end table + + +@node Reverse Scoring +@section Reverse Scoring +@cindex reverse scoring + +If you want to keep just articles that have @samp{Sex with Emacs} in the +subject header, and expunge all other articles, you could put something +like this in your score file: + +@lisp +(("subject" + ("Sex with Emacs" 2)) + (mark 1) + (expunge 1)) +@end lisp + +So, you raise all articles that match @samp{Sex with Emacs} and mark the +rest as read, and expunge them to boot. + + +@node Global Score Files +@section Global Score Files +@cindex global score files + +Sure, other newsreaders have ``global kill files''. These are usually +nothing more than a single kill file that applies to all groups, stored +in the user's home directory. Bah! Puny, weak newsreaders! + +What I'm talking about here are Global Score Files. Score files from +all over the world, from users everywhere, uniting all nations in one +big, happy score file union! Ange-score! New and untested! + +@vindex gnus-global-score-files +All you have to do to use other people's score files is to set the +@code{gnus-global-score-files} variable. One entry for each score file, +or each score file directory. Gnus will decide by itself what score +files are applicable to which group. + +Say you want to use the score file +@file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and +all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory: + +@lisp +(setq gnus-global-score-files + '("/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE" + "/ftp@@ftp.some-where:/pub/score/")) +@end lisp + +@findex gnus-score-search-global-directories +Simple, eh? Directory names must end with a @samp{/}. These +directories are typically scanned only once during each Gnus session. +If you feel the need to manually re-scan the remote directories, you can +use the @code{gnus-score-search-global-directories} command. + +Note that, at present, using this option will slow down group entry +somewhat. (That is---a lot.) + +If you want to start maintaining score files for other people to use, +just put your score file up for anonymous ftp and announce it to the +world. Become a retro-moderator! Participate in the retro-moderator +wars sure to ensue, where retro-moderators battle it out for the +sympathy of the people, luring them to use their score files on false +premises! Yay! The net is saved! + +Here are some tips for the would-be retro-moderator, off the top of my +head: + +@itemize @bullet + +@item +Articles heavily crossposted are probably junk. +@item +To lower a single inappropriate article, lower by @code{Message-ID}. +@item +Particularly brilliant authors can be raised on a permanent basis. +@item +Authors that repeatedly post off-charter for the group can safely be +lowered out of existence. +@item +Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest +articles completely. + +@item +Use expiring score entries to keep the size of the file down. You +should probably have a long expiry period, though, as some sites keep +old articles for a long time. +@end itemize + +... I wonder whether other newsreaders will support global score files +in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue +Wave, xrn and 1stReader are bound to implement scoring. Should we start +holding our breath yet? + + +@node Kill Files +@section Kill Files +@cindex kill files + +Gnus still supports those pesky old kill files. In fact, the kill file +entries can now be expiring, which is something I wrote before Daniel +Quinlan thought of doing score files, so I've left the code in there. + +In short, kill processing is a lot slower (and I do mean @emph{a lot}) +than score processing, so it might be a good idea to rewrite your kill +files into score files. + +Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any +forms into this file, which means that you can use kill files as some +sort of primitive hook function to be run on group entry, even though +that isn't a very good idea. + +Normal kill files look like this: + +@lisp +(gnus-kill "From" "Lars Ingebrigtsen") +(gnus-kill "Subject" "ding") +(gnus-expunge "X") +@end lisp + +This will mark every article written by me as read, and remove the +marked articles from the summary buffer. Very useful, you'll agree. + +Other programs use a totally different kill file syntax. If Gnus +encounters what looks like a @code{rn} kill file, it will take a stab at +interpreting it. + +Two summary functions for editing a GNUS kill file: + +@table @kbd + +@item M-k +@kindex M-k (Summary) +@findex gnus-summary-edit-local-kill +Edit this group's kill file (@code{gnus-summary-edit-local-kill}). + +@item M-K +@kindex M-K (Summary) +@findex gnus-summary-edit-global-kill +Edit the general kill file (@code{gnus-summary-edit-global-kill}). +@end table + +Two group mode functions for editing the kill files: + +@table @kbd + +@item M-k +@kindex M-k (Group) +@findex gnus-group-edit-local-kill +Edit this group's kill file (@code{gnus-group-edit-local-kill}). + +@item M-K +@kindex M-K (Group) +@findex gnus-group-edit-global-kill +Edit the general kill file (@code{gnus-group-edit-global-kill}). +@end table + +Kill file variables: + +@table @code +@item gnus-kill-file-name +@vindex gnus-kill-file-name +A kill file for the group @samp{soc.motss} is normally called +@file{soc.motss.KILL}. The suffix appended to the group name to get +this file name is detailed by the @code{gnus-kill-file-name} variable. +The ``global'' kill file (not in the score file sense of ``global'', of +course) is just called @file{KILL}. + +@vindex gnus-kill-save-kill-file +@item gnus-kill-save-kill-file +If this variable is non-@code{nil}, Gnus will save the +kill file after processing, which is necessary if you use expiring +kills. + +@item gnus-apply-kill-hook +@vindex gnus-apply-kill-hook +@findex gnus-apply-kill-file-unless-scored +@findex gnus-apply-kill-file +A hook called to apply kill files to a group. It is +@code{(gnus-apply-kill-file)} by default. If you want to ignore the +kill file if you have a score file for the same group, you can set this +hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want +kill files to be processed, you should set this variable to @code{nil}. + +@item gnus-kill-file-mode-hook +@vindex gnus-kill-file-mode-hook +A hook called in kill-file mode buffers. + +@end table + + +@node Converting Kill Files +@section Converting Kill Files +@cindex kill files +@cindex converting kill files + +If you have loads of old kill files, you may want to convert them into +score files. If they are ``regular'', you can use +the @file{gnus-kill-to-score.el} package; if not, you'll have to do it +by hand. + +The kill to score conversion package isn't included in Gnus by default. +You can fetch it from +@file{http://www.stud.ifi.uio.no/~larsi/ding-other/gnus-kill-to-score}. + +If your old kill files are very complex---if they contain more +non-@code{gnus-kill} forms than not, you'll have to convert them by +hand. Or just let them be as they are. Gnus will still use them as +before. + + +@node GroupLens +@section GroupLens +@cindex GroupLens + +GroupLens is a collaborative filtering system that helps you work +together with other people to find the quality news articles out of the +huge volume of news articles generated every day. + +To accomplish this the GroupLens system combines your opinions about +articles you have already read with the opinions of others who have done +likewise and gives you a personalized prediction for each unread news +article. Think of GroupLens as a matchmaker. GroupLens watches how you +rate articles, and finds other people that rate articles the same way. +Once it has found some people you agree with it tells you, in the form +of a prediction, what they thought of the article. You can use this +prediction to help you decide whether or not you want to read the +article. + +@menu +* 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. +@end menu + + +@node Using GroupLens +@subsection Using GroupLens + +To use GroupLens you must register a pseudonym with your local Better +Bit Bureau (BBB). +@samp{http://www.cs.umn.edu/Research/GroupLens/bbb.html} is the only +better bit in town at the moment. + +Once you have registered you'll need to set a couple of variables. + +@table @code + +@item gnus-use-grouplens +@vindex gnus-use-grouplens +Setting this variable to a non-@code{nil} value will make Gnus hook into +all the relevant GroupLens functions. + +@item grouplens-pseudonym +@vindex grouplens-pseudonym +This variable should be set to the pseudonym you got when registering +with the Better Bit Bureau. + +@item grouplens-newsgroups +@vindex grouplens-newsgroups +A list of groups that you want to get GroupLens predictions for. + +@end table + +That's the minimum of what you need to get up and running with GroupLens. +Once you've registered, GroupLens will start giving you scores for +articles based on the average of what other people think. But, to get +the real benefit of GroupLens you need to start rating articles +yourself. Then the scores GroupLens gives you will be personalized for +you, based on how the people you usually agree with have already rated. + + +@node Rating Articles +@subsection Rating Articles + +In GroupLens, an article is rated on a scale from 1 to 5, inclusive. +Where 1 means something like this article is a waste of bandwidth and 5 +means that the article was really good. The basic question to ask +yourself is, "on a scale from 1 to 5 would I like to see more articles +like this one?" + +There are four ways to enter a rating for an article in GroupLens. + +@table @kbd + +@item r +@kindex r (GroupLens) +@findex bbb-summary-rate-article +This function will prompt you for a rating on a scale of one to five. + +@item k +@kindex k (GroupLens) +@findex grouplens-score-thread +This function will prompt you for a rating, and rate all the articles in +the thread. This is really useful for some of those long running giant +threads in rec.humor. + +@end table + +The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be +the score of the article you're reading. + +@table @kbd + +@item 1-5 n +@kindex n (GroupLens) +@findex grouplens-next-unread-article +Rate the article and go to the next unread article. + +@item 1-5 , +@kindex , (GroupLens) +@findex grouplens-best-unread-article +Rate the article and go to the next unread article with the highest score. + +@end table + +If you want to give the current article a score of 4 and then go to the +next article, just type @kbd{4 n}. + + +@node Displaying Predictions +@subsection Displaying Predictions + +GroupLens makes a prediction for you about how much you will like a +news article. The predictions from GroupLens are on a scale from 1 to +5, where 1 is the worst and 5 is the best. You can use the predictions +from GroupLens in one of three ways controlled by the variable +@code{gnus-grouplens-override-scoring}. + +@vindex gnus-grouplens-override-scoring +There are three ways to display predictions in grouplens. You may +choose to have the GroupLens scores contribute to, or override the +regular gnus scoring mechanism. override is the default; however, some +people prefer to see the Gnus scores plus the grouplens scores. To get +the separate scoring behavior you need to set +@code{gnus-grouplens-override-scoring} to @code{'separate}. To have the +GroupLens predictions combined with the grouplens scores set it to +@code{'override} and to combine the scores set +@code{gnus-grouplens-override-scoring} to @code{'combine}. When you use +the combine option you will also want to set the values for +@code{grouplens-prediction-offset} and +@code{grouplens-score-scale-factor}. + +@vindex grouplens-prediction-display +In either case, GroupLens gives you a few choices for how you would like +to see your predictions displayed. The display of predictions is +controlled by the @code{grouplens-prediction-display} variable. + +The following are valid values for that variable. + +@table @code +@item prediction-spot +The higher the prediction, the further to the right an @samp{*} is +displayed. + +@item confidence-interval +A numeric confidence interval. + +@item prediction-bar +The higher the prediction, the longer the bar. + +@item confidence-bar +Numerical confidence. + +@item confidence-spot +The spot gets bigger with more confidence. + +@item prediction-num +Plain-old numeric value. + +@item confidence-plus-minus +Prediction +/- confidence. + +@end table + + +@node GroupLens Variables +@subsection GroupLens Variables + +@table @code + +@item gnus-summary-grouplens-line-format +The summary line format used in GroupLens-enhanced summary buffers. It +accepts the same specs as the normal summary line format (@pxref{Summary +Buffer Lines}). The default is @samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%) +%s\n}. + +@item grouplens-bbb-host +Host running the bbbd server. @samp{grouplens.cs.umn.edu} is the +default. + +@item grouplens-bbb-port +Port of the host running the bbbd server. The default is 9000. + +@item grouplens-score-offset +Offset the prediction by this value. In other words, subtract the +prediction value by this number to arrive at the effective score. The +default is 0. + +@item grouplens-score-scale-factor +This variable allows the user to magnify the effect of GroupLens scores. +The scale factor is applied after the offset. The default is 1. + +@end table + + +@node Advanced Scoring +@section Advanced Scoring + +Scoring on Subjects and From headers is nice enough, but what if you're +really interested in what a person has to say only when she's talking +about a particular subject? Or what if you really don't want to +read what person A has to say when she's following up to person B, but +want to read what she says when she's following up to person C? + +By using advanced scoring rules you may create arbitrarily complex +scoring patterns. + +@menu +* Advanced Scoring Syntax:: A definition. +* Advanced Scoring Examples:: What they look like. +* Advanced Scoring Tips:: Getting the most out of it. +@end menu + + +@node Advanced Scoring Syntax +@subsection Advanced Scoring Syntax + +Ordinary scoring rules have a string as the first element in the rule. +Advanced scoring rules have a list as the first element. The second +element is the score to be applied if the first element evaluated to a +non-@code{nil} value. + +These lists may consist of three logical operators, one redirection +operator, and various match operators. + +Logical operators: + +@table @code +@item & +@itemx and +This logical operator will evaluate each of its arguments until it finds +one that evaluates to @code{false}, and then it'll stop. If all arguments +evaluate to @code{true} values, then this operator will return +@code{true}. + +@item | +@itemx or +This logical operator will evaluate each of its arguments until it finds +one that evaluates to @code{true}. If no arguments are @code{true}, +then this operator will return @code{false}. + +@item ! +@itemx not +@itemx ,A,(B +This logical operator only takes a single argument. It returns the +logical negation of the value of its argument. + +@end table + +There is an @dfn{indirection operator} that will make its arguments +apply to the ancestors of the current article being scored. For +instance, @code{1-} will make score rules apply to the parent of the +current article. @code{2-} will make score rules apply to the +grandparent of the current article. Alternatively, you can write +@code{^^}, where the number of @code{^}s (carets) says how far back into +the ancestry you want to go. + +Finally, we have the match operators. These are the ones that do the +real work. Match operators are header name strings followed by a match +and a match type. A typical match operator looks like @samp{("from" +"Lars Ingebrigtsen" s)}. The header names are the same as when using +simple scoring, and the match types are also the same. + + +@node Advanced Scoring Examples +@subsection Advanced Scoring Examples + +Let's say you want to increase the score of articles written by Lars +when he's talking about Gnus: + +@example +((& + ("from" "Lars Ingebrigtsen") + ("subject" "Gnus")) + 1000) +@end example + +Quite simple, huh? + +When he writes long articles, he sometimes has something nice to say: + +@example +((& + ("from" "Lars Ingebrigtsen") + (| + ("subject" "Gnus") + ("lines" 100 >))) + 1000) +@end example + +However, when he responds to things written by Reig Eigil Logge, you +really don't want to read what he's written: + +@example +((& + ("from" "Lars Ingebrigtsen") + (1- ("from" "Reig Eigir Logge"))) + -100000) +@end example + +Everybody that follows up Redmondo when he writes about disappearing +socks should have their scores raised, but only when they talk about +white socks. However, when Lars talks about socks, it's usually not +very interesting: + +@example +((& + (1- + (& + ("from" "redmondo@@.*no" r) + ("body" "disappearing.*socks" t))) + (! ("from" "Lars Ingebrigtsen")) + ("body" "white.*socks")) + 1000) +@end example + +The possibilities are endless. + + +@node Advanced Scoring Tips +@subsection Advanced Scoring Tips + +The @code{&} and @code{|} logical operators do short-circuit logic. +That is, they stop processing their arguments when it's clear what the +result of the operation will be. For instance, if one of the arguments +of an @code{&} evaluates to @code{false}, there's no point in evaluating +the rest of the arguments. This means that you should put slow matches +(@samp{body}, @samp{header}) last and quick matches (@samp{from}, +@samp{subject}) first. + +The indirection arguments (@code{1-} and so on) will make their +arguments work on previous generations of the thread. If you say +something like: + +@example +... +(1- + (1- + ("from" "lars"))) +... +@end example + +Then that means "score on the from header of the grandparent of the +current article". An indirection is quite fast, but it's better to say: + +@example +(1- + (& + ("from" "Lars") + ("subject" "Gnus"))) +@end example + +than it is to say: + +@example +(& + (1- ("from" "Lars")) + (1- ("subject" "Gnus"))) +@end example + + +@node Score Decays +@section Score Decays +@cindex score decays +@cindex decays + +You may find that your scores have a tendency to grow without +bounds, especially if you're using adaptive scoring. If scores get too +big, they lose all meaning---they simply max out and it's difficult to +use them in any sensible way. + +@vindex gnus-decay-scores +@findex gnus-decay-score +@vindex gnus-decay-score-function +Gnus provides a mechanism for decaying scores to help with this problem. +When score files are loaded and @code{gnus-decay-scores} is +non-@code{nil}, Gnus will run the score files through the decaying +mechanism thereby lowering the scores of all non-permanent score rules. +The decay itself if performed by the @code{gnus-decay-score-function} +function, which is @code{gnus-decay-score} by default. Here's the +definition of that function: + +@lisp +(defun gnus-decay-score (score) + "Decay SCORE. +This is done according to `gnus-score-decay-constant' +and `gnus-score-decay-scale'." + (floor + (- score + (* (if (< score 0) 1 -1) + (min (abs score) + (max gnus-score-decay-constant + (* (abs score) + gnus-score-decay-scale))))))) +@end lisp + +@vindex gnus-score-decay-scale +@vindex gnus-score-decay-constant +@code{gnus-score-decay-constant} is 3 by default and +@code{gnus-score-decay-scale} is 0.05. This should cause the following: + +@enumerate +@item +Scores between -3 and 3 will be set to 0 when this function is called. + +@item +Scores with magnitudes between 3 and 60 will be shrunk by 3. + +@item +Scores with magnitudes greater than 60 will be shrunk by 5% of the +score. +@end enumerate + +If you don't like this decay function, write your own. It is called +with the score to be decayed as its only parameter, and it should return +the new score, which should be an integer. + +Gnus will try to decay scores once a day. If you haven't run Gnus for +four days, Gnus will decay the scores four times, for instance. + + +@node Various +@chapter Various + +@menu +* 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. +* Windows Configuration:: 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 tendonitis 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. +* Moderation:: What to do if you're a moderator. +* XEmacs Enhancements:: There are more pictures and stuff under XEmacs. +* Fuzzy Matching:: What's the big fuzz? +* Thwarting Email Spam:: A how-to on avoiding unsolicited commercial email. +* Various Various:: Things that are really various. +@end menu + + +@node Process/Prefix +@section Process/Prefix +@cindex process/prefix convention + +Many functions, among them functions for moving, decoding and saving +articles, use what is known as the @dfn{Process/Prefix convention}. + +This is a method for figuring out what articles the user wants the +command to be performed on. + +It goes like this: + +If the numeric prefix is N, perform the operation on the next N +articles, starting with the current one. If the numeric prefix is +negative, perform the operation on the previous N articles, starting +with the current one. + +@vindex transient-mark-mode +If @code{transient-mark-mode} in non-@code{nil} and the region is +active, all articles in the region will be worked upon. + +If there is no numeric prefix, but some articles are marked with the +process mark, perform the operation on the articles marked with +the process mark. + +If there is neither a numeric prefix nor any articles marked with the +process mark, just perform the operation on the current article. + +Quite simple, really, but it needs to be made clear so that surprises +are avoided. + +Commands that react to the process mark will push the current list of +process marked articles onto a stack and will then clear all process +marked articles. You can restore the previous configuration with the +@kbd{M P y} command (@pxref{Setting Process Marks}). + +@vindex gnus-summary-goto-unread +One thing that seems to shock & horrify lots of people is that, for +instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}. +Since each @kbd{d} (which marks the current article as read) by default +goes to the next unread article after marking, this means that @kbd{3 d} +will mark the next three unread articles as read, no matter what the +summary buffer looks like. Set @code{gnus-summary-goto-unread} to +@code{nil} for a more straightforward action. + + +@node Interactive +@section Interactive +@cindex interaction + +@table @code + +@item gnus-novice-user +@vindex gnus-novice-user +If this variable is non-@code{nil}, you are either a newcomer to the +World of Usenet, or you are very cautious, which is a nice thing to be, +really. You will be given questions of the type ``Are you sure you want +to do this?'' before doing anything dangerous. This is @code{t} by +default. + +@item gnus-expert-user +@vindex gnus-expert-user +If this variable is non-@code{nil}, you will seldom be asked any +questions by Gnus. It will simply assume you know what you're doing, no +matter how strange. + +@item gnus-interactive-catchup +@vindex gnus-interactive-catchup +Require confirmation before catching up a group if non-@code{nil}. It +is @code{t} by default. + +@item gnus-interactive-exit +@vindex gnus-interactive-exit +Require confirmation before exiting Gnus. This variable is @code{t} by +default. +@end table + + +@node Symbolic Prefixes +@section Symbolic Prefixes +@cindex symbolic prefixes + +Quite a lot of Emacs commands react to the (numeric) prefix. For +instance, @kbd{C-u 4 C-f} moves point four characters forward, and +@kbd{C-u 9 0 0 I s s p} adds a permanent @code{Subject} substring score +rule of 900 to the current article. + +This is all nice and well, but what if you want to give a command some +additional information? Well, what most commands do is interpret the +``raw'' prefix in some special way. @kbd{C-u 0 C-x C-s} means that one +doesn't want a backup file to be created when saving the current buffer, +for instance. But what if you want to save without making a backup +file, and you want Emacs to flash lights and play a nice tune at the +same time? You can't, and you're probably perfectly happy that way. + +@kindex M-i (Summary) +@findex gnus-symbolic-argument +I'm not, so I've added a second prefix---the @dfn{symbolic prefix}. The +prefix key is @kbd{M-i} (@code{gnus-symbolic-argument}), and the next +character typed in is the value. You can stack as many @kbd{M-i} +prefixes as you want. @kbd{M-i a M-C-u} means ``feed the @kbd{M-C-u} +command the symbolic prefix @code{a}''. @kbd{M-i a M-i b M-C-u} means +``feed the @kbd{M-C-u} command the symbolic prefixes @code{a} and +@code{b}''. You get the drift. + +Typing in symbolic prefixes to commands that don't accept them doesn't +hurt, but it doesn't do any good either. Currently not many Gnus +functions make use of the symbolic prefix. + +If you're interested in how Gnus implements this, @pxref{Extended +Interactive}. + + +@node Formatting Variables +@section Formatting Variables +@cindex formatting variables + +Throughout this manual you've probably noticed lots of variables called +things like @code{gnus-group-line-format} and +@code{gnus-summary-mode-line-format}. These control how Gnus is to +output lines in the various buffers. There's quite a lot of them. +Fortunately, they all use the same syntax, so there's not that much to +be annoyed by. + +Here's an example format spec (from the group buffer): @samp{%M%S%5y: +%(%g%)\n}. We see that it is indeed extremely ugly, and that there are +lots of percentages everywhere. + +@menu +* 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. +@end menu + +Currently Gnus uses the following formatting variables: +@code{gnus-group-line-format}, @code{gnus-summary-line-format}, +@code{gnus-server-line-format}, @code{gnus-topic-line-format}, +@code{gnus-group-mode-line-format}, +@code{gnus-summary-mode-line-format}, +@code{gnus-article-mode-line-format}, +@code{gnus-server-mode-line-format}, and +@code{gnus-summary-pick-line-format}. + +All these format variables can also be arbitrary elisp forms. In that +case, they will be @code{eval}ed to insert the required lines. + +@kindex M-x gnus-update-format +@findex gnus-update-format +Gnus includes a command to help you while creating your own format +specs. @kbd{M-x gnus-update-format} will @code{eval} the current form, +update the spec in question and pop you to a buffer where you can +examine the resulting lisp code to be run to generate the line. + + + +@node Formatting Basics +@subsection Formatting Basics + +Each @samp{%} element will be replaced by some string or other when the +buffer in question is generated. @samp{%5y} means ``insert the @samp{y} +spec, and pad with spaces to get a 5-character field''. + +As with normal C and Emacs Lisp formatting strings, the numerical +modifier between the @samp{%} and the formatting type character will +@dfn{pad} the output so that it is always at least that long. +@samp{%5y} will make the field always (at least) five characters wide by +padding with spaces to the left. If you say @samp{%-5y}, it will pad to +the right instead. + +You may also wish to limit the length of the field to protect against +particularly wide values. For that you can say @samp{%4,6y}, which +means that the field will never be more than 6 characters wide and never +less than 4 characters wide. + + +@node Mode Line Formatting +@subsection Mode Line Formatting + +Mode line formatting variables (e.g., +@code{gnus-summary-mode-line-format}) follow the same rules as other, +buffer line oriented formatting variables (@pxref{Formatting Basics}) +with the following two differences: + +@enumerate + +@item +There must be no newline (@samp{\n}) at the end. + +@item +The special @samp{%%b} spec can be used to display the buffer name. +Well, it's no spec at all, really---@samp{%%} is just a way to quote +@samp{%} to allow it to pass through the formatting machinery unmangled, +so that Emacs receives @samp{%b}, which is something the Emacs mode line +display interprets to mean ``show the buffer name''. For a full list of +mode line specs Emacs understands, see the documentation of the +@code{mode-line-format} variable. + +@end enumerate + + +@node Advanced Formatting +@subsection Advanced Formatting + +It is frequently useful to post-process the fields in some way. +Padding, limiting, cutting off parts and suppressing certain values can +be achieved by using @dfn{tilde modifiers}. A typical tilde spec might +look like @samp{%~(cut 3)~(ignore "0")y}. + +These are the valid modifiers: + +@table @code +@item pad +@itemx pad-left +Pad the field to the left with spaces until it reaches the required +length. + +@item pad-right +Pad the field to the right with spaces until it reaches the required +length. + +@item max +@itemx max-left +Cut off characters from the left until it reaches the specified length. + +@item max-right +Cut off characters from the right until it reaches the specified +length. + +@item cut +@itemx cut-left +Cut off the specified number of characters from the left. + +@item cut-right +Cut off the specified number of characters from the right. + +@item ignore +Return an empty string if the field is equal to the specified value. + +@item form +Use the specified form as the field value when the @samp{@@} spec is +used. +@end table + +Let's take an example. The @samp{%o} spec in the summary mode lines +will return a date in compact ISO8601 format---@samp{19960809T230410}. +This is quite a mouthful, so we want to shave off the century number and +the time, leaving us with a six-character date. That would be +@samp{%~(cut-left 2)~(max-right 6)~(pad 6)o}. (Cutting is done before +maxing, and we need the padding to ensure that the date is never less +than 6 characters to make it look nice in columns.) + +Ignoring is done first; then cutting; then maxing; and then as the very +last operation, padding. + +If you use lots of these advanced thingies, you'll find that Gnus gets +quite slow. This can be helped enormously by running @kbd{M-x +gnus-compile} when you are satisfied with the look of your lines. +@xref{Compilation}. + + +@node User-Defined Specs +@subsection User-Defined Specs + +All the specs allow for inserting user defined specifiers---@samp{u}. +The next character in the format string should be a letter. Gnus +will call the function @code{gnus-user-format-function-}@samp{X}, where +@samp{X} is the letter following @samp{%u}. The function will be passed +a single parameter---what the parameter means depends on what buffer +it's being called from. The function should return a string, which will +be inserted into the buffer just like information from any other +specifier. This function may also be called with dummy values, so it +should protect against that. + +You can also use tilde modifiers (@pxref{Advanced Formatting} to achieve +much the same without defining new functions. Here's an example: +@samp{%~(form (count-lines (point-min) (point)))@@}. The form +given here will be evaluated to yield the current line number, and then +inserted. + + +@node Formatting Fonts +@subsection Formatting Fonts + +There are specs for highlighting, and these are shared by all the format +variables. Text inside the @samp{%(} and @samp{%)} specifiers will get +the special @code{mouse-face} property set, which means that it will be +highlighted (with @code{gnus-mouse-face}) when you put the mouse pointer +over it. + +Text inside the @samp{%@{} and @samp{%@}} specifiers will have their +normal faces set using @code{gnus-face-0}, which is @code{bold} by +default. If you say @samp{%1@{}, you'll get @code{gnus-face-1} instead, +and so on. Create as many faces as you wish. The same goes for the +@code{mouse-face} specs---you can say @samp{%3(hello%)} to have +@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}. + +Here's an alternative recipe for the group buffer: + +@lisp +;; Create three face types. +(setq gnus-face-1 'bold) +(setq gnus-face-3 'italic) + +;; We want the article count to be in +;; a bold and green face. So we create +;; a new face called `my-green-bold'. +(copy-face 'bold 'my-green-bold) +;; Set the color. +(set-face-foreground 'my-green-bold "ForestGreen") +(setq gnus-face-2 'my-green-bold) + +;; Set the new & fancy format. +(setq gnus-group-line-format + "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n") +@end lisp + +I'm sure you'll be able to use this scheme to create totally unreadable +and extremely vulgar displays. Have fun! + +Note that the @samp{%(} specs (and friends) do not make any sense on the +mode-line variables. + + +@node Windows Configuration +@section Windows Configuration +@cindex windows configuration + +No, there's nothing here about X, so be quiet. + +@vindex gnus-use-full-window +If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all +other windows and occupy the entire Emacs screen by itself. It is +@code{t} by default. + +Setting this variable to @code{nil} kinda works, but there are +glitches. Use at your own peril. + +@vindex gnus-buffer-configuration +@code{gnus-buffer-configuration} describes how much space each Gnus +buffer should be given. Here's an excerpt of this variable: + +@lisp +((group (vertical 1.0 (group 1.0 point) + (if gnus-carpal (group-carpal 4)))) + (article (vertical 1.0 (summary 0.25 point) + (article 1.0)))) +@end lisp + +This is an alist. The @dfn{key} is a symbol that names some action or +other. For instance, when displaying the group buffer, the window +configuration function will use @code{group} as the key. A full list of +possible names is listed below. + +The @dfn{value} (i.e., the @dfn{split}) says how much space each buffer +should occupy. To take the @code{article} split as an example - + +@lisp +(article (vertical 1.0 (summary 0.25 point) + (article 1.0))) +@end lisp + +This @dfn{split} says that the summary buffer should occupy 25% of upper +half of the screen, and that it is placed over the article buffer. As +you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all +reaching for that calculator there). However, the special number +@code{1.0} is used to signal that this buffer should soak up all the +rest of the space available after the rest of the buffers have taken +whatever they need. There should be only one buffer with the @code{1.0} +size spec per split. + +Point will be put in the buffer that has the optional third element +@code{point}. In a @code{frame} split, the last subsplit having a leaf +split where the tag @code{frame-focus} is a member (i.e. is the third or +fourth element in the list, depending on whether the @code{point} tag is +present) gets focus. + +Here's a more complicated example: + +@lisp +(article (vertical 1.0 (group 4) + (summary 0.25 point) + (if gnus-carpal (summary-carpal 4)) + (article 1.0))) +@end lisp + +If the size spec is an integer instead of a floating point number, +then that number will be used to say how many lines a buffer should +occupy, not a percentage. + +If the @dfn{split} looks like something that can be @code{eval}ed (to be +precise---if the @code{car} of the split is a function or a subr), this +split will be @code{eval}ed. If the result is non-@code{nil}, it will +be used as a split. This means that there will be three buffers if +@code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal} +is non-@code{nil}. + +Not complicated enough for you? Well, try this on for size: + +@lisp +(article (horizontal 1.0 + (vertical 0.5 + (group 1.0) + (gnus-carpal 4)) + (vertical 1.0 + (summary 0.25 point) + (summary-carpal 4) + (article 1.0)))) +@end lisp + +Whoops. Two buffers with the mystery 100% tag. And what's that +@code{horizontal} thingie? + +If the first element in one of the split is @code{horizontal}, Gnus will +split the window horizontally, giving you two windows side-by-side. +Inside each of these strips you may carry on all you like in the normal +fashion. The number following @code{horizontal} says what percentage of +the screen is to be given to this strip. + +For each split, there @emph{must} be one element that has the 100% tag. +The splitting is never accurate, and this buffer will eat any leftover +lines from the splits. + +To be slightly more formal, here's a definition of what a valid split +may look like: + +@example +split = frame | horizontal | vertical | buffer | form +frame = "(frame " size *split ")" +horizontal = "(horizontal " size *split ")" +vertical = "(vertical " size *split ")" +buffer = "(" buffer-name " " size *[ "point" ] *[ "frame-focus"] ")" +size = number | frame-params +buffer-name = group | article | summary ... +@end example + +The limitations are that the @code{frame} split can only appear as the +top-level split. @var{form} should be an Emacs Lisp form that should +return a valid split. We see that each split is fully recursive, and +may contain any number of @code{vertical} and @code{horizontal} splits. + +@vindex gnus-window-min-width +@vindex gnus-window-min-height +@cindex window height +@cindex window width +Finding the right sizes can be a bit complicated. No window may be less +than @code{gnus-window-min-height} (default 1) characters high, and all +windows must be at least @code{gnus-window-min-width} (default 1) +characters wide. Gnus will try to enforce this before applying the +splits. If you want to use the normal Emacs window width/height limit, +you can just set these two variables to @code{nil}. + +If you're not familiar with Emacs terminology, @code{horizontal} and +@code{vertical} splits may work the opposite way of what you'd expect. +Windows inside a @code{horizontal} split are shown side-by-side, and +windows within a @code{vertical} split are shown above each other. + +@findex gnus-configure-frame +If you want to experiment with window placement, a good tip is to call +@code{gnus-configure-frame} directly with a split. This is the function +that does all the real work when splitting buffers. Below is a pretty +nonsensical configuration with 5 windows; two for the group buffer and +three for the article buffer. (I said it was nonsensical.) If you +@code{eval} the statement below, you can get an idea of how that would +look straight away, without going through the normal Gnus channels. +Play with it until you're satisfied, and then use +@code{gnus-add-configuration} to add your new creation to the buffer +configuration list. + +@lisp +(gnus-configure-frame + '(horizontal 1.0 + (vertical 10 + (group 1.0) + (article 0.3 point)) + (vertical 1.0 + (article 1.0) + (horizontal 4 + (group 1.0) + (article 10))))) +@end lisp + +You might want to have several frames as well. No prob---just use the +@code{frame} split: + +@lisp +(gnus-configure-frame + '(frame 1.0 + (vertical 1.0 + (summary 0.25 point frame-focus) + (article 1.0)) + (vertical ((height . 5) (width . 15) + (user-position . t) + (left . -1) (top . 1)) + (picon 1.0)))) + +@end lisp + +This split will result in the familiar summary/article window +configuration in the first (or ``main'') frame, while a small additional +frame will be created where picons will be shown. As you can see, +instead of the normal @code{1.0} top-level spec, each additional split +should have a frame parameter alist as the size spec. +@xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp +Reference Manual}. Under XEmacs, a frame property list will be +accepted, too---for instance, @code{(height 5 width 15 left -1 top 1)} +is such a plist. + +Here's a list of all possible keys for +@code{gnus-buffer-configuration}: + +@code{group}, @code{summary}, @code{article}, @code{server}, +@code{browse}, @code{message}, @code{pick}, @code{info}, +@code{summary-faq}, @code{edit-group}, @code{edit-server}, +@code{edit-score}, @code{post}, @code{reply}, @code{forward}, +@code{reply-yank}, @code{mail-bounce}, @code{draft}, @code{pipe}, +@code{bug}, @code{compose-bounce}, and @code{score-trace}. + +Note that the @code{message} key is used for both +@code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If +it is desirable to distinguish between the two, something like this +might be used: + +@lisp +(message (horizontal 1.0 + (vertical 1.0 (message 1.0 point)) + (vertical 0.24 + (if (buffer-live-p gnus-summary-buffer) + '(summary 0.5)) + (group 1.0))))) +@end lisp + +@findex gnus-add-configuration +Since the @code{gnus-buffer-configuration} variable is so long and +complicated, there's a function you can use to ease changing the config +of a single setting: @code{gnus-add-configuration}. If, for instance, +you want to change the @code{article} setting, you could say: + +@lisp +(gnus-add-configuration + '(article (vertical 1.0 + (group 4) + (summary .25 point) + (article 1.0)))) +@end lisp + +You'd typically stick these @code{gnus-add-configuration} calls in your +@file{.gnus.el} file or in some startup hook---they should be run after +Gnus has been loaded. + +@vindex gnus-always-force-window-configuration +If all windows mentioned in the configuration are already visible, Gnus +won't change the window configuration. If you always want to force the +``right'' window configuration, you can set +@code{gnus-always-force-window-configuration} to non-@code{nil}. + + +@node Faces and Fonts +@section Faces and Fonts +@cindex faces +@cindex fonts +@cindex colors + +Fiddling with fonts and faces used to be very difficult, but these days +it is very simple. You simply say @kbd{M-x customize-face}, pick out +the face you want to alter, and alter it via the standard Customize +interface. + + +@node Compilation +@section Compilation +@cindex compilation +@cindex byte-compilation + +@findex gnus-compile + +Remember all those line format specification variables? +@code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so +on. Now, Gnus will of course heed whatever these variables are, but, +unfortunately, changing them will mean a quite significant slow-down. +(The default values of these variables have byte-compiled functions +associated with them, while the user-generated versions do not, of +course.) + +To help with this, you can run @kbd{M-x gnus-compile} after you've +fiddled around with the variables and feel that you're (kind of) +satisfied. This will result in the new specs being byte-compiled, and +you'll get top speed again. Gnus will save these compiled specs in the +@file{.newsrc.eld} file. (User-defined functions aren't compiled by +this function, though---you should compile them yourself by sticking +them into the @code{.gnus.el} file and byte-compiling that file.) + + +@node Mode Lines +@section Mode Lines +@cindex mode lines + +@vindex gnus-updated-mode-lines +@code{gnus-updated-mode-lines} says what buffers should keep their mode +lines updated. It is a list of symbols. Supported symbols include +@code{group}, @code{article}, @code{summary}, @code{server}, +@code{browse}, and @code{tree}. If the corresponding symbol is present, +Gnus will keep that mode line updated with information that may be +pertinent. If this variable is @code{nil}, screen refresh may be +quicker. + +@cindex display-time + +@vindex gnus-mode-non-string-length +By default, Gnus displays information on the current article in the mode +lines of the summary and article buffers. The information Gnus wishes +to display (e.g. the subject of the article) is often longer than the +mode lines, and therefore have to be cut off at some point. The +@code{gnus-mode-non-string-length} variable says how long the other +elements on the line is (i.e., the non-info part). If you put +additional elements on the mode line (e.g. a clock), you should modify +this variable: + +@c Hook written by Francesco Potorti` +@lisp +(add-hook 'display-time-hook + (lambda () (setq gnus-mode-non-string-length + (+ 21 + (if line-number-mode 5 0) + (if column-number-mode 4 0) + (length display-time-string))))) +@end lisp + +If this variable is @code{nil} (which is the default), the mode line +strings won't be chopped off, and they won't be padded either. Note +that the default is unlikely to be desirable, as even the percentage +complete in the buffer may be crowded off the mode line; the user should +configure this variable appropriately for her configuration. + + +@node Highlighting and Menus +@section Highlighting and Menus +@cindex visual +@cindex highlighting +@cindex menus + +@vindex gnus-visual +The @code{gnus-visual} variable controls most of the Gnus-prettifying +aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy +colors or fonts. This will also inhibit loading the @file{gnus-vis.el} +file. + +This variable can be a list of visual properties that are enabled. The +following elements are valid, and are all included by default: + +@table @code +@item group-highlight +Do highlights in the group buffer. +@item summary-highlight +Do highlights in the summary buffer. +@item article-highlight +Do highlights according to @code{gnus-article-display-hook} in the +article buffer. +@item highlight +Turn on highlighting in all buffers. +@item group-menu +Create menus in the group buffer. +@item summary-menu +Create menus in the summary buffers. +@item article-menu +Create menus in the article buffer. +@item browse-menu +Create menus in the browse buffer. +@item server-menu +Create menus in the server buffer. +@item score-menu +Create menus in the score buffers. +@item menu +Create menus in all buffers. +@end table + +So if you only want highlighting in the article buffer and menus in all +buffers, you could say something like: + +@lisp +(setq gnus-visual '(article-highlight menu)) +@end lisp + +If you want highlighting only and no menus whatsoever, you'd say: + +@lisp +(setq gnus-visual '(highlight)) +@end lisp + +If @code{gnus-visual} is @code{t}, highlighting and menus will be used +in all Gnus buffers. + +Other general variables that influence the look of all buffers include: + +@table @code +@item gnus-mouse-face +@vindex gnus-mouse-face +This is the face (i.e., font) used for mouse highlighting in Gnus. No +mouse highlights will be done if @code{gnus-visual} is @code{nil}. + +@end table + +There are hooks associated with the creation of all the different menus: + +@table @code + +@item gnus-article-menu-hook +@vindex gnus-article-menu-hook +Hook called after creating the article mode menu. + +@item gnus-group-menu-hook +@vindex gnus-group-menu-hook +Hook called after creating the group mode menu. + +@item gnus-summary-menu-hook +@vindex gnus-summary-menu-hook +Hook called after creating the summary mode menu. + +@item gnus-server-menu-hook +@vindex gnus-server-menu-hook +Hook called after creating the server mode menu. + +@item gnus-browse-menu-hook +@vindex gnus-browse-menu-hook +Hook called after creating the browse mode menu. + +@item gnus-score-menu-hook +@vindex gnus-score-menu-hook +Hook called after creating the score mode menu. + +@end table + + +@node Buttons +@section Buttons +@cindex buttons +@cindex mouse +@cindex click + +Those new-fangled @dfn{mouse} contraptions is very popular with the +young, hep kids who don't want to learn the proper way to do things +these days. Why, I remember way back in the summer of '89, when I was +using Emacs on a Tops 20 system. Three hundred users on one single +machine, and every user was running Simula compilers. Bah! + +Right. + +@vindex gnus-carpal +Well, you can make Gnus display bufferfuls of buttons you can click to +do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple, +really. Tell the chiropractor I sent you. + + +@table @code + +@item gnus-carpal-mode-hook +@vindex gnus-carpal-mode-hook +Hook run in all carpal mode buffers. + +@item gnus-carpal-button-face +@vindex gnus-carpal-button-face +Face used on buttons. + +@item gnus-carpal-header-face +@vindex gnus-carpal-header-face +Face used on carpal buffer headers. + +@item gnus-carpal-group-buffer-buttons +@vindex gnus-carpal-group-buffer-buttons +Buttons in the group buffer. + +@item gnus-carpal-summary-buffer-buttons +@vindex gnus-carpal-summary-buffer-buttons +Buttons in the summary buffer. + +@item gnus-carpal-server-buffer-buttons +@vindex gnus-carpal-server-buffer-buttons +Buttons in the server buffer. + +@item gnus-carpal-browse-buffer-buttons +@vindex gnus-carpal-browse-buffer-buttons +Buttons in the browse buffer. +@end table + +All the @code{buttons} variables are lists. The elements in these list +are either cons cells where the @code{car} contains a text to be displayed and +the @code{cdr} contains a function symbol, or a simple string. + + +@node Daemons +@section Daemons +@cindex demons +@cindex daemons + +Gnus, being larger than any program ever written (allegedly), does lots +of strange stuff that you may wish to have done while you're not +present. For instance, you may want it to check for new mail once in a +while. Or you may want it to close down all connections to all servers +when you leave Emacs idle. And stuff like that. + +Gnus will let you do stuff like that by defining various +@dfn{handlers}. Each handler consists of three elements: A +@var{function}, a @var{time}, and an @var{idle} parameter. + +Here's an example of a handler that closes connections when Emacs has +been idle for thirty minutes: + +@lisp +(gnus-demon-close-connections nil 30) +@end lisp + +Here's a handler that scans for PGP headers every hour when Emacs is +idle: + +@lisp +(gnus-demon-scan-pgp 60 t) +@end lisp + +This @var{time} parameter and than @var{idle} parameter work together +in a strange, but wonderful fashion. Basically, if @var{idle} is +@code{nil}, then the function will be called every @var{time} minutes. + +If @var{idle} is @code{t}, then the function will be called after +@var{time} minutes only if Emacs is idle. So if Emacs is never idle, +the function will never be called. But once Emacs goes idle, the +function will be called every @var{time} minutes. + +If @var{idle} is a number and @var{time} is a number, the function will +be called every @var{time} minutes only when Emacs has been idle for +@var{idle} minutes. + +If @var{idle} is a number and @var{time} is @code{nil}, the function +will be called once every time Emacs has been idle for @var{idle} +minutes. + +And if @var{time} is a string, it should look like @samp{07:31}, and +the function will then be called once every day somewhere near that +time. Modified by the @var{idle} parameter, of course. + +@vindex gnus-demon-timestep +(When I say ``minute'' here, I really mean @code{gnus-demon-timestep} +seconds. This is 60 by default. If you change that variable, +all the timings in the handlers will be affected.) + +@vindex gnus-use-demon +To set the whole thing in motion, though, you have to set +@code{gnus-use-demon} to @code{t}. + +So, if you want to add a handler, you could put something like this in +your @file{.gnus} file: + +@findex gnus-demon-add-handler +@lisp +(gnus-demon-add-handler 'gnus-demon-close-connections 30 t) +@end lisp + +@findex gnus-demon-add-nocem +@findex gnus-demon-add-scanmail +@findex gnus-demon-add-rescan +@findex gnus-demon-add-scan-timestamps +@findex gnus-demon-add-disconnection +Some ready-made functions to do this have been created: +@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, +@code{gnus-demon-add-nntp-close-connection}, +@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and +@code{gnus-demon-add-scanmail}. Just put those functions in your +@file{.gnus} if you want those abilities. + +@findex gnus-demon-init +@findex gnus-demon-cancel +@vindex gnus-demon-handlers +If you add handlers to @code{gnus-demon-handlers} directly, you should +run @code{gnus-demon-init} to make the changes take hold. To cancel all +daemons, you can use the @code{gnus-demon-cancel} function. + +Note that adding daemons can be pretty naughty if you over do it. Adding +functions that scan all news and mail from all servers every two seconds +is a sure-fire way of getting booted off any respectable system. So +behave. + + +@node NoCeM +@section NoCeM +@cindex nocem +@cindex spam + +@dfn{Spamming} is posting the same article lots and lots of times. +Spamming is bad. Spamming is evil. + +Spamming is usually canceled within a day or so by various anti-spamming +agencies. These agencies usually also send out @dfn{NoCeM} messages. +NoCeM is pronounced ``no see-'em'', and means what the name +implies---these are messages that make the offending articles, like, go +away. + +What use are these NoCeM messages if the articles are canceled anyway? +Some sites do not honor cancel messages and some sites just honor cancels +from a select few people. Then you may wish to make use of the NoCeM +messages, which are distributed in the @samp{alt.nocem.misc} newsgroup. + +Gnus can read and parse the messages in this group automatically, and +this will make spam disappear. + +There are some variables to customize, of course: + +@table @code +@item gnus-use-nocem +@vindex gnus-use-nocem +Set this variable to @code{t} to set the ball rolling. It is @code{nil} +by default. + +@item gnus-nocem-groups +@vindex gnus-nocem-groups +Gnus will look for NoCeM messages in the groups in this list. The +default is @code{("news.lists.filters" "news.admin.net-abuse.bulletins" +"alt.nocem.misc" "news.admin.net-abuse.announce")}. + +@item gnus-nocem-issuers +@vindex gnus-nocem-issuers +There are many people issuing NoCeM messages. This list says what +people you want to listen to. The default is @code{("Automoose-1" +"rbraver@@ohww.norman.ok.us" "clewis@@ferret.ocunix.on.ca" +"jem@@xpat.com" "snowhare@@xmission.com" "red@@redpoll.mrfs.oh.us +(Richard E. Depew)")}; fine, upstanding citizens all of them. + +Known despammers that you can put in this list include: + +@table @samp +@item clewis@@ferret.ocunix.on.ca; +@cindex Chris Lewis +Chris Lewis---Major Canadian despammer who has probably canceled more +usenet abuse than anybody else. + +@item Automoose-1 +@cindex CancelMoose[tm] +The CancelMoose[tm] on autopilot. The CancelMoose[tm] is reputed to be +Norwegian, and was the person(s) who invented NoCeM. + +@item jem@@xpat.com; +@cindex Jem +John Milburn---despammer located in Korea who is getting very busy these +days. + +@item red@@redpoll.mrfs.oh.us (Richard E. Depew) +Richard E. Depew---lone American despammer. He mostly cancels binary +postings to non-binary groups and removes spews (regurgitated articles). +@end table + +You do not have to heed NoCeM messages from all these people---just the +ones you want to listen to. You also don't have to accept all NoCeM +messages from the people you like. Each NoCeM message has a @dfn{type} +header that gives the message a (more or less, usually less) rigorous +definition. Common types are @samp{spam}, @samp{spew}, @samp{mmf}, +@samp{binary}, and @samp{troll}. To specify this, you have to use +@var{(issuer conditions ...)} elements in the list. Each condition is +either a string (which is a regexp that matches types you want to use) +or a list on the form @code{(not STRING)}, where @var{string} is a +regexp that matches types you don't want to use. + +For instance, if you want all NoCeM messages from Chris Lewis except his +@samp{troll} messages, you'd say: + +@lisp +("clewis@@ferret.ocunix.on.ca" ".*" (not "troll")) +@end lisp + +On the other hand, if you just want nothing but his @samp{spam} and +@samp{spew} messages, you'd say: + +@lisp +("clewis@@ferret.ocunix.on.ca" (not ".*") "spew" "spam") +@end lisp + +The specs are applied left-to-right. + + +@item gnus-nocem-verifyer +@vindex gnus-nocem-verifyer +@findex mc-verify +This should be a function for verifying that the NoCeM issuer is who she +says she is. The default is @code{mc-verify}, which is a Mailcrypt +function. If this is too slow and you don't care for verification +(which may be dangerous), you can set this variable to @code{nil}. + +If you want signed NoCeM messages to be verified and unsigned messages +not to be verified (but used anyway), you could do something like: + +@lisp +(setq gnus-nocem-verifyer 'my-gnus-mc-verify) + +(defun my-gnus-mc-verify () + (not (eq 'forged + (ignore-errors + (if (mc-verify) + t + 'forged))))) +@end lisp + +This might be dangerous, though. + +@item gnus-nocem-directory +@vindex gnus-nocem-directory +This is where Gnus will store its NoCeM cache files. The default is +@file{~/News/NoCeM/}. + +@item gnus-nocem-expiry-wait +@vindex gnus-nocem-expiry-wait +The number of days before removing old NoCeM entries from the cache. +The default is 15. If you make it shorter Gnus will be faster, but you +might then see old spam. + +@end table + +Using NoCeM could potentially be a memory hog. If you have many living +(i. e., subscribed or unsubscribed groups), your Emacs process will grow +big. If this is a problem, you should kill off all (or most) of your +unsubscribed groups (@pxref{Subscription Commands}). + + +@node Undo +@section Undo +@cindex undo + +It is very useful to be able to undo actions one has done. In normal +Emacs buffers, it's easy enough---you just push the @code{undo} button. +In Gnus buffers, however, it isn't that simple. + +The things Gnus displays in its buffer is of no value whatsoever to +Gnus---it's all just data designed to look nice to the user. +Killing a group in the group buffer with @kbd{C-k} makes the line +disappear, but that's just a side-effect of the real action---the +removal of the group in question from the internal Gnus structures. +Undoing something like that can't be done by the normal Emacs +@code{undo} function. + +Gnus tries to remedy this somewhat by keeping track of what the user +does and coming up with actions that would reverse the actions the user +takes. When the user then presses the @code{undo} key, Gnus will run +the code to reverse the previous action, or the previous actions. +However, not all actions are easily reversible, so Gnus currently offers +a few key functions to be undoable. These include killing groups, +yanking groups, and changing the list of read articles of groups. +That's it, really. More functions may be added in the future, but each +added function means an increase in data to be stored, so Gnus will +never be totally undoable. + +@findex gnus-undo-mode +@vindex gnus-use-undo +@findex gnus-undo +The undoability is provided by the @code{gnus-undo-mode} minor mode. It +is used if @code{gnus-use-undo} is non-@code{nil}, which is the +default. The @kbd{M-C-_} key performs the @code{gnus-undo} command +command, which should feel kinda like the normal Emacs @code{undo} +command. + + +@node Moderation +@section Moderation +@cindex moderation + +If you are a moderator, you can use the @file{gnus-mdrtn.el} package. +It is not included in the standard Gnus package. Write a mail to +@samp{larsi@@gnus.org} and state what group you moderate, and you'll +get a copy. + +The moderation package is implemented as a minor mode for summary +buffers. Put + +@lisp +(add-hook 'gnus-summary-mode-hook 'gnus-moderate) +@end lisp + +in your @file{.gnus.el} file. + +If you are the moderator of @samp{rec.zoofle}, this is how it's +supposed to work: + +@enumerate +@item +You split your incoming mail by matching on +@samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted +articles in some mail group---for instance, @samp{nnml:rec.zoofle}. + +@item +You enter that group once in a while and post articles using the @kbd{e} +(edit-and-post) or @kbd{s} (just send unedited) commands. + +@item +If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some +articles that weren't approved by you, you can cancel them with the +@kbd{c} command. +@end enumerate + +To use moderation mode in these two groups, say: + +@lisp +(setq gnus-moderated-list + "^nnml:rec.zoofle$\\|^rec.zoofle$") +@end lisp + + +@node XEmacs Enhancements +@section XEmacs Enhancements +@cindex XEmacs + +XEmacs is able to display pictures and stuff, so Gnus has taken +advantage of that. + +@menu +* Picons:: How to display pictures of what your reading. +* Smileys:: Show all those happy faces the way they were meant to be shown. +* Toolbar:: Click'n'drool. +* XVarious:: Other XEmacsy Gnusey variables. +@end menu + + +@node Picons +@subsection Picons + +@iftex +@iflatex +\include{picons} +@end iflatex +@end iftex + +So... You want to slow down your news reader even more! This is a +good way to do so. Its also a great way to impress people staring +over your shoulder as you read news. + +@menu +* Picon Basics:: What are picons and How do I get them. +* Picon Requirements:: Don't go further if you aren't using XEmacs. +* Easy Picons:: Displaying Picons---the easy way. +* Hard Picons:: The way you should do it. You'll learn something. +* Picon Useless Configuration:: Other variables you can trash/tweak/munge/play with. +@end menu + + +@node Picon Basics +@subsubsection Picon Basics + +What are Picons? To quote directly from the Picons Web site: + +@iftex +@iflatex +\margindex{} +@end iflatex +@end iftex + +@quotation +@dfn{Picons} is short for ``personal icons''. They're small, +constrained images used to represent users and domains on the net, +organized into databases so that the appropriate image for a given +e-mail address can be found. Besides users and domains, there are picon +databases for Usenet newsgroups and weather forecasts. The picons are +in either monochrome @code{XBM} format or color @code{XPM} and +@code{GIF} formats. +@end quotation + +@vindex gnus-picons-piconsearch-url +If you have a permanent connection to the Internet you can use Steve +Kinzler's Picons Search engine by setting +@code{gnus-picons-piconsearch-url} to the string @* +@file{http://www.cs.indiana.edu/picons/search.html}. + +@vindex gnus-picons-database +Otherwise you need a local copy of his database. For instructions on +obtaining and installing the picons databases, point your Web browser at @* +@file{http://www.cs.indiana.edu/picons/ftp/index.html}. Gnus expects +picons to be installed into a location pointed to by +@code{gnus-picons-database}. + + +@node Picon Requirements +@subsubsection Picon Requirements + +To have Gnus display Picons for you, you must be running XEmacs +19.13 or greater since all other versions of Emacs aren't yet able to +display images. + +Additionally, you must have @code{x} support compiled into XEmacs. To +display color picons which are much nicer than the black & white one, +you also need one of @code{xpm} or @code{gif} compiled into XEmacs. + +@vindex gnus-picons-convert-x-face +If you want to display faces from @code{X-Face} headers, you should have +the @code{xface} support compiled into XEmacs. Otherwise you must have +the @code{netpbm} utilities installed, or munge the +@code{gnus-picons-convert-x-face} variable to use something else. + + +@node Easy Picons +@subsubsection Easy Picons + +To enable displaying picons, simply put the following line in your +@file{~/.gnus} file and start Gnus. + +@lisp +(setq gnus-use-picons t) +(add-hook 'gnus-article-display-hook + 'gnus-article-display-picons t) +(add-hook 'gnus-article-display-hook + 'gnus-picons-article-display-x-face) +@end lisp + +and make sure @code{gnus-picons-database} points to the directory +containing the Picons databases. + +Alternatively if you want to use the web piconsearch engine add this: + +@lisp +(setq gnus-picons-piconsearch-url + "http://www.cs.indiana.edu:800/piconsearch") +@end lisp + + +@node Hard Picons +@subsubsection Hard Picons + +@iftex +@iflatex +\margindex{} +@end iflatex +@end iftex + +Gnus can display picons for you as you enter and leave groups and +articles. It knows how to interact with three sections of the picons +database. Namely, it can display the picons newsgroup pictures, +author's face picture(s), and the authors domain. To enable this +feature, you need to select where to get the picons from, and where to +display them. + +@table @code + +@item gnus-picons-database +@vindex gnus-picons-database +The location of the picons database. Should point to a directory +containing the @file{news}, @file{domains}, @file{users} (and so on) +subdirectories. This is only useful if +@code{gnus-picons-piconsearch-url} is @code{nil}. Defaults to +@file{/usr/local/faces/}. + +@item gnus-picons-piconsearch-url +@vindex gnus-picons-piconsearch-url +The URL for the web picons search engine. The only currently known +engine is @file{http://www.cs.indiana.edu:800/piconsearch}. To +workaround network delays, icons will be fetched in the background. If +this is @code{nil} 'the default), then picons are fetched from local +database indicated by @code{gnus-picons-database}. + +@item gnus-picons-display-where +@vindex gnus-picons-display-where +Where the picon images should be displayed. It is @code{picons} by +default (which by default maps to the buffer @samp{*Picons*}). Other +valid places could be @code{article}, @code{summary}, or +@samp{*scratch*} for all I care. Just make sure that you've made the +buffer visible using the standard Gnus window configuration +routines---@pxref{Windows Configuration}. + +@item gnus-picons-group-excluded-groups +@vindex gnus-picons-group-excluded-groups +Groups that are matched by this regexp won't have their group icons +displayed. + +@end table + +Note: If you set @code{gnus-use-picons} to @code{t}, it will set up your +window configuration for you to include the @code{picons} buffer. + +Now that you've made those decision, you need to add the following +functions to the appropriate hooks so these pictures will get displayed +at the right time. + +@vindex gnus-article-display-hook +@vindex gnus-picons-display-where +@table @code +@item gnus-article-display-picons +@findex gnus-article-display-picons +Looks up and displays the picons for the author and the author's domain +in the @code{gnus-picons-display-where} buffer. Should be added to the +@code{gnus-article-display-hook}. + +@item gnus-picons-article-display-x-face +@findex gnus-article-display-picons +Decodes and displays the X-Face header if present. This function +should be added to @code{gnus-article-display-hook}. + +@end table + +Note: You must append them to the hook, so make sure to specify 't' +for the append flag of @code{add-hook}: + +@lisp +(add-hook 'gnus-article-display-hook 'gnus-article-display-picons t) +@end lisp + + +@node Picon Useless Configuration +@subsubsection Picon Useless Configuration + +@iftex +@iflatex +\margindex{} +@end iflatex +@end iftex + +The following variables offer further control over how things are +done, where things are located, and other useless stuff you really +don't need to worry about. + +@table @code + +@item gnus-picons-news-directories +@vindex gnus-picons-news-directories +List of subdirectories to search in @code{gnus-picons-database} for +newsgroups faces. @code{("news")} is the default. + +@item gnus-picons-user-directories +@vindex gnus-picons-user-directories +List of subdirectories to search in @code{gnus-picons-database} for user +faces. @code{("local" "users" "usenix" "misc")} is the default. + +@item gnus-picons-domain-directories +@vindex gnus-picons-domain-directories +List of subdirectories to search in @code{gnus-picons-database} for +domain name faces. Defaults to @code{("domains")}. Some people may +want to add @samp{"unknown"} to this list. + +@item gnus-picons-convert-x-face +@vindex gnus-picons-convert-x-face +If you don't have @code{xface} support builtin XEmacs, this is the +command to use to convert the @code{X-Face} header to an X bitmap +(@code{xbm}). Defaults to @code{(format "@{ echo '/* Width=48, +Height=48 */'; uncompface; @} | icontopbm | pbmtoxbm > %s" +gnus-picons-x-face-file-name)} + +@item gnus-picons-x-face-file-name +@vindex gnus-picons-x-face-file-name +Names a temporary file to store the @code{X-Face} bitmap in. Defaults +to @code{(format "/tmp/picon-xface.%s.xbm" (user-login-name))}. + +@item gnus-picons-has-modeline-p +@vindex gnus-picons-has-modeline-p +If you have set @code{gnus-picons-display-where} to @code{picons}, your +XEmacs frame will become really cluttered. To alleviate this a bit you +can set @code{gnus-picons-has-modeline-p} to @code{nil}; this will +remove the mode line from the Picons buffer. This is only useful if +@code{gnus-picons-display-where} is @code{picons}. + +@item gnus-picons-refresh-before-display +@vindex gnus-picons-refresh-before-display +If non-nil, display the article buffer before computing the picons. +Defaults to @code{nil}. + +@item gnus-picons-display-as-address +@vindex gnus-picons-display-as-address +If @code{t} display textual email addresses along with pictures. +Defaults to @code{t}. + +@item gnus-picons-file-suffixes +@vindex gnus-picons-file-suffixes +Ordered list of suffixes on picon file names to try. Defaults to +@code{("xpm" "gif" "xbm")} minus those not builtin your XEmacs. + +@item gnus-picons-display-article-move-p +@vindex gnus-picons-display-article-move-p +Whether to move point to first empty line when displaying picons. This +has only an effect if `gnus-picons-display-where' has value `article'. + +@item gnus-picons-clear-cache-on-shutdown +@vindex gnus-picons-clear-cache-on-shutdown +Whether to clear the picons cache when exiting gnus. Gnus caches every +picons it finds while it is running. This saves some time in the search +process but eats some memory. If this variable is set to @code{nil}, +Gnus will never clear the cache itself; you will have to manually call +@code{gnus-picons-clear-cache} to clear it. Otherwise the cache will be +cleared every time you exit Gnus. Defaults to @code{t}. + +@iftex +@iflatex +\margindex{} +@end iflatex +@end iftex + +@end table + +@node Smileys +@subsection Smileys +@cindex smileys + +@iftex +@iflatex +\gnusfig{-3cm}{0.5cm}{\epsfig{figure=tmp/BigFace.ps,height=20cm}} +\input{smiley} +@end iflatex +@end iftex + +@dfn{Smiley} is a package separate from Gnus, but since Gnus is +currently the only package that uses Smiley, it is documented here. + +In short---to use Smiley in Gnus, put the following in your +@file{.gnus.el} file: + +@lisp +(add-hook 'gnus-article-display-hook 'gnus-smiley-display t) +@end lisp + +Smiley maps text smiley faces---@samp{:-)}, @samp{:-=}, @samp{:-(} and +the like---to pictures and displays those instead of the text smiley +faces. The conversion is controlled by a list of regexps that matches +text and maps that to file names. + +@vindex smiley-nosey-regexp-alist +@vindex smiley-deformed-regexp-alist +Smiley supplies two example conversion alists by default: +@code{smiley-deformed-regexp-alist} (which matches @samp{:)}, @samp{:(} +and so on), and @code{smiley-nosey-regexp-alist} (which matches +@samp{:-)}, @samp{:-(} and so on). + +The alist used is specified by the @code{smiley-regexp-alist} variable, +which defaults to the value of @code{smiley-deformed-regexp-alist}. + +The first item in each element is the regexp to be matched; the second +element is the regexp match group that is to be replaced by the picture; +and the third element is the name of the file to be displayed. + +The following variables customize where Smiley will look for these +files, as well as the color to be used and stuff: + +@table @code + +@item smiley-data-directory +@vindex smiley-data-directory +Where Smiley will look for smiley faces files. + +@item smiley-flesh-color +@vindex smiley-flesh-color +Skin color. The default is @samp{yellow}, which is really racist. + +@item smiley-features-color +@vindex smiley-features-color +Color of the features of the face. The default is @samp{black}. + +@item smiley-tongue-color +@vindex smiley-tongue-color +Color of the tongue. The default is @samp{red}. + +@item smiley-circle-color +@vindex smiley-circle-color +Color of the circle around the face. The default is @samp{black}. + +@item smiley-mouse-face +@vindex smiley-mouse-face +Face used for mouse highlighting over the smiley face. + +@end table + + +@node Toolbar +@subsection Toolbar + +@table @code + +@iftex +@iflatex +\margindex{} +@end iflatex +@end iftex + +@item gnus-use-toolbar +@vindex gnus-use-toolbar +If @code{nil}, don't display toolbars. If non-@code{nil}, it should be +one of @code{default-toolbar}, @code{top-toolbar}, @code{bottom-toolbar}, +@code{right-toolbar}, or @code{left-toolbar}. + +@item gnus-group-toolbar +@vindex gnus-group-toolbar +The toolbar in the group buffer. + +@item gnus-summary-toolbar +@vindex gnus-summary-toolbar +The toolbar in the summary buffer. + +@item gnus-summary-mail-toolbar +@vindex gnus-summary-mail-toolbar +The toolbar in the summary buffer of mail groups. + +@end table + + +@node XVarious +@subsection Various XEmacs Variables + +@table @code +@item gnus-xmas-glyph-directory +@vindex gnus-xmas-glyph-directory +This is where Gnus will look for pictures. Gnus will normally +auto-detect this directory, but you may set it manually if you have an +unusual directory structure. + +@item gnus-xmas-logo-color-alist +@vindex gnus-xmas-logo-color-alist +This is an alist where the key is a type symbol and the values are the +foreground and background color of the splash page glyph. + +@item gnus-xmas-logo-color-style +@vindex gnus-xmas-logo-color-style +This is the key used to look up the color in the alist described above. +Valid values include @code{flame}, @code{pine}, @code{moss}, +@code{irish}, @code{sky}, @code{tin}, @code{velvet}, @code{grape}, +@code{labia}, @code{berry}, @code{neutral}, and @code{september}. + +@item gnus-xmas-modeline-glyph +@vindex gnus-xmas-modeline-glyph +A glyph displayed in all Gnus mode lines. It is a tiny gnu head by +default. + +@iftex +@iflatex +\margindex{} +@end iflatex +@end iftex + +@end table + + + + +@node Fuzzy Matching +@section Fuzzy Matching +@cindex fuzzy matching + +Gnus provides @dfn{fuzzy matching} of @code{Subject} lines when doing +things like scoring, thread gathering and thread comparison. + +As opposed to regular expression matching, fuzzy matching is very fuzzy. +It's so fuzzy that there's not even a definition of what @dfn{fuzziness} +means, and the implementation has changed over time. + +Basically, it tries to remove all noise from lines before comparing. +@samp{Re: }, parenthetical remarks, white space, and so on, are filtered +out of the strings before comparing the results. This often leads to +adequate results---even when faced with strings generated by text +manglers masquerading as newsreaders. + + +@node Thwarting Email Spam +@section Thwarting Email Spam +@cindex email spam +@cindex spam +@cindex UCE +@cindex unsolicited commercial email + +In these last days of the Usenet, commercial vultures are hanging about +and grepping through news like crazy to find email addresses they can +foist off their scams and products to. As a reaction to this, many +people have started putting nonsense addresses into their @code{From} +lines. I think this is counterproductive---it makes it difficult for +people to send you legitimate mail in response to things you write, as +well as making it difficult to see who wrote what. This rewriting may +perhaps be a bigger menace than the unsolicited commercial email itself +in the end. + +The biggest problem I have with email spam is that it comes in under +false pretenses. I press @kbd{g} and Gnus merrily informs me that I +have 10 new emails. I say ``Golly gee! Happy is me!'' and select the +mail group, only to find two pyramid schemes, seven advertisements +(``New! Miracle tonic for growing full, lustrous hair on your toes!'') +and one mail asking me to repent and find some god. + +This is annoying. + +The way to deal with this is having Gnus split out all spam into a +@samp{spam} mail group (@pxref{Splitting Mail}). + +First, pick one (1) valid mail address that you can be reached at, and +put it in your @code{From} header of all your news articles. (I've +chosen @samp{larsi@@trym.ifi.uio.no}, but for many addresses on the form +@samp{larsi+usenet@@ifi.uio.no} will be a better choice. Ask your +sysadm whether your sendmail installation accepts keywords in the local +part of the mail address.) + +@lisp +(setq message-default-news-headers + "From: Lars Magne Ingebrigtsen \n") +@end lisp + +Then put the following split rule in @code{nnmail-split-fancy} +(@pxref{Fancy Mail Splitting}): + +@lisp +( + ... + (to "larsi@@trym.ifi.uio.no" + (| ("subject" "re:.*" "misc") + ("references" ".*@@.*" "misc") + "spam")) + ... +) +@end lisp + +This says that all mail to this address is suspect, but if it has a +@code{Subject} that starts with a @samp{Re:} or has a @code{References} +header, it's probably ok. All the rest goes to the @samp{spam} group. +(This idea probably comes from Tim Pierce.) + +In addition, many mail spammers talk directly to your @code{smtp} server +and do not include your email address explicitly in the @code{To} +header. Why they do this is unknown---perhaps it's to thwart this +thwarting scheme? In any case, this is trivial to deal with---you just +put anything not addressed to you in the @samp{spam} group by ending +your fancy split rule in this way: + +@lisp +( + ... + (to "larsi" "misc") + "spam") +@end lisp + +In my experience, this will sort virtually everything into the right +group. You still have to check the @samp{spam} group from time to time to +check for legitimate mail, though. If you feel like being a good net +citizen, you can even send off complaints to the proper authorities on +each unsolicited commercial email---at your leisure. + +If you are also a lazy net citizen, you will probably prefer complaining +automatically with the @file{gnus-junk.el} package, available FOR FREE +at @* @file{}. +Since most e-mail spam is sent automatically, this may reconcile the +cosmic balance somewhat. + +This works for me. It allows people an easy way to contact me (they can +just press @kbd{r} in the usual way), and I'm not bothered at all with +spam. It's a win-win situation. Forging @code{From} headers to point +to non-existent domains is yucky, in my opinion. + + +@node Various Various +@section Various Various +@cindex mode lines +@cindex highlights + +@table @code + +@item gnus-home-directory +All Gnus path variables will be initialized from this variable, which +defaults to @file{~/}. + +@item gnus-directory +@vindex gnus-directory +Most Gnus storage path variables will be initialized from this variable, +which defaults to the @samp{SAVEDIR} environment variable, or +@file{~/News/} if that variable isn't set. + +Note that gnus is mostly loaded when the @file{.gnus.el} file is read. +This means that other directory variables that are initialized from this +variable won't be set properly if you set this variable in +@file{.gnus.el}. Set this variable in @file{.emacs} instead. + +@item gnus-default-directory +@vindex gnus-default-directory +Not related to the above variable at all---this variable says what the +default directory of all Gnus buffers should be. If you issue commands +like @kbd{C-x C-f}, the prompt you'll get starts in the current buffer's +default directory. If this variable is @code{nil} (which is the +default), the default directory will be the default directory of the +buffer you were in when you started Gnus. + +@item gnus-verbose +@vindex gnus-verbose +This variable is an integer between zero and ten. The higher the value, +the more messages will be displayed. If this variable is zero, Gnus +will never flash any messages, if it is seven (which is the default), +most important messages will be shown, and if it is ten, Gnus won't ever +shut up, but will flash so many messages it will make your head swim. + +@item gnus-verbose-backends +@vindex gnus-verbose-backends +This variable works the same way as @code{gnus-verbose}, but it applies +to the Gnus backends instead of Gnus proper. + +@item nnheader-max-head-length +@vindex nnheader-max-head-length +When the backends read straight heads of articles, they all try to read +as little as possible. This variable (default 4096) specifies +the absolute max length the backends will try to read before giving up +on finding a separator line between the head and the body. If this +variable is @code{nil}, there is no upper read bound. If it is +@code{t}, the backends won't try to read the articles piece by piece, +but read the entire articles. This makes sense with some versions of +@code{ange-ftp} or @code{efs}. + +@item nnheader-head-chop-length +@vindex nnheader-head-chop-length +This variable (default 2048) says how big a piece of each article to +read when doing the operation described above. + +@item nnheader-file-name-translation-alist +@vindex nnheader-file-name-translation-alist +@cindex file names +@cindex invalid characters in file names +@cindex characters in file names +This is an alist that says how to translate characters in file names. +For instance, if @samp{:} is invalid as a file character in file names +on your system (you OS/2 user you), you could say something like: + +@lisp +(setq nnheader-file-name-translation-alist + '((?: . ?_))) +@end lisp + +In fact, this is the default value for this variable on OS/2 and MS +Windows (phooey) systems. + +@item gnus-hidden-properties +@vindex gnus-hidden-properties +This is a list of properties to use to hide ``invisible'' text. It is +@code{(invisible t intangible t)} by default on most systems, which +makes invisible text invisible and intangible. + +@item gnus-parse-headers-hook +@vindex gnus-parse-headers-hook +A hook called before parsing headers. It can be used, for instance, to +gather statistics on the headers fetched, or perhaps you'd like to prune +some headers. I don't see why you'd want that, though. + +@item gnus-shell-command-separator +@vindex gnus-shell-command-separator +String used to separate two shell commands. The default is @samp{;}. + + +@end table + + +@node The End +@chapter The End + +Well, that's the manual---you can get on with your life now. Keep in +touch. Say hello to your cats from me. + +My @strong{ghod}---I just can't stand goodbyes. Sniffle. + +Ol' Charles Reznikoff said it pretty well, so I leave the floor to him: + +@quotation +@strong{Te Deum} + +@sp 1 +Not because of victories @* +I sing,@* +having none,@* +but for the common sunshine,@* +the breeze,@* +the largess of the spring. + +@sp 1 +Not for victory@* +but for the day's work done@* +as well as I was able;@* +not for a seat upon the dais@* +but at the common table.@* +@end quotation + + +@node Appendices +@chapter Appendices + +@menu +* History:: How Gnus got where it is today. +* Terminology:: We use really difficult, like, words here. +* Customization:: Tailoring Gnus to your needs. +* Troubleshooting:: What you might try if things do not work. +* A Programmers Guide to Gnus:: Rilly, rilly technical stuff. +* Emacs for Heathens:: A short introduction to Emacsian terms. +* Frequently Asked Questions:: A question-and-answer session. +@end menu + + +@node History +@section History + +@cindex history +@sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in +'94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus. + +If you want to investigate the person responsible for this outrage, you +can point your (feh!) web browser to +@file{http://www.stud.ifi.uio.no/~larsi/}. This is also the primary +distribution point for the new and spiffy versions of Gnus, and is known +as The Site That Destroys Newsrcs And Drives People Mad. + +During the first extended alpha period of development, the new Gnus was +called ``(ding) Gnus''. @dfn{(ding)} is, of course, short for +@dfn{ding is not Gnus}, which is a total and utter lie, but who cares? +(Besides, the ``Gnus'' in this abbreviation should probably be +pronounced ``news'' as @sc{Umeda} intended, which makes it a more +appropriate name, don't you think?) + +In any case, after spending all that energy on coming up with a new and +spunky name, we decided that the name was @emph{too} spunky, so we +renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs. +``@sc{gnus}''. New vs. old. + +The first ``proper'' release of Gnus 5 was done in November 1995 when it +was included in the Emacs 19.30 distribution (132 (ding) Gnus releases +plus 15 Gnus 5.0 releases). + +In May 1996 the next Gnus generation (aka. ``September Gnus'' (after 99 +releases)) was released under the name ``Gnus 5.2'' (40 releases). + +On July 28th 1996 work on Red Gnus was begun, and it was released on +January 25th 1997 (after 84 releases) as ``Gnus 5.4'' (67 releases). + +On September 13th 1997, Quassia Gnus was started and lasted 37 +releases. If was released as ``Gnus 5.6 on March 8th 1998. + +If you happen upon a version of Gnus that has a prefixed name -- +``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'' -- +don't panic. Don't let it know that you're frightened. Back away. +Slowly. Whatever you do, don't run. Walk away, calmly, until you're +out of its reach. Find a proper released version of Gnus and snuggle up +to that instead. + +@menu +* 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. +* Contributors:: Oodles of people. +* New Features:: Pointers to some of the new stuff in Gnus. +* Newest Features:: Features so new that they haven't been written yet. +@end menu + + +@node Why? +@subsection Why? + +What's the point of Gnus? + +I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep'' +newsreader, that lets you do anything you can think of. That was my +original motivation, but while working on Gnus, it has become clear to +me that this generation of newsreaders really belong in the stone age. +Newsreaders haven't developed much since the infancy of the net. If the +volume continues to rise with the current rate of increase, all current +newsreaders will be pretty much useless. How do you deal with +newsgroups that have thousands of new articles each day? How do you +keep track of millions of people who post? + +Gnus offers no real solutions to these questions, but I would very much +like to see Gnus being used as a testing ground for new methods of +reading and fetching news. Expanding on @sc{Umeda}-san's wise decision +to separate the newsreader from the backends, Gnus now offers a simple +interface for anybody who wants to write new backends for fetching mail +and news from different sources. I have added hooks for customizations +everywhere I could imagine it being useful. By doing so, I'm inviting +every one of you to explore and invent. + +May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs} and +@kbd{C-u 100 M-x all-hail-xemacs}. + + +@node Compatibility +@subsection Compatibility + +@cindex compatibility +Gnus was designed to be fully compatible with @sc{gnus}. Almost all key +bindings have been kept. More key bindings have been added, of course, +but only in one or two obscure cases have old bindings been changed. + +Our motto is: +@quotation +@cartouche +@center In a cloud bones of steel. +@end cartouche +@end quotation + +All commands have kept their names. Some internal functions have changed +their names. + +The @code{gnus-uu} package has changed drastically. @xref{Decoding +Articles}. + +One major compatibility question is the presence of several summary +buffers. All variables relevant while reading a group are +buffer-local to the summary buffer they belong in. Although many +important variables have their values copied into their global +counterparts whenever a command is executed in the summary buffer, this +change might lead to incorrect values being used unless you are careful. + +All code that relies on knowledge of @sc{gnus} internals will probably +fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or +changing it in any way, as a matter of fact) is strictly verboten. Gnus +maintains a hash table that points to the entries in this alist (which +speeds up many functions), and changing the alist directly will lead to +peculiar results. + +@cindex hilit19 +@cindex highlighting +Old hilit19 code does not work at all. In fact, you should probably +remove all hilit code from all Gnus hooks +(@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}). +Gnus provides various integrated functions for highlighting. These are +faster and more accurate. To make life easier for everybody, Gnus will +by default remove all hilit calls from all hilit hooks. Uncleanliness! +Away! + +Packages like @code{expire-kill} will no longer work. As a matter of +fact, you should probably remove all old @sc{gnus} packages (and other +code) when you start using Gnus. More likely than not, Gnus already +does what you have written code to make @sc{gnus} do. (Snicker.) + +Even though old methods of doing things are still supported, only the +new methods are documented in this manual. If you detect a new method of +doing something while reading this manual, that does not mean you have +to stop doing it the old way. + +Gnus understands all @sc{gnus} startup files. + +@kindex M-x gnus-bug +@findex gnus-bug +@cindex reporting bugs +@cindex bugs +Overall, a casual user who hasn't written much code that depends on +@sc{gnus} internals should suffer no problems. If problems occur, +please let me know by issuing that magic command @kbd{M-x gnus-bug}. + +@vindex gnus-bug-create-help-buffer +If you are in the habit of sending bug reports @emph{very} often, you +may find the helpful help buffer annoying after a while. If so, set +@code{gnus-bug-create-help-buffer} to @code{nil} to avoid having it pop +up at you. + + +@node Conformity +@subsection Conformity + +No rebels without a clue here, ma'am. We conform to all standards known +to (wo)man. Except for those standards and/or conventions we disagree +with, of course. + +@table @strong + +@item RFC 822 +@cindex RFC 822 +There are no known breaches of this standard. + +@item RFC 1036 +@cindex RFC 1036 +There are no known breaches of this standard, either. + +@item Son-of-RFC 1036 +@cindex Son-of-RFC 1036 +We do have some breaches to this one. + +@table @emph + +@item MIME +Gnus does not yet fully handle MIME, and this standard-to-be seems to +think that MIME is the bees' knees, so we have major breakage here. + +@item X-Newsreader +This is considered to be a ``vanity header'', while I consider it to be +consumer information. After seeing so many badly formatted articles +coming from @code{tin} and @code{Netscape} I know not to use either of +those for posting articles. I would not have known that if it wasn't +for the @code{X-Newsreader} header. +@end table + +@item USEFOR +@cindex USEFOR +USEFOR is an IETF working group writing a successor to RFC 1036, based +on Son-of-RFC 1036. They have produced a number of drafts proposing +various changes to the format of news articles. The Gnus towers will +look into implementing the changes when the draft is accepted as an RFC. + +@end table + +If you ever notice Gnus acting non-compliant with regards to the texts +mentioned above, don't hesitate to drop a note to Gnus Towers and let us +know. + + +@node Emacsen +@subsection Emacsen +@cindex Emacsen +@cindex XEmacs +@cindex Mule +@cindex Emacs + +Gnus should work on : + +@itemize @bullet + +@item +Emacs 20.2 and up. + +@item +XEmacs 20.4 and up. + +@end itemize + +Gnus will absolutely not work on any Emacsen older than that. Not +reliably, at least. + +There are some vague differences between Gnus on the various +platforms---XEmacs features more graphics (a logo and a toolbar)---but +other than that, things should look pretty much the same under all +Emacsen. + + +@node Contributors +@subsection Contributors +@cindex contributors + +The new Gnus version couldn't have been done without the help of all the +people on the (ding) mailing list. Every day for over a year I have +gotten billions of nice bug reports from them, filling me with joy, +every single one of them. Smooches. The people on the list have been +tried beyond endurance, what with my ``oh, that's a neat idea , yup, I'll release it right away no wait, that doesn't +work at all , yup, I'll ship that one off right away no, wait, that absolutely does not work'' policy for releases. +Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that +``worser''? ``much worser''? ``worsest''?) + +I would like to take this opportunity to thank the Academy for... oops, +wrong show. + +@itemize @bullet + +@item +Masanobu @sc{Umeda}---the writer of the original @sc{gnus}. + +@item +Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as +well as numerous other things). + +@item +Luis Fernandes---design and graphics. + +@item +Erik Naggum---help, ideas, support, code and stuff. + +@item +Wes Hardaker---@file{gnus-picon.el} and the manual section on +@dfn{picons} (@pxref{Picons}). + +@item +Kim-Minh Kaplan---further work on the picon code. + +@item +Brad Miller---@file{gnus-gl.el} and the GroupLens manual section +(@pxref{GroupLens}). + +@item +Sudish Joseph---innumerable bug fixes. + +@item +Ilja Weis---@file{gnus-topic.el}. + +@item +Steven L. Baur---lots and lots and lots of bugs detections and fixes. + +@item +Vladimir Alexiev---the refcard and reference booklets. + +@item +Felix Lee & Jamie Zawinski---I stole some pieces from the XGnus +distribution by Felix Lee and JWZ. + +@item +Scott Byer---@file{nnfolder.el} enhancements & rewrite. + +@item +Peter Mutsaers---orphan article scoring code. + +@item +Ken Raeburn---POP mail support. + +@item +Hallvard B Furuseth---various bits and pieces, especially dealing with +.newsrc files. + +@item +Brian Edmonds---@file{gnus-bbdb.el}. + +@item +David Moore---rewrite of @file{nnvirtual.el} and many other things. + +@item +Kevin Davidson---came up with the name @dfn{ding}, so blame him. + +@item +Fran,Ag(Bois Pinard---many, many interesting and thorough bug reports, as +well as autoconf support. + +@end itemize + +This manual was proof-read by Adrian Aichner, with Ricardo Nassif, Mark +Borges, and Jost Krieger proof-reading parts of the manual. + +The following people have contributed many patches and suggestions: + +Christopher Davis, +Andrew Eskilsson, +Kai Grossjohann, +David K,Ae(Bgedal, +Richard Pieri, +Fabrice Popineau, +Daniel Quinlan, +Jason L. Tibbitts, III, +and +Jack Vinson. + +Also thanks to the following for patches and stuff: + +Jari Aalto, +Adrian Aichner, +Vladimir Alexiev, +Russ Allbery, +Peter Arius, +Matt Armstrong, +Marc Auslander, +Frank Bennett, +Robert Bihlmeyer, +Chris Bone, +Mark Borges, +Mark Boyns, +Lance A. Brown, +Kees de Bruin, +Martin Buchholz, +Joe Buehler, +Kevin Buhr, +Alastair Burt, +Joao Cachopo, +Zlatko Calusic, +Massimo Campostrini, +Castor, +David Charlap, +Dan Christensen, +Kevin Christian, +Michael R. Cook, +Glenn Coombs, +Frank D. Cringle, +Geoffrey T. Dairiki, +Andre Deparade, +Ulrik Dickow, +Dave Disser, +Rui-Tao Dong, @c ? +Joev Dubach, +Michael Welsh Duggan, +Dave Edmondson, +Paul Eggert, +Enami Tsugutomo, @c Enami +Michael Ernst, +Luc Van Eycken, +Sam Falkner, +Nelson Jose dos Santos Ferreira, +Sigbjorn Finne, +Paul Fisher, +Decklin Foster, +Gary D. Foster, +Paul Franklin, +Guy Geens, +Arne Georg Gleditsch, +David S. Goldberg, +Michelangelo Grigni, +D. Hall, +Magnus Hammerin, +Kenichi Handa, @c Handa +Raja R. Harinath, +Yoshiki Hayashi, @c ? +P. E. Jareth Hein, +Hisashige Kenji, @c Hisashige +Marc Horowitz, +Gunnar Horrigmo, +Richard Hoskins, +Brad Howes, +Fran,Ag(Bois Felix Ingrand, +Ishikawa Ichiro, @c Ishikawa +Lee Iverson, +Iwamuro Motonori, @c Iwamuro +Rajappa Iyer, +Andreas Jaeger, +Randell Jesup, +Fred Johansen, +Gareth Jones, +Simon Josefsson, +Greg Klanderman, +Karl Kleinpaste, +Peter Skov Knudsen, +Shuhei Kobayashi, @c Kobayashi +Koseki Yoshinori, @c Koseki +Thor Kristoffersen, +Jens Lautenbacher, +Martin Larose, +Seokchan Lee, @c Lee +Carsten Leonhardt, +James LewisMoss, +Christian Limpach, +Markus Linnala, +Dave Love, +Mike McEwan, +Tonny Madsen, +Shlomo Mahlab, +Nat Makarevitch, +Istvan Marko, +David Martin, +Jason R. Mastaler, +Gordon Matzigkeit, +Timo Metzemakers, +Richard Mlynarik, +Lantz Moore, +Morioka Tomohiko, @c Morioka +Erik Toubro Nielsen, +Hrvoje Niksic, +Andy Norman, +Fred Oberhauser, +C. R. Oldham, +Alexandre Oliva, +Ken Olstad, +Masaharu Onishi, @c Onishi +Hideki Ono, @c Ono +William Perry, +Stephen Peters, +Jens-Ulrik Holger Petersen, +Ulrich Pfeifer, +Matt Pharr, +John McClary Prevost, +Bill Pringlemeir, +Mike Pullen, +Jim Radford, +Colin Rafferty, +Lasse Rasinen, +Lars Balker Rasmussen, +Joe Reiss, +Renaud Rioboo, +Roland B. Roberts, +Bart Robinson, +Christian von Roques, +Jason Rumney, +Wolfgang Rupprecht, +Jay Sachs, +Dewey M. Sasser, +Conrad Sauerwald, +Loren Schall, +Dan Schmidt, +Ralph Schleicher, +Philippe Schnoebelen, +Andreas Schwab, +Randal L. Schwartz, +Justin Sheehy, +Danny Siu, +Matt Simmons, +Paul D. Smith, +Jeff Sparkes, +Toby Speight, +Michael Sperber, +Darren Stalder, +Richard Stallman, +Greg Stark, +Sam Steingold, +Paul Stodghill, +Kurt Swanson, +Samuel Tardieu, +Teddy, +Chuck Thompson, +Philippe Troin, +James Troup, +Trung Tran-Duc, +Aaron M. Ucko, +Aki Vehtari, +Didier Verna, +Jan Vroonhof, +Stefan Waldherr, +Pete Ware, +Barry A. Warsaw, +Christoph Wedler, +Joe Wells, +Katsumi Yamaoka, @c Yamaoka +and +Shenghuo Zhu. @c Zhu + +For a full overview of what each person has done, the ChangeLogs +included in the Gnus alpha distributions should give ample reading +(550kB and counting). + +Apologies to everybody that I've forgotten, of which there are many, I'm +sure. + +Gee, that's quite a list of people. I guess that must mean that there +actually are people who are using Gnus. Who'd'a thunk it! + + +@node New Features +@subsection New Features +@cindex new features + +@menu +* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus. +* September Gnus:: The Thing Formally Known As Gnus 5.3/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. +@end menu + +These lists are, of course, just @emph{short} overviews of the +@emph{most} important new features. No, really. There are tons more. +Yes, we have feeping creaturism in full effect. + + +@node ding Gnus +@subsubsection (ding) Gnus + +New features in Gnus 5.0/5.1: + +@itemize @bullet + +@item +The look of all buffers can be changed by setting format-like variables +(@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}). + +@item +Local spool and several @sc{nntp} servers can be used at once +(@pxref{Select Methods}). + +@item +You can combine groups into virtual groups (@pxref{Virtual Groups}). + +@item +You can read a number of different mail formats (@pxref{Getting Mail}). +All the mail backends implement a convenient mail expiry scheme +(@pxref{Expiring Mail}). + +@item +Gnus can use various strategies for gathering threads that have lost +their roots (thereby gathering loose sub-threads into one thread) or it +can go back and retrieve enough headers to build a complete thread +(@pxref{Customizing Threading}). + +@item +Killed groups can be displayed in the group buffer, and you can read +them as well (@pxref{Listing Groups}). + +@item +Gnus can do partial group updates---you do not have to retrieve the +entire active file just to check for new articles in a few groups +(@pxref{The Active File}). + +@item +Gnus implements a sliding scale of subscribedness to groups +(@pxref{Group Levels}). + +@item +You can score articles according to any number of criteria +(@pxref{Scoring}). You can even get Gnus to find out how to score +articles for you (@pxref{Adaptive Scoring}). + +@item +Gnus maintains a dribble buffer that is auto-saved the normal Emacs +manner, so it should be difficult to lose much data on what you have +read if your machine should go down (@pxref{Auto Save}). + +@item +Gnus now has its own startup file (@file{.gnus}) to avoid cluttering up +the @file{.emacs} file. + +@item +You can set the process mark on both groups and articles and perform +operations on all the marked items (@pxref{Process/Prefix}). + +@item +You can grep through a subset of groups and create a group from the +results (@pxref{Kibozed Groups}). + +@item +You can list subsets of groups according to, well, anything +(@pxref{Listing Groups}). + +@item +You can browse foreign servers and subscribe to groups from those +servers (@pxref{Browse Foreign Server}). + +@item +Gnus can fetch articles, asynchronously, on a second connection to the +server (@pxref{Asynchronous Fetching}). + +@item +You can cache articles locally (@pxref{Article Caching}). + +@item +The uudecode functions have been expanded and generalized +(@pxref{Decoding Articles}). + +@item +You can still post uuencoded articles, which was a little-known feature +of @sc{gnus}' past (@pxref{Uuencoding and Posting}). + +@item +Fetching parents (and other articles) now actually works without +glitches (@pxref{Finding the Parent}). + +@item +Gnus can fetch FAQs and group descriptions (@pxref{Group Information}). + +@item +Digests (and other files) can be used as the basis for groups +(@pxref{Document Groups}). + +@item +Articles can be highlighted and customized (@pxref{Customizing +Articles}). + +@item +URLs and other external references can be buttonized (@pxref{Article +Buttons}). + +@item +You can do lots of strange stuff with the Gnus window & frame +configuration (@pxref{Windows Configuration}). + +@item +You can click on buttons instead of using the keyboard +(@pxref{Buttons}). + +@end itemize + + +@node September Gnus +@subsubsection September Gnus + +@iftex +@iflatex +\gnusfig{-28cm}{0cm}{\epsfig{figure=tmp/september.ps,height=20cm}} +@end iflatex +@end iftex + +New features in Gnus 5.2/5.3: + +@itemize @bullet + +@item +A new message composition mode is used. All old customization variables +for @code{mail-mode}, @code{rnews-reply-mode} and @code{gnus-msg} are +now obsolete. + +@item +Gnus is now able to generate @dfn{sparse} threads---threads where +missing articles are represented by empty nodes (@pxref{Customizing +Threading}). + +@lisp +(setq gnus-build-sparse-threads 'some) +@end lisp + +@item +Outgoing articles are stored on a special archive server +(@pxref{Archived Messages}). + +@item +Partial thread regeneration now happens when articles are +referred. + +@item +Gnus can make use of GroupLens predictions (@pxref{GroupLens}). + +@item +Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}). + +@item +A @code{trn}-like tree buffer can be displayed (@pxref{Tree Display}). + +@lisp +(setq gnus-use-trees t) +@end lisp + +@item +An @code{nn}-like pick-and-read minor mode is available for the summary +buffers (@pxref{Pick and Read}). + +@lisp +(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) +@end lisp + +@item +In binary groups you can use a special binary minor mode (@pxref{Binary +Groups}). + +@item +Groups can be grouped in a folding topic hierarchy (@pxref{Group +Topics}). + +@lisp +(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) +@end lisp + +@item +Gnus can re-send and bounce mail (@pxref{Summary Mail Commands}). + +@item +Groups can now have a score, and bubbling based on entry frequency +is possible (@pxref{Group Score}). + +@lisp +(add-hook 'gnus-summary-exit-hook 'gnus-summary-bubble-group) +@end lisp + +@item +Groups can be process-marked, and commands can be performed on +groups of groups (@pxref{Marking Groups}). + +@item +Caching is possible in virtual groups. + +@item +@code{nndoc} now understands all kinds of digests, mail boxes, rnews +news batches, ClariNet briefs collections, and just about everything +else (@pxref{Document Groups}). + +@item +Gnus has a new backend (@code{nnsoup}) to create/read SOUP packets +(@pxref{SOUP}). + +@item +The Gnus cache is much faster. + +@item +Groups can be sorted according to many criteria (@pxref{Sorting +Groups}). + +@item +New group parameters have been introduced to set list-addresses and +expiry times (@pxref{Group Parameters}). + +@item +All formatting specs allow specifying faces to be used +(@pxref{Formatting Fonts}). + +@item +There are several more commands for setting/removing/acting on process +marked articles on the @kbd{M P} submap (@pxref{Setting Process Marks}). + +@item +The summary buffer can be limited to show parts of the available +articles based on a wide range of criteria. These commands have been +bound to keys on the @kbd{/} submap (@pxref{Limiting}). + +@item +Articles can be made persistent with the @kbd{*} command +(@pxref{Persistent Articles}). + +@item +All functions for hiding article elements are now toggles. + +@item +Article headers can be buttonized (@pxref{Article Washing}). + +@lisp +(add-hook 'gnus-article-display-hook + 'gnus-article-add-buttons-to-head) +@end lisp + +@item +All mail backends support fetching articles by @code{Message-ID}. + +@item +Duplicate mail can now be treated properly (@pxref{Duplicates}). + +@item +All summary mode commands are available directly from the article +buffer (@pxref{Article Keymap}). + +@item +Frames can be part of @code{gnus-buffer-configuration} (@pxref{Windows +Configuration}). + +@item +Mail can be re-scanned by a daemonic process (@pxref{Daemons}). +@iftex +@iflatex +\marginpar[\mbox{}\hfill\epsfig{figure=tmp/fseptember.ps,height=5cm}]{\epsfig{figure=tmp/fseptember.ps,height=5cm}} +@end iflatex +@end iftex + +@item +Gnus can make use of NoCeM files to weed out spam (@pxref{NoCeM}). + +@lisp +(setq gnus-use-nocem t) +@end lisp + +@item +Groups can be made permanently visible (@pxref{Listing Groups}). + +@lisp +(setq gnus-permanently-visible-groups "^nnml:") +@end lisp + +@item +Many new hooks have been introduced to make customizing easier. + +@item +Gnus respects the @code{Mail-Copies-To} header. + +@item +Threads can be gathered by looking at the @code{References} header +(@pxref{Customizing Threading}). + +@lisp +(setq gnus-summary-thread-gathering-function + 'gnus-gather-threads-by-references) +@end lisp + +@item +Read articles can be stored in a special backlog buffer to avoid +refetching (@pxref{Article Backlog}). + +@lisp +(setq gnus-keep-backlog 50) +@end lisp + +@item +A clean copy of the current article is always stored in a separate +buffer to allow easier treatment. + +@item +Gnus can suggest where to save articles (@pxref{Saving Articles}). + +@item +Gnus doesn't have to do as much prompting when saving (@pxref{Saving +Articles}). + +@lisp +(setq gnus-prompt-before-saving t) +@end lisp + +@item +@code{gnus-uu} can view decoded files asynchronously while fetching +articles (@pxref{Other Decode Variables}). + +@lisp +(setq gnus-uu-grabbed-file-functions 'gnus-uu-grab-view) +@end lisp + +@item +Filling in the article buffer now works properly on cited text +(@pxref{Article Washing}). + +@item +Hiding cited text adds buttons to toggle hiding, and how much +cited text to hide is now customizable (@pxref{Article Hiding}). + +@lisp +(setq gnus-cited-lines-visible 2) +@end lisp + +@item +Boring headers can be hidden (@pxref{Article Hiding}). + +@lisp +(add-hook 'gnus-article-display-hook + 'gnus-article-hide-boring-headers t) +@end lisp + +@item +Default scoring values can now be set from the menu bar. + +@item +Further syntax checking of outgoing articles have been added. + +@end itemize + + +@node Red Gnus +@subsubsection Red Gnus + +New features in Gnus 5.4/5.5: + +@iftex +@iflatex +\gnusfig{-5.5cm}{-4cm}{\epsfig{figure=tmp/red.ps,height=20cm}} +@end iflatex +@end iftex + +@itemize @bullet + +@item +@file{nntp.el} has been totally rewritten in an asynchronous fashion. + +@item +Article prefetching functionality has been moved up into +Gnus (@pxref{Asynchronous Fetching}). + +@item +Scoring can now be performed with logical operators like @code{and}, +@code{or}, @code{not}, and parent redirection (@pxref{Advanced +Scoring}). + +@item +Article washing status can be displayed in the +article mode line (@pxref{Misc Article}). + +@item +@file{gnus.el} has been split into many smaller files. + +@item +Suppression of duplicate articles based on Message-ID can be done +(@pxref{Duplicate Suppression}). + +@lisp +(setq gnus-suppress-duplicates t) +@end lisp + +@item +New variables for specifying what score and adapt files are to be +considered home score and adapt files (@pxref{Home Score File}) have +been added. + +@item +@code{nndoc} was rewritten to be easily extendable (@pxref{Document +Server Internals}). + +@item +Groups can inherit group parameters from parent topics (@pxref{Topic +Parameters}). + +@item +Article editing has been revamped and is now actually usable. + +@item +Signatures can be recognized in more intelligent fashions +(@pxref{Article Signature}). + +@item +Summary pick mode has been made to look more @code{nn}-like. Line +numbers are displayed and the @kbd{.} command can be used to pick +articles (@code{Pick and Read}). + +@item +Commands for moving the @file{.newsrc.eld} from one server to +another have been added (@pxref{Changing Servers}). + +@item +There's a way now to specify that ``uninteresting'' fields be suppressed +when generating lines in buffers (@pxref{Advanced Formatting}). + +@item +Several commands in the group buffer can be undone with @kbd{M-C-_} +(@pxref{Undo}). + +@item +Scoring can be done on words using the new score type @code{w} +(@pxref{Score File Format}). + +@item +Adaptive scoring can be done on a Subject word-by-word basis +(@pxref{Adaptive Scoring}). + +@lisp +(setq gnus-use-adaptive-scoring '(word)) +@end lisp + +@item +Scores can be decayed (@pxref{Score Decays}). + +@lisp +(setq gnus-decay-scores t) +@end lisp + +@item +Scoring can be performed using a regexp on the Date header. The Date is +normalized to compact ISO 8601 format first (@pxref{Score File Format}). + +@item +A new command has been added to remove all data on articles from +the native server (@pxref{Changing Servers}). + +@item +A new command for reading collections of documents +(@code{nndoc} with @code{nnvirtual} on top) has been added---@kbd{M-C-d} +(@pxref{Really Various Summary Commands}). + +@item +Process mark sets can be pushed and popped (@pxref{Setting Process +Marks}). + +@item +A new mail-to-news backend makes it possible to post even when the NNTP +server doesn't allow posting (@pxref{Mail-To-News Gateways}). + +@item +A new backend for reading searches from Web search engines +(@dfn{DejaNews}, @dfn{Alta Vista}, @dfn{InReference}) has been added +(@pxref{Web Searches}). + +@item +Groups inside topics can now be sorted using the standard sorting +functions, and each topic can be sorted independently (@pxref{Topic +Sorting}). + +@item +Subsets of the groups can be sorted independently (@code{Sorting +Groups}). + +@item +Cached articles can be pulled into the groups (@pxref{Summary Generation +Commands}). +@iftex +@iflatex +\marginpar[\mbox{}\hfill\epsfig{figure=tmp/fred.ps,width=3cm}]{\epsfig{figure=tmp/fred.ps,width=3cm}} +@end iflatex +@end iftex + +@item +Score files are now applied in a more reliable order (@pxref{Score +Variables}). + +@item +Reports on where mail messages end up can be generated (@pxref{Splitting +Mail}). + +@item +More hooks and functions have been added to remove junk from incoming +mail before saving the mail (@pxref{Washing Mail}). + +@item +Emphasized text can be properly fontisized: + +@lisp +(add-hook 'gnus-article-display-hook + 'gnus-article-emphasize) +@end lisp + +@end itemize + + +@node Quassia Gnus +@subsubsection Quassia Gnus + +New features in Gnus 5.6: + +@itemize @bullet + +@item +New functionality for using Gnus as an offline newsreader has been +added. A plethora of new commands and modes have been added. See +@pxref{Gnus Unplugged} for the full story. + +@item + The @code{nndraft} backend has returned, but works differently than +before. All Message buffers are now also articles in the @code{nndraft} +group, which is created automatically. + +@item +@code{gnus-alter-header-function} can now be used to alter header +values. + +@item + @code{gnus-summary-goto-article} now accept Message-ID's. + +@item + A new Message command for deleting text in the body of a message +outside the region: @kbd{C-c C-v}. + +@item + You can now post to component group in @code{nnvirtual} groups with +@kbd{C-u C-c C-c}. + +@item + @code{nntp-rlogin-program}---new variable to ease customization. + +@item + @code{C-u C-c C-c} in @code{gnus-article-edit-mode} will now inhibit +re-highlighting of the article buffer. + +@item + New element in @code{gnus-boring-article-headers}---@code{long-to}. + +@item + @kbd{M-i} symbolic prefix command. See the section "Symbolic +Prefixes" in the Gnus manual for details. + +@item + @kbd{L} and @kbd{I} in the summary buffer now take the symbolic prefix +@kbd{a} to add the score rule to the "all.SCORE" file. + +@item + @code{gnus-simplify-subject-functions} variable to allow greater +control over simplification. + +@item + @kbd{A T}---new command for fetching the current thread. + +@item + @kbd{/ T}---new command for including the current thread in the +limit. + +@item + @kbd{M-RET} is a new Message command for breaking cited text. + +@item + @samp{\\1}-expressions are now valid in @code{nnmail-split-methods}. + +@item + The @code{custom-face-lookup} function has been removed. +If you used this function in your initialization files, you must +rewrite them to use @code{face-spec-set} instead. + +@item + Canceling now uses the current select method. Symbolic prefix +@kbd{a} forces normal posting method. + +@item + New command to translate M******** sm*rtq**t*s into proper +text---@kbd{W d}. + +@item + For easier debugging of @code{nntp}, you can set +@code{nntp-record-commands} to a non-@code{nil} value. + +@item + @code{nntp} now uses @file{~/.authinfo}, a @file{.netrc}-like file, for +controlling where and how to send @sc{authinfo} to @sc{nntp} servers. + +@item + A command for editing group parameters from the summary buffer +has been added. + +@item + A history of where mails have been split is available. + +@item + A new article date command has been added---@code{article-date-iso8601}. + +@item + Subjects can be simplified when threading by setting +@code{gnus-score-thread-simplify}. + +@item + A new function for citing in Message has been +added---@code{message-cite-original-without-signature}. + +@item + @code{article-strip-all-blank-lines}---new article command. + +@item + A new Message command to kill to the end of the article has +been added. + +@item + A minimum adaptive score can be specified by using the +@code{gnus-adaptive-word-minimum} variable. + +@item + The "lapsed date" article header can be kept continually +updated by the @code{gnus-start-date-timer} command. + +@item + Web listserv archives can be read with the @code{nnlistserv} backend. + +@item + Old dejanews archives can now be read by @code{nnweb}. + +@end itemize + + +@node Newest Features +@subsection Newest Features +@cindex todo + +Also known as the @dfn{todo list}. Sure to be implemented before the +next millennium. + +Be afraid. Be very afraid. + +(That a feature appears in this list doesn't necessarily mean that I've +decided to actually implement it. It just means that I think it sounds +interesting.) + +(Yes, this is the actual, up-to-the-second todo list.) + +@itemize @bullet + +@item +Native @sc{mime} support is something that should be done. + +@item +Really do unbinhexing. + +@item + I would like the zombie-page to contain an URL to the source of the +latest version of gnus or some explanation on where to find it. + +@item + A way to continue editing the latest Message composition. + +@item + http://www.sonicnet.com/feature/ari3/ + +@item + facep is not declared. + +@item + Include a section in the manual on why the number of articles +isn't the same in the group buffer and on the SPC prompt. + +@item + Interacting with rmail fcc isn't easy. + +@item +@example + Hypermail: + + + + +http://www.uwsg.indiana.edu/hypermail/linux/kernel/9610/index.html + +http://www.miranova.com/gnus-list/ + +@end example + +@item +@samp{^-- } is made into - in LaTeX. + +@item + gnus-kill is much slower than it was in GNUS 4.1.3. + +@item + when expunging articles on low score, the sparse nodes keep hanging on? +@item + starting the first time seems to hang Gnus on some systems. Does +NEWGROUPS answer too fast? +@item + nndir doesn't read gzipped files. +@item + FAQ doesn't have an up node? +@item + when moving mail from a procmail spool to the crash-box, +the crash-box is only appropriate to one specific group. +@item + `t' `t' makes X-Faces disappear. +@item + nnmh-be-safe means that crossposted articles will +be marked as unread. +@item + Orphan score entries don't show on "V t" score trace +@item + when clearing out data, the cache data should also be reset. +@item + rewrite gnus-summary-limit-children to be non-recursive +to avoid exceeding lisp nesting on huge groups. +@item + expunged articles are counted when computing scores. +@item + implement gnus-batch-brew-soup +@item + ticked articles aren't easy to read in pick mode -- `n' and +stuff just skips past them. Read articles are the same. +@item + topics that contain just groups with ticked +articles aren't displayed. +@item + nndoc should always allocate unique Message-IDs. +@item + If there are mail groups the first time you use Gnus, Gnus'll +make the mail groups killed. +@item + no "no news is good news" when using topics. +@item + when doing crosspost marking, the cache has to be consulted +and articles have to be removed. +@item + nnweb should fetch complete articles when they are split into several +parts. +@item + scoring on head immediate doesn't work. +@item + finding short score file names takes forever. +@item + canceling articles in foreign groups. +@item + nntp-open-rlogin no longer works. +@item + C-u C-x C-s (Summary) switches to the group buffer. +@item + move nnmail-split-history out to the backends. +@item + nnweb doesn't work properly. +@item + using a virtual server name as `gnus-select-method' doesn't work? +@item + when killing/yanking a group from one topic to another in a slave, the +master will yank it first to one topic and then add it to another. +Perhaps. + +@item + warn user about `=' redirection of a group in the active file? +@item + really unbinhex binhex files. +@item + take over the XEmacs menubar and offer a toggle between the XEmacs +bar and the Gnus bar. +@item +@example + push active file and NOV file parsing down into C code. +`(canonize-message-id id)' +`(mail-parent-message-id references n)' +`(parse-news-nov-line &optional dependency-hashtb)' +`(parse-news-nov-region beg end &optional dependency-hashtb fullp)' +`(parse-news-active-region beg end hashtb)' + +@end example + +@item + nnml .overview directory with splits. +@item + asynchronous cache +@item + postponed commands. +@item + the selected article show have its Subject displayed in its summary line. +@item + when entering groups, get the real number of unread articles from +the server? +@item + sort after gathering threads -- make false roots have the +headers of the oldest orphan with a 0 article number? +@item + nndoc groups should inherit the score files of their parents? Also +inherit copy prompts and save files. +@item + command to start up Gnus (if not running) and enter a mail mode buffer. +@item + allow editing the group description from the group buffer +for backends that support that. +@item +gnus-hide,show-all-topics +@item + groups and sub-topics should be allowed to mingle inside each topic, +and not just list all subtopics at the end. +@item + a command to remove all read articles that are not needed to connect +threads -- `gnus-summary-limit-to-sparse-unread'? +@item + a variable to turn off limiting/cutting of threads in the tree buffer. +@item + a variable to limit how many files are uudecoded. +@item + add zombie groups to a special "New Groups" topic. +@item + server mode command: close/open all connections +@item + put a file date in gnus-score-alist and check whether the file +has been changed before using it. +@item + on exit from a digest group, go to the next article in the parent group. +@item + hide (sub)threads with low score. +@item + when expiring, remove all marks from expired articles. +@item + gnus-summary-limit-to-body +@item + a regexp alist that says what level groups are to be subscribed +on. Eg. -- `(("nnml:" . 1))'. +@item + easier interface to nnkiboze to create ephemeral groups that +contain groups that match a regexp. +@item + allow newlines in urls, but remove them before using +the URL. +@item + If there is no From line, the mail backends should fudge one from the +"From " line. +@item + fuzzy simplifying should strip all non-alpha-numerical info +from subject lines. +@item + gnus-soup-brew-soup-with-high-scores. +@item + nntp-ping-before-connect +@item + command to check whether NOV is evil. "list overview.fmt". +@item + when entering a group, Gnus should look through the score +files very early for `local' atoms and set those local variables. +@item + message annotations. +@item + topics are always yanked before groups, and that's not good. +@item + (set-extent-property extent 'help-echo "String to display in minibuf") +to display help in the minibuffer on buttons under XEmacs. +@item + allow group line format spec to say how many articles there +are in the cache. +@item + AUTHINFO GENERIC +@item + support qmail maildir spools +@item + `run-with-idle-timer' in gnus-demon. +@item + stop using invisible text properties and start using overlays instead +@item + C-c C-f C-e to add an Expires header. +@item + go from one group to the next; everything is expunged; go to the +next group instead of going to the group buffer. +@item + gnus-renumber-cache -- to renumber the cache using "low" numbers. +@item + record topic changes in the dribble buffer. +@item + `nnfolder-generate-active-file' should look at the folders it +finds and generate proper active ranges. +@item + nneething-look-in-files-for-article-heads variable to control +whether nneething should sniff all files in the directories. +@item + gnus-fetch-article -- start Gnus, enter group, display article +@item + gnus-dont-move-articles-to-same-group variable when respooling. +@item + when messages are crossposted between several auto-expirable groups, +articles aren't properly marked as expirable. +@item + nneething should allow deletion/moving. +@item + TAB on the last button should go to the first button. +@item + if the car of an element in `mail-split-methods' is a function, +and the function returns non-nil, use that as the name of the group(s) to +save mail in. +@item + command for listing all score files that have been applied. +@item + a command in the article buffer to return to `summary' config. +@item + `gnus-always-post-using-current-server' -- variable to override +`C-c C-c' when posting. +@item + nnmail-group-spool-alist -- says where each group should use +as a spool file. +@item + when an article is crossposted to an auto-expirable group, the article +should be marker as expirable. +@item + article mode command/menu for "send region as URL to browser". +@item + on errors, jump to info nodes that explain the error. For instance, +on invalid From headers, or on error messages from the nntp server. +@item + when gathering threads, make the article that has no "Re: " the parent. +Also consult Date headers. +@item + a token in splits to call shrink-window-if-larger-than-buffer +@item + `1 0 A M' to do matches on the active hashtb. +@item + duplicates -- command to remove Gnus-Warning header, use the read +Message-ID, delete the "original". +@item + when replying to several messages at once, put the "other" message-ids +into a See-Also header. +@item + support setext: URL:http://www.bsdi.com/setext/ +@item + support ProleText: +@item + when browsing a foreign server, the groups that are already subscribed +should be listed as such and not as "K". +@item + generate font names dynamically. +@item + score file mode auto-alist. +@item + allow nndoc to change/add/delete things from documents. Implement +methods for each format for adding an article to the document. +@item + `gnus-fetch-old-headers' `all' value to incorporate +absolutely all headers there is. +@item + function like `|', but concatenate all marked articles +and pipe them to the process. +@item + cache the list of killed (or active) groups in a separate file. Update +the file whenever we read the active file or the list +of killed groups in the .eld file reaches a certain length. +@item + function for starting to edit a file to put into +the current mail group. +@item + score-find-trace should display the total score of the article. +@item + "ghettozie" -- score on Xref header and nix it out after using it +to avoid marking as read in other groups it has been crossposted to. +@item + look at procmail splitting. The backends should create +the groups automatically if a spool file exists for that group. +@item + function for backends to register themselves with Gnus. +@item + when replying to several process-marked articles, +have all the From end up in Cc headers? Variable to toggle. +@item + command to delete a crossposted mail article from all +groups it has been mailed to. +@item + `B c' and `B m' should be crosspost aware. +@item + hide-pgp should also hide PGP public key blocks. +@item + Command in the group buffer to respool process-marked groups. +@item + `gnus-summary-find-matching' should accept +pseudo-"headers" like "body", "head" and "all" +@item + When buttifying things, all white space (including +newlines) should be ignored. +@item + Process-marking all groups in a topic should process-mark +groups in subtopics as well. +@item + Add non-native groups to the list of killed groups when killing them. +@item + nntp-suggest-kewl-config to probe the nntp server and suggest +variable settings. +@item + add edit and forward secondary marks. +@item + nnml shouldn't visit its .overview files. +@item + allow customizing sorting within gathered threads. +@item + `B q' shouldn't select the current article. +@item + nnmbox should support a newsgroups file for descriptions. +@item + allow fetching mail from several pop servers. +@item + Be able to specify whether the saving commands save the original +or the formatted article. +@item + a command to reparent with the child process-marked (cf. `T ^'.). +@item + I think the possibility to send a password with nntp-open-rlogin +should be a feature in Red Gnus. +@item + The `Z n' command should be possible to execute from a mouse click. +@item + more limiting functions -- date, etc. +@item + be able to limit on a random header; on body; using reverse matches. +@item + a group parameter (`absofucking-total-expiry') that will make Gnus expire +even unread articles. +@item + a command to print the article buffer as postscript. +@item + variable to disable password fetching when opening by nntp-open-telnet. +@item + manual: more example servers -- nntp with rlogin, telnet +@item + checking for bogus groups should clean topic alists as well. +@item + canceling articles in foreign groups. +@item + article number in folded topics isn't properly updated by +Xref handling. +@item + Movement in the group buffer to the next unread group should go to the +next closed topic with unread messages if no group can be found. +@item + Extensive info pages generated on the fly with help everywhere -- +in the "*Gnus edit*" buffers, for instance. +@item + Topic movement commands -- like thread movement. Up, down, forward, next. +@item + a way to tick/mark as read Gcc'd articles. +@item + a way to say that all groups within a specific topic comes +from a particular server? Hm. +@item + `gnus-article-fill-if-long-lines' -- a function to fill +the article buffer if there are any looong lines there. +@item + `T h' should jump to the parent topic and fold it. +@item + a command to create an ephemeral nndoc group out of a file, +and then splitting it/moving it to some other group/backend. +@item + a group parameter for nnkiboze groups that says that +all kibozed articles should be entered into the cache. +@item + It should also probably be possible to delimit what +`gnus-jog-cache' does -- for instance, work on just some groups, or on +some levels, and entering just articles that have a score higher than +a certain number. +@item + nnfolder should append to the folder instead of re-writing +the entire folder to disk when accepting new messages. +@item + allow all backends to do the proper thing with .gz files. +@item + a backend for reading collections of babyl files nnbabylfolder? +@item + a command for making the native groups into foreign groups. +@item + server mode command for clearing read marks from all groups +from a server. +@item + when following up multiple articles, include all To, Cc, etc headers +from all articles. +@item + a command for deciding what the total score of the current +thread is. Also a way to highlight based on this. +@item + command to show and edit group scores +@item + a gnus-tree-minimize-horizontal to minimize tree buffers +horizontally. +@item + command to generate nnml overview file for one group. +@item + `C-u C-u a' -- prompt for many crossposted groups. +@item + keep track of which mail groups have received new articles (in this session). +Be able to generate a report and perhaps do some marking in the group +buffer. +@item + gnus-build-sparse-threads to a number -- build only sparse threads +that are of that length. +@item + have nnmh respect mh's unseen sequence in .mh_profile. +@item + cache the newsgroups descriptions locally. +@item + asynchronous posting under nntp. +@item + be able to control word adaptive scoring from the score files. +@item + a variable to make `C-c C-c' post using the "current" select method. +@item + `limit-exclude-low-scored-articles'. +@item + if `gnus-summary-show-thread' is a number, hide threads that have +a score lower than this number. +@item + split newsgroup subscription variable up into "order" and "method". +@item + buttonize ange-ftp file names. +@item + a command to make a duplicate copy of the current article +so that each copy can be edited separately. +@item + nnweb should allow fetching from the local nntp server. +@item + record the sorting done in the summary buffer so that +it can be repeated when limiting/regenerating the buffer. +@item + nnml-generate-nov-databses should generate for +all nnml servers. +@item + when the user does commands in the group buffer, check +the modification time of the .newsrc.eld file and use +ask-user-about-supersession-threat. Also warn when trying +to save .newsrc.eld and it has changed. +@item + M-g on a topic will display all groups with 0 articles in +the topic. +@item + command to remove all topic stuff. +@item + allow exploding incoming digests when reading incoming mail +and splitting the resulting digests. +@item + nnsoup shouldn't set the `message-' variables. +@item + command to nix out all nnoo state information. +@item + nnmail-process-alist that calls functions if group names +matches an alist -- before saving. +@item + use buffer-invisibility-spec everywhere for hiding text. +@item + variable to activate each group before entering them +to get the (new) number of articles. `gnus-activate-before-entering'. +@item + command to fetch a Message-ID from any buffer, even +starting Gnus first if necessary. +@item + when posting and checking whether a group exists or not, just +ask the nntp server instead of relying on the active hashtb. +@item + buttonize the output of `C-c C-a' in an apropos-like way. +@item + `G p' should understand process/prefix, and allow editing +of several groups at once. +@item + command to create an ephemeral nnvirtual group that +matches some regexp(s). +@item + nndoc should understand "Content-Type: message/rfc822" forwarded messages. +@item + it should be possible to score "thread" on the From header. +@item + hitting RET on a "gnus-uu-archive" pseudo article should unpack it. +@item + `B i' should display the article at once in the summary buffer. +@item + remove the "*" mark at once when unticking an article. +@item + `M-s' should highlight the matching text. +@item + when checking for duplicated mails, use Resent-Message-ID if present. +@item + killing and yanking groups in topics should be better. If killing one copy +of a group that exists in multiple topics, only that copy should +be removed. Yanking should insert the copy, and yanking topics +should be possible to be interspersed with the other yankings. +@item + command for enter a group just to read the cached articles. A way to say +"ignore the nntp connection; just read from the cache." +@item + `X u' should decode base64 articles. +@item + a way to hide all "inner" cited text, leaving just the most +recently cited text. +@item + nnvirtual should be asynchronous. +@item + after editing an article, gnus-original-article-buffer should +be invalidated. +@item + there should probably be a way to make Gnus not connect to the +server and just read the articles in the server +@item + allow a `set-default' (or something) to change the default +value of nnoo variables. +@item + a command to import group infos from a .newsrc.eld file. +@item + groups from secondary servers have the entire select method +listed in each group info. +@item + a command for just switching from the summary buffer to the group +buffer. +@item + a way to specify that some incoming mail washing functions +should only be applied to some groups. +@item + Message `C-f C-t' should ask the user whether to heed +mail-copies-to: never. +@item + new group parameter -- `post-to-server' that says to post +using the current server. Also a variable to do the same. +@item + the slave dribble files should autosave to the slave file names. +@item + a group parameter that says what articles to display on group entry, based +on article marks. +@item + a way to visually distinguish slave Gnusae from masters. (Whip instead +of normal logo?) +@item + Use DJ Bernstein "From " quoting/dequoting, where applicable. +@item + Why is hide-citation-maybe and hide-citation different? Also +clear up info. +@item + group user-defined meta-parameters. + + + +From: John Griffith +@item + I like the option for trying to retrieve the FAQ for a group and I was +thinking it would be great if for those newsgroups that had archives +you could also try to read the archive for that group. Part of the +problem is that archives are spread all over the net, unlike FAQs. +What would be best I suppose is to find the one closest to your site. + +In any case, there is a list of general news group archives at @* +ftp://ftp.neosoft.com/pub/users/claird/news.lists/newsgroup_archives.html + + + + +@item +@example +From: Jason L Tibbitts III +(add-hook 'gnus-select-group-hook + (lambda () + (gnus-group-add-parameter group + (cons 'gnus-group-date-last-entered (list (current-time-string)))))) + +(defun gnus-user-format-function-d (headers) + "Return the date the group was last read." + (cond ((car (gnus-group-get-parameter gnus-tmp-group 'gnus-group-date-last-entered))) + (t ""))) +@end example + +@item + tanken var at n,Ae(Br du bruker `gnus-startup-file' som prefix (FOO) til ilete +opp en fil FOO-SERVER, FOO-SERVER.el, FOO-SERVER.eld, kan du la den v,Af(Bre en +liste hvor du bruker hvert element i listen som FOO, istedet. da kunne man +hatt forskjellige serveres startup-filer forskjellige steder. + + +@item +LMI> Well, nnbabyl could alter the group info to heed labels like +LMI> answered and read, I guess. + +It could also keep them updated (the same for the Status: header of +unix mbox files). + +They could be used like this: + + +@example +`M l RET' add label to current message. +`M u RET' remove label from current message. +`/ l RET' limit summary buffer according to . + + would be a boolean expression on the labels, e.g. + +`/ l bug & !fixed RET' +@end example + +would show all the messages which are labeled `bug' but not labeled +`fixed'. + +One could also imagine the labels being used for highlighting, or +affect the summary line format. + + +@item +Sender: abraham@@dina.kvl.dk + +I'd like a gnus-find-file which work like find file, except that it +would recognize things that looks like messages or folders: + +- If it is a directory containing numbered files, create an nndir +summary buffer. + +- For other directories, create a nneething summary buffer. + +- For files matching "\\`From ", create a nndoc/mbox summary. + +- For files matching "\\`BABYL OPTIONS:", create a nndoc/baby summary. + +- For files matching "\\`[^ \t\n]+:", create an *Article* buffer. + +- For other files, just find them normally. + +I'd like `nneething' to use this function, so it would work on a +directory potentially containing mboxes or babyl files. + +@item +Please send a mail to bwarsaw@@cnri.reston.va.us (Barry A. Warsaw) and +tell him what you are doing. + +@item +Currently, I get prompted: + +decend into sci? +- type y +decend into sci.something ? +- type n +decend into ucd? + +The problem above is that since there is really only one subsection of +science, shouldn't it prompt you for only descending sci.something? If +there was a sci.somethingelse group or section, then it should prompt +for sci? first the sci.something? then sci.somethingelse?... + +@item +Ja, det burde v,Af(Bre en m,Ae(Bte ,Ae(B si slikt. Kanskje en ny variabel? +`gnus-use-few-score-files'? S,Ae(B kunne score-regler legges til den +"mest" lokale score-fila. F. eks. ville no-gruppene betjenes av +"no.all.SCORE", osv. + +@item +What i want is for Gnus to treat any sequence or combination of the following +as a single spoiler warning and hide it all, replacing it with a "Next Page" +button: + + +^L's + +more than n blank lines + +more than m identical lines +(which should be replaced with button to show them) + +any whitespace surrounding any of the above + + +@item +Well, we could allow a new value to `gnus-thread-ignore-subject' -- +`spaces', or something. (We could even default to that.) And then +subjects that differ in white space only could be considered the +"same" subject for threading purposes. + +@item +Modes to preprocess the contents (e.g. jka-compr) use the second form +"(REGEXP FUNCTION NON-NIL)" while ordinary modes (e.g. tex) use the first +form "(REGEXP . FUNCTION)", so you could use it to distinguish between +those two types of modes. (auto-modes-alist, insert-file-contents-literally.) + +@item + Under XEmacs -- do funny article marks: +tick - thumb tack +killed - skull +soup - bowl of soup +score below - dim light bulb +score over - bright light bulb + +@item +Yes. I think the algorithm is as follows: + +@example +Group-mode + + show-list-of-articles-in-group + if (key-pressed == SPACE) + if (no-more-articles-in-group-to-select) + if (articles-selected) + start-reading-selected-articles; + junk-unread-articles; + next-group; + else + show-next-page; + + else if (key-pressed = '.') + if (consolidated-menus) # same as hide-thread in Gnus + select-thread-under-cursor; + else + select-article-under-cursor; + + +Article-mode + if (key-pressed == SPACE) + if (more-pages-in-article) + next-page; + else if (more-selected-articles-to-read) + next-article; + else + next-group; +@end example + +@item +My precise need here would have been to limit files to Incoming*. +One could think of some `nneething-only-files' variable, but I guess +it would have been unacceptable if one was using many unrelated such +nneething groups. + +A more useful approach would be to, in response to the `G D' prompt, be +allowed to say something like: `~/.mail/Incoming*', somewhat limiting +the top-level directory only (in case directories would be matched by +the wildcard expression). + +@item +It would be nice if it also handled + + + +which should correspond to `B nntp RET sunsite.auc.dk' in *Group*. + + +@item + + Take a look at w3-menu.el in the Emacs-W3 distribution - this works out +really well. Each menu is 'named' by a symbol that would be on a +gnus-*-menus (where * would be whatever, but at least group, summary, and +article versions) variable. + + So for gnus-summary-menus, I would set to '(sort mark dispose ...) + + A value of '1' would just put _all_ the menus in a single 'GNUS' menu in +the main menubar. This approach works really well for Emacs-W3 and VM. + + +@item + nndoc should take care to create unique Message-IDs for all its +articles. +@item + gnus-score-followup-article only works when you have a summary buffer +active. Make it work when posting from the group buffer as well. +(message-sent-hook). +@item + rewrite gnus-demon to use run-with-idle-timers. + +@item + * Enhancements to Gnus: + + Add two commands: + + * gnus-servers (gnus-start-server-buffer?)--enters Gnus and goes + straight to the server buffer, without opening any connections to + servers first. + + * gnus-server-read-server-newsrc--produces a buffer very similar to + the group buffer, but with only groups from that server listed; + quitting this buffer returns to the server buffer. + +@item + add a command to check the integrity of an nnfolder folder -- +go through the article numbers and see that there are no duplicates, +and stuff. + +@item + `unsmileyfy-buffer' to undo smileification. + +@item + a command to give all relevant info on an article, including all +secondary marks. + +@item + when doing `-request-accept-article', the backends should do +the nnmail duplicate checking. + +@item + allow `message-signature-file' to be a function to return the +value of the signature file. + +@item + In addition, I would love it if I could configure message-tab so that it +could call `bbdb-complete-name' in other headers. So, some sort of +interface like + +(setq message-tab-alist + '((message-header-regexp message-expand-group) + ("^\\(To\\|[cC]c\\|[bB]cc\\)" bbdb-complete-name))) + +then you could run the relevant function to complete the information in +the header + +@item + cache the newsgroups file locally to avoid reloading it all the time. + +@item + a command to import a buffer into a group. + +@item + nnweb should allow fetching by Message-ID from servers. + +@item + point in the article buffer doesn't always go to the +beginning of the buffer when selecting new articles. + +@item + a command to process mark all unread articles. + +@item + `gnus-gather-threads-by-references-and-subject' -- first +do gathering by references, and then go through the dummy roots and +do more gathering by subject. + +@item + gnus-uu-mark-in-numerical-order -- process mark articles in +article numerical order. + +@item + (gnus-thread-total-score + (gnus-id-to-thread (mail-header-id (gnus-summary-article-header)))) +bind to a key. + +@item + sorting by score is wrong when using sparse threads. + +@item + a command to fetch an arbitrary article -- without having to be +in the summary buffer. + +@item + a new nncvs backend. Each group would show an article, using +version branches as threading, checkin date as the date, etc. + +@item + http://www.dejanews.com/forms/dnsetfilter_exp.html ? +This filter allows one to construct advance queries on the Dejanews +database such as specifying start and end dates, subject, author, +and/or newsgroup name. + +@item + new Date header scoring type -- older, newer + +@item + use the summary toolbar in the article buffer. + +@item + a command to fetch all articles that are less than X days old. + +@item + in pick mode, `q' should save the list of selected articles in the +group info. The next time the group is selected, these articles +will automatically get the process mark. + +@item + Isn't it possible to (also?) allow M-^ to automatically try the +default server if it fails on the current server? (controlled by a +user variable, (nil, t, 'ask)). + +@item + make it possible to cancel articles using the select method for the +current group. + +@item + `gnus-summary-select-article-on-entry' or something. It'll default +to t and will select whatever article decided by `gnus-auto-select-first'. + +@item + a new variable to control which selection commands should be unselecting. +`first', `best', `next', `prev', `next-unread', `prev-unread' are +candidates. + +@item + be able to select groups that have no articles in them +to be able to post in them (using the current select method). + +@item + be able to post via DejaNews. + +@item + `x' should retain any sortings that have been performed. + +@item + allow the user to specify the precedence of the secondary marks. Also +allow them to be displayed separately. + +@item + gnus-summary-save-in-pipe should concatenate the results from +the processes when doing a process marked pipe. + +@item + a new match type, like Followup, but which adds Thread matches on all +articles that match a certain From header. + +@item + a function that can be read from kill-emacs-query-functions to offer +saving living summary buffers. + +@item + a function for selecting a particular group which will contain +the articles listed in a list of article numbers/id's. + +@item + a battery of character translation functions to translate common +Mac, MS (etc) characters into ISO 8859-1. + +@example +(defun article-fix-m$word () + "Fix M$Word smartquotes in an article." + (interactive) + (save-excursion + (let ((buffer-read-only nil)) + (goto-char (point-min)) + (while (search-forward "\221" nil t) + (replace-match "`" t t)) + (goto-char (point-min)) + (while (search-forward "\222" nil t) + (replace-match "'" t t)) + (goto-char (point-min)) + (while (search-forward "\223" nil t) + (replace-match "\"" t t)) + (goto-char (point-min)) + (while (search-forward "\224" nil t) + (replace-match "\"" t t))))) +@end example + +@item +@example + (add-hook 'gnus-exit-query-functions +'(lambda () + (if (and (file-exists-p nnmail-spool-file) + (> (nnheader-file-size nnmail-spool-file) 0)) + (yes-or-no-p "New mail has arrived. Quit Gnus anyways? ") + (y-or-n-p "Are you sure you want to quit Gnus? ")))) +@end example + +@item + allow message-default-headers to be a function. + +@item + new Date score match types -- < > = (etc) that take floating point +numbers and match on the age of the article. + +@item +@example +> > > If so, I've got one gripe: It seems that when I fire up gnus 5.2.25 +> > > under xemacs-19.14, it's creating a new frame, but is erasing the +> > > buffer in the frame that it was called from =:-O +> +> > Hm. How do you start up Gnus? From the toolbar or with +> > `M-x gnus-other-frame'? +> +> I normally start it up from the toolbar; at +> least that's the way I've caught it doing the +> deed before. +@end example + +@item + all commands that react to the process mark should push +the current process mark set onto the stack. + +@item + gnus-article-hide-pgp +Selv ville jeg nok ha valgt islette den dersom teksten matcher +@example +"\\(This\s+\\)?[^ ]+ has been automatically signed by" +@end example +og det er maks hundre tegn mellom match-end og ----linja. Men -det- +er min type heuristikk og langt fra alles. + +@item + `gnus-subscribe-sorted' -- insert new groups where they would have been +sorted to if `gnus-group-sort-function' were run. + +@item + gnus-(group,summary)-highlight should respect any `face' text props set +on the lines. + +@item + use run-with-idle-timer for gnus-demon instead of the +home-brewed stuff for better reliability. + +@item + add a way to select which NoCeM type to apply -- spam, troll, etc. + +@item + nndraft-request-group should tally autosave files. + +@item + implement nntp-retry-on-break and nntp-command-timeout. + +@item + gnus-article-highlight-limit that says when not to highlight (long) +articles. + +@item + (nnoo-set SERVER VARIABLE VALUE) + +@item + nn*-spool-methods + +@item + interrupitng agent fetching of articles should save articles. + +@item + command to open a digest group, and copy all the articles there to the +current group. + +@item + a variable to disable article body highlights if there's more than +X characters in the body. + +@item + handle 480/381 authinfo requests separately. + +@item + include the texi/dir file in the distribution. + +@item + format spec to "tab" to a position. + +@item + Move all prompting to the new `M-n' default style. + +@item + command to display all dormant articles. + +@item + gnus-auto-select-next makeover -- list of things it should do. + +@item + a score match type that adds scores matching on From if From has replied +to something someone else has said. + +@item + Read Netscape discussion groups: +snews://secnews.netscape.com/netscape.communicator.unix + +@item +One command to edit the original version if an article, and one to edit +the displayed version. + +@item +@kbd{T v} -- make all process-marked articles the children of the +current article. + +@item +Switch from initial text to the new default text mechanism. + +@item +How about making it possible to expire local articles? Will it be +possible to make various constraints on when an article can be +expired, e.g. (read), (age > 14 days), or the more interesting (read +& age > 14 days)? + +@item +New limit command---limit to articles that have a certain string +in the head or body. + +@item +Allow breaking lengthy NNTP commands. + +@item +gnus-article-highlight-limit, to disable highlighting in big articles. + +@item +Editing an article should put the article to be edited +in a special, unique buffer. + +@item +A command to send a mail to the admin-address group param. + +@item +A Date scoring type that will match if the article +is less than a certain number of days old. + +@item +New spec: %~(tab 56) to put point on column 56 + +@item +Allow Gnus Agent scoring to use normal score files. + +@item +Rething the Agent active file thing. `M-g' doesn't update the active +file, for instance. + +@item +With dummy roots, `^' and then selecing the first article +in any other dummy thread will make gnus highlight the +dummy root instead of the first article. + +@item +Propagate all group properties (marks, article numbers, etc) up to the +topics for displaying. + +@item +`n' in the group buffer with topics should go to the next group +with unread articles, even if that group is hidden in a topic. + +@item +gnus-posting-styles doesn't work in drafts. + +@item +gnus-summary-limit-include-cached is slow when there are +many articles in the cache, since it regenerates big parts of the +summary buffer for each article. + +@item +Implement gnus-batch-brew-soup. + +@item +Group parameters and summary commands for un/subscribing to mailing +lists. + +@item +Introduce nnmail-home-directory. + +@item +gnus-fetch-group and friends should exit Gnus when the user +exits the group. + +@item +The jingle is only played on the second invocation of Gnus. + +@item +gnus-ignored-mime-types to avoid seeing buttons for Vcards and the +like. + +@item +Boucing articles should do MIME. + +@item +Solve the halting problem. + +@c TODO +@end itemize + +@iftex + +@page +@node The Manual +@section The Manual +@cindex colophon +@cindex manual + +This manual was generated from a TeXinfo file and then run through +either @code{texi2dvi} +@iflatex +or my own home-brewed TeXinfo to \LaTeX\ transformer, +and then run through @code{latex} and @code{dvips} +@end iflatex +to get what you hold in your hands now. + +The following conventions have been used: + +@enumerate + +@item +This is a @samp{string} + +@item +This is a @kbd{keystroke} + +@item +This is a @file{file} + +@item +This is a @code{symbol} + +@end enumerate + +So if I were to say ``set @code{flargnoze} to @samp{yes}'', that would +mean: + +@lisp +(setq flargnoze "yes") +@end lisp + +If I say ``set @code{flumphel} to @code{yes}'', that would mean: + +@lisp +(setq flumphel 'yes) +@end lisp + +@samp{yes} and @code{yes} are two @emph{very} different things---don't +ever get them confused. + +@iflatex +@c @head +Of course, everything in this manual is of vital interest, so you should +read it all. Several times. However, if you feel like skimming the +manual, look for that gnu head you should see in the margin over +there---it means that what's being discussed is of more importance than +the rest of the stuff. (On the other hand, if everything is infinitely +important, how can anything be more important than that? Just one more +of the mysteries of this world, I guess.) +@end iflatex + +@end iftex + + +@page +@node Terminology +@section Terminology + +@cindex terminology +@table @dfn + +@item news +@cindex news +This is what you are supposed to use this thing for---reading news. +News is generally fetched from a nearby @sc{nntp} server, and is +generally publicly available to everybody. If you post news, the entire +world is likely to read just what you have written, and they'll all +snigger mischievously. Behind your back. + +@item mail +@cindex mail +Everything that's delivered to you personally is mail. Some news/mail +readers (like Gnus) blur the distinction between mail and news, but +there is a difference. Mail is private. News is public. Mailing is +not posting, and replying is not following up. + +@item reply +@cindex reply +Send a mail to the person who has written what you are reading. + +@item follow up +@cindex follow up +Post an article to the current newsgroup responding to the article you +are reading. + +@item backend +@cindex backend +Gnus gets fed articles from a number of backends, both news and mail +backends. Gnus does not handle the underlying media, so to speak---this +is all done by the backends. + +@item native +@cindex native +Gnus will always use one method (and backend) as the @dfn{native}, or +default, way of getting news. + +@item foreign +@cindex foreign +You can also have any number of foreign groups active at the same time. +These are groups that use non-native non-secondary backends for getting +news. + +@item secondary +@cindex secondary +Secondary backends are somewhere half-way between being native and being +foreign, but they mostly act like they are native. + +@item article +@cindex article +A message that has been posted as news. + +@item mail message +@cindex mail message +A message that has been mailed. + +@item message +@cindex message +A mail message or news article + +@item head +@cindex head +The top part of a message, where administrative information (etc.) is +put. + +@item body +@cindex body +The rest of an article. Everything not in the head is in the +body. + +@item header +@cindex header +A line from the head of an article. + +@item headers +@cindex headers +A collection of such lines, or a collection of heads. Or even a +collection of @sc{nov} lines. + +@item @sc{nov} +@cindex nov +When Gnus enters a group, it asks the backend for the headers of all +unread articles in the group. Most servers support the News OverView +format, which is more compact and much faster to read and parse than the +normal @sc{head} format. + +@item level +@cindex levels +Each group is subscribed at some @dfn{level} or other (1-9). The ones +that have a lower level are ``more'' subscribed than the groups with a +higher level. In fact, groups on levels 1-5 are considered +@dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9 +are @dfn{killed}. Commands for listing groups and scanning for new +articles will all use the numeric prefix as @dfn{working level}. + +@item killed groups +@cindex killed groups +No information on killed groups is stored or updated, which makes killed +groups much easier to handle than subscribed groups. + +@item zombie groups +@cindex zombie groups +Just like killed groups, only slightly less dead. + +@item active file +@cindex active file +The news server has to keep track of what articles it carries, and what +groups exist. All this information in stored in the active file, which +is rather large, as you might surmise. + +@item bogus groups +@cindex bogus groups +A group that exists in the @file{.newsrc} file, but isn't known to the +server (i.e., it isn't in the active file), is a @emph{bogus group}. +This means that the group probably doesn't exist (any more). + +@item activating +@cindex activating groups +The act of asking the server for info on a group and computing the +number of unread articles is called @dfn{activating the group}. +Un-activated groups are listed with @samp{*} in the group buffer. + +@item server +@cindex server +A machine one can connect to and get news (or mail) from. + +@item select method +@cindex select method +A structure that specifies the backend, the server and the virtual +server settings. + +@item virtual server +@cindex virtual server +A named select method. Since a select method defines all there is to +know about connecting to a (physical) server, taking the thing as a +whole is a virtual server. + +@item washing +@cindex washing +Taking a buffer and running it through a filter of some sort. The +result will (more often than not) be cleaner and more pleasing than the +original. + +@item ephemeral groups +@cindex ephemeral groups +Most groups store data on what articles you have read. @dfn{Ephemeral} +groups are groups that will have no data stored---when you exit the +group, it'll disappear into the aether. + +@item solid groups +@cindex solid groups +This is the opposite of ephemeral groups. All groups listed in the +group buffer are solid groups. + +@item sparse articles +@cindex sparse articles +These are article placeholders shown in the summary buffer when +@code{gnus-build-sparse-threads} has been switched on. + +@item threading +@cindex threading +To put responses to articles directly after the articles they respond +to---in a hierarchical fashion. + +@item root +@cindex root +@cindex thread root +The first article in a thread is the root. It is the ancestor of all +articles in the thread. + +@item parent +@cindex parent +An article that has responses. + +@item child +@cindex child +An article that responds to a different article---its parent. + +@item digest +@cindex digest +A collection of messages in one file. The most common digest format is +specified by RFC1153. + +@end table + + +@page +@node Customization +@section Customization +@cindex general customization + +All variables are properly documented elsewhere in this manual. This +section is designed to give general pointers on how to customize Gnus +for some quite common situations. + +@menu +* 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. +@end menu + + +@node Slow/Expensive Connection +@subsection Slow/Expensive @sc{nntp} Connection + +If you run Emacs on a machine locally, and get your news from a machine +over some very thin strings, you want to cut down on the amount of data +Gnus has to get from the @sc{nntp} server. + +@table @code + +@item gnus-read-active-file +Set this to @code{nil}, which will inhibit Gnus from requesting the +entire active file from the server. This file is often v. large. You +also have to set @code{gnus-check-new-newsgroups} and +@code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus +doesn't suddenly decide to fetch the active file anyway. + +@item gnus-nov-is-evil +This one has to be @code{nil}. If not, grabbing article headers from +the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers +support @sc{xover}; Gnus will detect this by itself. +@end table + + +@node Slow Terminal Connection +@subsection Slow Terminal Connection + +Let's say you use your home computer for dialing up the system that runs +Emacs and Gnus. If your modem is slow, you want to reduce (as much as +possible) the amount of data sent over the wires. + +@table @code + +@item gnus-auto-center-summary +Set this to @code{nil} to inhibit Gnus from re-centering the summary +buffer all the time. If it is @code{vertical}, do only vertical +re-centering. If it is neither @code{nil} nor @code{vertical}, do both +horizontal and vertical recentering. + +@item gnus-visible-headers +Cut down on the headers included in the articles to the +minimum. You can, in fact, make do without them altogether---most of the +useful data is in the summary buffer, anyway. Set this variable to +@samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need. + +@item gnus-article-display-hook +Set this hook to all the available hiding commands: +@lisp +(setq gnus-article-display-hook + '(gnus-article-hide-headers + gnus-article-hide-signature + gnus-article-hide-citation)) +@end lisp + +@item gnus-use-full-window +By setting this to @code{nil}, you can make all the windows smaller. +While this doesn't really cut down much generally, it means that you +have to see smaller portions of articles before deciding that you didn't +want to read them anyway. + +@item gnus-thread-hide-subtree +If this is non-@code{nil}, all threads in the summary buffer will be +hidden initially. + +@item gnus-updated-mode-lines +If this is @code{nil}, Gnus will not put information in the buffer mode +lines, which might save some time. +@end table + + +@node Little Disk Space +@subsection Little Disk Space +@cindex disk space + +The startup files can get rather large, so you may want to cut their +sizes a bit if you are running out of space. + +@table @code + +@item gnus-save-newsrc-file +If this is @code{nil}, Gnus will never save @file{.newsrc}---it will +only save @file{.newsrc.eld}. This means that you will not be able to +use any other newsreaders than Gnus. This variable is @code{t} by +default. + +@item gnus-save-killed-list +If this is @code{nil}, Gnus will not save the list of dead groups. You +should also set @code{gnus-check-new-newsgroups} to @code{ask-server} +and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this +variable to @code{nil}. This variable is @code{t} by default. + +@end table + + +@node Slow Machine +@subsection Slow Machine +@cindex slow machine + +If you have a slow machine, or are just really impatient, there are a +few things you can do to make Gnus run faster. + +Set @code{gnus-check-new-newsgroups} and +@code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster. + +Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and +@code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the +summary buffer faster. + +Set @code{gnus-article-display-hook} to @code{nil} to make article +processing a bit faster. + + +@page +@node Troubleshooting +@section Troubleshooting +@cindex troubleshooting + +Gnus works @emph{so} well straight out of the box---I can't imagine any +problems, really. + +Ahem. + +@enumerate + +@item +Make sure your computer is switched on. + +@item +Make sure that you really load the current Gnus version. If you have +been running @sc{gnus}, you need to exit Emacs and start it up again before +Gnus will work. + +@item +Try doing an @kbd{M-x gnus-version}. If you get something that looks +like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If, +on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp +flee}, you have some old @file{.el} files lying around. Delete these. + +@item +Read the help group (@kbd{G h} in the group buffer) for a FAQ and a +how-to. + +@item +@vindex max-lisp-eval-depth +Gnus works on many recursive structures, and in some extreme (and very +rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at +you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or +something like that. +@end enumerate + +If all else fails, report the problem as a bug. + +@cindex bugs +@cindex reporting bugs + +@kindex M-x gnus-bug +@findex gnus-bug +If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug} +command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send +me the backtrace. I will fix bugs, but I can only fix them if you send +me a precise description as to how to reproduce the bug. + +You really can never be too detailed in a bug report. Always use the +@kbd{M-x gnus-bug} command when you make bug reports, even if it creates +a 10Kb mail each time you use it, and even if you have sent me your +environment 500 times before. I don't care. I want the full info each +time. + +It is also important to remember that I have no memory whatsoever. If +you send a bug report, and I send you a reply, and then you just send +back ``No, it's not! Moron!'', I will have no idea what you are +insulting me about. Always over-explain everything. It's much easier +for all of us---if I don't have all the information I need, I will just +mail you and ask for more info, and everything takes more time. + +If the problem you're seeing is very visual, and you can't quite explain +it, copy the Emacs window to a file (with @code{xwd}, for instance), put +it somewhere it can be reached, and include the URL of the picture in +the bug report. + +If you just need help, you are better off asking on +@samp{gnu.emacs.gnus}. I'm not very helpful. + +@cindex gnu.emacs.gnus +@cindex ding mailing list +You can also ask on the ding mailing list---@samp{ding@@gnus.org}. +Write to @samp{ding-request@@gnus.org} to subscribe. + + +@page +@node A Programmers Guide to Gnus +@section A Programmer@'s Guide to Gnus + +It is my hope that other people will figure out smart stuff that Gnus +can do, and that other people will write those smart things as well. To +facilitate that I thought it would be a good idea to describe the inner +workings of Gnus. And some of the not-so-inner workings, while I'm at +it. + +You can never expect the internals of a program not to change, but I +will be defining (in some details) the interface between Gnus and its +backends (this is written in stone), the format of the score files +(ditto), data structures (some are less likely to change than others) +and general methods of operation. + +@menu +* Gnus Utility Functions:: Common functions and variable to use. +* Backend 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. +@end menu + + +@node Gnus Utility Functions +@subsection Gnus Utility Functions +@cindex Gnus utility functions +@cindex utility functions +@cindex functions +@cindex internal variables + +When writing small functions to be run from hooks (and stuff), it's +vital to have access to the Gnus internal functions and variables. +Below is a list of the most common ones. + +@table @code + +@item gnus-newsgroup-name +@vindex gnus-newsgroup-name +This variable holds the name of the current newsgroup. + +@item gnus-find-method-for-group +@findex gnus-find-method-for-group +A function that returns the select method for @var{group}. + +@item gnus-group-real-name +@findex gnus-group-real-name +Takes a full (prefixed) Gnus group name, and returns the unprefixed +name. + +@item gnus-group-prefixed-name +@findex gnus-group-prefixed-name +Takes an unprefixed group name and a select method, and returns the full +(prefixed) Gnus group name. + +@item gnus-get-info +@findex gnus-get-info +Returns the group info list for @var{group}. + +@item gnus-group-unread +@findex gnus-group-unread +The number of unread articles in @var{group}, or @code{t} if that is +unknown. + +@item gnus-active +@findex gnus-active +The active entry for @var{group}. + +@item gnus-set-active +@findex gnus-set-active +Set the active entry for @var{group}. + +@item gnus-add-current-to-buffer-list +@findex gnus-add-current-to-buffer-list +Adds the current buffer to the list of buffers to be killed on Gnus +exit. + +@item gnus-continuum-version +@findex gnus-continuum-version +Takes a Gnus version string as a parameter and returns a floating point +number. Earlier versions will always get a lower number than later +versions. + +@item gnus-group-read-only-p +@findex gnus-group-read-only-p +Says whether @var{group} is read-only or not. + +@item gnus-news-group-p +@findex gnus-news-group-p +Says whether @var{group} came from a news backend. + +@item gnus-ephemeral-group-p +@findex gnus-ephemeral-group-p +Says whether @var{group} is ephemeral or not. + +@item gnus-server-to-method +@findex gnus-server-to-method +Returns the select method corresponding to @var{server}. + +@item gnus-server-equal +@findex gnus-server-equal +Says whether two virtual servers are equal. + +@item gnus-group-native-p +@findex gnus-group-native-p +Says whether @var{group} is native or not. + +@item gnus-group-secondary-p +@findex gnus-group-secondary-p +Says whether @var{group} is secondary or not. + +@item gnus-group-foreign-p +@findex gnus-group-foreign-p +Says whether @var{group} is foreign or not. + +@item group-group-find-parameter +@findex group-group-find-parameter +Returns the parameter list of @var{group}. If given a second parameter, +returns the value of that parameter for @var{group}. + +@item gnus-group-set-parameter +@findex gnus-group-set-parameter +Takes three parameters; @var{group}, @var{parameter} and @var{value}. + +@item gnus-narrow-to-body +@findex gnus-narrow-to-body +Narrows the current buffer to the body of the article. + +@item gnus-check-backend-function +@findex gnus-check-backend-function +Takes two parameters, @var{function} and @var{group}. If the backend +@var{group} comes from supports @var{function}, return non-@code{nil}. + +@lisp +(gnus-check-backend-function "request-scan" "nnml:misc") +=> t +@end lisp + +@item gnus-read-method +@findex gnus-read-method +Prompts the user for a select method. + +@end table + + +@node Backend Interface +@subsection Backend Interface + +Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual +groups. It only knows how to talk to @dfn{virtual servers}. A virtual +server is a @dfn{backend} and some @dfn{backend variables}. As examples +of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As +examples of the latter we have @code{nntp-port-number} and +@code{nnmbox-directory}. + +When Gnus asks for information from a backend---say @code{nntp}---on +something, it will normally include a virtual server name in the +function parameters. (If not, the backend should use the ``current'' +virtual server.) For instance, @code{nntp-request-list} takes a virtual +server as its only (optional) parameter. If this virtual server hasn't +been opened, the function should fail. + +Note that a virtual server name has no relation to some physical server +name. Take this example: + +@lisp +(nntp "odd-one" + (nntp-address "ifi.uio.no") + (nntp-port-number 4324)) +@end lisp + +Here the virtual server name is @samp{odd-one} while the name of +the physical server is @samp{ifi.uio.no}. + +The backends should be able to switch between several virtual servers. +The standard backends implement this by keeping an alist of virtual +server environments that they pull down/push up when needed. + +There are two groups of interface functions: @dfn{required functions}, +which must be present, and @dfn{optional functions}, which Gnus will +always check for presence before attempting to call 'em. + +All these functions are expected to return data in the buffer +@code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat +unfortunately named, but we'll have to live with it. When I talk about +@dfn{resulting data}, I always refer to the data in that buffer. When I +talk about @dfn{return value}, I talk about the function value returned by +the function call. Functions that fail should return @code{nil} as the +return value. + +Some backends could be said to be @dfn{server-forming} backends, and +some might be said not to be. The latter are backends that generally +only operate on one group at a time, and have no concept of ``server'' +-- they have a group, and they deliver info on that group and nothing +more. + +In the examples and definitions I will refer to the imaginary backend +@code{nnchoke}. + +@cindex @code{nnchoke} + +@menu +* Required Backend Functions:: Functions that must be implemented. +* Optional Backend Functions:: Functions that need not be implemented. +* Error Messaging:: How to get messages and report errors. +* Writing New Backends:: Extending old backends. +* Hooking New Backends Into Gnus:: What has to be done on the Gnus end. +* Mail-like Backends:: Some tips on mail backends. +@end menu + + +@node Required Backend Functions +@subsubsection Required Backend Functions + +@table @code + +@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD) + +@var{articles} is either a range of article numbers or a list of +@code{Message-ID}s. Current backends do not fully support either---only +sequences (lists) of article numbers, and most backends do not support +retrieval of @code{Message-ID}s. But they should try for both. + +The result data should either be HEADs or NOV lines, and the result +value should either be @code{headers} or @code{nov} to reflect this. +This might later be expanded to @code{various}, which will be a mixture +of HEADs and NOV lines, but this is currently not supported by Gnus. + +If @var{fetch-old} is non-@code{nil} it says to try fetching "extra +headers", in some meaning of the word. This is generally done by +fetching (at most) @var{fetch-old} extra headers less than the smallest +article number in @code{articles}, and filling the gaps as well. The +presence of this parameter can be ignored if the backend finds it +cumbersome to follow the request. If this is non-@code{nil} and not a +number, do maximum fetches. + +Here's an example HEAD: + +@example +221 1056 Article retrieved. +Path: ifi.uio.no!sturles +From: sturles@@ifi.uio.no (Sturle Sunde) +Newsgroups: ifi.discussion +Subject: Re: Something very droll +Date: 27 Oct 1994 14:02:57 +0100 +Organization: Dept. of Informatics, University of Oslo, Norway +Lines: 26 +Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no> +References: <38jdmq$4qu@@visbur.ifi.uio.no> +NNTP-Posting-Host: holmenkollen.ifi.uio.no +. +@end example + +So a @code{headers} return value would imply that there's a number of +these in the data buffer. + +Here's a BNF definition of such a buffer: + +@example +headers = *head +head = error / valid-head +error-message = [ "4" / "5" ] 2number " " eol +valid-head = valid-message *header "." eol +valid-message = "221 " " Article retrieved." eol +header = eol +@end example + +If the return value is @code{nov}, the data buffer should contain +@dfn{network overview database} lines. These are basically fields +separated by tabs. + +@example +nov-buffer = *nov-line +nov-line = 8*9 [ field ] eol +field = +@end example + +For a closer look at what should be in those fields, +@pxref{Headers}. + + +@item (nnchoke-open-server SERVER &optional DEFINITIONS) + +@var{server} is here the virtual server name. @var{definitions} is a +list of @code{(VARIABLE VALUE)} pairs that define this virtual server. + +If the server can't be opened, no error should be signaled. The backend +may then choose to refuse further attempts at connecting to this +server. In fact, it should do so. + +If the server is opened already, this function should return a +non-@code{nil} value. There should be no data returned. + + +@item (nnchoke-close-server &optional SERVER) + +Close connection to @var{server} and free all resources connected +to it. Return @code{nil} if the server couldn't be closed for some +reason. + +There should be no data returned. + + +@item (nnchoke-request-close) + +Close connection to all servers and free all resources that the backend +have reserved. All buffers that have been created by that backend +should be killed. (Not the @code{nntp-server-buffer}, though.) This +function is generally only called when Gnus is shutting down. + +There should be no data returned. + + +@item (nnchoke-server-opened &optional SERVER) + +If @var{server} is the current virtual server, and the connection to the +physical server is alive, then this function should return a +non-@code{nil} vlue. This function should under no circumstances +attempt to reconnect to a server we have lost connection to. + +There should be no data returned. + + +@item (nnchoke-status-message &optional SERVER) + +This function should return the last error message from @var{server}. + +There should be no data returned. + + +@item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER) + +The result data from this function should be the article specified by +@var{article}. This might either be a @code{Message-ID} or a number. +It is optional whether to implement retrieval by @code{Message-ID}, but +it would be nice if that were possible. + +If @var{to-buffer} is non-@code{nil}, the result data should be returned +in this buffer instead of the normal data buffer. This is to make it +possible to avoid copying large amounts of data from one buffer to +another, while Gnus mainly requests articles to be inserted directly +into its article buffer. + +If it is at all possible, this function should return a cons cell where +the @code{car} is the group name the article was fetched from, and the @code{cdr} is +the article number. This will enable Gnus to find out what the real +group and article numbers are when fetching articles by +@code{Message-ID}. If this isn't possible, @code{t} should be returned +on successful article retrieval. + + +@item (nnchoke-request-group GROUP &optional SERVER FAST) + +Get data on @var{group}. This function also has the side effect of +making @var{group} the current group. + +If @var{FAST}, don't bother to return useful data, just make @var{group} +the current group. + +Here's an example of some result data and a definition of the same: + +@example +211 56 1000 1059 ifi.discussion +@end example + +The first number is the status, which should be 211. Next is the +total number of articles in the group, the lowest article number, the +highest article number, and finally the group name. Note that the total +number of articles may be less than one might think while just +considering the highest and lowest article numbers, but some articles +may have been canceled. Gnus just discards the total-number, so +whether one should take the bother to generate it properly (if that is a +problem) is left as an exercise to the reader. + +@example +group-status = [ error / info ] eol +error = [ "4" / "5" ] 2 " " +info = "211 " 3* [ " " ] +@end example + + +@item (nnchoke-close-group GROUP &optional SERVER) + +Close @var{group} and free any resources connected to it. This will be +a no-op on most backends. + +There should be no data returned. + + +@item (nnchoke-request-list &optional SERVER) + +Return a list of all groups available on @var{server}. And that means +@emph{all}. + +Here's an example from a server that only carries two groups: + +@example +ifi.test 0000002200 0000002000 y +ifi.discussion 3324 3300 n +@end example + +On each line we have a group name, then the highest article number in +that group, the lowest article number, and finally a flag. + +@example +active-file = *active-line +active-line = name " " " " " " flags eol +name = +flags = "n" / "y" / "m" / "x" / "j" / "=" name +@end example + +The flag says whether the group is read-only (@samp{n}), is moderated +(@samp{m}), is dead (@samp{x}), is aliased to some other group +(@samp{=other-group}) or none of the above (@samp{y}). + + +@item (nnchoke-request-post &optional SERVER) + +This function should post the current buffer. It might return whether +the posting was successful or not, but that's not required. If, for +instance, the posting is done asynchronously, it has generally not been +completed by the time this function concludes. In that case, this +function should set up some kind of sentinel to beep the user loud and +clear if the posting could not be completed. + +There should be no result data from this function. + +@end table + + +@node Optional Backend Functions +@subsubsection Optional Backend Functions + +@table @code + +@item (nnchoke-retrieve-groups GROUPS &optional SERVER) + +@var{groups} is a list of groups, and this function should request data +on all those groups. How it does it is of no concern to Gnus, but it +should attempt to do this in a speedy fashion. + +The return value of this function can be either @code{active} or +@code{group}, which says what the format of the result data is. The +former is in the same format as the data from +@code{nnchoke-request-list}, while the latter is a buffer full of lines +in the same format as @code{nnchoke-request-group} gives. + +@example +group-buffer = *active-line / *group-status +@end example + + +@item (nnchoke-request-update-info GROUP INFO &optional SERVER) + +A Gnus group info (@pxref{Group Info}) is handed to the backend for +alterations. This comes in handy if the backend really carries all the +information (as is the case with virtual and imap groups). This +function should destructively alter the info to suit its needs, and +should return the (altered) group info. + +There should be no result data from this function. + + +@item (nnchoke-request-type GROUP &optional ARTICLE) + +When the user issues commands for ``sending news'' (@kbd{F} in the +summary buffer, for instance), Gnus has to know whether the article the +user is following up on is news or mail. This function should return +@code{news} if @var{article} in @var{group} is news, @code{mail} if it +is mail and @code{unknown} if the type can't be decided. (The +@var{article} parameter is necessary in @code{nnvirtual} groups which +might very well combine mail groups and news groups.) Both @var{group} +and @var{article} may be @code{nil}. + +There should be no result data from this function. + + +@item (nnchoke-request-update-mark GROUP ARTICLE MARK) + +If the user tries to set a mark that the backend doesn't like, this +function may change the mark. Gnus will use whatever this function +returns as the mark for @var{article} instead of the original +@var{mark}. If the backend doesn't care, it must return the original +@var{mark}, and not @code{nil} or any other type of garbage. + +The only use for this I can see is what @code{nnvirtual} does with +it---if a component group is auto-expirable, marking an article as read +in the virtual group should result in the article being marked as +expirable. + +There should be no result data from this function. + + +@item (nnchoke-request-scan &optional GROUP SERVER) + +This function may be called at any time (by Gnus or anything else) to +request that the backend check for incoming articles, in one way or +another. A mail backend will typically read the spool file or query the +POP server when this function is invoked. The @var{group} doesn't have +to be heeded---if the backend decides that it is too much work just +scanning for a single group, it may do a total scan of all groups. It +would be nice, however, to keep things local if that's practical. + +There should be no result data from this function. + + +@item (nnchoke-request-group-description GROUP &optional SERVER) + +The result data from this function should be a description of +@var{group}. + +@example +description-line = name description eol +name = +description = +@end example + +@item (nnchoke-request-list-newsgroups &optional SERVER) + +The result data from this function should be the description of all +groups available on the server. + +@example +description-buffer = *description-line +@end example + + +@item (nnchoke-request-newgroups DATE &optional SERVER) + +The result data from this function should be all groups that were +created after @samp{date}, which is in normal human-readable date +format. The data should be in the active buffer format. + + +@item (nnchoke-request-create-group GROUP &optional SERVER) + +This function should create an empty group with name @var{group}. + +There should be no return data. + + +@item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE) + +This function should run the expiry process on all articles in the +@var{articles} range (which is currently a simple list of article +numbers.) It is left up to the backend to decide how old articles +should be before they are removed by this function. If @var{force} is +non-@code{nil}, all @var{articles} should be deleted, no matter how new +they are. + +This function should return a list of articles that it did not/was not +able to delete. + +There should be no result data returned. + + +@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM +&optional LAST) + +This function should move @var{article} (which is a number) from +@var{group} by calling @var{accept-form}. + +This function should ready the article in question for moving by +removing any header lines it has added to the article, and generally +should ``tidy up'' the article. Then it should @code{eval} +@var{accept-form} in the buffer where the ``tidy'' article is. This +will do the actual copying. If this @code{eval} returns a +non-@code{nil} value, the article should be removed. + +If @var{last} is @code{nil}, that means that there is a high likelihood +that there will be more requests issued shortly, so that allows some +optimizations. + +The function should return a cons where the @code{car} is the group name and +the @code{cdr} is the article number that the article was entered as. + +There should be no data returned. + + +@item (nnchoke-request-accept-article GROUP &optional SERVER LAST) + +This function takes the current buffer and inserts it into @var{group}. +If @var{last} in @code{nil}, that means that there will be more calls to +this function in short order. + +The function should return a cons where the @code{car} is the group name and +the @code{cdr} is the article number that the article was entered as. + +There should be no data returned. + + +@item (nnchoke-request-replace-article ARTICLE GROUP BUFFER) + +This function should remove @var{article} (which is a number) from +@var{group} and insert @var{buffer} there instead. + +There should be no data returned. + + +@item (nnchoke-request-delete-group GROUP FORCE &optional SERVER) + +This function should delete @var{group}. If @var{force}, it should +really delete all the articles in the group, and then delete the group +itself. (If there is such a thing as ``the group itself''.) + +There should be no data returned. + + +@item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER) + +This function should rename @var{group} into @var{new-name}. All +articles in @var{group} should move to @var{new-name}. + +There should be no data returned. + +@end table + + +@node Error Messaging +@subsubsection Error Messaging + +@findex nnheader-report +@findex nnheader-get-report +The backends should use the function @code{nnheader-report} to report +error conditions---they should not raise errors when they aren't able to +perform a request. The first argument to this function is the backend +symbol, and the rest are interpreted as arguments to @code{format} if +there are multiple of them, or just a string if there is one of them. +This function must always returns @code{nil}. + +@lisp +(nnheader-report 'nnchoke "You did something totally bogus") + +(nnheader-report 'nnchoke "Could not request group %s" group) +@end lisp + +Gnus, in turn, will call @code{nnheader-get-report} when it gets a +@code{nil} back from a server, and this function returns the most +recently reported message for the backend in question. This function +takes one argument---the server symbol. + +Internally, these functions access @var{backend}@code{-status-string}, +so the @code{nnchoke} backend will have its error message stored in +@code{nnchoke-status-string}. + + +@node Writing New Backends +@subsubsection Writing New Backends + +Many backends are quite similar. @code{nnml} is just like +@code{nnspool}, but it allows you to edit the articles on the server. +@code{nnmh} is just like @code{nnml}, but it doesn't use an active file, +and it doesn't maintain overview databases. @code{nndir} is just like +@code{nnml}, but it has no concept of ``groups'', and it doesn't allow +editing articles. + +It would make sense if it were possible to ``inherit'' functions from +backends when writing new backends. And, indeed, you can do that if you +want to. (You don't have to if you don't want to, of course.) + +All the backends declare their public variables and functions by using a +package called @code{nnoo}. + +To inherit functions from other backends (and allow other backends to +inherit functions from the current backend), you should use the +following macros: + +@table @code + +@item nnoo-declare +This macro declares the first parameter to be a child of the subsequent +parameters. For instance: + +@lisp +(nnoo-declare nndir + nnml nnmh) +@end lisp + +@code{nndir} has declared here that it intends to inherit functions from +both @code{nnml} and @code{nnmh}. + +@item defvoo +This macro is equivalent to @code{defvar}, but registers the variable as +a public server variable. Most state-oriented variables should be +declared with @code{defvoo} instead of @code{defvar}. + +In addition to the normal @code{defvar} parameters, it takes a list of +variables in the parent backends to map the variable to when executing +a function in those backends. + +@lisp +(defvoo nndir-directory nil + "Where nndir will look for groups." + nnml-current-directory nnmh-current-directory) +@end lisp + +This means that @code{nnml-current-directory} will be set to +@code{nndir-directory} when an @code{nnml} function is called on behalf +of @code{nndir}. (The same with @code{nnmh}.) + +@item nnoo-define-basics +This macro defines some common functions that almost all backends should +have. + +@example +(nnoo-define-basics nndir) +@end example + +@item deffoo +This macro is just like @code{defun} and takes the same parameters. In +addition to doing the normal @code{defun} things, it registers the +function as being public so that other backends can inherit it. + +@item nnoo-map-functions +This macro allows mapping of functions from the current backend to +functions from the parent backends. + +@example +(nnoo-map-functions nndir + (nnml-retrieve-headers 0 nndir-current-group 0 0) + (nnmh-request-article 0 nndir-current-group 0 0)) +@end example + +This means that when @code{nndir-retrieve-headers} is called, the first, +third, and fourth parameters will be passed on to +@code{nnml-retrieve-headers}, while the second parameter is set to the +value of @code{nndir-current-group}. + +@item nnoo-import +This macro allows importing functions from backends. It should be the +last thing in the source file, since it will only define functions that +haven't already been defined. + +@example +(nnoo-import nndir + (nnmh + nnmh-request-list + nnmh-request-newgroups) + (nnml)) +@end example + +This means that calls to @code{nndir-request-list} should just be passed +on to @code{nnmh-request-list}, while all public functions from +@code{nnml} that haven't been defined in @code{nndir} yet should be +defined now. + +@end table + +Below is a slightly shortened version of the @code{nndir} backend. + +@lisp +;;; nndir.el --- single directory newsgroup access for Gnus +;; Copyright (C) 1995,96 Free Software Foundation, Inc. + +;;; Code: + +(require 'nnheader) +(require 'nnmh) +(require 'nnml) +(require 'nnoo) +(eval-when-compile (require 'cl)) + +(nnoo-declare nndir + nnml nnmh) + +(defvoo nndir-directory nil + "Where nndir will look for groups." + nnml-current-directory nnmh-current-directory) + +(defvoo nndir-nov-is-evil nil + "*Non-nil means that nndir will never retrieve NOV headers." + nnml-nov-is-evil) + +(defvoo nndir-current-group "" nil nnml-current-group nnmh-current-group) +(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory) +(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail) + +(defvoo nndir-status-string "" nil nnmh-status-string) +(defconst nndir-version "nndir 1.0") + +;;; Interface functions. + +(nnoo-define-basics nndir) + +(deffoo nndir-open-server (server &optional defs) + (setq nndir-directory + (or (cadr (assq 'nndir-directory defs)) + server)) + (unless (assq 'nndir-directory defs) + (push `(nndir-directory ,server) defs)) + (push `(nndir-current-group + ,(file-name-nondirectory (directory-file-name nndir-directory))) + defs) + (push `(nndir-top-directory + ,(file-name-directory (directory-file-name nndir-directory))) + defs) + (nnoo-change-server 'nndir server defs)) + +(nnoo-map-functions nndir + (nnml-retrieve-headers 0 nndir-current-group 0 0) + (nnmh-request-article 0 nndir-current-group 0 0) + (nnmh-request-group nndir-current-group 0 0) + (nnmh-close-group nndir-current-group 0)) + +(nnoo-import nndir + (nnmh + nnmh-status-message + nnmh-request-list + nnmh-request-newgroups)) + +(provide 'nndir) +@end lisp + + +@node Hooking New Backends Into Gnus +@subsubsection Hooking New Backends Into Gnus + +@vindex gnus-valid-select-methods +Having Gnus start using your new backend is rather easy---you just +declare it with the @code{gnus-declare-backend} functions. This will +enter the backend into the @code{gnus-valid-select-methods} variable. + +@code{gnus-declare-backend} takes two parameters---the backend name and +an arbitrary number of @dfn{abilities}. + +Here's an example: + +@lisp +(gnus-declare-backend "nnchoke" 'mail 'respool 'address) +@end lisp + +The abilities can be: + +@table @code +@item mail +This is a mailish backend---followups should (probably) go via mail. +@item post +This is a newsish backend---followups should (probably) go via news. +@item post-mail +This backend supports both mail and news. +@item none +This is neither a post nor mail backend---it's something completely +different. +@item respool +It supports respooling---or rather, it is able to modify its source +articles and groups. +@item address +The name of the server should be in the virtual server name. This is +true for almost all backends. +@item prompt-address +The user should be prompted for an address when doing commands like +@kbd{B} in the group buffer. This is true for backends like +@code{nntp}, but not @code{nnmbox}, for instance. +@end table + + +@node Mail-like Backends +@subsubsection Mail-like Backends + +One of the things that separate the mail backends from the rest of the +backends is the heavy dependence by the mail backends on common +functions in @file{nnmail.el}. For instance, here's the definition of +@code{nnml-request-scan}: + +@lisp +(deffoo nnml-request-scan (&optional group server) + (setq nnml-article-file-alist nil) + (nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group)) +@end lisp + +It simply calls @code{nnmail-get-new-mail} with a few parameters, +and @code{nnmail} takes care of all the moving and splitting of the +mail. + +This function takes four parameters. + +@table @var +@item method +This should be a symbol to designate which backend is responsible for +the call. + +@item exit-function +This function should be called after the splitting has been performed. + +@item temp-directory +Where the temporary files should be stored. + +@item group +This optional argument should be a group name if the splitting is to be +performed for one group only. +@end table + +@code{nnmail-get-new-mail} will call @var{backend}@code{-save-mail} to +save each article. @var{backend}@code{-active-number} will be called to +find the article number assigned to this article. + +The function also uses the following variables: +@var{backend}@code{-get-new-mail} (to see whether to get new mail for +this backend); and @var{backend}@code{-group-alist} and +@var{backend}@code{-active-file} to generate the new active file. +@var{backend}@code{-group-alist} should be a group-active alist, like +this: + +@example +(("a-group" (1 . 10)) + ("some-group" (34 . 39))) +@end example + + +@node Score File Syntax +@subsection Score File Syntax + +Score files are meant to be easily parseable, but yet extremely +mallable. It was decided that something that had the same read syntax +as an Emacs Lisp list would fit that spec. + +Here's a typical score file: + +@lisp +(("summary" + ("win95" -10000 nil s) + ("Gnus")) + ("from" + ("Lars" -1000)) + (mark -100)) +@end lisp + +BNF definition of a score file: + +@example +score-file = "" / "(" *element ")" +element = rule / atom +rule = string-rule / number-rule / date-rule +string-rule = "(" quote string-header quote space *string-match ")" +number-rule = "(" quote number-header quote space *number-match ")" +date-rule = "(" quote date-header quote space *date-match ")" +quote = +string-header = "subject" / "from" / "references" / "message-id" / + "xref" / "body" / "head" / "all" / "followup" +number-header = "lines" / "chars" +date-header = "date" +string-match = "(" quote quote [ "" / [ space score [ "" / + space date [ "" / [ space string-match-t ] ] ] ] ] ")" +score = "nil" / +date = "nil" / +string-match-t = "nil" / "s" / "substring" / "S" / "Substring" / + "r" / "regex" / "R" / "Regex" / + "e" / "exact" / "E" / "Exact" / + "f" / "fuzzy" / "F" / "Fuzzy" +number-match = "(" [ "" / [ space score [ "" / + space date [ "" / [ space number-match-t ] ] ] ] ] ")" +number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<=" +date-match = "(" quote quote [ "" / [ space score [ "" / + space date [ "" / [ space date-match-t ] ] ] ] ")" +date-match-t = "nil" / "at" / "before" / "after" +atom = "(" [ required-atom / optional-atom ] ")" +required-atom = mark / expunge / mark-and-expunge / files / + exclude-files / read-only / touched +optional-atom = adapt / local / eval +mark = "mark" space nil-or-number +nil-or-number = "nil" / +expunge = "expunge" space nil-or-number +mark-and-expunge = "mark-and-expunge" space nil-or-number +files = "files" *[ space ] +exclude-files = "exclude-files" *[ space ] +read-only = "read-only" [ space "nil" / space "t" ] +adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ] +adapt-rule = "(" *[ *[ "(" ")" ] ")" +local = "local" *[ space "(" space
")" ] +eval = "eval" space +space = *[ " " / / ] +@end example + +Any unrecognized elements in a score file should be ignored, but not +discarded. + +As you can see, white space is needed, but the type and amount of white +space is irrelevant. This means that formatting of the score file is +left up to the programmer---if it's simpler to just spew it all out on +one looong line, then that's ok. + +The meaning of the various atoms are explained elsewhere in this +manual (@pxref{Score File Format}). + + +@node Headers +@subsection Headers + +Internally Gnus uses a format for storing article headers that +corresponds to the @sc{nov} format in a mysterious fashion. One could +almost suspect that the author looked at the @sc{nov} specification and +just shamelessly @emph{stole} the entire thing, and one would be right. + +@dfn{Header} is a severely overloaded term. ``Header'' is used in +RFC1036 to talk about lines in the head of an article (e.g., +@code{From}). It is used by many people as a synonym for +``head''---``the header and the body''. (That should be avoided, in my +opinion.) And Gnus uses a format internally that it calls ``header'', +which is what I'm talking about here. This is a 9-element vector, +basically, with each header (ouch) having one slot. + +These slots are, in order: @code{number}, @code{subject}, @code{from}, +@code{date}, @code{id}, @code{references}, @code{chars}, @code{lines}, +@code{xref}. There are macros for accessing and setting these +slots---they all have predictable names beginning with +@code{mail-header-} and @code{mail-header-set-}, respectively. + +The @code{xref} slot is really a @code{misc} slot. Any extra info will +be put in there. + + +@node Ranges +@subsection Ranges + +@sc{gnus} introduced a concept that I found so useful that I've started +using it a lot and have elaborated on it greatly. + +The question is simple: If you have a large amount of objects that are +identified by numbers (say, articles, to take a @emph{wild} example) +that you want to qualify as being ``included'', a normal sequence isn't +very useful. (A 200,000 length sequence is a bit long-winded.) + +The solution is as simple as the question: You just collapse the +sequence. + +@example +(1 2 3 4 5 6 10 11 12) +@end example + +is transformed into + +@example +((1 . 6) (10 . 12)) +@end example + +To avoid having those nasty @samp{(13 . 13)} elements to denote a +lonesome object, a @samp{13} is a valid element: + +@example +((1 . 6) 7 (10 . 12)) +@end example + +This means that comparing two ranges to find out whether they are equal +is slightly tricky: + +@example +((1 . 5) 7 8 (10 . 12)) +@end example + +and + +@example +((1 . 5) (7 . 8) (10 . 12)) +@end example + +are equal. In fact, any non-descending list is a range: + +@example +(1 2 3 4 5) +@end example + +is a perfectly valid range, although a pretty long-winded one. This is +also valid: + +@example +(1 . 5) +@end example + +and is equal to the previous range. + +Here's a BNF definition of ranges. Of course, one must remember the +semantic requirement that the numbers are non-descending. (Any number +of repetition of the same number is allowed, but apt to disappear in +range handling.) + +@example +range = simple-range / normal-range +simple-range = "(" number " . " number ")" +normal-range = "(" start-contents ")" +contents = "" / simple-range *[ " " contents ] / + number *[ " " contents ] +@end example + +Gnus currently uses ranges to keep track of read articles and article +marks. I plan on implementing a number of range operators in C if The +Powers That Be are willing to let me. (I haven't asked yet, because I +need to do some more thinking on what operators I need to make life +totally range-based without ever having to convert back to normal +sequences.) + + +@node Group Info +@subsection Group Info + +Gnus stores all permanent info on groups in a @dfn{group info} list. +This list is from three to six elements (or more) long and exhaustively +describes the group. + +Here are two example group infos; one is a very simple group while the +second is a more complex one: + +@example +("no.group" 5 (1 . 54324)) + +("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55)) + ((tick (15 . 19)) (replied 3 6 (19 . 3))) + (nnml "") + ((auto-expire . t) (to-address . "ding@@gnus.org"))) +@end example + +The first element is the @dfn{group name}---as Gnus knows the group, +anyway. The second element is the @dfn{subscription level}, which +normally is a small integer. (It can also be the @dfn{rank}, which is a +cons cell where the @code{car} is the level and the @code{cdr} is the +score.) The third element is a list of ranges of read articles. The +fourth element is a list of lists of article marks of various kinds. +The fifth element is the select method (or virtual server, if you like). +The sixth element is a list of @dfn{group parameters}, which is what +this section is about. + +Any of the last three elements may be missing if they are not required. +In fact, the vast majority of groups will normally only have the first +three elements, which saves quite a lot of cons cells. + +Here's a BNF definition of the group info format: + +@example +info = "(" group space ralevel space read + [ "" / [ space marks-list [ "" / [ space method [ "" / + space parameters ] ] ] ] ] ")" +group = quote quote +ralevel = rank / level +level = +rank = "(" level "." score ")" +score = +read = range +marks-lists = nil / "(" *marks ")" +marks = "(" range ")" +method = "(" *elisp-forms ")" +parameters = "(" *elisp-forms ")" +@end example + +Actually that @samp{marks} rule is a fib. A @samp{marks} is a +@samp{} consed on to a @samp{range}, but that's a bitch to say +in pseudo-BNF. + +If you have a Gnus info and want to access the elements, Gnus offers a +series of macros for getting/setting these elements. + +@table @code +@item gnus-info-group +@itemx gnus-info-set-group +@findex gnus-info-group +@findex gnus-info-set-group +Get/set the group name. + +@item gnus-info-rank +@itemx gnus-info-set-rank +@findex gnus-info-rank +@findex gnus-info-set-rank +Get/set the group rank (@pxref{Group Score}). + +@item gnus-info-level +@itemx gnus-info-set-level +@findex gnus-info-level +@findex gnus-info-set-level +Get/set the group level. + +@item gnus-info-score +@itemx gnus-info-set-score +@findex gnus-info-score +@findex gnus-info-set-score +Get/set the group score (@pxref{Group Score}). + +@item gnus-info-read +@itemx gnus-info-set-read +@findex gnus-info-read +@findex gnus-info-set-read +Get/set the ranges of read articles. + +@item gnus-info-marks +@itemx gnus-info-set-marks +@findex gnus-info-marks +@findex gnus-info-set-marks +Get/set the lists of ranges of marked articles. + +@item gnus-info-method +@itemx gnus-info-set-method +@findex gnus-info-method +@findex gnus-info-set-method +Get/set the group select method. + +@item gnus-info-params +@itemx gnus-info-set-params +@findex gnus-info-params +@findex gnus-info-set-params +Get/set the group parameters. +@end table + +All the getter functions take one parameter---the info list. The setter +functions take two parameters---the info list and the new value. + +The last three elements in the group info aren't mandatory, so it may be +necessary to extend the group info before setting the element. If this +is necessary, you can just pass on a non-@code{nil} third parameter to +the three final setter functions to have this happen automatically. + + +@node Extended Interactive +@subsection Extended Interactive +@cindex interactive +@findex gnus-interactive + +Gnus extends the standard Emacs @code{interactive} specification +slightly to allow easy use of the symbolic prefix (@pxref{Symbolic +Prefixes}). Here's an example of how this is used: + +@lisp +(defun gnus-summary-increase-score (&optional score symp) + (interactive (gnus-interactive "P\ny")) + ... + ) +@end lisp + +The best thing to do would have been to implement +@code{gnus-interactive} as a macro which would have returned an +@code{interactive} form, but this isn't possible since Emacs checks +whether a function is interactive or not by simply doing an @code{assq} +on the lambda form. So, instead we have @code{gnus-interactive} +function that takes a string and returns values that are usable to +@code{interactive}. + +This function accepts (almost) all normal @code{interactive} specs, but +adds a few more. + +@table @samp +@item y +@vindex gnus-current-prefix-symbol +The current symbolic prefix---the @code{gnus-current-prefix-symbol} +variable. + +@item Y +@vindex gnus-current-prefix-symbols +A list of the current symbolic prefixes---the +@code{gnus-current-prefix-symbol} variable. + +@item A +The current article number---the @code{gnus-summary-article-number} +function. + +@item H +The current article header---the @code{gnus-summary-article-header} +function. + +@item g +The current group name---the @code{gnus-group-group-name} +function. + +@end table + + +@node Emacs/XEmacs Code +@subsection Emacs/XEmacs Code +@cindex XEmacs +@cindex Emacsen + +While Gnus runs under Emacs, XEmacs and Mule, I decided that one of the +platforms must be the primary one. I chose Emacs. Not because I don't +like XEmacs or Mule, but because it comes first alphabetically. + +This means that Gnus will byte-compile under Emacs with nary a warning, +while XEmacs will pump out gigabytes of warnings while byte-compiling. +As I use byte-compilation warnings to help me root out trivial errors in +Gnus, that's very useful. + +I've also consistently used Emacs function interfaces, but have used +Gnusey aliases for the functions. To take an example: Emacs defines a +@code{run-at-time} function while XEmacs defines a @code{start-itimer} +function. I then define a function called @code{gnus-run-at-time} that +takes the same parameters as the Emacs @code{run-at-time}. When running +Gnus under Emacs, the former function is just an alias for the latter. +However, when running under XEmacs, the former is an alias for the +following function: + +@lisp +(defun gnus-xmas-run-at-time (time repeat function &rest args) + (start-itimer + "gnus-run-at-time" + `(lambda () + (,function ,@@args)) + time repeat)) +@end lisp + +This sort of thing has been done for bunches of functions. Gnus does +not redefine any native Emacs functions while running under XEmacs---it +does this @code{defalias} thing with Gnus equivalents instead. Cleaner +all over. + +In the cases where the XEmacs function interface was obviously cleaner, +I used it instead. For example @code{gnus-region-active-p} is an alias +for @code{region-active-p} in XEmacs, whereas in Emacs it is a function. + +Of course, I could have chosen XEmacs as my native platform and done +mapping functions the other way around. But I didn't. The performance +hit these indirections impose on Gnus under XEmacs should be slight. + + +@node Various File Formats +@subsection Various File Formats + +@menu +* Active File Format:: Information on articles and groups available. +* Newsgroups File Format:: Group descriptions. +@end menu + + +@node Active File Format +@subsubsection Active File Format + +The active file lists all groups available on the server in +question. It also lists the highest and lowest current article numbers +in each group. + +Here's an excerpt from a typical active file: + +@example +soc.motss 296030 293865 y +alt.binaries.pictures.fractals 3922 3913 n +comp.sources.unix 1605 1593 m +comp.binaries.ibm.pc 5097 5089 y +no.general 1000 900 y +@end example + +Here's a pseudo-BNF definition of this file: + +@example +active = *group-line +group-line = group space high-number space low-number space flag +group = +space = " " +high-number = +low-number = +flag = "y" / "n" / "m" / "j" / "x" / "=" group +@end example + +For a full description of this file, see the manual pages for +@samp{innd}, in particular @samp{active(5)}. + + +@node Newsgroups File Format +@subsubsection Newsgroups File Format + +The newsgroups file lists groups along with their descriptions. Not all +groups on the server have to be listed, and not all groups in the file +have to exist on the server. The file is meant purely as information to +the user. + +The format is quite simple; a group name, a tab, and the description. +Here's the definition: + +@example +newsgroups = *line +line = group tab description +group = +tab = +description = +@end example + + +@page +@node Emacs for Heathens +@section Emacs for Heathens + +Believe it or not, but some people who use Gnus haven't really used +Emacs much before they embarked on their journey on the Gnus Love Boat. +If you are one of those unfortunates whom ``@kbd{M-C-a}'', ``kill the +region'', and ``set @code{gnus-flargblossen} to an alist where the key +is a regexp that is used for matching on the group name'' are magical +phrases with little or no meaning, then this appendix is for you. If +you are already familiar with Emacs, just ignore this and go fondle your +cat instead. + +@menu +* Keystrokes:: Entering text and executing commands. +* Emacs Lisp:: The built-in Emacs programming language. +@end menu + + +@node Keystrokes +@subsection Keystrokes + +@itemize @bullet +@item +Q: What is an experienced Emacs user? + +@item +A: A person who wishes that the terminal had pedals. +@end itemize + +Yes, when you use Emacs, you are apt to use the control key, the shift +key and the meta key a lot. This is very annoying to some people +(notably @code{vi}le users), and the rest of us just love the hell out +of it. Just give up and submit. Emacs really does stand for +``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you +may have heard from other disreputable sources (like the Emacs author). + +The shift keys are normally located near your pinky fingers, and are +normally used to get capital letters and stuff. You probably use it all +the time. The control key is normally marked ``CTRL'' or something like +that. The meta key is, funnily enough, never marked as such on any +keyboard. The one I'm currently at has a key that's marked ``Alt'', +which is the meta key on this keyboard. It's usually located somewhere +to the left hand side of the keyboard, usually on the bottom row. + +Now, us Emacs people don't say ``press the meta-control-m key'', +because that's just too inconvenient. We say ``press the @kbd{M-C-m} +key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the +prefix that means ``control''. So ``press @kbd{C-k}'' means ``press +down the control key, and hold it down while you press @kbd{k}''. +``Press @kbd{M-C-k}'' means ``press down and hold down the meta key and +the control key and then press @kbd{k}''. Simple, ay? + +This is somewhat complicated by the fact that not all keyboards have a +meta key. In that case you can use the ``escape'' key. Then @kbd{M-k} +means ``press escape, release escape, press @kbd{k}''. That's much more +work than if you have a meta key, so if that's the case, I respectfully +suggest you get a real keyboard with a meta key. You can't live without +it. + + + +@node Emacs Lisp +@subsection Emacs Lisp + +Emacs is the King of Editors because it's really a Lisp interpreter. +Each and every key you tap runs some Emacs Lisp code snippet, and since +Emacs Lisp is an interpreted language, that means that you can configure +any key to run any arbitrary code. You just, like, do it. + +Gnus is written in Emacs Lisp, and is run as a bunch of interpreted +functions. (These are byte-compiled for speed, but it's still +interpreted.) If you decide that you don't like the way Gnus does +certain things, it's trivial to have it do something a different way. +(Well, at least if you know how to write Lisp code.) However, that's +beyond the scope of this manual, so we are simply going to talk about +some common constructs that you normally use in your @file{.emacs} file +to customize Gnus. + +If you want to set the variable @code{gnus-florgbnize} to four (4), you +write the following: + +@lisp +(setq gnus-florgbnize 4) +@end lisp + +This function (really ``special form'') @code{setq} is the one that can +set a variable to some value. This is really all you need to know. Now +you can go and fill your @code{.emacs} file with lots of these to change +how Gnus works. + +If you have put that thing in your @code{.emacs} file, it will be read +and @code{eval}ed (which is lisp-ese for ``run'') the next time you +start Emacs. If you want to change the variable right away, simply say +@kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the +previous ``form'', which is a simple @code{setq} statement here. + +Go ahead---just try it, if you're located at your Emacs. After you +@kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which +is the return value of the form you @code{eval}ed. + +Some pitfalls: + +If the manual says ``set @code{gnus-read-active-file} to @code{some}'', +that means: + +@lisp +(setq gnus-read-active-file 'some) +@end lisp + +On the other hand, if the manual says ``set @code{gnus-nntp-server} to +@samp{nntp.ifi.uio.no}'', that means: + +@lisp +(setq gnus-nntp-server "nntp.ifi.uio.no") +@end lisp + +So be careful not to mix up strings (the latter) with symbols (the +former). The manual is unambiguous, but it can be confusing. + +@page +@include gnus-faq.texi + +@node Index +@chapter Index +@printindex cp + +@node Key Index +@chapter Key Index +@printindex ky + +@summarycontents +@contents +@bye + +@iftex +@iflatex +\end{document} +@end iflatex +@end iftex + +@c End: + diff --git a/texi/message.texi b/texi/message.texi new file mode 100644 index 0000000..ec14254 --- /dev/null +++ b/texi/message.texi @@ -0,0 +1,1340 @@ +\input texinfo @c -*-texinfo-*- + +@setfilename message +@settitle Pterodactyl Message 0.32 Manual +@synindex fn cp +@synindex vr cp +@synindex pg cp +@c @direntry +@c * Message: (message). Mail and news composition mode that goes with Gnus. +@c @end direntry +@iftex +@finalout +@end iftex +@setchapternewpage odd + +@ifinfo + +This file documents Message, the Emacs message composition mode. + +Copyright (C) 1996,97,98 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@tex + +@titlepage +@title Pterodactyl Message 0.32 Manual + +@author by Lars Magne Ingebrigtsen +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1996 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. + +@end titlepage +@page + +@end tex + +@node Top +@top Message + +All message composition from Gnus (both mail and news) takes place in +Message mode buffers. + +@menu +* Interface:: Setting up message buffers. +* Commands:: Commands you can execute in message mode buffers. +* Variables:: Customizing the message buffers. +* Compatibility:: Making Message backwards compatible. +* Appendices:: More technical things. +* Index:: Variable, function and concept index. +* Key Index:: List of Message mode keys. +@end menu + +This manual corresponds to Pterodactyl Message 0.32. Message is +distributed with the Gnus distribution bearing the same version number +as this manual. + + +@node Interface +@chapter Interface + +When a program (or a person) wants to respond to a message -- reply, +follow up, forward, cancel -- the program (or person) should just put +point in the buffer where the message is and call the required command. +@code{Message} will then pop up a new @code{message} mode buffer with +appropriate headers filled out, and the user can edit the message before +sending it. + +@menu +* New Mail Message:: Editing a brand new mail message. +* New News Message:: Editing a brand new news message. +* Reply:: Replying via mail. +* Wide Reply:: Responding to all people via mail. +* Followup:: Following up via news. +* Canceling News:: Canceling a news article. +* Superseding:: Superseding a message. +* Forwarding:: Forwarding a message via news or mail. +* Resending:: Resending a mail message. +* Bouncing:: Bouncing a mail message. +@end menu + + +@node New Mail Message +@section New Mail Message + +@findex message-mail +The @code{message-mail} command pops up a new message buffer. + +Two optional parameters are accepted: The first will be used as the +@code{To} header and the second as the @code{Subject} header. If these +are @code{nil}, those two headers will be empty. + + +@node New News Message +@section New News Message + +@findex message-news +The @code{message-news} command pops up a new message buffer. + +This function accepts two optional parameters. The first will be used +as the @code{Newsgroups} header and the second as the @code{Subject} +header. If these are @code{nil}, those two headers will be empty. + + +@node Reply +@section Reply + +@findex message-reply +The @code{message-reply} function pops up a message buffer that's a +reply to the message in the current buffer. + +@vindex message-reply-to-function +Message uses the normal methods to determine where replies are to go +(@pxref{Responses}), but you can change the behavior to suit your needs +by fiddling with the @code{message-reply-to-function} variable. + +If you want the replies to go to the @code{Sender} instead of the +@code{From}, you could do something like this: + +@lisp +(setq message-reply-to-function + (lambda () + (cond ((equal (mail-fetch-field "from") "somebody") + (mail-fetch-field "sender")) + (t + nil)))) +@end lisp + +This function will be called narrowed to the head of the article that is +being replied to. + +As you can see, this function should return a string if it has an +opinion as to what the To header should be. If it does not, it should +just return @code{nil}, and the normal methods for determining the To +header will be used. + +This function can also return a list. In that case, each list element +should be a cons, where the car should be the name of an header +(eg. @code{Cc}) and the cdr should be the header value +(eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into +the head of the outgoing mail. + + +@node Wide Reply +@section Wide Reply + +@findex message-wide-reply +The @code{message-wide-reply} pops up a message buffer that's a wide +reply to the message in the current buffer. A @dfn{wide reply} is a +reply that goes out to all people listed in the @code{To}, @code{From} +(or @code{Reply-to}) and @code{Cc} headers. + +@vindex message-wide-reply-to-function +Message uses the normal methods to determine where wide replies are to go, +but you can change the behavior to suit your needs by fiddling with the +@code{message-wide-reply-to-function}. It is used in the same way as +@code{message-reply-to-function} (@pxref{Reply}). + +@findex rmail-dont-reply-to-names +Addresses that match the @code{rmail-dont-reply-to-names} regular +expression will be removed from the @code{Cc} header. + + +@node Followup +@section Followup + +@findex message-followup +The @code{message-followup} command pops up a message buffer that's a +followup to the message in the current buffer. + +@vindex message-followup-to-function +Message uses the normal methods to determine where followups are to go, +but you can change the behavior to suit your needs by fiddling with the +@code{message-followup-to-function}. It is used in the same way as +@code{message-reply-to-function} (@pxref{Reply}). + +@vindex message-use-followup-to +The @code{message-use-followup-to} variable says what to do about +@code{Followup-To} headers. If it is @code{use}, always use the value. +If it is @code{ask} (which is the default), ask whether to use the +value. If it is @code{t}, use the value unless it is @samp{poster}. If +it is @code{nil}, don't use the value. + + +@node Canceling News +@section Canceling News + +@findex message-cancel-news +The @code{message-cancel-news} command cancels the article in the +current buffer. + + +@node Superseding +@section Superseding + +@findex message-supersede +The @code{message-supersede} command pops up a message buffer that will +supersede the message in the current buffer. + +@vindex message-ignored-supersedes-headers +Headers matching the @code{message-ignored-supersedes-headers} are +removed before popping up the new message buffer. The default is@* +@samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|@* +^Received:\\|^X-From-Line:\\|Return-Path:\\|^Supersedes:}. + + + +@node Forwarding +@section Forwarding + +@findex message-forward +The @code{message-forward} command pops up a message buffer to forward +the message in the current buffer. If given a prefix, forward using +news. + +@table @code +@item message-forward-start-separator +@vindex message-forward-start-separator +Delimiter inserted before forwarded messages. The default is@* +@samp{------- Start of forwarded message -------\n}. + +@vindex message-forward-end-separator +@item message-forward-end-separator +@vindex message-forward-end-separator +Delimiter inserted after forwarded messages. The default is@* +@samp{------- End of forwarded message -------\n}. + +@item message-signature-before-forwarded-message +@vindex message-signature-before-forwarded-message +If this variable is @code{t}, which it is by default, your personal +signature will be inserted before the forwarded message. If not, the +forwarded message will be inserted first in the new mail. + +@item message-included-forward-headers +@vindex message-included-forward-headers +Regexp matching header lines to be included in forwarded messages. + +@item message-make-forward-subject-function +@vindex message-make-forward-subject-function +A list of functions that are called to generate a subject header for +forwarded messages. The subject generated by the previous function is +passed into each successive function. + +The provided functions are: + +@table @code +@item message-forward-subject-author-subject +@findex message-forward-subject-author-subject +Source of article (author or newsgroup), in brackets followed by the +subject. + +@item message-forward-subject-fwd +Subject of article with @samp{Fwd:} prepended to it. +@end table + +@item message-wash-forwarded-subjects +@vindex message-wash-forwarded-subjects +If this variable is @code{t}, the subjects of forwarded messages have +the evidence of previous forwards (such as @samp{Fwd:}, @samp{Re:}, +@samp{(fwd)}) removed before the new subject is +constructed. The default value is @code{nil}. + +@end table + + +@node Resending +@section Resending + +@findex message-resend +The @code{message-resend} command will prompt the user for an address +and resend the message in the current buffer to that address. + +@vindex message-ignored-resent-headers +Headers that match the @code{message-ignored-resent-headers} regexp will +be removed before sending the message. The default is +@samp{^Return-receipt}. + + +@node Bouncing +@section Bouncing + +@findex message-bounce +The @code{message-bounce} command will, if the current buffer contains a +bounced mail message, pop up a message buffer stripped of the bounce +information. A @dfn{bounced message} is typically a mail you've sent +out that has been returned by some @code{mailer-daemon} as +undeliverable. + +@vindex message-ignored-bounced-headers +Headers that match the @code{message-ignored-bounced-headers} regexp +will be removed before popping up the buffer. The default is +@samp{^\\(Received\\|Return-Path\\):}. + + +@node Commands +@chapter Commands + +@menu +* Header Commands:: Commands for moving to headers. +* Movement:: Moving around in message buffers. +* Insertion:: Inserting things into message buffers. +* Various Commands:: Various things. +* Sending:: Actually sending the message. +* Mail Aliases:: How to use mail aliases. +@end menu + + +@node Header Commands +@section Header Commands + +All these commands move to the header in question. If it doesn't exist, +it will be inserted. + +@table @kbd + +@item C-c ? +@kindex C-c ? +@findex message-goto-to +Describe the message mode. + +@item C-c C-f C-t +@kindex C-c C-f C-t +@findex message-goto-to +Go to the @code{To} header (@code{message-goto-to}). + +@item C-c C-f C-b +@kindex C-c C-f C-b +@findex message-goto-bcc +Go to the @code{Bcc} header (@code{message-goto-bcc}). + +@item C-c C-f C-f +@kindex C-c C-f C-f +@findex message-goto-fcc +Go to the @code{Fcc} header (@code{message-goto-fcc}). + +@item C-c C-f C-c +@kindex C-c C-f C-c +@findex message-goto-cc +Go to the @code{Cc} header (@code{message-goto-cc}). + +@item C-c C-f C-s +@kindex C-c C-f C-s +@findex message-goto-subject +Go to the @code{Subject} header (@code{message-goto-subject}). + +@item C-c C-f C-r +@kindex C-c C-f C-r +@findex message-goto-reply-to +Go to the @code{Reply-To} header (@code{message-goto-reply-to}). + +@item C-c C-f C-n +@kindex C-c C-f C-n +@findex message-goto-newsgroups +Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}). + +@item C-c C-f C-d +@kindex C-c C-f C-d +@findex message-goto-distribution +Go to the @code{Distribution} header (@code{message-goto-distribution}). + +@item C-c C-f C-o +@kindex C-c C-f C-o +@findex message-goto-followup-to +Go to the @code{Followup-To} header (@code{message-goto-followup-to}). + +@item C-c C-f C-k +@kindex C-c C-f C-k +@findex message-goto-keywords +Go to the @code{Keywords} header (@code{message-goto-keywords}). + +@item C-c C-f C-u +@kindex C-c C-f C-u +@findex message-goto-summary +Go to the @code{Summary} header (@code{message-goto-summary}). + +@end table + + +@node Movement +@section Movement + +@table @kbd +@item C-c C-b +@kindex C-c C-b +@findex message-goto-body +Move to the beginning of the body of the message +(@code{message-goto-body}). + +@item C-c C-i +@kindex C-c C-i +@findex message-goto-signature +Move to the signature of the message (@code{message-goto-signature}). + +@end table + + +@node Insertion +@section Insertion + +@table @kbd + +@item C-c C-y +@kindex C-c C-y +@findex message-yank-original +Yank the message in the buffer @code{gnus-article-copy} into the message +buffer. Normally @code{gnus-article-copy} is what you are replying to +(@code{message-yank-original}). + +@item C-c C-q +@kindex C-c C-q +@findex message-fill-yanked-message +Fill the yanked message (@code{message-fill-yanked-message}). Warning: +Can severely mess up the yanked text if its quoting conventions are +strange. You'll quickly get a feel for when it's safe, though. Anyway, +just remember that @kbd{C-x u} (@code{undo}) is available and you'll be +all right. + + +@item C-c C-w +@kindex C-c C-w +@findex message-insert-signature +Insert a signature at the end of the buffer +(@code{message-insert-signature}). + +@end table + +@table @code +@item message-ignored-cited-headers +@vindex message-ignored-cited-headers +All headers that match this regexp will be removed from yanked +messages. The default is @samp{.}, which means that all headers will be +removed. + +@item message-citation-line-function +@vindex message-citation-line-function +Function called to insert the citation line. The default is +@code{message-insert-citation-line}, which will lead to citation lines +that look like: + +@example +Hallvard B Furuseth writes: +@end example + +Point will be at the beginning of the body of the message when this +function is called. + +@item message-yank-prefix +@vindex message-yank-prefix +@cindex yanking +@cindex quoting +When you are replying to or following up an article, you normally want +to quote the person you are answering. Inserting quoted text is done by +@dfn{yanking}, and each quoted line you yank will have +@code{message-yank-prefix} prepended to it. The default is @samp{> }. +If it is @code{nil}, just indent the message. + +@item message-indentation-spaces +@vindex message-indentation-spaces +Number of spaces to indent yanked messages. + +@item message-cite-function +@vindex message-cite-function +@findex message-cite-original +@findex sc-cite-original +@findex message-cite-original-without-signature +@cindex Supercite +Function for citing an original message. The default is +@code{message-cite-original}, which simply inserts the original message +and prepends @samp{> } to each line. +@code{message-cite-original-without-signature} does the same, but elides +the signature. You can also set it to @code{sc-cite-original} to use +Supercite. + +@item message-indent-citation-function +@vindex message-indent-citation-function +Function for modifying a citation just inserted in the mail buffer. +This can also be a list of functions. Each function can find the +citation between @code{(point)} and @code{(mark t)}. And each function +should leave point and mark around the citation text as modified. + +@item message-signature +@vindex message-signature +String to be inserted at the end of the message buffer. If @code{t} +(which is the default), the @code{message-signature-file} file will be +inserted instead. If a function, the result from the function will be +used instead. If a form, the result from the form will be used instead. +If this variable is @code{nil}, no signature will be inserted at all. + +@item message-signature-file +@vindex message-signature-file +File containing the signature to be inserted at the end of the buffer. +The default is @samp{~/.signature}. + +@end table + +Note that RFC1036bis says that a signature should be preceded by the three +characters @samp{-- } on a line by themselves. This is to make it +easier for the recipient to automatically recognize and process the +signature. So don't remove those characters, even though you might feel +that they ruin your beautiful design, like, totally. + +Also note that no signature should be more than four lines long. +Including ASCII graphics is an efficient way to get everybody to believe +that you are silly and have nothing important to say. + + + +@node Various Commands +@section Various Commands + +@table @kbd + +@item C-c C-r +@kindex C-c C-r +@findex message-caesar-buffer-body +Caesar rotate (aka. rot13) the current message +(@code{message-caesar-buffer-body}). If narrowing is in effect, just +rotate the visible portion of the buffer. A numerical prefix says how +many places to rotate the text. The default is 13. + +@item C-c C-e +@kindex C-c C-e +@findex message-elide-region +Elide the text between point and mark (@code{message-elide-region}). +The text is killed and an ellipsis (@samp{[...]}) will be inserted in +its place. + +@item C-c C-z +@kindex C-c C-x +@findex message-kill-to-signature +Kill all the text up to the signature, or if that's missing, up to the +end of the message (@code{message-kill-to-signature}). + +@item C-c C-v +@kindex C-c C-v +@findex message-delete-not-region +Delete all text in the body of the message that is outside the region +(@code{message-delete-not-region}). + +@item M-RET +@kindex M-RET +@kindex message-newline-and-reformat +Insert four newlines, and then reformat if inside quoted text. + +Here's an example: + +@example +> This is some quoted text. And here's more quoted text. +@end example + +If point is before @samp{And} and you press @kbd{M-RET}, you'll get: + +@example +> This is some quoted text. + +* + +> And here's more quoted text. +@end example + +@samp{*} says where point will be placed. + +@item C-c C-t +@kindex C-c C-t +@findex message-insert-to +Insert a @code{To} header that contains the @code{Reply-To} or +@code{From} header of the message you're following up +(@code{message-insert-to}). + +@item C-c C-n +@kindex C-c C-n +@findex message-insert-newsgroups +Insert a @code{Newsgroups} header that reflects the @code{Followup-To} +or @code{Newsgroups} header of the article you're replying to +(@code{message-insert-newsgroups}). + +@item C-c M-r +@kindex C-c M-r +@findex message-rename-buffer +Rename the buffer (@code{message-rename-buffer}). If given a prefix, +prompt for a new buffer name. + +@end table + + +@node Sending +@section Sending + +@table @kbd +@item C-c C-c +@kindex C-c C-c +@findex message-send-and-exit +Send the message and bury the current buffer +(@code{message-send-and-exit}). + +@item C-c C-s +@kindex C-c C-s +@findex message-send +Send the message (@code{message-send}). + +@item C-c C-d +@kindex C-c C-d +@findex message-dont-send +Bury the message buffer and exit (@code{message-dont-send}). + +@item C-c C-k +@kindex C-c C-k +@findex message-kill-buffer +Kill the message buffer and exit (@code{message-kill-buffer}). + +@end table + + + +@node Mail Aliases +@section Mail Aliases +@cindex mail aliases +@cindex aliases + +@vindex message-mail-alias-type +The @code{message-mail-alias-type} variable controls what type of mail +alias expansion to use. Currently only one form is supported---Message +uses @code{mailabbrev} to handle mail aliases. If this variable is +@code{nil}, no mail alias expansion will be performed. + +@code{mailabbrev} works by parsing the @file{/etc/mailrc} and +@file{~/.mailrc} files. These files look like: + +@example +alias lmi "Lars Magne Ingebrigtsen " +alias ding "ding@@ifi.uio.no (ding mailing list)" +@end example + +After adding lines like this to your @file{~/.mailrc} file, you should +be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so +on) headers and press @kbd{SPC} to expand the alias. + +No expansion will be performed upon sending of the message---all +expansions have to be done explicitly. + + + +@node Variables +@chapter Variables + +@menu +* Message Headers:: General message header stuff. +* Mail Headers:: Customizing mail headers. +* Mail Variables:: Other mail variables. +* News Headers:: Customizing news headers. +* News Variables:: Other news variables. +* Various Message Variables:: Other message variables. +* Sending Variables:: Variables for sending. +* Message Buffers:: How Message names its buffers. +* Message Actions:: Actions to be performed when exiting. +@end menu + + +@node Message Headers +@section Message Headers + +Message is quite aggressive on the message generation front. It has to +be -- it's a combined news and mail agent. To be able to send combined +messages, it has to generate all headers itself (instead of letting the +mail/news system do it) to ensure that mail and news copies of messages +look sufficiently similar. + +@table @code + +@item message-generate-headers-first +@vindex message-generate-headers-first +If non-@code{nil}, generate all headers before starting to compose the +message. + +@item message-from-style +@vindex message-from-style +Specifies how @code{From} headers should look. There are four valid +values: + +@table @code +@item nil +Just the address -- @samp{king@@grassland.com}. + +@item parens +@samp{king@@grassland.com (Elvis Parsley)}. + +@item angles +@samp{Elvis Parsley }. + +@item default +Look like @code{angles} if that doesn't require quoting, and +@code{parens} if it does. If even @code{parens} requires quoting, use +@code{angles} anyway. + +@end table + +@item message-deletable-headers +@vindex message-deletable-headers +Headers in this list that were previously generated by Message will be +deleted before posting. Let's say you post an article. Then you decide +to post it again to some other group, you naughty boy, so you jump back +to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and +ship it off again. By default, this variable makes sure that the old +generated @code{Message-ID} is deleted, and a new one generated. If +this isn't done, the entire empire would probably crumble, anarchy would +prevail, and cats would start walking on two legs and rule the world. +Allegedly. + +@item message-default-headers +@vindex message-default-headers +This string is inserted at the end of the headers in all message +buffers. + +@item message-subject-re-regexp +@vindex message-subject-re-regexp +Responses to messages have subjects that start with @samp{Re: }. This +is @emph{not} an abbreviation of the English word ``response'', but in +Latin, and means ``in response to''. Some illiterate nincompoops have +failed to grasp this fact, and have ``internationalized'' their software +to use abonimations like @samp{Aw: } (``antwort'') or @samp{Sv: } +(``svar'') instead, which is meaningless and evil. However, you may +have to deal with users that use these evil tools, in which case you may +set this variable to a regexp that matches these prefixes. Myself, I +just throw away non-compliant mail. + +@end table + + +@node Mail Headers +@section Mail Headers + +@table @code +@item message-required-mail-headers +@vindex message-required-mail-headers +@xref{News Headers}, for the syntax of this variable. It is +@code{(From Date Subject (optional . In-Reply-To) Message-ID Lines +(optional . X-Mailer))} by default. + +@item message-ignored-mail-headers +@vindex message-ignored-mail-headers +Regexp of headers to be removed before mailing. The default is +@samp{^[GF]cc:\\|^Resent-Fcc:}. + +@item message-default-mail-headers +@vindex message-default-mail-headers +This string is inserted at the end of the headers in all message +buffers that are initialized as mail. + +@end table + + +@node Mail Variables +@section Mail Variables + +@table @code +@item message-send-mail-function +@vindex message-send-mail-function +Function used to send the current buffer as mail. The default is +@code{message-send-mail-with-sendmail}. If you prefer using MH +instead, set this variable to @code{message-send-mail-with-mh}. + +@item message-mh-deletable-headers +@vindex message-mh-deletable-headers +Most versions of MH doesn't like being fed messages that contain the +headers in this variable. If this variable is non-@code{nil} (which is +the default), these headers will be removed before mailing when sending +messages via MH. Set it to @code{nil} if your MH can handle these +headers. + +@end table + + +@node News Headers +@section News Headers + +@vindex message-required-news-headers +@code{message-required-news-headers} a list of header symbols. These +headers will either be automatically generated, or, if that's +impossible, they will be prompted for. The following symbols are valid: + +@table @code + +@item From +@cindex From +@findex user-full-name +@findex user-mail-address +This required header will be filled out with the result of the +@code{message-make-from} function, which depends on the +@code{message-from-style}, @code{user-full-name}, +@code{user-mail-address} variables. + +@item Subject +@cindex Subject +This required header will be prompted for if not present already. + +@item Newsgroups +@cindex Newsgroups +This required header says which newsgroups the article is to be posted +to. If it isn't present already, it will be prompted for. + +@item Organization +@cindex organization +This optional header will be filled out depending on the +@code{message-user-organization} variable. +@code{message-user-organization-file} will be used if this variable is +@code{t}. This variable can also be a string (in which case this string +will be used), or it can be a function (which will be called with no +parameters and should return a string to be used). + +@item Lines +@cindex Lines +This optional header will be computed by Message. + +@item Message-ID +@cindex Message-ID +@vindex mail-host-address +@findex system-name +@cindex Sun +This required header will be generated by Message. A unique ID will be +created based on the date, time, user name and system name. Message will +use @code{mail-host-address} as the fully qualified domain name (FQDN) +of the machine if that variable is defined. If not, it will use +@code{system-name}, which doesn't report a FQDN on some machines -- +notably Suns. + +@item X-Newsreader +@cindex X-Newsreader +This optional header will be filled out according to the +@code{message-newsreader} local variable. + +@item X-Mailer +This optional header will be filled out according to the +@code{message-mailer} local variable, unless there already is an +@code{X-Newsreader} header present. + +@item In-Reply-To +This optional header is filled out using the @code{Date} and @code{From} +header of the article being replied to. + +@item Expires +@cindex Expires +This extremely optional header will be inserted according to the +@code{message-expires} variable. It is highly deprecated and shouldn't +be used unless you know what you're doing. + +@item Distribution +@cindex Distribution +This optional header is filled out according to the +@code{message-distribution-function} variable. It is a deprecated and +much misunderstood header. + +@item Path +@cindex path +This extremely optional header should probably never be used. +However, some @emph{very} old servers require that this header is +present. @code{message-user-path} further controls how this +@code{Path} header is to look. If it is @code{nil}, use the server name +as the leaf node. If it is a string, use the string. If it is neither +a string nor @code{nil}, use the user name only. However, it is highly +unlikely that you should need to fiddle with this variable at all. +@end table + +@findex yow +@cindex Mime-Version +In addition, you can enter conses into this list. The car of this cons +should be a symbol. This symbol's name is the name of the header, and +the cdr can either be a string to be entered verbatim as the value of +this header, or it can be a function to be called. This function should +return a string to be inserted. For instance, if you want to insert +@code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")} +into the list. If you want to insert a funny quote, you could enter +something like @code{(X-Yow . yow)} into the list. The function +@code{yow} will then be called without any arguments. + +If the list contains a cons where the car of the cons is +@code{optional}, the cdr of this cons will only be inserted if it is +non-@code{nil}. + +Other variables for customizing outgoing news articles: + +@table @code + +@item message-syntax-checks +@vindex message-syntax-checks +Controls what syntax checks should not be performed on outgoing posts. +To disable checking of long signatures, for instance, add + +@lisp +(signature . disabled) +@end lisp + +to this list. + +Valid checks are: + +@table @code +@item subject-cmsg +Check the subject for commands. +@item sender +@cindex Sender +Insert a new @code{Sender} header if the @code{From} header looks odd. +@item multiple-headers +Check for the existence of multiple equal headers. +@item sendsys +@cindex sendsys +Check for the existence of version and sendsys commands. +@item message-id +Check whether the @code{Message-ID} looks ok. +@item from +Check whether the @code{From} header seems nice. +@item long-lines +@cindex long lines +Check for too long lines. +@item control-chars +Check for invalid characters. +@item size +Check for excessive size. +@item new-text +Check whether there is any new text in the messages. +@item signature +Check the length of the signature. +@item approved +@cindex approved +Check whether the article has an @code{Approved} header, which is +something only moderators should include. +@item empty +Check whether the article is empty. +@item invisible-text +Check whether there is any invisible text in the buffer. +@item empty-headers +Check whether any of the headers are empty. +@item existing-newsgroups +Check whether the newsgroups mentioned in the @code{Newsgroups} and +@code{Followup-To} headers exist. +@item valid-newsgroups +Check whether the @code{Newsgroups} and @code{Followup-to} headers +are valid syntactically. +@item repeated-newsgroups +Check whether the @code{Newsgroups} and @code{Followup-to} headers +contains repeated group names. +@item shorten-followup-to +Check whether to add a @code{Followup-to} header to shorten the number +of groups to post to. +@end table + +All these conditions are checked by default. + +@item message-ignored-news-headers +@vindex message-ignored-news-headers +Regexp of headers to be removed before posting. The default is@* +@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:}. + +@item message-default-news-headers +@vindex message-default-news-headers +This string is inserted at the end of the headers in all message +buffers that are initialized as news. + +@end table + + +@node News Variables +@section News Variables + +@table @code +@item message-send-news-function +@vindex message-send-news-function +Function used to send the current buffer as news. The default is +@code{message-send-news}. + +@item message-post-method +@vindex message-post-method +Gnusish @dfn{select method} (see the Gnus manual for details) used for +posting a prepared news message. + +@end table + + +@node Various Message Variables +@section Various Message Variables + +@table @code +@item message-signature-separator +@vindex message-signature-separator +Regexp matching the signature separator. It is @samp{^-- *$} by +default. + +@item mail-header-separator +@vindex mail-header-separator +String used to separate the headers from the body. It is @samp{--text +follows this line--} by default. + +@item message-directory +@vindex message-directory +Directory used by many mailey things. The default is @file{~/Mail/}. + +@item message-signature-setup-hook +@vindex message-signature-setup-hook +Hook run when initializing the message buffer. It is run after the +headers have been inserted but before the signature has been inserted. + +@item message-setup-hook +@vindex message-setup-hook +Hook run as the last thing when the message buffer has been initialized, +but before yanked text is inserted. + +@item message-header-setup-hook +@vindex message-header-setup-hook +Hook called narrowed to the headers after initializing the headers. + +For instance, if you're running Gnus and wish to insert a +@samp{Mail-Copies-To} header in all your news articles and all messages +you send to mailing lists, you could do something like the following: + +@lisp +(defun my-message-header-setup-hook () + (let ((group (or gnus-newsgroup-name ""))) + (when (or (message-fetch-field "newsgroups") + (gnus-group-find-parameter group 'to-address) + (gnus-group-find-parameter group 'to-list)) + (insert "Mail-Copies-To: never\n")))) + +(add-hook 'message-header-setup-hook + 'my-message-header-setup-hook) +@end lisp + +@item message-send-hook +@vindex message-send-hook +Hook run before sending messages. + +If you want to add certain headers before sending, you can use the +@code{message-add-header} function in this hook. For instance: +@findex message-add-header + +@lisp +(add-hook 'message-send-hook 'my-message-add-content) +(defun my-message-add-content () + (message-add-header + "Mime-Version: 1.0" + "Content-Type: text/plain" + "Content-Transfer-Encoding: 7bit")) +@end lisp + +This function won't add the header if the header is already present. + +@item message-send-mail-hook +@vindex message-send-mail-hook +Hook run before sending mail messages. + +@item message-send-news-hook +@vindex message-send-news-hook +Hook run before sending news messages. + +@item message-sent-hook +@vindex message-sent-hook +Hook run after sending messages. + +@item message-mode-syntax-table +@vindex message-mode-syntax-table +Syntax table used in message mode buffers. + +@item message-send-method-alist +@vindex message-send-method-alist + +Alist of ways to send outgoing messages. Each element has the form + +@lisp +(TYPE PREDICATE FUNCTION) +@end lisp + +@table @var +@item type +A symbol that names the method. + +@item predicate +A function called without any parameters to determine whether the +message is a message of type @var{type}. + +@item function +A function to be called if @var{predicate} returns non-@code{nil}. +@var{function} is called with one parameter -- the prefix. +@end table + +@lisp +((news message-news-p message-send-via-news) + (mail message-mail-p message-send-via-mail)) +@end lisp + + + +@end table + + + +@node Sending Variables +@section Sending Variables + +@table @code + +@item message-fcc-handler-function +@vindex message-fcc-handler-function +A function called to save outgoing articles. This function will be +called with the name of the file to store the article in. The default +function is @code{message-output} which saves in Unix mailbox format. + +@item message-courtesy-message +@vindex message-courtesy-message +When sending combined messages, this string is inserted at the start of +the mailed copy. If the string contains the format spec @samp{%s}, the +newsgroups the article has been posted to will be inserted there. If +this variable is @code{nil}, no such courtesy message will be added. +The default value is @samp{"The following message is a courtesy copy of +an article\nthat has been posted to %s as well.\n\n"}. + +@end table + + +@node Message Buffers +@section Message Buffers + +Message will generate new buffers with unique buffer names when you +request a message buffer. When you send the message, the buffer isn't +normally killed off. Its name is changed and a certain number of old +message buffers are kept alive. + +@table @code +@item message-generate-new-buffers +@vindex message-generate-new-buffers +If non-@code{nil}, generate new buffers. The default is @code{t}. If +this is a function, call that function with three parameters: The type, +the to address and the group name. (Any of these may be @code{nil}.) +The function should return the new buffer name. + +@item message-use-multi-frames +@vindex message-use-multi-frames +If non-@code{nil}, generate new frames. The default is @code{nil}. + +@item message-delete-frame-on-exit +@vindex message-delete-frame-on-exit +The @code{message-delete-frame-on-exit} variable says whether to delete +the frame after sending the message or killing the message buffer. If it +is @code{nil} (which is the default), don't delete the frame. If it is +@code{ask}, ask wheter to delete the frame. If it is @code{t}, always +delete the frame. + +@item message-max-buffers +@vindex message-max-buffers +This variable says how many old message buffers to keep. If there are +more message buffers than this, the oldest buffer will be killed. The +default is 10. If this variable is @code{nil}, no old message buffers +will ever be killed. + +@item message-send-rename-function +@vindex message-send-rename-function +After sending a message, the buffer is renamed from, for instance, +@samp{*reply to Lars*} to @samp{*sent reply to Lars*}. If you don't +like this, set this variable to a function that renames the buffer in a +manner you like. If you don't want to rename the buffer at all, you can +say: + +@lisp +(setq message-send-rename-function 'ignore) +@end lisp + +@item message-kill-buffer-on-exit +@findex message-kill-buffer-on-exit +If non-@code{nil}, kill the buffer immediately on exit. + +@end table + + +@node Message Actions +@section Message Actions + +When Message is being used from a news/mail reader, the reader is likely +to want to perform some task after the message has been sent. Perhaps +return to the previous window configuration or mark an article as +replied. + +@vindex message-kill-actions +@vindex message-postpone-actions +@vindex message-exit-actions +@vindex message-send-actions +The user may exit from the message buffer in various ways. The most +common is @kbd{C-c C-c}, which sends the message and exits. Other +possibilities are @kbd{C-c C-s} which just sends the message, @kbd{C-c +C-d} which postpones the message editing and buries the message buffer, +and @kbd{C-c C-k} which kills the message buffer. Each of these actions +have lists associated with them that contains actions to be executed: +@code{message-send-actions}, @code{message-exit-actions}, +@code{message-postpone-actions}, and @code{message-kill-actions}. + +Message provides a function to interface with these lists: +@code{message-add-action}. The first parameter is the action to be +added, and the rest of the arguments are which lists to add this action +to. Here's an example from Gnus: + +@lisp + (message-add-action + `(set-window-configuration ,(current-window-configuration)) + 'exit 'postpone 'kill) +@end lisp + +This restores the Gnus window configuration when the message buffer is +killed, postponed or exited. + +An @dfn{action} can be either: a normal function, or a list where the +@code{car} is a function and the @code{cdr} is the list of arguments, or +a form to be @code{eval}ed. + + +@node Compatibility +@chapter Compatibility +@cindex compatibility + +Message uses virtually only its own variables---older @code{mail-} +variables aren't consulted. To force Message to take those variables +into account, you can put the following in your @code{.emacs} file: + +@lisp +(require 'messcompat) +@end lisp + +This will initialize many Message variables from the values in the +corresponding mail variables. + + +@node Appendices +@chapter Appendices + +@menu +* Responses:: Standard rules for determining where responses go. +@end menu + + +@node Responses +@section Responses + +To determine where a message is to go, the following algorithm is used +by default. + +@table @dfn +@item reply +A @dfn{reply} is when you want to respond @emph{just} to the person who +sent the message via mail. There will only be one recipient. To +determine who the recipient will be, the following headers are +consulted, in turn: + +@table @code +@item Reply-To + +@item From +@end table + + +@item wide reply +A @dfn{wide reply} is a mail response that includes @emph{all} entities +mentioned in the message you are responded to. All mailboxes from the +following headers will be concatenated to form the outgoing +@code{To}/@code{Cc} headers: + +@table @code +@item From +(unless there's a @code{Reply-To}, in which case that is used instead). + +@item Cc + +@item To +@end table + +If a @code{Mail-Copies-To} header is present, it will also be included +in the list of mailboxes. If this header is @samp{never}, that means +that the @code{From} (or @code{Reply-To}) mailbox will be suppressed. + + +@item followup +A @dfn{followup} is a response sent via news. The following headers +(listed in order of precedence) determine where the response is to be +sent: + +@table @code + +@item Followup-To + +@item Newsgroups + +@end table + +If a @code{Mail-Copies-To} header is present, it will be used as the +basis of the new @code{Cc} header, except if this header is +@samp{never}. + +@end table + + + +@node Index +@chapter Index +@printindex cp + +@node Key Index +@chapter Key Index +@printindex ky + +@summarycontents +@contents +@bye + +@c End: