Mercurial > emacs
changeset 32769:6c4bf57935ff
Update from version 5.213 from the Gnus repository.
Change @setfilename.
| author | Gerd Moellmann <gerd@gnu.org> |
|---|---|
| date | Mon, 23 Oct 2000 13:15:56 +0000 |
| parents | f716c5596ce8 |
| children | 9c198c1dc72f |
| files | man/gnus.texi |
| diffstat | 1 files changed, 4652 insertions(+), 819 deletions(-) [+] |
line wrap: on
line diff
--- a/man/gnus.texi Mon Oct 23 12:35:01 2000 +0000 +++ b/man/gnus.texi Mon Oct 23 13:15:56 2000 +0000 @@ -1,10 +1,11 @@ -\input texinfo @c -*-texinfo-*- +\input texinfo @c -*-texinfo-*- -*- coding: iso-latin-1 -*- @setfilename ../info/gnus @settitle Gnus Manual @synindex fn cp @synindex vr cp @synindex pg cp +@dircategory Editors @direntry * Gnus: (gnus). The newsreader Gnus. @end direntry @@ -14,57 +15,338 @@ @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{\gnusresult}[1]{\gnustt{=> #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 - -@ifinfo +@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,99,2000 Free Software Foundation, Inc. + + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +\newpage +\end{titlepage} +@end iflatex +@end iftex + +@ifnottex 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 +Copyright (C) 1995,96,97,98,99,2000 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being none, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end ifnottex @tex @titlepage -@title Gnus 5.7 Manual +@title Gnus 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. +Copyright @copyright{} 1995,96,97,98,99,2000 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. @end titlepage @page @@ -82,12 +364,17 @@ spool or your mbox file. All at the same time, if you want to push your luck. -This manual corresponds to Gnus 5.7. +This manual corresponds to Gnus 5.8.7. @end ifinfo @iftex +@iflatex +\tableofcontents +\gnuscleardoublepage +@end iflatex + Gnus is the advanced, self-documenting, customizable, extensible unreal-time newsreader for GNU Emacs. @@ -96,8 +383,8 @@ 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! +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 @@ -108,7 +395,6 @@ @end iftex - @menu * Starting Up:: Finding news can be a pain. * The Group Buffer:: Selecting, subscribing and killing groups. @@ -122,6 +408,463 @@ * Appendices:: Terminology, Emacs intro, FAQ, History, Internals. * Index:: Variable, function and concept index. * Key Index:: Key Index. + +@detailmenu + --- The Detailed Node Listing --- + +Starting Gnus + +* 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. + +New Groups + +* 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. + +The Group Buffer + +* Group Buffer Format:: Information listed and how you can change it. +* Group Maneuvering:: Commands for moving in the group buffer. +* Selecting a Group:: Actually reading news. +* 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. + +Group Buffer Format + +* 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. + +Group Topics + +* 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. + +Misc Group Stuff + +* 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. + +The Summary Buffer + +* 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. +* 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. +* Charsets:: Character set issues. +* Article Commands:: Doing various things with the article buffer. +* Summary Sorting:: Sorting the summary buffer in various ways. +* Finding the Parent:: No child support? Get the parent. +* Alternative Approaches:: Reading using non-default summaries. +* Tree Display:: A more visual display of threads. +* Mail Group Commands:: Some commands can only be used in mail groups. +* Various Summary Stuff:: What didn't fit anywhere else. +* 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. + +Summary Buffer Format + +* Summary Buffer Lines:: You can specify how summary lines should look. +* To From Newsgroups:: How to not display your own name. +* Summary Buffer Mode Line:: You can say how the mode line should look. +* Summary Highlighting:: Making the summary buffer all pretty and nice. + +Choosing Articles + +* Choosing Commands:: Commands for choosing articles. +* Choosing Variables:: Variables that influence these commands. + +Reply, Followup and Post + +* Summary Mail Commands:: Sending mail. +* Summary Post Commands:: Sending news. +* Summary Message Commands:: Other Message-related commands. +* Canceling and Superseding:: ``Whoops, I shouldn't have called him that.'' + +Marking Articles + +* Unread Articles:: Marks for unread articles. +* Read Articles:: Marks for read articles. +* Other Marks:: Marks that do not affect readedness. +* Setting Marks:: How to set and remove marks. +* Generic Marking Commands:: How to customize the marking. +* Setting Process Marks:: How to mark articles for later processing. + +Threading + +* Customizing Threading:: Variables you can change to affect the threading. +* Thread Commands:: Thread based commands in the summary buffer. + +Customizing Threading + +* 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! + +Decoding Articles + +* 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? + +Decoding Variables + +* 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. + +Article Treatment + +* 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? +* Article Miscellania:: Various other stuff. + +Alternative Approaches + +* Pick and Read:: First mark articles and then read them. +* Binary Groups:: Auto-decode all articles. + +Various Summary Stuff + +* 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. + +The Article Buffer + +* Hiding Headers:: Deciding what headers should be displayed. +* Using MIME:: Pushing articles through @sc{mime} before reading them. +* Customizing Articles:: Tailoring the look of the articles. +* Article Keymap:: Keystrokes available in the article buffer. +* Misc Article:: Other stuff. + +Composing Messages + +* 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? + +Select Methods + +* The Server Buffer:: Making and editing virtual servers. +* Getting News:: Reading USENET news with Gnus. +* Getting Mail:: Reading your personal mail with Gnus. +* Browsing the Web:: Getting messages from a plethora of Web sources. +* Other Sources:: Reading directories, files, SOUP packets. +* Combined Groups:: Combining groups into one group. +* Gnus Unplugged:: Reading news and mail offline. + +The Server Buffer + +* Server Buffer Format:: You can customize the look of this buffer. +* Server Commands:: Commands to manipulate servers. +* Example Methods:: Examples server specifications. +* Creating a Virtual Server:: An example session. +* Server Variables:: Which variables to set. +* Servers and Methods:: You can use server names as select methods. +* Unavailable Servers:: Some servers you try to contact may be down. + +Getting News + +* NNTP:: Reading news from an @sc{nntp} server. +* News Spool:: Reading news from the local spool. + +Getting Mail + +* Mail in a Newsreader:: Important introductory notes. +* Getting Started Reading Mail:: A simple cookbook example. +* Splitting Mail:: How to create mail groups. +* Mail Sources:: How to tell Gnus where to get mail from. +* Mail Backend Variables:: Variables for customizing mail handling. +* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. +* Group Mail Splitting:: Use group customize to drive mail splitting. +* Incorporating Old Mail:: What about the old mail you have? +* Expiring Mail:: Getting rid of unwanted mail. +* Washing Mail:: Removing 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. + +Mail Sources + +* Mail Source Specifiers:: How to specify what a mail source is. +* Mail Source Customization:: Some variables that influence things. +* Fetching Mail:: Using the mail source specifiers. + +Choosing a Mail Backend + +* 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. +* Comparing Mail Backends:: An in-depth looks at pros and cons. + +Browsing the Web + +* Web Searches:: Creating groups from articles that match a string. +* Slashdot:: Reading the Slashdot comments. +* Ultimate:: The Ultimate Bulletin Board systems. +* Web Archive:: Reading mailing list archived on web. + +Other Sources + +* Directory Groups:: You can read a directory as if it was a newsgroup. +* Anything Groups:: Dired? Who needs dired? +* Document Groups:: Single files can be the basis of a group. +* SOUP:: Reading @sc{soup} packets ``offline''. +* Mail-To-News Gateways:: Posting articles via mail-to-news gateways. +* IMAP:: Using Gnus as a @sc{imap} client. + +Document Groups + +* Document Server Internals:: How to add your own document types. + +SOUP + +* 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. + +@sc{imap} + +* Splitting in IMAP:: Splitting mail with nnimap. +* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. +* Expunging mailboxes:: Equivalent of a "compress mailbox" button. + +Combined Groups + +* Virtual Groups:: Combining articles from many groups. +* Kibozed Groups:: Looking through parts of the newsfeed for articles. + +Gnus Unplugged + +* 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. +* Agent and IMAP:: How to use the Agent with IMAP. +* Outgoing Messages:: What happens when you post/mail something? +* Agent Variables:: Customizing is fun. +* Example Setup:: An example @file{.gnus.el} file for offline people. +* Batching Agents:: How to fetch news from a @code{cron} job. +* Agent Caveats:: What you think it'll do and what it does. + +Agent Categories + +* Category Syntax:: What a category looks like. +* The Category Buffer:: A buffer for maintaining categories. +* Category Variables:: Customize'r'Us. + +Agent Commands + +* Group Agent Commands:: +* Summary Agent Commands:: +* Server Agent Commands:: + +Scoring + +* 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. + +GroupLens + +* 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. + +Advanced Scoring + +* Advanced Scoring Syntax:: A definition. +* Advanced Scoring Examples:: What they look like. +* Advanced Scoring Tips:: Getting the most out of it. + +Various + +* 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. + +Formatting Variables + +* 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. + +XEmacs Enhancements + +* 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. + +Picons + +* 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. + +Appendices + +* History:: How Gnus got where it is today. +* On Writing Manuals:: Why this is not a beginner's guide. +* Terminology:: We use really difficult, like, words here. +* Customization:: Tailoring Gnus to your needs. +* Troubleshooting:: What you might try if things do not work. +* Gnus Reference Guide:: Rilly, rilly technical stuff. +* Emacs for Heathens:: A short introduction to Emacsian terms. +* Frequently Asked Questions:: A question-and-answer session. + +History + +* Gnus Versions:: What Gnus versions have been released. +* Other Gnus Versions:: Other Gnus versions that also have been released. +* Why?:: What's the point of Gnus? +* Compatibility:: Just how compatible is Gnus with @sc{gnus}? +* Conformity:: Gnus tries to conform to all standards. +* Emacsen:: Gnus can be run on a few modern Emacsen. +* Gnus Development:: How Gnus is developed. +* Contributors:: Oodles of people. +* New Features:: Pointers to some of the new stuff in Gnus. +* Newest Features:: Features so new that they haven't been written yet. + +New Features + +* 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. + +Customization + +* 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. + +Gnus Reference Guide + +* 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. + +Backend Interface + +* 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. + +Various File Formats + +* Active File Format:: Information on articles and groups available. +* Newsgroups File Format:: Group descriptions. + +Emacs for Heathens + +* Keystrokes:: Entering text and executing commands. +* Emacs Lisp:: The built-in Emacs programming language. + +@end detailmenu @end menu @node Starting Up @@ -204,11 +947,15 @@ @code{gnus-nntp-server} to @code{nil}, which is what it is by default. @vindex gnus-secondary-servers +@vindex gnus-nntp-server 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. +type in the name of any server you feel like visiting. (Note that this +will set @code{gnus-nntp-server}, which means that if you then @kbd{M-x +gnus} later in the same Emacs session, Gnus will contact the same +server.) @findex gnus-group-browse-foreign-server @kindex B (Group) @@ -425,7 +1172,7 @@ 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 +alphabetical fashion, while this function will enter groups into its 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. @@ -440,6 +1187,22 @@ @vindex gnus-subscribe-killed Kill all new groups. +@item gnus-subscribe-topics +@vindex gnus-subscribe-topics +Put the groups into the topic that has a matching @code{subscribe} topic +parameter (@pxref{Topic Parameters}). For instance, a @code{subscribe} +topic parameter that looks like + +@example +"nnslashdot" +@end example + +will mean that all groups that match that regex will be subscribed under +that topic. + +If no topics match the groups, the groups will be subscribed in the +top-level topic. + @end table @vindex gnus-subscribe-hierarchical-interactive @@ -546,6 +1309,10 @@ gnus-group-clear-data-on-native-groups} command to clear out all data that you have on your native groups. Use with caution. +After changing servers, you @strong{must} move the cache hierarchy away, +since the cached articles will have wrong article numbers, which will +affect which articles Gnus thinks are read. + @node Startup Files @section Startup Files @@ -573,11 +1340,15 @@ not stored in the @file{.newsrc} file. @vindex gnus-save-newsrc-file +@vindex gnus-read-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? +Gnus. But hey, who would want to, right? Similarly, setting +@code{gnus-read-newsrc-file} to @code{nil} makes Gnus ignore the +@file{.newsrc} file and any @file{.newsrc-SERVER} files, which is +convenient if you have a tendency to use Netscape once in a while. @vindex gnus-save-killed-list If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus @@ -703,6 +1474,10 @@ at all. In any case, @code{some} should be faster than @code{nil}, and is certainly faster than @code{t} over slow lines. +Some news servers (Leafnode and old versions of INN, for instance) do +not support the @code{LIST ACTIVE group}. For these servers, @code{nil} +is probably the most efficient value for this variable. + 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 @@ -710,6 +1485,9 @@ performance, but if the server does not support the aforementioned @code{LIST ACTIVE group} command, this isn't very nice to the server. +If you think that starting up Gnus takes too long, try all the three +different values for this variable and see what works best for you. + 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. @@ -741,8 +1519,8 @@ A hook that is run as the very last thing after starting up Gnus successfully. -@item gnus-started-hook -@vindex gnus-started-hook +@item gnus-setup-news-hook +@vindex gnus-setup-news-hook A hook that is run after reading the @file{.newsrc} file(s), but before generating the group buffer. @@ -786,6 +1564,19 @@ 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. @@ -926,7 +1717,7 @@ 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}. +@samp{gnu.emacs.gnus} will be shortened to @samp{g.e.gnus}. @item m @vindex gnus-new-mail-mark @@ -986,16 +1777,18 @@ 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)))) +(cond (window-system + (setq custom-background-mode 'light) + (defface my-group-face-1 + '((t (:foreground "Red" :bold t))) "First group face") + (defface my-group-face-2 + '((t (:foreground "DarkSeaGreen4" :bold t))) "Second group face") + (defface my-group-face-3 + '((t (:foreground "Green4" :bold t))) "Third group face") + (defface my-group-face-4 + '((t (:foreground "SteelBlue" :bold t))) "Fourth group face") + (defface my-group-face-5 + '((t (:foreground "Blue" :bold t))) "Fifth group face"))) (setq gnus-group-highlight '(((> unread 200) . my-group-face-1) @@ -1137,7 +1930,7 @@ 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 @math{abs(N)} oldest articles. +negative, Gnus fetches the @code{abs(@var{N})} oldest articles. @item RET @kindex RET (Group) @@ -1205,7 +1998,25 @@ @item best Select the highest scored article in the group when entering the group. -@end table + +@end table + +This variable can also be a function. In that case, that function will +be called to place point on a subject line, and/or select some article. +Useful functions include: + +@table @code +@item gnus-summary-first-unread-subject +Place point on the subject line of the first unread article, but +don't select the article. + +@item gnus-summary-first-unread-article +Select the first unread article. + +@item gnus-summary-best-unread-article +Select the highest-scored unread article. +@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} @@ -1387,6 +2198,9 @@ handy if you want to read the most important groups before you read the rest. +If this variable is @code{best}, Gnus will make the next newsgroup the +one with the best level. + @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 @@ -1421,13 +2235,14 @@ 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.)) +This is what @dfn{group score} is for. You can have Gnus assign a score +to each group through the mechanism described below. 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 @@ -1607,9 +2422,9 @@ 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}. +@code{rfc934}, @code{rfc822-forward}, @code{nsmail} 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) @@ -1668,7 +2483,7 @@ 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. +newsgroups. @node Group Parameters @@ -1714,7 +2529,7 @@ @item to-list @cindex to-list -Address used when doing a @kbd{a} in that group. +Address used when doing @kbd{a} in that group. @example (to-list . "some@@where.com") @@ -1763,7 +2578,7 @@ @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 +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 @@ -1830,7 +2645,12 @@ Gnus, but provide a place for you to store information on particular groups. -@item @code{(@var{variable} @var{form})} +@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} @var{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 @@ -1844,6 +2664,23 @@ group. @code{dummy-variable} will be set to the result of the @code{(ding)} form, but who cares? +@item posting-style +You can store additional posting style information for this group only +here (@pxref{Posting Styles}). The format is that of an entry in the +@code{gnus-posting-styles} alist, except that there's no regexp matching +the group name (of course). Style elements in this group parameter will +take precedence over the ones found in @code{gnus-posting-styles}. + +For instance, if you want a funky name and signature in this group only, +instead of hacking @code{gnus-posting-styles}, you could put something +like this in the group parameters: + +@example +(posting-style + (name "Funky Name") + (signature "Funky Signature")) +@end example + @end table Use the @kbd{G p} command to edit group parameters of a group. You @@ -1936,6 +2773,16 @@ List all groups that have names or descriptions that match a regexp (@code{gnus-group-description-apropos}). +@item A c +@kindex A c (Group) +@findex gnus-group-list-cached +List all groups with cached articles (@code{gnus-group-list-cached}). + +@item A ? +@kindex A ? (Group) +@findex gnus-group-list-dormant +List all groups with dormant articles (@code{gnus-group-list-dormant}). + @end table @vindex gnus-permanently-visible-groups @@ -2045,7 +2892,11 @@ @end table -When given a prefix, all these commands will sort in reverse order. +All the commands below obey 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: @@ -2053,38 +2904,38 @@ @item G P a @kindex G P a (Group) @findex gnus-group-sort-selected-groups-by-alphabet -Sort the process/prefixed groups in the group buffer alphabetically by -group name (@code{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 process/prefixed groups in the group buffer by the number of -unread articles (@code{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 process/prefixed groups in the group buffer by group 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 process/prefixed groups in the group buffer by group 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 process/prefixed groups in the group buffer by group 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 process/prefixed groups in the group buffer alphabetically by -backend name (@code{gnus-group-sort-selected-groups-by-method}). +Sort the groups alphabetically by backend name +(@code{gnus-group-sort-selected-groups-by-method}). @end table @@ -2250,6 +3101,14 @@ 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 @@ -2358,6 +3217,11 @@ (@code{gnus-topic-move-group}). This command uses the process/prefix convention (@pxref{Process/Prefix}). +@item T j +@kindex T j (Topic) +@findex gnus-topic-jump-to-topic +Go to a topic (@code{gnus-topic-jump-to-topic}). + @item T c @kindex T c (Topic) @findex gnus-topic-copy-group @@ -2365,6 +3229,18 @@ (@code{gnus-topic-copy-group}). This command uses the process/prefix convention (@pxref{Process/Prefix}). +@item T h +@kindex T h (Topic) +@findex gnus-topic-hide-topic +Hide the current topic (@code{gnus-topic-hide-topic}). If given +a prefix, hide the topic permanently. + +@item T s +@kindex T s (Topic) +@findex gnus-topic-show-topic +Show the current topic (@code{gnus-topic-show-topic}). If given +a prefix, show the topic permanently. + @item T D @kindex T D (Topic) @findex gnus-topic-remove-group @@ -2374,7 +3250,7 @@ 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. +topic. This command uses the process/prefix convention (@pxref{Process/Prefix}). @@ -2409,17 +3285,6 @@ 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) @@ -2433,7 +3298,24 @@ @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}). +parent of its current parent (@code{gnus-topic-unindent}). + +@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 C-c C-x +@kindex C-c C-x (Topic) +@findex gnus-topic-expire-articles +Run all expirable articles in the current group or topic through the expiry +process (if any) (@code{gnus-topic-expire-articles}). @item C-k @kindex C-k (Topic) @@ -2578,6 +3460,18 @@ ancestor) topic parameters. All valid group parameters are valid topic parameters (@pxref{Group Parameters}). +In addition, the following parameters are only valid as topic +parameters: + +@table @code +@item subscribe +When subscribing new groups by topic (@pxref{Subscription Methods}), the +@code{subscribe} topic parameter says what groups go in what topic. Its +value should be a regexp to match the groups that should go in that +topic. + +@end table + 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 @@ -2677,8 +3571,29 @@ Groups matching this regexp will always be listed in the group buffer, whether they are empty or not. -@end table - +@item gnus-group-name-charset-method-alist +@vindex gnus-group-name-charset-method-alist +An alist of method and the charset for group names. It is used to show +non-ASCII group names. + +For example: +@lisp +(setq gnus-group-name-charset-method-alist + '(((nntp "news.com.cn") . cn-gb-2312))) +@end lisp + +@item gnus-group-name-charset-group-alist +@vindex gnus-group-name-charset-group-alist +An alist of regexp of group name and the charset for group names. +It is used to show non-ASCII group names. + +For example: +@lisp +(setq gnus-group-name-charset-group-alist + '(("\\.com\\.cn:" . cn-gb-2312))) +@end lisp + +@end table @node Scanning New Messages @subsection Scanning New Messages @@ -2883,7 +3798,6 @@ * 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. @@ -2895,6 +3809,8 @@ * Saving Articles:: Ways of customizing article saving. * Decoding Articles:: Gnus can treat series of (uu)encoded articles. * Article Treatment:: The article buffer can be mangled at will. +* MIME Commands:: Doing MIMEy things with the articles. +* Charsets:: Character set issues. * Article Commands:: Doing various things with the article buffer. * Summary Sorting:: Sorting the summary buffer in various ways. * Finding the Parent:: No child support? Get the parent. @@ -2912,8 +3828,18 @@ @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. +* To From Newsgroups:: How to not display your own name. * Summary Buffer Mode Line:: You can say how the mode line should look. * Summary Highlighting:: Making the summary buffer all pretty and nice. @end menu @@ -2928,7 +3854,12 @@ fast, and too simplistic solution; and @code{mail-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. +cases. If this is unacceptable to you, use the other function instead: + +@lisp +(setq gnus-extract-address-components + 'mail-extract-address-components) +@end lisp @vindex gnus-summary-same-subject @code{gnus-summary-same-subject} is a string indicating that the current @@ -2953,7 +3884,8 @@ @item N Article number. @item S -Subject string. +Subject string. List identifiers stripped, +@code{gnus-list-identifies}. @xref{Article Hiding}. @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. @@ -2962,6 +3894,9 @@ Full @code{From} header. @item n The name (from the @code{From} header). +@item f +The name, code @code{To} header or the @code{Newsgroups} header +(@pxref{To From Newsgroups}). @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 @@ -2973,7 +3908,8 @@ @item L Number of lines in the article. @item c -Number of characters in the article. +Number of characters in the article. This specifier is not supported in some +methods (like nnfolder). @item I Indentation based on thread level (@pxref{Customizing Threading}). @item T @@ -2995,7 +3931,7 @@ @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. +or has been saved. @item i Score as a number (@pxref{Scoring}). @@ -3051,6 +3987,87 @@ This restriction may disappear in later versions of Gnus. +@node To From Newsgroups +@subsection To From Newsgroups +@cindex To +@cindex Newsgroups + +In some groups (particularly in archive groups), the @code{From} header +isn't very interesting, since all the articles there are written by +you. To display the information in the @code{To} or @code{Newsgroups} +headers instead, you need to decide three things: What information to +gather; where to display it; and when to display it. + +@enumerate +@item +@vindex gnus-extra-headers +The reading of extra header information is controlled by the +@code{gnus-extra-headers}. This is a list of header symbols. For +instance: + +@lisp +(setq gnus-extra-headers + '(To Newsgroups X-Newsreader)) +@end lisp + +This will result in Gnus trying to obtain these three headers, and +storing it in header structures for later easy retrieval. + +@item +@findex gnus-extra-header +The value of these extra headers can be accessed via the +@code{gnus-extra-header} function. Here's a format line spec that will +access the @code{X-Newsreader} header: + +@example +"%~(form (gnus-extra-header 'X-Newsreader))@@" +@end example + +@item +@vindex gnus-ignored-from-addresses +The @code{gnus-ignored-from-addresses} variable says when the @samp{%f} +summary line spec returns the @code{To}, @code{Newsreader} or +@code{From} header. If this regexp matches the contents of the +@code{From} header, the value of the @code{To} or @code{Newsreader} +headers are used instead. + +@end enumerate + +@vindex nnmail-extra-headers +A related variable is @code{nnmail-extra-headers}, which controls when +to include extra headers when generating overview (@sc{nov}) files. If +you have old overview files, you should regenerate them after changing +this variable. + +@vindex gnus-summary-line-format +You also have to instruct Gnus to display the data by changing the +@code{%n} spec to the @code{%f} spec in the +@code{gnus-summary-line-format} variable. + +In summary, you'd typically do something like the following: + +@lisp +(setq gnus-extra-headers + '(To Newsgroups)) +(setq nnmail-extra-headers gnus-extra-headers) +(setq gnus-summary-line-format + "%U%R%z%I%(%[%4L: %-20,20f%]%) %s\n") +(setq gnus-ignored-from-addresses + "Your Name Here") +@end lisp + +Now, this is mostly useful for mail groups, where you have control over +the @sc{nov} files that are created. However, if you can persuade your +nntp admin to add: + +@example +Newsgroups:full +@end example + +to the end of her @file{overview.fmt} file, then you can use that just +as you would the extra headers from the mail groups. + + @node Summary Buffer Mode Line @subsection Summary Buffer Mode Line @@ -3126,15 +4143,16 @@ @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 @code{(@var{form} . @var{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 +list where the elements are of the format @code{(@var{form} +. @var{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. +As you may have guessed, if @var{form} returns a non-@code{nil} value, +@var{face} will be applied to the line. @end table @@ -3229,6 +4247,9 @@ buffer, which might make it more inconvenient to read extremely long threads. +This variable can also be a number. In that case, center the window at +the given number of lines from the top. + @end table @@ -3404,11 +4425,24 @@ @kindex A g (Summary) @kindex g (Summary) @findex gnus-summary-show-article +@vindex gnus-summary-show-article-charset-alist (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. +If given a numerical prefix, you can do semi-manual charset stuff. +@kbd{C-u 0 g cn-gb-2312 RET} will decode the message as if it were +encoded in the @code{cn-gb-2312} charset. If you have + +@lisp +(setq gnus-summary-show-article-charset-alist + '((1 . cn-gb-2312) + (2 . big5))) +@end lisp + +then you can say @kbd{C-u 1 g} to get the same effect. + @item A < @itemx < @kindex < (Summary) @@ -3444,8 +4478,10 @@ @section Reply, Followup and Post @menu -* Summary Mail Commands:: Sending mail. -* Summary Post Commands:: Sending news. +* Summary Mail Commands:: Sending mail. +* Summary Post Commands:: Sending news. +* Summary Message Commands:: Other Message-related commands. +* Canceling and Superseding:: ``Whoops, I shouldn't have called him that.'' @end menu @@ -3490,16 +4526,25 @@ @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 +message (@code{gnus-summary-wide-reply-with-original}). This command uses the process/prefix convention. @item S o m +@itemx C-c C-f @kindex S o m (Summary) +@kindex C-c C-f (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. +(@code{gnus-summary-mail-forward}). If no prefix is given, the message +is forwarded according to the value of (@code{message-forward-as-mime}) +and (@code{message-forward-show-mml}); if the prefix is 1, decode the +message and forward directly inline; if the prefix is 2, foward message +as an rfc822 MIME section; if the prefix is 3, decode message and +forward as an rfc822 MIME section; if the prefix is 4, foward message +directly inline; otherwise, the message is forwarded as no prefix given +but use the flipped value of (@code{message-forward-as-mime}). By +default, the message is decoded and forwarded as an rfc822 MIME section. @item S m @itemx m @@ -3624,8 +4669,16 @@ @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. +(@code{gnus-summary-post-forward}). + If no prefix is given, the message is forwarded according to the value +of (@code{message-forward-as-mime}) and +(@code{message-forward-show-mml}); if the prefix is 1, decode the +message and forward directly inline; if the prefix is 2, foward message +as an rfc822 MIME section; if the prefix is 3, decode message and +forward as an rfc822 MIME section; if the prefix is 4, foward message +directly inline; otherwise, the message is forwarded as no prefix given +but use the flipped value of (@code{message-forward-as-mime}). By +default, the message is decoded and forwarded as an rfc822 MIME section. @item S O p @kindex S O p (Summary) @@ -3641,14 +4694,29 @@ @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}). +(@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}). @end table Also @pxref{(message)Header Commands} for more information. +@node Summary Message Commands +@subsection Summary Message Commands + +@table @kbd +@item S y +@kindex S y (Summary) +@findex gnus-summary-yank-message +Yank the current article into an already existing Message composition +buffer (@code{gnus-summary-yank-message}). This command prompts for +what message buffer you want to yank into, and understands the +process/prefix convention (@pxref{Process/Prefix}). + +@end table + + @node Canceling and Superseding -@section Canceling Articles +@subsection Canceling Articles @cindex canceling articles @cindex superseding articles @@ -3728,8 +4796,9 @@ @end ifinfo @menu -* Setting Marks:: How to set and remove marks. -* Setting Process Marks:: How to mark articles for later processing. +* Setting Marks:: How to set and remove marks. +* Generic Marking Commands:: How to customize the marking. +* Setting Process Marks:: How to mark articles for later processing. @end menu @@ -4047,6 +5116,44 @@ The default is @code{t}. +@node Generic Marking Commands +@subsection Generic Marking Commands + +Some people would like the command that ticks an article (@kbd{!}) go to +the next article. Others would like it to go to the next unread +article. Yet others would like it to stay on the current article. And +even though I haven't heard of anybody wanting it to go to the +previous (unread) article, I'm sure there are people that want that as +well. + +Multiply these five behaviours with five different marking commands, and +you get a potentially complex set of variable to control what each +command should do. + +To sidestep that mess, Gnus provides commands that do all these +different things. They can be found on the @kbd{M M} map in the summary +buffer. Type @kbd{M M C-h} to see them all---there are too many of them +to list in this manual. + +While you can use these commands directly, most users would prefer +altering the summary mode keymap. For instance, if you would like the +@kbd{!} command to go to the next article instead of the next unread +article, you could say something like: + +@lisp +(add-hook 'gnus-summary-mode-hook 'my-alter-summary-map) +(defun my-alter-summary-map () + (local-set-key "!" 'gnus-summary-put-mark-as-ticked-next)) +@end lisp + +or + +@lisp +(defun my-alter-summary-map () + (local-set-key "!" "MM!n")) +@end lisp + + @node Setting Process Marks @subsection Setting Process Marks @cindex setting process marks @@ -4087,6 +5194,12 @@ Mark articles that have a @code{Subject} header that matches a regular expression (@code{gnus-uu-mark-by-regexp}). +@item M P G +@kindex M P G (Summary) +@findex gnus-uu-unmark-by-regexp +Unmark articles that have a @code{Subject} header that matches a regular +expression (@code{gnus-uu-unmark-by-regexp}). + @item M P r @kindex M P r (Summary) @findex gnus-uu-mark-region @@ -4152,6 +5265,9 @@ @end table +Also see the @kbd{&} command in @pxref{Searching for Articles} for how to +set process marks based on article body contents. + @node Limiting @section Limiting @@ -4181,6 +5297,13 @@ Limit the summary buffer to articles that match some author (@code{gnus-summary-limit-to-author}). +@item / x +@kindex / x (Summary) +@findex gnus-summary-limit-to-extra +Limit the summary buffer to articles that match one of the ``extra'' +headers (@pxref{To From Newsgroups}) +(@code{gnus-summary-limit-to-extra}). + @item / u @itemx x @kindex / u (Summary) @@ -4201,7 +5324,7 @@ @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 +(@code{gnus-summary-limit-to-age}). If given a prefix, limit to articles younger than that number of days. @item / n @@ -4250,6 +5373,11 @@ Exclude all dormant articles from the limit (@code{gnus-summary-limit-exclude-dormant}). +@item / M +@kindex / M (Summary) +@findex gnus-summary-limit-exclude-marks +Exclude all marked articles (@code{gnus-summary-limit-exclude-marks}). + @item / T @kindex / T (Summary) @findex gnus-summary-limit-include-thread @@ -4353,6 +5481,17 @@ 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 @@ -4586,6 +5725,18 @@ This is a number that says how much each sub-thread should be indented. The default is 4. +@item gnus-sort-gathered-threads-function +@vindex gnus-sort-gathered-threads-function +Sometimes, particularly with mailing lists, the order in which mails +arrive locally is not necessarily the same as the order in which they +arrived on the mailing list. Consequently, when sorting sub-threads +using the default @code{gnus-thread-sort-by-number}, responses can end +up appearing before the article to which they are responding to. +Setting this variable to an alternate value +(e.g. @code{gnus-thread-sort-by-date}), in a group's parameters or in an +appropriate hook (e.g. @code{gnus-summary-generate-hook}) can produce a +more logical sub-thread ordering in such instances. + @end table @@ -4596,10 +5747,7 @@ @item gnus-parse-headers-hook @vindex gnus-parse-headers-hook -Hook run before parsing any headers. The default value is -@code{(gnus-decode-rfc1522)}, which means that QPized headers will be -slightly decoded in a hackish way. This is likely to change in the -future when Gnus becomes @sc{mime}ified. +Hook run before parsing any headers. @item gnus-alter-header-function @vindex gnus-alter-header-function @@ -4716,11 +5864,19 @@ @item T n @kindex T n (Summary) +@itemx M-C-n +@kindex M-C-n (Summary) +@itemx M-down +@kindex M-down (Summary) @findex gnus-summary-next-thread Go to the next thread (@code{gnus-summary-next-thread}). @item T p @kindex T p (Summary) +@itemx M-C-p +@kindex M-C-p (Summary) +@itemx M-up +@kindex M-up (Summary) @findex gnus-summary-prev-thread Go to the previous thread (@code{gnus-summary-prev-thread}). @@ -4766,7 +5922,10 @@ @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. +setting @code{gnus-thread-sort-functions}, which can be either a single +function, a list of functions, or a list containing functions and +@code{(not some-function)} elements. + 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}, @@ -4775,22 +5934,23 @@ 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 +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: +If you would like to sort by reverse 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)) + (not gnus-thread-sort-by-total-score))) @end lisp The threads that have highest score will be displayed first in the @@ -4989,12 +6149,12 @@ 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. +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 +Both variables are @code{nil} by default. If a group matches both variables, the group is not cached. @findex gnus-cache-generate-nov-databases @@ -5176,7 +6336,7 @@ @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 +Gnus do what you want it to. You can use any of the six ready-made functions below, or you can create your own. @table @code @@ -5550,7 +6710,7 @@ say something like: @lisp (setq gnus-uu-user-view-rules - (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\"))) + (list '("\\\\.au$" "sox %s -t .aiff > /dev/audio"))) @end lisp @item gnus-uu-user-view-rules-end @@ -5662,7 +6822,7 @@ 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 +embellishments. The digesting almost conforms to RFC 1153---no easy way to specify any meaningful volume and issue numbers were found, so I simply dropped them. @@ -5765,6 +6925,7 @@ * Article Buttons:: Click on URLs, Message-IDs, addresses and the like. * Article Date:: Grumble, UT! * Article Signature:: What is a signature? +* Article Miscellania:: Various other stuff. @end menu @@ -5773,7 +6934,7 @@ @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. +you want it to look like technicolor fruit salad. @table @kbd @@ -5785,19 +6946,15 @@ (@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 @code{(@var{regexp} -@var{name} @var{content})}. @var{regexp} is a regular expression for matching the +variable, which is a list where each element has the form +@code{(@var{regexp} @var{name} @var{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 @@ -5885,8 +7042,8 @@ @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} +like @samp{_this_} or @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 @@ -5905,6 +7062,12 @@ ("\\*\\(\\w+\\)\\*" 0 1 gnus-emphasis-bold))) @end lisp +@cindex slash +@cindex asterisk +@cindex underline +@cindex / +@cindex * + @vindex gnus-emphasis-underline @vindex gnus-emphasis-bold @vindex gnus-emphasis-italic @@ -5928,6 +7091,13 @@ (copy-face 'red 'gnus-emphasis-italic) @end lisp +@vindex gnus-group-highlight-words-alist + +If you want to highlight arbitrary words, you can use the +@code{gnus-group-highlight-words-alist} variable, which uses the same +syntax as @code{gnus-emphasis-alist}. The @code{highlight-words} group +parameter (@pxref{Group Parameters}) can also be used. + @xref{Customizing Articles}, for how to fontize articles automatically. @@ -5945,7 +7115,7 @@ @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. +headers, PGP, cited text and the signature. @item W W h @kindex W W h (Summary) @@ -5965,13 +7135,47 @@ Hide signature (@code{gnus-article-hide-signature}). @xref{Article Signature}. +@item W W l +@kindex W W l (Summary) +@findex gnus-article-hide-list-identifiers +@vindex gnus-list-identifiers +Strip list identifiers specified in @code{gnus-list-identifiers}. These +are strings some mailing list servers add to the beginning of all +@code{Subject} headers---for example, @samp{[zebra 4711]}. Any leading +@samp{Re: } is skipped before stripping. @code{gnus-list-identifiers} +may not contain @code{\\(..\\)}. + +@table @code + +@item gnus-list-identifiers +@vindex gnus-list-identifiers +A regular expression that matches list identifiers to be removed from +subject. This can also be a list of regular expressions. + +@end table + @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. +signature has been hidden. For example, to automatically verify +articles that have signatures in them do: +@lisp +;;; Hide pgp cruft if any. + +(setq gnus-treat-strip-pgp t) + +;;; 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) @@ -5979,6 +7183,25 @@ Hide @sc{pem} (privacy enhanced messages) cruft (@code{gnus-article-hide-pem}). +@item W W B +@kindex W W B (Summary) +@findex gnus-article-strip-banner +@cindex banner +@cindex OneList +@cindex stripping advertisments +@cindex advertisments +Strip the banner specified by the @code{banner} group parameter +(@code{gnus-article-strip-banner}). This is mainly used to hide those +annoying banners and/or signatures that some mailing lists and moderated +groups adds to all the messages. The way to use this function is to add +the @code{banner} group parameter (@pxref{Group Parameters}) to the +group you want banners stripped from. The parameter either be a string, +which will be interpreted as a regular expression matching text to be +removed, or the symbol @code{signature}, meaning that the (last) +signature should be removed, or other symbol, meaning that the +corresponding regular expression in @code{gnus-article-banner-alist} is +used. + @item W W c @kindex W W c (Summary) @findex gnus-article-hide-citation @@ -6009,7 +7232,9 @@ @item gnus-cited-lines-visible @vindex gnus-cited-lines-visible -The number of lines at the beginning of the cited text to leave shown. +The number of lines at the beginning of the cited text to leave +shown. This can also be a cons cell with the number of lines at the top +and bottom of the text, respectively, to remain visible. @end table @@ -6038,7 +7263,7 @@ 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}). +have happen automatically (@pxref{Customizing Articles}). @end table @@ -6072,7 +7297,7 @@ @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. +delimiters. @item W r @kindex W r (Summary) @@ -6089,7 +7314,9 @@ is rumored to have employed this form of, uh, somewhat weak encryption. @item W t +@item t @kindex W t (Summary) +@kindex t (Summary) @findex gnus-summary-toggle-header Toggle whether to display all headers in the article buffer (@code{gnus-summary-toggle-header}). @@ -6100,12 +7327,6 @@ 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 run the article through @sc{mime} before displaying -(@code{gnus-summary-toggle-mime}). - @item W o @kindex W o (Summary) @findex gnus-article-treat-overstrike @@ -6114,22 +7335,41 @@ @item W d @kindex W d (Summary) @findex gnus-article-treat-dumbquotes -Treat M******** sm*rtq**t*s (@code{gnus-article-treat-dumbquotes}). +@vindex gnus-article-dumbquotes-map +@cindex Smartquotes +@cindex M******** sm*rtq**t*s +@cindex Latin 1 +Treat M******** sm*rtq**t*s according to +@code{gnus-article-dumbquotes-map} +(@code{gnus-article-treat-dumbquotes}). Note that this function guesses +whether a character is a sm*rtq**t* or not, so it should only be used +interactively. @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. +Do word wrap (@code{gnus-article-fill-cited-article}). You can give the command a numerical prefix to specify the width to use when filling. +@item W Q +@kindex W Q (Summary) +@findex gnus-article-fill-long-lines +Fill long lines (@code{gnus-article-fill-long-lines}). + +@item W C +@kindex W C (Summary) +@findex gnus-article-capitalize-sentences +Capitalize the first word in each sentence +(@code{gnus-article-capitalize-sentences}). + @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) +Translate CRLF pairs (i. e., @samp{^M}s on the end of the lines) into LF +(this takes care of DOS line endings), and then translate any remaining +CRs into LF (this takes care of Mac line endings) (@code{gnus-article-remove-cr}). @item W q @@ -6139,7 +7379,34 @@ Quoted-Printable is one common @sc{mime} encoding employed when sending non-ASCII (i. e., 8-bit) articles. It typically makes strings like @samp{déjà vu} look like @samp{d=E9j=E0 vu}, which doesn't look very -readable to me. +readable to me. Note that the this is usually done automatically by +Gnus if the message in question has a @code{Content-Transfer-Encoding} +header that says that this encoding has been done. + +@item W 6 +@kindex W 6 (Summary) +@findex gnus-article-de-base64-unreadable +Treat base64 (@code{gnus-article-de-base64-unreadable}). +Base64 is one common @sc{mime} encoding employed when sending non-ASCII +(i. e., 8-bit) articles. Note that the this is usually done +automatically by Gnus if the message in question has a +@code{Content-Transfer-Encoding} header that says that this encoding has +been done. + +@item W Z +@kindex W Z (Summary) +@findex gnus-article-decode-HZ +Treat HZ or HZP (@code{gnus-article-decode-HZ}). HZ (or HZP) is one +common encoding employed when sending Chinese articles. It typically +makes strings look like @samp{~@{<:Ky2;S@{#,NpJ)l6HK!#~@}}. + +@item W h +@kindex W h (Summary) +@findex gnus-article-wash-html +Treat HTML (@code{gnus-article-wash-html}). +Note that the this is usually done automatically by Gnus if the message +in question has a @code{Content-Type} header that says that this type +has been done. @item W f @kindex W f (Summary) @@ -6148,6 +7415,11 @@ @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. @@ -6155,12 +7427,18 @@ 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 +The default action under Emacs is to fork off the @code{display} +program@footnote{@code{display} is from the ImageMagick package. For the +@code{uncompface} and @code{icontopbm} programs look for a package +like `compface' or `faces-xface' on a GNU/Linux system.} +to view the face. Under XEmacs or Emacs 21+ with suitable image +support, 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 +external programs from the @code{pbmplus} package and +friends.@footnote{On a GNU/Linux system look for packages with names +like @code{netpbm} or @code{libgr-progs}.}) If you want to have this function in the display hook, it should probably come last. @@ -6176,6 +7454,12 @@ Add clickable buttons to the article headers (@code{gnus-article-add-buttons-to-head}). +@item W W H +@kindex W W H (Summary) +@findex gnus-article-strip-headers-from-body +Strip headers like the @code{X-No-Archive} header from the beginning of +article bodies (@code{gnus-article-strip-headers-from-body}). + @item W E l @kindex W E l (Summary) @findex gnus-article-strip-leading-blank-lines @@ -6213,6 +7497,12 @@ Remove all white space from the beginning of all lines of the article body (@code{gnus-article-strip-leading-space}). +@item W E e +@kindex W E e (Summary) +@findex gnus-article-strip-trailing-space +Remove all white space from the end of all lines of the article +body (@code{gnus-article-strip-trailing-space}). + @end table @xref{Customizing Articles}, for how to wash articles automatically. @@ -6284,7 +7574,7 @@ (HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR) @end lisp -@var{HEADER} is a regular expression. +@var{header} is a regular expression. @item gnus-button-url-regexp @vindex gnus-button-url-regexp @@ -6348,8 +7638,20 @@ @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 +(@code{gnus-article-date-lapsed}). It looks something like: + +@example +X-Sent: 9 years, 6 weeks, 4 days, 9 hours, 3 minutes, 28 seconds ago +@end example + +The value of @code{gnus-article-date-lapsed-new-header} determines +whether this header will just be added below the old Date one, or will +replace it. + +An advantage of using Gnus to read mail is that it converts simple bugs +into wonderful absurdities. + +If you want to have this line updated continually, you can put @lisp (gnus-start-date-timer) @@ -6405,7 +7707,7 @@ @vindex gnus-signature-limit @code{gnus-signature-limit} provides a limit to what is considered a -signature. +signature when displaying articles. @enumerate @item @@ -6436,6 +7738,247 @@ signature after all. +@node Article Miscellania +@subsection Article Miscellania + +@table @kbd +@item A t +@kindex A t (Summary) +@findex gnus-article-babel +Translate the article from one language to another +(@code{gnus-article-babel}). + +@end table + + +@node MIME Commands +@section @sc{mime} Commands +@cindex MIME decoding +@cindex attachments +@cindex viewing attachments + +The following commands all understand the numerical prefix. For +instance, @kbd{3 b} means ``view the third @sc{mime} part''. + +@table @kbd +@item b +@itemx K v +@kindex b (Summary) +@kindex K v (Summary) +View the @sc{mime} part. + +@item K o +@kindex K o (Summary) +Save the @sc{mime} part. + +@item K c +@kindex K c (Summary) +Copy the @sc{mime} part. + +@item K e +@kindex K e (Summary) +View the @sc{mime} part externally. + +@item K i +@kindex K i (Summary) +View the @sc{mime} part internally. + +@item K | +@kindex K | (Summary) +Pipe the @sc{mime} part to an external command. +@end table + +The rest of these @sc{mime} commands do not use the numerical prefix in +the same manner: + +@table @kbd +@item K b +@kindex K b (Summary) +Make all the @sc{mime} parts have buttons in front of them. This is +mostly useful if you wish to save (or perform other actions) on inlined +parts. + +@item K m +@kindex K m (Summary) +@findex gnus-summary-repair-multipart +Some multipart messages are transmitted with missing or faulty headers. +This command will attempt to ``repair'' these messages so that they can +be viewed in a more pleasant manner +(@code{gnus-summary-repair-multipart}). + +@item X m +@kindex X m (Summary) +@findex gnus-summary-save-parts +Save all parts matching a @sc{mime} type to a directory +(@code{gnus-summary-save-parts}). Understands the process/prefix +convention (@pxref{Process/Prefix}). + +@item M-t +@kindex M-t (Summary) +@findex gnus-summary-display-buttonized +Toggle the buttonized display of the article buffer +(@code{gnus-summary-toggle-display-buttonized}). + +@item W M w +@kindex W M w (Summary) +Decode RFC 2047-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}). + +@item W M v +@kindex W M v (Summary) +View all the @sc{mime} parts in the current article +(@code{gnus-mime-view-all-parts}). + +@end table + +Relevant variables: + +@table @code +@item gnus-ignored-mime-types +@vindex gnus-ignored-mime-types +This is a list of regexps. @sc{mime} types that match a regexp from +this list will be completely ignored by Gnus. The default value is +@code{nil}. + +To have all Vcards be ignored, you'd say something like this: + +@lisp +(setq gnus-ignored-mime-types + '("text/x-vcard")) +@end lisp + +@item gnus-unbuttonized-mime-types +@vindex gnus-unbuttonized-mime-types +This is a list of regexps. @sc{mime} types that match a regexp from +this list won't have @sc{mime} buttons inserted unless they aren't +displayed. The default value is @code{(".*/.*")}. + +@item gnus-article-mime-part-function +@vindex gnus-article-mime-part-function +For each @sc{mime} part, this function will be called with the @sc{mime} +handle as the parameter. The function is meant to be used to allow +users to gather information from the article (e. g., add Vcard info to +the bbdb database) or to do actions based on parts (e. g., automatically +save all jpegs into some directory). + +Here's an example function the does the latter: + +@lisp +(defun my-save-all-jpeg-parts (handle) + (when (equal (car (mm-handle-type handle)) "image/jpeg") + (with-temp-buffer + (insert (mm-get-part handle)) + (write-region (point-min) (point-max) + (read-file-name "Save jpeg to: "))))) +(setq gnus-article-mime-part-function + 'my-save-all-jpeg-parts) +@end lisp + +@vindex gnus-mime-multipart-functions +@item gnus-mime-multipart-functions +Alist of @sc{mime} multipart types and functions to handle them. + +@end table + + +@node Charsets +@section Charsets +@cindex charsets + +People use different charsets, and we have @sc{mime} to let us know what +charsets they use. Or rather, we wish we had. Many people use +newsreaders and mailers that do not understand or use @sc{mime}, and +just send out messages without saying what character sets they use. To +help a bit with this, some local news hierarchies have policies that say +what character set is the default. For instance, the @samp{fj} +hierarchy uses @code{iso-2022-jp-2}. + +@vindex gnus-group-charset-alist +This knowledge is encoded in the @code{gnus-group-charset-alist} +variable, which is an alist of regexps (to match group names) and +default charsets to be used when reading these groups. + +In addition, some people do use soi-disant @sc{mime}-aware agents that +aren't. These blitely mark messages as being in @code{iso-8859-1} even +if they really are in @code{koi-8}. To help here, the +@code{gnus-newsgroup-ignored-charsets} variable can be used. The +charsets that are listed here will be ignored. The variable can be set +on a group-by-group basis using the group parameters (@pxref{Group +Parameters}). The default value is @code{(unknown-8bit)}, which is +something some agents insist on having in there. + +@vindex gnus-group-posting-charset-alist +When posting, @code{gnus-group-posting-charset-alist} is used to +determine which charsets should not be encoded using the @sc{mime} +encodings. For instance, some hierarchies discourage using +quoted-printable header encoding. + +This variable is an alist of regexps and permitted unencoded charsets +for posting. Each element of the alist has the form @code{(}@var{test +header body-list}@code{)}, where: + +@table @var +@item test +is either a regular expression matching the newsgroup header or a +variable to query, +@item header +is the charset which may be left unencoded in the header (@code{nil} +means encode all charsets), +@item body-list +is a list of charsets which may be encoded using 8bit content-transfer +encoding in the body, or one of the special values @code{nil} (always +encode using quoted-printable) or @code{t} (always use 8bit). +@end table + +@cindex Russian +@cindex koi8-r +@cindex koi8-u +@cindex iso-8859-5 +@cindex coding system aliases +@cindex preferred charset + +Other charset tricks that may be useful, although not Gnus-specific: + +If there are several @sc{mime} charsets that encode the same Emacs +charset, you can choose what charset to use by saying the following: + +@lisp +(put-charset-property 'cyrillic-iso8859-5 + 'preferred-coding-system 'koi8-r) +@end lisp + +This means that Russian will be encoded using @code{koi8-r} instead of +the default @code{iso-8859-5} @sc{mime} charset. + +If you want to read messages in @code{koi8-u}, you can cheat and say + +@lisp +(define-coding-system-alias 'koi8-u 'koi8-r) +@end lisp + +This will almost do the right thing. + +And finally, to read charsets like @code{windows-1251}, you can say +something like + +@lisp +(codepage-setup 1251) +(define-coding-system-alias 'windows-1251 'cp1251) +@end lisp + + @node Article Commands @section Article Commands @@ -6488,6 +8031,11 @@ @findex gnus-summary-sort-by-lines Sort by lines (@code{gnus-summary-sort-by-lines}). +@item C-c C-s C-c +@kindex C-c C-s C-c (Summary) +@findex gnus-summary-sort-by-chars +Sort by article length (@code{gnus-summary-sort-by-chars}). + @item C-c C-s C-i @kindex C-c C-s C-i (Summary) @findex gnus-summary-sort-by-score @@ -6576,6 +8124,20 @@ updating the spool you are reading from, but that's not really necessary. +It can also be a list of select methods, as well as the special symbol +@code{current}, which means to use the current select method. If it +is a list, Gnus will try all the methods in the list until it finds a +match. + +Here's an example setting that will first try the current method, and +then ask Deja if that fails: + +@lisp +(setq gnus-refer-article-method + '(current + (nnweb "refer" (nnweb-type dejanews)))) +@end lisp + 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 @@ -6622,7 +8184,7 @@ (@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 +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.) @@ -6638,7 +8200,7 @@ 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 +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. @@ -6879,8 +8441,10 @@ @kindex B m (Summary) @cindex move mail @findex gnus-summary-move-article +@vindex gnus-preserve-marks Move the article from one mail group to another -(@code{gnus-summary-move-article}). +(@code{gnus-summary-move-article}). Marks will be preserved if +@var{gnus-preserve-marks} is non-@code{nil} (which is the default). @item B c @kindex B c (Summary) @@ -6888,7 +8452,8 @@ @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}). +(@code{gnus-summary-copy-article}). Marks will be preserved if +@var{gnus-preserve-marks} is non-@code{nil} (which is the default). @item B B @kindex B B (Summary) @@ -6913,6 +8478,8 @@ @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. +Marks will be preserved if @var{gnus-preserve-marks} is non-@code{nil} +(which is the default). @item B w @itemx e @@ -6999,6 +8566,11 @@ 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}, @@ -7010,6 +8582,22 @@ any other article. If this variable is @code{t}, it won't display the article---it'll be as if it never existed. +@vindex gnus-alter-articles-to-read-function +@item gnus-alter-articles-to-read-function +This function, which takes two parameters (the group name and the list +of articles to be selected), is called to allow the user to alter the +list of articles to be selected. + +For instance, the following function adds the list of cached articles to +the list in one particular group: + +@lisp +(defun my-add-cached-articles (group articles) + (if (string= group "some.group") + (append gnus-newsgroup-cached articles) + articles)) +@end lisp + @end table @@ -7070,10 +8658,14 @@ @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. +This command will prompt you for a header, 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 the header is an empty +string, the match is done on the entire article. If given a prefix, +search backward instead. + +For instance, @kbd{& RET some.*string #} will put the process mark on +all articles that have heads or bodies that match @samp{some.*string}. @item M-& @kindex M-& (Summary) @@ -7106,8 +8698,10 @@ @table @kbd -@item C-d +@item A D +@itemx C-d @kindex C-d (Summary) +@kindex A 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 @@ -7149,6 +8743,12 @@ Edit the group parameters (@pxref{Group Parameters}) of the current group (@code{gnus-summary-edit-parameters}). +@item M-C-a +@kindex M-C-a (Summary) +@findex gnus-summary-customize-parameters +Customize the group parameters (@pxref{Group Parameters}) of the current +group (@code{gnus-summary-customize-parameters}). + @end table @@ -7171,7 +8771,7 @@ @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 +(@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 @@ -7246,8 +8846,9 @@ @end table @vindex gnus-exit-group-hook -@code{gnus-exit-group-hook} is called when you exit the current -group. +@code{gnus-exit-group-hook} is called when you exit the current group +with an ``updating'' exit. For instance @kbd{Q} +(@code{gnus-summary-exit-no-update}) does not call this hook. @findex gnus-summary-wake-up-the-dead @findex gnus-dead-summary-mode @@ -7499,14 +9100,13 @@ 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. +You can hide further boring headers by setting +@code{gnus-treat-hide-boring-header} to @code{head}. 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 @@ -7554,71 +9154,193 @@ 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-show-mime-method -@vindex gnus-strict-mime -@findex metamail-buffer -Gnus handles @sc{mime} by pushing the articles through -@code{gnus-show-mime-method}, which is @code{metamail-buffer} by -default. This function calls the external @code{metamail} program to -actually do the work. One common problem with this program is that is -thinks that it can't display 8-bit things in the Emacs buffer. To tell -it the truth, put something like the following in your -@file{.bash_profile} file. (You do use @code{bash}, don't you?) - -@example -export MM_CHARSET="iso-8859-1" -@end example - -For more information on @code{metamail}, see its manual page. - -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. - -It might be best to just use the toggling functions from the summary -buffer to avoid getting nasty surprises. (For instance, you enter the +@vindex gnus-display-mime-function +@findex gnus-display-mime +Gnus pushes @sc{mime} articles through @code{gnus-display-mime-function} +to display the @sc{mime} parts. This is @code{gnus-display-mime} by +default, which creates a bundle of clickable buttons that can be used to +display, save and manipulate the @sc{mime} objects. + +The following commands are available when you have placed point over a +@sc{mime} button: + +@table @kbd +@findex gnus-article-press-button +@item RET (Article) +@itemx BUTTON-2 (Article) +Toggle displaying of the @sc{mime} object +(@code{gnus-article-press-button}). + +@findex gnus-mime-view-part +@item M-RET (Article) +@itemx v (Article) +Prompt for a method, and then view the @sc{mime} object using this +method (@code{gnus-mime-view-part}). + +@findex gnus-mime-save-part +@item o (Article) +Prompt for a file name, and then save the @sc{mime} object +(@code{gnus-mime-save-part}). + +@findex gnus-mime-copy-part +@item c (Article) +Copy the @sc{mime} object to a fresh buffer and display this buffer +(@code{gnus-mime-copy-part}). + +@findex gnus-mime-view-part-as-type +@item t (Article) +View the @sc{mime} object as if it were a different @sc{mime} media type +(@code{gnus-mime-view-part-as-type}). + +@findex gnus-mime-pipe-part +@item | (Article) +Output the @sc{mime} object to a process (@code{gnus-mime-pipe-part}). + +@findex gnus-mime-inline-part +@item i (Article) +Insert the contents of the @sc{mime} object into the buffer +(@code{gnus-mime-inline-part}) as text/plain. If given a prefix, insert +the raw contens without decoding. If given a numerical prefix, you can +do semi-manual charset stuff (see +@code{gnus-summary-show-article-charset-alist} in @pxref{Paging the +Article}). + +@findex gnus-mime-action-on-part +@item . (Article) +Interactively run an action on the @sc{mime} object +(@code{gnus-mime-action-on-part}). + +@end table + +Gnus will display some @sc{mime} objects automatically. The way Gnus +determines which parts to do this with is described in the Emacs MIME +manual. + +It might be best to just use the toggling functions from the article +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.) +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. +Also see @pxref{MIME Commands}. + @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. +A slew of functions for customizing how the articles are to look like +exist. You can call these functions interactively, or you can have them +called automatically when you select the articles. + +To have them called automatically, you should set the corresponding +``treatment'' variable. For instance, to have headers hidden, you'd set +@code{gnus-treat-hide-headers}. Below is a list of variables that can +be set, but first we discuss the values these variables can have. + +Note: Some values, while valid, make little sense. Check the list below +for sensible values. + +@enumerate +@item +@code{nil}: Don't do this treatment. + +@item +@code{t}: Do this treatment on all body parts. + +@item +@code{head}: Do the treatment on the headers. + +@item +@code{last}: Do this treatment on the last part. + +@item +An integer: Do this treatment on all body parts that have a length less +than this number. + +@item +A list of strings: Do this treatment on all body parts that are in +articles that are read in groups that have names that match one of the +regexps in the list. + +@item +A list where the first element is not a string: + +The list is evaluated recursively. The first element of the list is a +predicate. The following predicates are recognized: @code{or}, +@code{and}, @code{not} and @code{typep}. Here's an example: + +@lisp +(or last + (typep "text/x-vcard")) +@end lisp + +@end enumerate + +You may have noticed that the word @dfn{part} is used here. This refers +to the fact that some messages are @sc{mime} multipart articles that may +be divided into several parts. Articles that are not multiparts are +considered to contain just a single part. + +@vindex gnus-article-treat-types +Are the treatments applied to all sorts of multipart parts? Yes, if you +want to, but by default, only @samp{text/plain} parts are given the +treatment. This is controlled by the @code{gnus-article-treat-types} +variable, which is a list of regular expressions that are matched to the +type of the part. This variable is ignored if the value of the +controlling variable is a predicate list, as described above. + +The following treatment options are available. The easiest way to +customize this is to examine the @code{gnus-article-treat} customization +group. Values in parenthesis are suggested sensible values. Others are +possible but those listed are probably sufficient for most people. + +@table @code +@item gnus-treat-highlight-signature (t, last) +@item gnus-treat-buttonize (t, integer) +@item gnus-treat-buttonize-head (head) +@item gnus-treat-emphasize (t, head, integer) +@item gnus-treat-fill-article (t, integer) +@item gnus-treat-strip-cr (t, integer) +@item gnus-treat-hide-headers (head) +@item gnus-treat-hide-boring-headers (head) +@item gnus-treat-hide-signature (t, last) +@item gnus-treat-hide-citation (t, integer) +@item gnus-treat-strip-pgp (t, last, integer) +@item gnus-treat-strip-pem (t, last, integer) +@item gnus-treat-highlight-headers (head) +@item gnus-treat-highlight-citation (t, integer) +@item gnus-treat-highlight-signature (t, last, integer) +@item gnus-treat-date-ut (head) +@item gnus-treat-date-local (head) +@item gnus-treat-date-lapsed (head) +@item gnus-treat-date-original (head) +@item gnus-treat-strip-headers-in-body (t, integer) +@item gnus-treat-strip-trailing-blank-lines (t, last, integer) +@item gnus-treat-strip-leading-blank-lines (t, integer) +@item gnus-treat-strip-multiple-blank-lines (t, integer) +@item gnus-treat-overstrike (t, integer) +@item gnus-treat-display-xface (head) +@item gnus-treat-display-smileys (t, integer) +@item gnus-treat-display-picons (head) +@item gnus-treat-capitalize-sentences (t, integer) +@item gnus-treat-fill-long-lines (t, integer) +@item gnus-treat-play-sounds +@item gnus-treat-translate +@end table + +@vindex gnus-part-display-hook +You can, of course, write your own functions to be called from +@code{gnus-part-display-hook}. The functions are called narrowed to the +part, 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. @node Article Keymap @@ -7694,6 +9416,12 @@ (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 @@ -7701,12 +9429,6 @@ 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. @@ -7720,14 +9442,16 @@ @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: +accepts the same format specifications as that variable, with two +extensions: @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. +@item m +The number of @sc{mime} parts in the article. @end table @vindex gnus-break-pages @@ -7757,11 +9481,10 @@ @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. +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}. Where the message will be posted/mailed to depends +on your setup (@pxref{Posting Server}). @menu * Mail:: Mailing and replying. @@ -7794,6 +9517,12 @@ If non-@code{nil}, add a @code{to-list} group parameter to mail groups that have none when you do a @kbd{a}. +@item message-send-mail-partially-limit +@vindex message-send-mail-partially-limit +The limitation of messages sent as message/partial. +The lower bound of message size in characters, beyond which the message +should be sent in several parts. If it is nil, the size is unlimited. + @end table @@ -7857,7 +9586,7 @@ 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}. +@code{current}. @node Mail and Post @@ -7893,6 +9622,21 @@ (add-hook 'message-send-hook 'ispell-message) @end lisp +If you want to change the @code{ispell} dictionary based on what group +you're in, you could say something like the following: + +@lisp +(add-hook 'gnus-select-group-hook + (lambda () + (cond + ((string-match "^de\\." gnus-newsgroup-name) + (ispell-change-dictionary "deutsch")) + (t + (ispell-change-dictionary "english"))))) +@end lisp + +Modify to suit your needs. + @node Archived Messages @section Archived Messages @@ -7984,8 +9728,7 @@ (setq gnus-message-archive-group '((if (message-news-p) "misc-news" - (concat "mail." (format-time-string - "%Y-%m" (current-time)))))) + (concat "mail." (format-time-string "%Y-%m"))))) @end lisp (XEmacs 19.13 doesn't have @code{format-time-string}, so you'll have to @@ -8065,31 +9808,37 @@ 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 +If it is the symbol @code{header}, then Gnus will look for header that +match the next element in the match, and compare that to the last header +in the match. 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 @code{(@var{name} . @var{value})} pair. The attribute name -can be one of @code{signature}, @code{signature-file}, +attribute consists of a @code{(@var{name} . @var{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). +article; if the value is @code{nil}, the header name will be removed. +If the attribute name is @code{eval}, the form is evaluated, and the +result is thrown away. + +The attribute value can be a string (used verbatim), a function with +zero arguments (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). The functions and sexps are called/@code{eval}ed in the +message buffer that is being set up. The headers of the current article +are available through the @code{message-reply-headers} variable. 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 +of the @code{message-news-p} and @code{message-mail-p} functions. + +@findex message-mail-p +@findex message-news-p So here's a new example: @@ -8104,9 +9853,11 @@ (signature my-funny-signature-randomizer)) ((equal (system-name) "gnarly") (signature my-quote-randomizer)) - (message-this-is-news + ((message-news-p) (signature my-news-signature)) - (posting-from-work-p + (header "From\\|To" "larsi.*org" + (Organization "Somewhere, Inc.")) + ((posting-from-work-p) (signature-file "~/.work-signature") (address "user@@bar.foo") (body "You are fired.\n\nSincerely, your boss.") @@ -8243,6 +9994,7 @@ * The Server Buffer:: Making and editing virtual servers. * Getting News:: Reading USENET news with Gnus. * Getting Mail:: Reading your personal mail with Gnus. +* Browsing the Web:: Getting messages from a plethora of Web sources. * Other Sources:: Reading directories, files, SOUP packets. * Combined Groups:: Combining groups into one group. * Gnus Unplugged:: Reading news and mail offline. @@ -8445,6 +10197,9 @@ (nnmh-get-new-mail nil)) @end lisp +@cindex proxy +@cindex firewall + 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. @@ -8688,8 +10443,8 @@ @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 +@samp{default}, @samp{port} and @samp{force}. (The latter is not a +valid @file{.netrc}/@code{ftp} token, which is almost the only way the @file{.authinfo} file format deviates from the @file{.netrc} file format.) @@ -9044,11 +10799,13 @@ course. @menu +* Mail in a Newsreader:: Important introductory notes. * Getting Started Reading Mail:: A simple cookbook example. * Splitting Mail:: How to create mail groups. +* Mail Sources:: How to tell Gnus where to get mail from. * Mail 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. +* Group Mail Splitting:: Use group customize to drive mail splitting. * Incorporating Old Mail:: What about the old mail you have? * Expiring Mail:: Getting rid of unwanted mail. * Washing Mail:: Removing gruft from the mail you get. @@ -9058,6 +10815,71 @@ @end menu +@node Mail in a Newsreader +@subsection Mail in a Newsreader + +If you are used to traditional mail readers, but have decided to switch +to reading mail with Gnus, you may find yourself experiencing something +of a culture shock. + +Gnus does not behave like traditional mail readers. If you want to make +it behave that way, you can, but it's an uphill battle. + +Gnus, by default, handles all its groups using the same approach. This +approach is very newsreaderly---you enter a group, see the new/unread +messages, and when you read the messages, they get marked as read, and +you don't see them any more. (Unless you explicitly ask for them.) + +In particular, you do not do anything explicitly to delete messages. + +Does this mean that all the messages that have been marked as read are +deleted? How awful! + +But, no, it means that old messages are @dfn{expired} according to some +scheme or other. For news messages, the expire process is controlled by +the news administrator; for mail, the expire process is controlled by +you. The expire process for mail is covered in depth in @pxref{Expiring +Mail}. + +What many Gnus users find, after using it a while for both news and +mail, is that the transport mechanism has very little to do with how +they want to treat a message. + +Many people subscribe to several mailing lists. These are transported +via SMTP, and are therefore mail. But we might go for weeks without +answering, or even reading these messages very carefully. We may not +need to save them because if we should need to read one again, they are +archived somewhere else. + +Some people have local news groups which have only a handful of readers. +These are transported via @sc{nntp}, and are therefore news. But we may need +to read and answer a large fraction of the messages very carefully in +order to do our work. And there may not be an archive, so we may need +to save the interesting messages the same way we would personal mail. + +The important distinction turns out to be not the transport mechanism, +but other factors such as how interested we are in the subject matter, +or how easy it is to retrieve the message if we need to read it again. + +Gnus provides many options for sorting mail into ``groups'' which behave +like newsgroups, and for treating each group (whether mail or news) +differently. + +Some users never get comfortable using the Gnus (ahem) paradigm and wish +that Gnus should grow up and be a male, er, mail reader. It is possible +to whip Gnus into a more mailreaderly being, but, as said before, it's +not easy. People who prefer proper mail readers should try @sc{vm} +instead, which is an excellent, and proper, mail reader. + +I don't mean to scare anybody off, but I want to make it clear that you +may be required to learn a new way of thinking about messages. After +you've been subjected to The Gnus Way, you will come to love it. I can +guarantee it. (At least the guy who sold me the Emacs Subliminal +Brain-Washing Functions that I've put into Gnus did guarantee it. You +Will Be Assimilated. You Love Gnus. You Love The Gnus Mail Way. +You Do.) + + @node Getting Started Reading Mail @subsection Getting Started Reading Mail @@ -9123,7 +10945,7 @@ insert sub-expressions from the matched text. For instance: @lisp -("list.\\1" "From:.*\\(.*\\)-list@@majordomo.com") +("list.\\1" "From:.* \\(.*\\)-list@@majordomo.com") @end lisp The second element can also be a function. In that case, it will be @@ -9167,7 +10989,10 @@ @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. +can use the @kbd{M-x nnmail-split-history} command. If you wish to see +where re-spooling messages would put the messages, you can use +@code{gnus-summary-respool-trace} and related commands (@pxref{Mail +Group Commands}). 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 @@ -9180,6 +11005,498 @@ month's rent money. +@node Mail Sources +@subsection Mail Sources + +Mail can be gotten from many different sources---the mail spool, from a +POP mail server, from a procmail directory, or from a maildir, for +instance. + +@menu +* Mail Source Specifiers:: How to specify what a mail source is. +* Mail Source Customization:: Some variables that influence things. +* Fetching Mail:: Using the mail source specifiers. +@end menu + + +@node Mail Source Specifiers +@subsubsection Mail Source Specifiers +@cindex POP +@cindex mail server +@cindex procmail +@cindex mail spool +@cindex mail source + +You tell Gnus how to fetch mail by setting @code{mail-sources} +(@pxref{Fetching Mail}) to a @dfn{mail source specifier}. + +Here's an example: + +@lisp +(pop :server "pop3.mailserver.com" :user "myname") +@end lisp + +As can be observed, a mail source specifier is a list where the first +element is a @dfn{mail source type}, followed by an arbitrary number of +@dfn{keywords}. Keywords that are not explicitly specified are given +default values. + +The following mail source types are available: + +@table @code +@item file +Get mail from a single file; typically from the mail spool. + +Keywords: + +@table @code +@item :path +The path of the file. Defaults to the value of the @code{MAIL} +environment variable or @file{/usr/mail/spool/user-name}. +@end table + +An example file mail source: + +@lisp +(file :path "/usr/spool/mail/user-name") +@end lisp + +Or using the default path: + +@lisp +(file) +@end lisp + +If the mail spool file is not located on the local machine, it's best to +use POP or @sc{imap} or the like to fetch the mail. You can not use ange-ftp +file names here---it has no way to lock the mail spool while moving the +mail. + +If it's impossible to set up a proper server, you can use ssh instead. + +@lisp +(setq mail-sources + '((file :prescript "ssh host bin/getmail >%t"))) +@end lisp + +The @samp{getmail} script would look something like the following: + +@example +#!/bin/sh +# getmail - move mail from spool to stdout +# flu@@iki.fi + +MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail +TMP=$HOME/Mail/tmp +rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP +@end example + +Alter this script to fit find the @samp{movemail} you want to use. + + +@item directory +Get mail from several files in a directory. This is typically used when +you have procmail split the incoming mail into several files. Setting +@code{nnmail-scan-directory-mail-source-once} to non-nil force Gnus to +scan the mail source only once. + +Keywords: + +@table @code +@item :path +The path of the directory where the files are. There is no default +value. + +@item :suffix +Only files ending with this suffix are used. The default is +@samp{.spool}. + +@item :predicate +Only files that have this predicate return non-@code{nil} are returned. +The default is @code{identity}. This is used as an additional +filter---only files that have the right suffix @emph{and} satisfy this +predicate are considered. + +@item :prescript +@itemx :postscript +Script run before/after fetching mail. + +@end table + +An example directory mail source: + +@lisp +(directory :path "/home/user-name/procmail-dir/" + :suffix ".prcml") +@end lisp + +@item pop +Get mail from a POP server. + +Keywords: + +@table @code +@item :server +The name of the POP server. The default is taken from the +@code{MAILHOST} environment variable. + +@item :port +The port number of the POP server. This can be a number (eg, +@samp{:port 1234}) or a string (eg, @samp{:port "pop3"}). If it is a +string, it should be a service name as listed in @file{/etc/services} on +Unix systems. The default is @samp{"pop3"}. + +@item :user +The user name to give to the POP server. The default is the login +name. + +@item :password +The password to give to the POP server. If not specified, the user is +prompted. + +@item :program +The program to use to fetch mail from the POP server. This is should be +a @code{format}-like string. Here's an example: + +@example +fetchmail %u@@%s -P %p %t +@end example + +The valid format specifier characters are: + +@table @samp +@item t +The name of the file the mail is to be moved to. This must always be +included in this string. + +@item s +The name of the server. + +@item P +The port number of the server. + +@item u +The user name to use. + +@item p +The password to use. +@end table + +The values used for these specs are taken from the values you give the +corresponding keywords. + +@item :prescript +A script to be run before fetching the mail. The syntax is the same as +the @code{:program} keyword. This can also be a function to be run. + +@item :postscript +A script to be run after fetching the mail. The syntax is the same as +the @code{:program} keyword. This can also be a function to be run. + +@item :function +The function to use to fetch mail from the POP server. The function is +called with one parameter---the name of the file where the mail should +be moved to. + +@item :authentication +This can be either the symbol @code{password} or the symbol @code{apop} +and says what authentication scheme to use. The default is +@code{password}. + +@end table + +If the @code{:program} and @code{:function} keywords aren't specified, +@code{pop3-movemail} will be used. + +Here are some examples. Fetch from the default POP server, using the +default user name, and default fetcher: + +@lisp +(pop) +@end lisp + +Fetch from a named server with a named user and password: + +@lisp +(pop :server "my.pop.server" + :user "user-name" :password "secret") +@end lisp + +Use @samp{movemail} to move the mail: + +@lisp +(pop :program "movemail po:%u %t %p") +@end lisp + +@item maildir +Get mail from a maildir. This is a type of mailbox that is supported by +at least qmail and postfix, where each file in a special directory +contains exactly one mail. + +Keywords: + +@table @code +@item :path +The path of the directory where the mails are stored. The default is +taken from the @code{MAILDIR} environment variable or +@samp{~/Maildir/}. +@item :subdirs +The subdirectories of the Maildir. The default is +@samp{("new" "cur")}. + +@c If you sometimes look at your mail through a pop3 daemon before fetching +@c them with Gnus, you may also have to fetch your mails from the +@c @code{cur} directory inside the maildir, like in the first example +@c below. + +You can also get mails from remote hosts (because maildirs don't suffer +from locking problems). + +@end table + +Two example maildir mail sources: + +@lisp +(maildir :path "/home/user-name/Maildir/" :subdirs ("cur" "new")) +@end lisp + +@lisp +(maildir :path "/user@@remotehost.org:~/Maildir/" :subdirs ("new")) +@end lisp + +@item imap +Get mail from a @sc{imap} server. If you don't want to use @sc{imap} as +intended, as a network mail reading protocol (ie with nnimap), for some +reason or other, Gnus let you treat it similar to a POP server and +fetches articles from a given @sc{imap} mailbox. + +Keywords: + +@table @code +@item :server +The name of the @sc{imap} server. The default is taken from the +@code{MAILHOST} environment variable. + +@item :port +The port number of the @sc{imap} server. The default is @samp{143}, or +@samp{993} for SSL connections. + +@item :user +The user name to give to the @sc{imap} server. The default is the login +name. + +@item :password +The password to give to the @sc{imap} server. If not specified, the user is +prompted. + +@item :stream +What stream to use for connecting to the server, this is one of the +symbols in @code{imap-stream-alist}. Right now, this means +@samp{kerberos4}, @samp{ssl} or the default @samp{network}. + +@item :authentication +Which authenticator to use for authenticating to the server, this is one +of the symbols in @code{imap-authenticator-alist}. Right now, this +means @samp{kerberos4}, @samp{cram-md5}, @samp{anonymous} or the default +@samp{login}. + +@item :mailbox +The name of the mailbox to get mail from. The default is @samp{INBOX} +which normally is the mailbox which receive incoming mail. + +@item :predicate +The predicate used to find articles to fetch. The default, @samp{UNSEEN +UNDELETED}, is probably the best choice for most people, but if you +sometimes peek in your mailbox with a @sc{imap} client and mark some +articles as read (or; SEEN) you might want to set this to @samp{nil}. +Then all articles in the mailbox is fetched, no matter what. For a +complete list of predicates, see RFC 2060 §6.4.4. + +@item :fetchflag +How to flag fetched articles on the server, the default @samp{\Deleted} +will mark them as deleted, an alternative would be @samp{\Seen} which +would simply mark them as read. These are the two most likely choices, +but more flags are defined in RFC 2060 §2.3.2. + +@item :dontexpunge +If non-nil, don't remove all articles marked as deleted in the mailbox +after finishing the fetch. + +@end table + +An example @sc{imap} mail source: + +@lisp +(imap :server "mail.mycorp.com" :stream kerberos4 :fetchflag "\\Seen") +@end lisp + +@item webmail +Get mail from a webmail server, such as www.hotmail.com, +webmail.netscape.com, www.netaddress.com, www.my-deja.com. + +NOTE: Now mail.yahoo.com provides POP3 service, so @sc{pop} mail source +is suggested. + +NOTE: Webmail largely depends cookies. A "one-line-cookie" patch is +required for url "4.0pre.46". + +WARNING: Mails may lost. NO WARRANTY. + +Keywords: + +@table @code +@item :subtype +The type of the webmail server. The default is @code{hotmail}. The +alternatives are @code{netscape}, @code{netaddress}, @code{my-deja}. + +@item :user +The user name to give to the webmail server. The default is the login +name. + +@item :password +The password to give to the webmail server. If not specified, the user is +prompted. + +@item :dontexpunge +If non-nil, only fetch unread articles and don't move them to trash +folder after finishing the fetch. + +@end table + +An example webmail source: + +@lisp +(webmail :subtype 'hotmail :user "user-name" :password "secret") +@end lisp +@end table + +@table @dfn +@item Common Keywords +Common keywords can be used in any type of mail source. + +Keywords: + +@table @code +@item :plugged +If non-nil, fetch the mail even when Gnus is unplugged. If you use +directory source to get mail, you can specify it as in this example: + +@lisp +(setq mail-sources + '((directory :path "/home/pavel/.Spool/" + :suffix "" + :plugged t))) +@end lisp + +Gnus will then fetch your mail even when you are unplugged. This is +useful when you use local mail and news. + +@end table +@end table + +@subsubheading Function Interface + +Some of the above keywords specify a Lisp function to be executed. +For each keyword @code{:foo}, the Lisp variable @code{foo} is bound to +the value of the keyword while the function is executing. For example, +consider the following mail-source setting: + +@lisp +(setq mail-sources '((pop :user "jrl" + :server "pophost" :function fetchfunc))) +@end lisp + +While the function @code{fetchfunc} is executing, the symbol @code{user} +is bound to @code{"jrl"}, and the symbol @code{server} is bound to +@code{"pophost"}. The symbols @code{port}, @code{password}, +@code{program}, @code{prescript}, @code{postscript}, @code{function}, +and @code{authentication} are also bound (to their default values). + +See above for a list of keywords for each type of mail source. + + +@node Mail Source Customization +@subsubsection Mail Source Customization + +The following is a list of variables that influence how the mail is +fetched. You would normally not need to set or change any of these +variables. + +@table @code +@item mail-source-crash-box +@vindex mail-source-crash-box +File where mail will be stored while processing it. The default is +@file{~/.emacs-mail-crash-box}. + +@item mail-source-delete-incoming +@vindex mail-source-delete-incoming +If non-@code{nil}, delete incoming files after handling them. + +@item mail-source-directory +@vindex mail-source-directory +Directory where files (if any) will be stored. The default is +@file{~/Mail/}. At present, the only thing this is used for is to say +where the incoming files will be stored if the previous variable is +@code{nil}. + +@item mail-source-incoming-file-prefix +@vindex mail-source-incoming-file-prefix +Prefix for file name for storing incoming mail. The default is +@file{Incoming}, in which case files will end up with names like +@file{Incoming30630D_} or @file{Incoming298602ZD}. This is really only +relevant if @code{mail-source-delete-incoming} is @code{nil}. + +@item mail-source-default-file-modes +@vindex mail-source-default-file-modes +All new mail files will get this file mode. The default is 384. + +@end table + + +@node Fetching Mail +@subsubsection Fetching Mail + +@vindex mail-sources +@vindex nnmail-spool-file +The way to actually tell Gnus where to get new mail from is to set +@code{mail-sources} to a list of mail source specifiers +(@pxref{Mail Source Specifiers}). + +If this variable (and the obsolescent @code{nnmail-spool-file}) is +@code{nil}, the mail backends will never attempt to fetch mail by +themselves. + +If you want to fetch mail both from your local spool as well as a POP +mail server, you'd say something like: + +@lisp +(setq mail-sources + '((file) + (pop :server "pop3.mail.server" + :password "secret"))) +@end lisp + +Or, if you don't want to use any of the keyword defaults: + +@lisp +(setq mail-sources + '((file :path "/var/spool/mail/user-name") + (pop :server "pop3.mail.server" + :user "user-name" + :port "pop3" + :password "secret"))) +@end lisp + + +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. + + + @node Mail Backend Variables @subsection Mail Backend Variables @@ -9192,73 +11509,18 @@ 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. You may also specify the POP -server host name in @code{nnmail-spool-file} using the syntax -@samp{po:larsi:@var{pop-server-host-name}}. 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-rfc1522 -@findex RFC1522 decoding +@findex article-decode-encoded-words +@findex RFC 1522 decoding +@findex RFC 2047 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-rfc1522} -is one likely function to add to this hook. +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 @@ -9279,42 +11541,6 @@ (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 @@ -9365,6 +11591,12 @@ ;; Other mailing lists... (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list") (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list") + ;; Both lists below have the same suffix, so prevent + ;; cross-posting to mkpkg.list of messages posted only to + ;; the bugs- list, but allow cross-posting when the + ;; message was really cross-posted. + (any "bugs-mypackage@@somewhere" "mypkg.bugs") + (any "mypackage@@somewhere\" - "bugs-mypackage" "mypkg.list") ;; People... (any "larsi@@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen")) ;; Unmatched mail goes to the catch all group. @@ -9380,46 +11612,69 @@ @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 -@code{(@var{field} @var{value} @var{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 -@code{(| @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 @var{split} is said to match if it will cause the mail message to -be stored in one or more groups. - -@item -@code{(& @var{split}...)}: If the split is a list, and the first element is -@code{&}, then process all @var{split}s in the list. +examples. + +@item +@code{(@var{field} @var{value} @code{[-} @var{restrict} +@code{[@dots{}]}@code{]} @var{split})}: If the split is a list, the +first element of which is a string, then store the message as +specified by @var{split}, if header @var{field} (a regexp) contains +@var{value} (also a regexp). If @var{restrict} (yet another regexp) +matches some string after @var{field} and before the end of the +matched @var{value}, the @var{split} is ignored. If none of the +@var{restrict} clauses match, @var{split} is processed. + +@item +@code{(| @var{split}@dots{})}: If the split is a list, and the first +element is @code{|} (vertical bar), then process each @var{split} until +one of them matches. A @var{split} is said to match if it will cause +the mail message to be stored in one or more groups. + +@item +@code{(& @var{split}@dots{})}: If the split is a list, and the first +element is @code{&}, then process all @var{split}s 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 -@code{(: @var{function} @var{arg1} @var{arg2} @dots{})}: 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. +this message. Use with extreme caution. + +@item +@code{(: @var{function} @var{arg1} @var{arg2} @dots{})}: 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 @var{split}. + +For instance, the following function could be used to split based on the +body of the messages: + +@lisp +(defun split-on-body () + (save-excursion + (set-buffer " *nnmail incoming*") + (goto-char (point-min)) + (when (re-search-forward "Some.*string" nil t) + "string.group"))) +@end lisp + +@item +@code{(! @var{func} @var{split})}: If the split is a list, and the first +element is @code{!}, then SPLIT will be processed, and FUNC will be +called as a function with the result of SPLIT as argument. FUNC 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 +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 +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 +@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 @@ -9437,97 +11692,139 @@ (any "debian-\\b\\(\\w+\\)@@lists.debian.org" "mail.debian.\\1") @end example +In this example, messages sent to @samp{debian-foo@@lists.debian.org} +will be filed in @samp{mail.debian.foo}. + 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 Group Mail Splitting +@subsection Group Mail Splitting +@cindex mail splitting +@cindex group mail splitting + +@findex gnus-group-split +If you subscribe to dozens of mailing lists but you don't want to +maintain mail splitting rules manually, group mail splitting is for you. +You just have to set @var{to-list} and/or @var{to-address} in group +parameters or group customization and set @code{nnmail-split-methods} to +@code{gnus-group-split}. This splitting function will scan all groups +for those parameters and split mail accordingly, i.e., messages posted +from or to the addresses specified in the parameters @var{to-list} or +@var{to-address} of a mail group will be stored in that group. + +Sometimes, mailing lists have multiple addresses, and you may want mail +splitting to recognize them all: just set the @var{extra-aliases} group +parameter to the list of additional addresses and it's done. If you'd +rather use a regular expression, set @var{split-regexp}. + +All these parameters in a group will be used to create an +@code{nnmail-split-fancy} split, in which the @var{field} is @samp{any}, +the @var{value} is a single regular expression that matches +@var{to-list}, @var{to-address}, all of @var{extra-aliases} and all +matches of @var{split-regexp}, and the @var{split} is the name of the +group. @var{restrict}s are also supported: just set the +@var{split-exclude} parameter to a list of regular expressions. + +If you can't get the right split to be generated using all these +parameters, or you just need something fancier, you can set the +parameter @var{split-spec} to an @code{nnmail-split-fancy} split. In +this case, all other aforementioned parameters will be ignored by +@code{gnus-group-split}. In particular, @var{split-spec} may be set to +@code{nil}, in which case the group will be ignored by +@code{gnus-group-split}. + +@vindex gnus-group-split-default-catch-all-group +@code{gnus-group-split} will do cross-posting on all groups that match, +by defining a single @code{&} fancy split containing one split for each +group. If a message doesn't match any split, it will be stored in the +group named in @code{gnus-group-split-default-catch-all-group}, unless +some group has @var{split-spec} set to @code{catch-all}, in which case +that group is used as the catch-all group. Note that, in this case, +there's no cross-posting, as a @code{|} fancy split encloses the +@code{&} split and the catch-all group. + +It's time for an example. Assume the following group parameters have +been defined: + +@example +nnml:mail.bar: +((to-address . "bar@@femail.com") + (split-regexp . ".*@@femail\\.com")) +nnml:mail.foo: +((to-list . "foo@@nowhere.gov") + (extra-aliases "foo@@localhost" "foo-redist@@home") + (split-exclude "bugs-foo" "rambling-foo") + (admin-address . "foo-request@@nowhere.gov")) +nnml:mail.others: +((split-spec . catch-all)) +@end example + +Setting @code{nnmail-split-methods} to @code{gnus-group-split} will +behave as if @code{nnmail-split-fancy} had been selected and variable +@code{nnmail-split-fancy} had been set as follows: + +@lisp +(| (& (any "\\(bar@@femail\\.com\\|.*@@femail\\.com\\)" "mail.bar") + (any "\\(foo@@nowhere\\.gov\\|foo@@localhost\\|foo-redist@@home\\)" + - "bugs-foo" - "rambling-foo" "mail.foo")) + "mail.others") +@end lisp + +@findex gnus-group-split-fancy +If you'd rather not use group splitting for all your mail groups, you +may use it for only some of them, by using @code{nnmail-split-fancy} +splits like this: + +@lisp +(: gnus-mlsplt-fancy GROUPS NO-CROSSPOST CATCH-ALL) +@end lisp + +@var{groups} may be a regular expression or a list of group names whose +parameters will be scanned to generate the output split. +@var{no-crosspost} can be used to disable cross-posting; in this case, a +single @code{|} split will be output. @var{catch-all} may be the name +of a group to be used as the default catch-all group. If +@var{catch-all} is @code{nil}, or if @var{split-regexp} matches the +empty string in any selected group, no catch-all split will be issued. +Otherwise, if some group has @var{split-spec} set to @code{catch-all}, +this group will override the value of the @var{catch-all} argument. + +@findex gnus-group-split-setup +Unfortunately, scanning all groups and their parameters can be quite +slow, especially considering that it has to be done for every message. +But don't despair! The function @code{gnus-group-split-setup} can be +used to select @code{gnus-group-split} in a much more efficient way. It +sets @code{nnmail-split-methods} to @code{nnmail-split-fancy} and sets +@code{nnmail-split-fancy} to the split produced by +@code{gnus-group-split-fancy}. Thus, the group parameters are only +scanned once, no matter how many messages are split. + +@findex gnus-group-split-update +However, if you change group parameters, you have to update +@code{nnmail-split-fancy} manually. You can do it by running +@code{gnus-group-split-update}. If you'd rather have it updated +automatically, just tell @code{gnus-group-split-setup} to do it for +you. For example, add to your @file{.gnus}: + +@lisp +(gnus-group-split-setup AUTO-UPDATE CATCH-ALL) +@end lisp + +If @var{auto-update} is non-@code{nil}, @code{gnus-group-split-update} +will be added to @code{nnmail-pre-get-new-mail-hook}, so you won't ever +have to worry about updating @code{nnmail-split-fancy} again. If you +don't omit @var{catch-all} (it's optional), +@code{gnus-group-split-default-catch-all-group} will be set to its +value. + +@vindex gnus-group-split-updated-hook +Because you may want to change @code{nnmail-split-fancy} after it is set +by @code{gnus-group-split-update}, this function will run +@code{gnus-group-split-updated-hook} just before finishing. @node Incorporating Old Mail @subsection Incorporating Old Mail @@ -9681,6 +11978,26 @@ You can also use the @code{expiry-wait} group parameter to selectively change the expiry period (@pxref{Group Parameters}). +@vindex nnmail-expiry-target +The normal action taken when expiring articles is to delete them. +However, in some circumstances it might make more sense to move them to +other groups instead of deleting them. The variable @code{nnmail-expiry-target} +(and the @code{expiry-target} group parameter) controls this. The +variable supplies a default value for all groups, which can be +overridden for specific groups by the group parameter. +default value is @code{delete}, but this can also be a string (which +should be the name of the group the message should be moved to), or a +function (which will be called in a buffer narrowed to the message in +question, and with the name of the group being moved from as its +parameter) which should return a target -- either a group name or +@code{delete}. + +Here's an example for specifying a group name: +@lisp +(setq nnmail-expiry-target "nnml:expired") +@end lisp + + @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 @@ -9703,6 +12020,11 @@ Most people make most of their mail groups total-expirable, though. +@vindex gnus-inhibit-user-auto-expire +If @code{gnus-inhibit-user-auto-expire} is non-@code{nil}, user marking +commands will not mark an article as expirable, even if the group has +auto-expire turned on. + @node Washing Mail @subsection Washing Mail @@ -9711,10 +12033,10 @@ @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 +really stupid things with mail. ``Hey, RFC 822 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 +Yes, but RFC 822 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: @@ -9731,7 +12053,8 @@ @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: +grand, sweeping gestures. It is called in a buffer that contains all +the new, incoming mail. Functions to be used include: @table @code @item nnheader-ms-strip-cr @@ -9758,7 +12081,8 @@ 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. +also be a list of regexp. @code{nnmail-list-identifiers} may not contain +@code{\\(..\\)}. For instance, if you want to remove the @samp{(idm)} and the @samp{nagnagnag} identifiers: @@ -9768,10 +12092,20 @@ '("(idm)" "nagnagnag")) @end lisp +This can also be done non-destructively with +@code{gnus-list-identifiers}, @xref{Article Hiding}. + @item nnmail-remove-tabs @findex nnmail-remove-tabs Translate all @samp{TAB} characters into @samp{SPACE} characters. +@item nnmail-fix-eudora-headers +@findex nnmail-fix-eudora-headers +@cindex Eudora +Eudora produces broken @code{References} headers, but OK +@code{In-Reply-To} headers. This function will get rid of the +@code{References} headers. + @end table @item nnmail-prepare-incoming-message-hook @@ -9802,7 +12136,7 @@ @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 +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 @@ -9853,8 +12187,9 @@ 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. +If you set @code{mail-sources} and @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 @@ -9880,12 +12215,18 @@ file is first copied to your home directory. What happens after that depends on what format you want to store your mail in. +There are five different mail backends in the standard Gnus, and more +backends are available separately. The mail backend most people use +(because it is the fastest and most flexible) is @code{nnml} +(@pxref{Mail Spool}). + @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. +* Comparing Mail Backends:: An in-depth looks at pros and cons. @end menu @@ -9926,8 +12267,8 @@ @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. +mbox}) to store mail. @code{nnbabyl} will add extra headers to each +mail article to say which group it belongs in. Virtual server settings: @@ -10098,6 +12439,12 @@ (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 @@ -10106,7 +12453,453 @@ 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}. +@code{nnfolder-directory}. This only works if you use long file names, +though. + +@node Comparing Mail Backends +@subsubsection Comparing Mail Backends + +First, just for terminology, the @dfn{backend} is the common word for a +low-level access method---a transport, if you will, by which something +is acquired. The sense is that one's mail has to come from somewhere, +and so selection of a suitable backend is required in order to get that +mail within spitting distance of Gnus. + +The same concept exists for Usenet itself: Though access to articles is +typically done by @sc{nntp} these days, once upon a midnight dreary, everyone +in the world got at Usenet by running a reader on the machine where the +articles lay (the machine which today we call an @sc{nntp} server), and +access was by the reader stepping into the articles' directory spool +area directly. One can still select between either the @code{nntp} or +@code{nnspool} backends, to select between these methods, if one happens +actually to live on the server (or can see its spool directly, anyway, +via NFS). + +The goal in selecting a mail backend is to pick one which +simultaneously represents a suitable way of dealing with the original +format plus leaving mail in a form that is convenient to use in the +future. Here are some high and low points on each: + +@table @code +@item nnmbox + +UNIX systems have historically had a single, very common, and well- +defined format. All messages arrive in a single @dfn{spool file}, and +they are delineated by a line whose regular expression matches +@samp{^From_}. (My notational use of @samp{_} is to indicate a space, +to make it clear in this instance that this is not the RFC-specified +@samp{From:} header.) Because Emacs and therefore Gnus emanate +historically from the Unix environment, it is simplest if one does not +mess a great deal with the original mailbox format, so if one chooses +this backend, Gnus' primary activity in getting mail from the real spool +area to Gnus' preferred directory is simply to copy it, with no +(appreciable) format change in the process. It is the ``dumbest'' way +to move mail into availability in the Gnus environment. This makes it +fast to move into place, but slow to parse, when Gnus has to look at +what's where. + +@item nnbabyl + +Once upon a time, there was the DEC-10 and DEC-20, running operating +systems called TOPS and related things, and the usual (only?) mail +reading environment was a thing called Babyl. I don't know what format +was used for mail landing on the system, but Babyl had its own internal +format to which mail was converted, primarily involving creating a +spool-file-like entity with a scheme for inserting Babyl-specific +headers and status bits above the top of each message in the file. +RMAIL was Emacs' first mail reader, it was written by Richard Stallman, +and Stallman came out of that TOPS/Babyl environment, so he wrote RMAIL +to understand the mail files folks already had in existence. Gnus (and +VM, for that matter) continue to support this format because it's +perceived as having some good qualities in those mailer-specific +headers/status bits stuff. RMAIL itself still exists as well, of +course, and is still maintained by Stallman. + +Both of the above forms leave your mail in a single file on your +filesystem, and they must parse that entire file each time you take a +look at your mail. + +@item nnml + +@code{nnml} is the backend which smells the most as though you were +actually operating with an @code{nnspool}-accessed Usenet system. (In +fact, I believe @code{nnml} actually derived from @code{nnspool} code, +lo these years ago.) One's mail is taken from the original spool file, +and is then cut up into individual message files, 1:1. It maintains a +Usenet-style active file (analogous to what one finds in an INN- or +CNews-based news system in (for instance) @file{/var/lib/news/active}, +or what is returned via the @samp{NNTP LIST} verb) and also creates +@dfn{overview} files for efficient group entry, as has been defined for +@sc{nntp} servers for some years now. It is slower in mail-splitting, +due to the creation of lots of files, updates to the @code{nnml} active +file, and additions to overview files on a per-message basis, but it is +extremely fast on access because of what amounts to the indexing support +provided by the active file and overviews. + +@code{nnml} costs @dfn{inodes} in a big way; that is, it soaks up the +resource which defines available places in the filesystem to put new +files. Sysadmins take a dim view of heavy inode occupation within +tight, shared filesystems. But if you live on a personal machine where +the filesystem is your own and space is not at a premium, @code{nnml} +wins big. + +It is also problematic using this backend if you are living in a +FAT16-based Windows world, since much space will be wasted on all these +tiny files. + +@item nnmh + +The Rand MH mail-reading system has been around UNIX systems for a very +long time; it operates by splitting one's spool file of messages into +individual files, but with little or no indexing support -- @code{nnmh} +is considered to be semantically equivalent to ``@code{nnml} without +active file or overviews''. This is arguably the worst choice, because +one gets the slowness of individual file creation married to the +slowness of access parsing when learning what's new in one's groups. + +@item nnfolder + +Basically the effect of @code{nnfolder} is @code{nnmbox} (the first +method described above) on a per-group basis. That is, @code{nnmbox} +itself puts *all* one's mail in one file; @code{nnfolder} provides a +little bit of optimization to this so that each of one's mail groups has +a Unix mail box file. It's faster than @code{nnmbox} because each group +can be parsed separately, and still provides the simple Unix mail box +format requiring minimal effort in moving the mail around. In addition, +it maintains an ``active'' file making it much faster for Gnus to figure +out how many messages there are in each separate group. + +If you have groups that are expected to have a massive amount of +messages, @code{nnfolder} is not the best choice, but if you receive +only a moderate amount of mail, @code{nnfolder} is probably the most +friendly mail backend all over. + +@end table + + +@node Browsing the Web +@section Browsing the Web +@cindex web +@cindex browsing the web +@cindex www +@cindex http + +Web-based discussion forums are getting more and more popular. On many +subjects, the web-based forums have become the most important forums, +eclipsing the importance of mailing lists and news groups. The reason +is easy to understand---they are friendly to new users; you just point +and click, and there's the discussion. With mailing lists, you have to +go through a cumbersome subscription procedure, and most people don't +even know what a news group is. + +The problem with this scenario is that web browsers are not very good at +being newsreaders. They do not keep track of what articles you've read; +they do not allow you to score on subjects you're interested in; they do +not allow off-line browsing; they require you to click around and drive +you mad in the end. + +So---if web browsers suck at reading discussion forums, why not use Gnus +to do it instead? + +Gnus has been getting a bit of a collection of backends for providing +interfaces to these sources. + +@menu +* Web Searches:: Creating groups from articles that match a string. +* Slashdot:: Reading the Slashdot comments. +* Ultimate:: The Ultimate Bulletin Board systems. +* Web Archive:: Reading mailing list archived on web. +* Customizing w3:: Doing stuff to Emacs/w3 from Gnus. +@end menu + +All the web sources require Emacs/w3 and the url library to work. + +The main caveat with all these web sources is that they probably won't +work for a very long time. Gleaning information from the @sc{html} data +is guesswork at best, and when the layout is altered, the Gnus backend +will fail. If you have reasonably new versions of these backends, +though, you should be ok. + +One thing all these Web methods have in common is that the Web sources +are often down, unavailable or just plain too slow to be fun. In those +cases, it makes a lot of sense to let the Gnus Agent (@pxref{Gnus +Unplugged}) handle downloading articles, and then you can read them at +leisure from your local disk. No more World Wide Wait for you. + + +@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'être} 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 Slashdot +@subsection Slashdot +@cindex Slashdot +@cindex nnslashdot + +Slashdot (@file{http://slashdot.org/}) is a popular news site, with +lively discussion following the news articles. @code{nnslashdot} will +let you read this forum in a convenient manner. + +The easiest way to read this source is to put something like the +following in your @file{.gnus.el} file: + +@lisp +(setq gnus-secondary-select-methods + '((nnslashdot ""))) +@end lisp + +This will make Gnus query the @code{nnslashdot} backend for new comments +and groups. The @kbd{F} command will subscribe each new news article as +a new Gnus group, and you can read the comments by entering these +groups. (Note that the default subscription method is to subscribe new +groups as zombies. Other methods are available (@pxref{Subscription +Methods}). + +If you want to remove an old @code{nnslashdot} group, the @kbd{G DEL} +command is the most handy tool (@pxref{Foreign Groups}). + +When following up to @code{nnslashdot} comments (or posting new +comments), some light @sc{html}izations will be performed. In +particular, text quoted with @samp{> } will be quoted with +@code{blockquote} instead, and signatures will have @code{br} added to +the end of each line. Other than that, you can just write @sc{html} +directly into the message buffer. Note that Slashdot filters out some +@sc{html} forms. + +The following variables can be altered to change its behavior: + +@table @code +@item nnslashdot-threaded +Whether @code{nnslashdot} should display threaded groups or not. The +default is @code{t}. To be able to display threads, @code{nnslashdot} +has to retrieve absolutely all comments in a group upon entry. If a +threaded display is not required, @code{nnslashdot} will only retrieve +the comments that are actually wanted by the user. Threading is nicer, +but much, much slower than untreaded. + +@item nnslashdot-login-name +@vindex nnslashdot-login-name +The login name to use when posting. + +@item nnslashdot-password +@vindex nnslashdot-password +The password to use when posting. + +@item nnslashdot-directory +@vindex nnslashdot-directory +Where @code{nnslashdot} will store its files. The default value is +@samp{~/News/slashdot/}. + +@item nnslashdot-active-url +@vindex nnslashdot-active-url +The @sc{url} format string that will be used to fetch the information on +news articles and comments. The default is +@samp{http://slashdot.org/search.pl?section=&min=%d}. + +@item nnslashdot-comments-url +@vindex nnslashdot-comments-url +The @sc{url} format string that will be used to fetch comments. The +default is +@samp{http://slashdot.org/comments.pl?sid=%s&threshold=%d&commentsort=%d&mode=flat&startat=%d}. + +@item nnslashdot-article-url +@vindex nnslashdot-article-url +The @sc{url} format string that will be used to fetch the news article. The +default is +@samp{http://slashdot.org/article.pl?sid=%s&mode=nocomment}. + +@item nnslashdot-threshold +@vindex nnslashdot-threshold +The score threshold. The default is -1. + +@item nnslashdot-group-number +@vindex nnslashdot-group-number +The number of old groups, in addition to the ten latest, to keep +updated. The default is 0. + +@end table + + + +@node Ultimate +@subsection Ultimate +@cindex nnultimate +@cindex Ultimate Bulletin Board + +The Ultimate Bulletin Board (@file{http://www.ultimatebb.com/}) is +probably the most popular Web bulletin board system used. It has a +quite regular and nice interface, and it's possible to get the +information Gnus needs to keep groups updated. + +The easiest way to get started with @code{nnultimate} is to say +something like the following in the group buffer: @kbd{B nnultimate RET +http://www.tcj.com/messboard/ubbcgi/ RET}. (Substitute the @sc{url} +(not including @samp{Ultimate.cgi} or the like at the end) for a forum +you're interested in; there's quite a list of them on the Ultimate web +site.) Then subscribe to the groups you're interested in from the +server buffer, and read them from the group buffer. + +The following @code{nnultimate} variables can be altered: + +@table @code +@item nnultimate-directory +@vindex nnultimate-directory +The directory where @code{nnultimate} stores its files. The default is +@samp{~/News/ultimate/}. +@end table + + +@node Web Archive +@subsection Web Archive +@cindex nnwarchive +@cindex Web Archive + +Some mailing lists only have archives on Web servers, such as +@file{http://www.egroups.com/} and +@file{http://www.mail-archive.com/}. It has a quite regular and nice +interface, and it's possible to get the information Gnus needs to keep +groups updated. + +The easiest way to get started with @code{nnwarchive} is to say +something like the following in the group buffer: @kbd{M-x +gnus-group-make-warchive-group RET an_egroup RET egroups RET +www.egroups.com RET your@@email.address RET}. (Substitute the +@sc{an_egroup} with the mailing list you subscribed, the +@sc{your@@email.address} with your email address.), or to browse the +backend by @kbd{B nnwarchive RET mail-archive RET}. + +The following @code{nnwarchive} variables can be altered: + +@table @code +@item nnwarchive-directory +@vindex nnwarchive-directory +The directory where @code{nnwarchive} stores its files. The default is +@samp{~/News/warchive/}. + +@item nnwarchive-login +@vindex nnwarchive-login +The account name on the web server. + +@item nnwarchive-passwd +@vindex nnwarchive-passwd +The password for your account on the web server. +@end table + + +@node Customizing w3 +@subsection Customizing w3 +@cindex w3 +@cindex html +@cindex url +@cindex Netscape + +Gnus uses the url library to fetch web pages and Emacs/w3 to display web +pages. Emacs/w3 is documented in its own manual, but there are some +things that may be more relevant for Gnus users. + +For instance, a common question is how to make Emacs/w3 follow links +using the @code{browse-url} functions (which will call some external web +browser like Netscape). Here's one way: + +@lisp +(eval-after-load "w3" + '(progn + (fset 'w3-fetch-orig (symbol-function 'w3-fetch)) + (defun w3-fetch (&optional url target) + (interactive (list (w3-read-url-with-default))) + (if (eq major-mode 'gnus-article-mode) + (browse-url url) + (w3-fetch-orig url target))))) +@end lisp + +Put that in your @file{.emacs} file, and hitting links in w3-rendered +@sc{html} in the Gnus article buffers will use @code{browse-url} to +follow the link. @node Other Sources @@ -10121,8 +12914,8 @@ * 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. +* IMAP:: Using Gnus as a @sc{imap} client. @end menu @@ -10166,13 +12959,13 @@ 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 +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 @@ -10207,6 +13000,11 @@ 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-include-files +@vindex nneething-include-files +Regexp saying what files to include in the group. If this variable is +non-@code{nil}, only files matching this regexp will be included. + @item nneething-map-file @vindex nneething-map-file Name of the map files. @@ -10249,16 +13047,11 @@ @item forward Forwarded articles. +@item nsmail +Netscape mail boxes. + @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. +MIME multipart messages. @item standard-digest The standard (RFC 1153) digest format. @@ -10294,9 +13087,8 @@ @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}. +@code{rfc822-forward}, @code{mime-parts}, @code{standard-digest}, +@code{slack-digest}, @code{clari-briefs}, @code{nsmail} or @code{guess}. @item nndoc-post-type @vindex nndoc-post-type @@ -10446,7 +13238,7 @@ 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 +However, it can sometimes be convenient to do something 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. @@ -10474,12 +13266,12 @@ @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. +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. +default, where @var{x} is a number. @end table @@ -10715,96 +13507,6 @@ @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'être} 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 @@ -10883,6 +13585,436 @@ @end lisp + +@node IMAP +@subsection @sc{imap} +@cindex nnimap +@cindex @sc{imap} + +@sc{imap} is a network protocol for reading mail (or news, or ...), +think of it as a modernized @sc{nntp}. Connecting to a @sc{imap} server +is much similar to connecting to a news server, you just specify the +network address of the server. + +A server configuration in @code{~/.gnus} with a few @sc{imap} servers +might look something like this: + +@lisp +(setq gnus-secondary-select-methods + '((nnimap "simpleserver") ; no special configuration + ; perhaps a ssh port forwarded server: + (nnimap "dolk" + (nnimap-address "localhost") + (nnimap-server-port 1430)) + ; a UW server running on localhost + (nnimap "barbar" + (nnimap-server-port 143) + (nnimap-address "localhost") + (nnimap-list-pattern ("INBOX" "mail/*"))) + ; anonymous public cyrus server: + (nnimap "cyrus.andrew.cmu.edu" + (nnimap-authenticator anonymous) + (nnimap-list-pattern "archive.*") + (nnimap-stream network)) + ; a ssl server on a non-standard port: + (nnimap "vic20" + (nnimap-address "vic20.somewhere.com") + (nnimap-server-port 9930) + (nnimap-stream ssl)))) +@end lisp + +The following variables can be used to create a virtual @code{nnimap} +server: + +@table @code + +@item nnimap-address +@vindex nnimap-address + +The address of the remote @sc{imap} server. Defaults to the virtual +server name if not specified. + +@item nnimap-server-port +@vindex nnimap-server-port +Port on server to contact. Defaults to port 143, or 993 for SSL. + +Note that this should be a integer, example server specification: + +@lisp +(nnimap "mail.server.com" + (nnimap-server-port 4711)) +@end lisp + +@item nnimap-list-pattern +@vindex nnimap-list-pattern +String or list of strings of mailboxes to limit available groups to. +This is used when the server has very many mailboxes and you're only +interested in a few -- some servers export your home directory via +@sc{imap}, you'll probably want to limit the mailboxes to those in +@file{~/Mail/*} then. + +The string can also be a cons of REFERENCE and the string as above, what +REFERENCE is used for is server specific, but on the University of +Washington server it's a directory that will be concatenated with the +mailbox. + +Example server specification: + +@lisp +(nnimap "mail.server.com" + (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" + ("~friend/Mail/" . "list/*")))) +@end lisp + +@item nnimap-stream +@vindex nnimap-stream +The type of stream used to connect to your server. By default, nnimap +will detect and automatically use all of the below, with the exception +of SSL. (SSL is being replaced by STARTTLS, which can be automatically +detected, but it's not widely deployed yet). + +Example server specification: + +@lisp +(nnimap "mail.server.com" + (nnimap-stream ssl)) +@end lisp + +Please note that the value of @code{nnimap-stream} is a symbol! + +@itemize @bullet +@item +@dfn{gssapi:} Connect with GSSAPI (usually kerberos 5). Require the +@samp{imtest} program. +@item +@dfn{kerberos4:} Connect with kerberos 4. Require the @samp{imtest} program. +@item +@dfn{starttls:} Connect via the STARTTLS extension (similar to +SSL). Require the external library @samp{starttls.el} and program +@samp{starttls}. +@item +@dfn{ssl:} Connect through SSL. Require OpenSSL (the +program @samp{openssl}) or SSLeay (@samp{s_client}). +@item +@dfn{shell:} Use a shell command to start IMAP connection. +@item +@dfn{network:} Plain, TCP/IP network connection. +@end itemize + +@vindex imap-kerberos4-program +The @samp{imtest} program is shipped with Cyrus IMAPD, nnimap support +both @samp{imtest} version 1.5.x and version 1.6.x. The variable +@code{imap-kerberos4-program} contain parameters to pass to the imtest +program. + +@vindex imap-ssl-program +For SSL connections, the OpenSSL program is available from +@file{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay, +and nnimap support it too - altough the most recent versions of +SSLeay, 0.9.x, are known to have serious bugs making it +useless. Earlier versions, especially 0.8.x, of SSLeay are known to +work. The variable @code{imap-ssl-program} contain parameters to pass +to OpenSSL/SSLeay. + +@vindex imap-shell-program +@vindex imap-shell-host +For IMAP connections using the @code{shell} stream, the variable +@code{imap-shell-program} specify what program to call. + +@item nnimap-authenticator +@vindex nnimap-authenticator + +The authenticator used to connect to the server. By default, nnimap +will use the most secure authenticator your server is capable of. + +Example server specification: + +@lisp +(nnimap "mail.server.com" + (nnimap-authenticator anonymous)) +@end lisp + +Please note that the value of @code{nnimap-authenticator} is a symbol! + +@itemize @bullet +@item +@dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Require +external program @code{imtest}. +@item +@dfn{kerberos4:} Kerberos authentication. Require external program +@code{imtest}. +@item +@dfn{digest-md5:} Encrypted username/password via DIGEST-MD5. Require +external library @code{digest-md5.el}. +@item +@dfn{cram-md5:} Encrypted username/password via CRAM-MD5. +@item +@dfn{login:} Plain-text username/password via LOGIN. +@item +@dfn{anonymous:} Login as `anonymous', supplying your emailadress as password. +@end itemize + +@item nnimap-expunge-on-close +@cindex Expunging +@vindex nnimap-expunge-on-close +Unlike Parmenides the @sc{imap} designers has decided that things that +doesn't exist actually does exist. More specifically, @sc{imap} has +this concept of marking articles @code{Deleted} which doesn't actually +delete them, and this (marking them @code{Deleted}, that is) is what +nnimap does when you delete a article in Gnus (with @kbd{G DEL} or +similair). + +Since the articles aren't really removed when we mark them with the +@code{Deleted} flag we'll need a way to actually delete them. Feel like +running in circles yet? + +Traditionally, nnimap has removed all articles marked as @code{Deleted} +when closing a mailbox but this is now configurable by this server +variable. + +The possible options are: + +@table @code + +@item always +The default behaviour, delete all articles marked as "Deleted" when +closing a mailbox. +@item never +Never actually delete articles. Currently there is no way of showing +the articles marked for deletion in nnimap, but other @sc{imap} clients +may allow you to do this. If you ever want to run the EXPUNGE command +manually, @xref{Expunging mailboxes}. +@item ask +When closing mailboxes, nnimap will ask if you wish to expunge deleted +articles or not. + +@end table + +@item nnimap-authinfo-file +@vindex nnimap-authinfo-file + +A file containing credentials used to log in on servers. The format +is (almost) the same as the @code{ftp} @file{~/.netrc} file. See +`nntp-authinfo-file' for exact syntax. + +A file containing credentials used to log in on servers. The format is +(almost) the same as the @code{ftp} @file{~/.netrc} file. See the +variable @code{nntp-authinfo-file} for exact syntax; also see +@xref{NNTP}. + +@end table + +@menu +* Splitting in IMAP:: Splitting mail with nnimap. +* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. +* Expunging mailboxes:: Equivalent of a "compress mailbox" button. +@end menu + + + +@node Splitting in IMAP +@subsubsection Splitting in @sc{imap} +@cindex splitting imap mail + +Splitting is something Gnus users has loved and used for years, and now +the rest of the world is catching up. Yeah, dream on, not many +@sc{imap} server has server side splitting and those that have splitting +seem to use some non-standard protocol. This means that @sc{imap} +support for Gnus has to do it's own splitting. + +And it does. + +Here are the variables of interest: + +@table @code + +@item nnimap-split-crosspost +@cindex splitting, crosspost +@cindex crosspost +@vindex nnimap-split-crosspost + +If non-nil, do crossposting if several split methods match the mail. If +nil, the first match in @code{nnimap-split-rule} found will be used. + +Nnmail equivalent: @code{nnmail-crosspost}. + +@item nnimap-split-inbox +@cindex splitting, inbox +@cindex inbox +@vindex nnimap-split-inbox + +A string or a list of strings that gives the name(s) of @sc{imap} +mailboxes to split from. Defaults to nil, which means that splitting is +disabled! + +@lisp +(setq nnimap-split-inbox + '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap")) +@end lisp + +No nnmail equivalent. + +@item nnimap-split-rule +@cindex Splitting, rules +@vindex nnimap-split-rule + +New mail found in @code{nnimap-split-inbox} will be split according to +this variable. + +This variable contains a list of lists, where the first element in the +sublist gives the name of the @sc{imap} mailbox to move articles +matching the regexp in the second element in the sublist. Got that? +Neither did I, we need examples. + +@lisp +(setq nnimap-split-rule + '(("INBOX.nnimap" "^Sender: owner-nnimap@@vic20.globalcom.se") + ("INBOX.junk" "^Subject:.*MAKE MONEY") + ("INBOX.private" ""))) +@end lisp + +This will put all articles from the nnimap mailing list into mailbox +INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line +into INBOX.spam and everything else in INBOX.private. + +The first string may contain `\\1' forms, like the ones used by +replace-match to insert sub-expressions from the matched text. For +instance: + +@lisp +("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@@") +@end lisp + +The second element can also be a function. In that case, it will be +called with the first element of the rule as the argument, in a buffer +containing the headers of the article. It should return a non-nil value +if it thinks that the mail belongs in that group. + +Nnmail users might recollect that the last regexp had to be empty to +match all articles (like in the example above). This is not required in +nnimap. Articles not matching any of the regexps will not be moved out +of your inbox. (This might might affect performance if you keep lots of +unread articles in your inbox, since the splitting code would go over +them every time you fetch new mail.) + +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". + +This variable can also have a function as its value, the function will +be called with the headers narrowed and should return a group where it +thinks the article should be splitted to. See @code{nnimap-split-fancy}. + +The splitting code tries to create mailboxes if it need too. + +To allow for different split rules on different virtual servers, and +even different split rules in different inboxes on the same server, +the syntax of this variable have been extended along the lines of: + +@lisp +(setq nnimap-split-rule + '(("my1server" (".*" (("ding" "ding@@gnus.org") + ("junk" "From:.*Simon"))) + ("my2server" ("INBOX" nnimap-split-fancy)) + ("my[34]server" (".*" (("private" "To:.*Simon") + ("junk" my-junk-func))))) +@end lisp + +The virtual server name is in fact a regexp, so that the same rules +may apply to several servers. In the example, the servers +@code{my3server} and @code{my4server} both use the same rules. +Similarly, the inbox string is also a regexp. The actual splitting +rules are as before, either a function, or a list with group/regexp or +group/function elements. + +Nnmail equivalent: @code{nnmail-split-methods}. + +@item nnimap-split-predicate +@cindex splitting +@vindex nnimap-split-predicate + +Mail matching this predicate in @code{nnimap-split-inbox} will be +splitted, it is a string and the default is @samp{UNSEEN UNDELETED}. + +This might be useful if you use another @sc{imap} client to read mail in +your inbox but would like Gnus to split all articles in the inbox +regardless of readedness. Then you might change this to +@samp{UNDELETED}. + +@item nnimap-split-fancy +@cindex splitting, fancy +@findex nnimap-split-fancy +@vindex nnimap-split-fancy + +It's possible to set @code{nnimap-split-rule} to +@code{nnmail-split-fancy} if you want to use fancy +splitting. @xref{Fancy Mail Splitting}. + +However, to be able to have different fancy split rules for nnmail and +nnimap backends you can set @code{nnimap-split-rule} to +@code{nnimap-split-fancy} and define the nnimap specific fancy split +rule in @code{nnimap-split-fancy}. + +Example: + +@lisp +(setq nnimap-split-rule 'nnimap-split-fancy + nnimap-split-fancy ...) +@end lisp + +Nnmail equivalent: @code{nnmail-split-fancy}. + +@end table + +@node Editing IMAP ACLs +@subsubsection Editing @sc{imap} ACLs +@cindex editing imap acls +@cindex Access Control Lists +@cindex Editing @sc{imap} ACLs +@kindex G l +@findex gnus-group-nnimap-edit-acl + +ACL stands for Access Control List. ACLs are used in @sc{imap} for +limiting (or enabling) other users access to your mail boxes. Not all +@sc{imap} servers support this, this function will give an error if it +doesn't. + +To edit a ACL for a mailbox, type @kbd{G l} +(@code{gnus-group-edit-nnimap-acl}) and you'll be presented with a ACL +editing window with detailed instructions. + +Some possible uses: + +@itemize @bullet +@item +Giving "anyone" the "lrs" rights (lookup, read, keep seen/unseen flags) +on your mailing list mailboxes enables other users on the same server to +follow the list without subscribing to it. +@item +At least with the Cyrus server, you are required to give the user +"anyone" posting ("p") capabilities to have "plussing" work (that is, +mail sent to user+mailbox@@domain ending up in the @sc{imap} mailbox +INBOX.mailbox). +@end itemize + +@node Expunging mailboxes +@subsubsection Expunging mailboxes +@cindex expunging + +@cindex Expunge +@cindex Manual expunging +@kindex G x +@findex gnus-group-nnimap-expunge + +If you're using the @code{never} setting of @code{nnimap-expunge-close}, +you may want the option of expunging all deleted articles in a mailbox +manually. This is exactly what @kbd{G x} does. + +Currently there is no way of showing deleted articles, you can just +delete them. + + + @node Combined Groups @section Combined Groups @@ -11077,10 +14209,12 @@ * 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. +* Agent and IMAP:: How to use the Agent with IMAP. * Outgoing Messages:: What happens when you post/mail something? * Agent Variables:: Customizing is fun. * Example Setup:: An example @file{.gnus.el} file for offline people. * Batching Agents:: How to fetch news from a @code{cron} job. +* Agent Caveats:: What you think it'll do and what it does. @end menu @@ -11112,11 +14246,14 @@ @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}. +to make Gnus become @dfn{plugged} and use @kbd{g} to check for new mail +as usual. To check for new mail in unplugged mode, see (@pxref{Mail +Source Specifiers}). @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 +onto your local machine. If you want to do the latter, you press @kbd{g} +to check if there are any new news and then @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}.) @@ -11163,7 +14300,9 @@ 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. +Groups that do not belong in any other category belong to the +@code{default} category. Gnus has its own buffer for creating and +managing categories. @menu * Category Syntax:: What a category looks like. @@ -11185,11 +14324,21 @@ @item a score rule which (generally) gives you a finer granularity when deciding what articles to download. (Note that this @dfn{download -score} is wholly unrelated to normal scores.) +score} is not necessarily related to normal scores.) @end enumerate -A predicate consists of predicates with logical operators sprinkled in -between. +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. @@ -11257,13 +14406,181 @@ @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-days (date-to-time (mail-header-date gnus-headers))) + (- (time-to-days (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{From}, @code{Subject}, -@code{Date}, @code{Xref}, @code{Lines}, @code{Chars}, @code{Message-ID}, -and @code{References}. - +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: + +@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 @node The Category Buffer @subsubsection The Category Buffer @@ -11415,13 +14732,27 @@ @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}. +(@code{gnus-group-send-drafts}). @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}). +(@code{gnus-agent-add-group}). This command understands the +process/prefix convention (@pxref{Process/Prefix}). + +@item J r +@kindex J r (Agent Group) +@findex gnus-agent-remove-group +Remove the current group from its category, if any +(@code{gnus-agent-remove-group}). This command understands the +process/prefix convention (@pxref{Process/Prefix}). + +@item J Y +@kindex J Y (Agent Group) +@findex gnus-agent-synchronize-flags +Synchronize flags changed while unplugged with remote server, if any. + @end table @@ -11441,7 +14772,7 @@ Remove the downloading mark from the article (@code{gnus-agent-unmark-article}). -@item @@ +@item @@ @kindex @@ (Agent Summary) @findex gnus-agent-toggle-mark Toggle whether to download the article (@code{gnus-agent-toggle-mark}). @@ -11479,8 +14810,8 @@ @vindex gnus-agent-expire-days @findex gnus-agent-expire @kindex M-x gnus-agent-expire -@cindex Agent expire -@cindex Gnus Agent expire +@cindex Agent expiry +@cindex Gnus Agent expiry @cindex expiry @code{nnagent} doesn't handle expiry. Instead, there's a special @@ -11497,6 +14828,60 @@ unread, ticked and dormant articles will be kept indefinitely. +@node Agent and IMAP +@subsection Agent and IMAP + +The Agent work with any Gnus backend, including nnimap. However, since +there are some conceptual differences between NNTP and IMAP, this +section (should) provide you with some information to make Gnus Agent +work smoother as a IMAP Disconnected Mode client. + +The first thing to keep in mind is that all flags (read, ticked, etc) +are kept on the IMAP server, rather than in @code{.newsrc} as is the +case for nntp. Thus Gnus need to remember flag changes when +disconnected, and synchronize these flags when you plug back in. + +Gnus keep track of flag changes when reading nnimap groups under the +Agent by default. When you plug back in, by default Gnus will check if +you have any changed any flags and ask if you wish to synchronize theese +with the server. This behaviour is customizable with +@code{gnus-agent-synchronize-flags}. + +@vindex gnus-agent-synchronize-flags +If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will +never automatically synchronize flags. If it is @code{ask}, the +default, the Agent will check if you made any changes and if so ask if +you wish to synchronize these when you re-connect. If it has any other +value, all flags will be synchronized automatically. + +If you do not wish to automatically synchronize flags when you +re-connect, this can be done manually with the +@code{gnus-agent-synchronize-flags} command that is bound to @kbd{J Y} +in the group buffer by default. + +Some things are currently not implemented in the Agent that you'd might +expect from a disconnected IMAP client, including: + +@itemize @bullet + +@item +Copying/moving articles into nnimap groups when unplugged. + +@item +Creating/deleting nnimap groups when unplugged. + +@end itemize + +Technical note: the synchronization algorithm does not work by "pushing" +all local flags to the server, but rather incrementally update the +server view of flags by changing only those flags that were changed by +the user. Thus, if you set one flag on a article, quit the group and +re-select the group and remove the flag; the flag will be set and +removed from the server when you "synchronize". The queued flag +operations can be found in the per-server @code{flags} file in the Agent +directory. It's emptied when you synchronize flags. + + @node Outgoing Messages @subsection Outgoing Messages @@ -11546,14 +14931,13 @@ @file{.gnus.el} file to get started. @lisp -;;; Define how Gnus is to fetch news. We do this over NNTP +;;; Define how Gnus is to fetch news. We do this over @sc{nntp} ;;; from your ISP's server. -(setq gnus-select-method '(nntp "nntp.your-isp.com")) +(setq gnus-select-method '(nntp "news.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") +(setq mail-sources '((pop :server "pop.your-isp.com"))) ;;; Say how Gnus is to store the mail. We use nnml groups. (setq gnus-secondary-select-methods '((nnml ""))) @@ -11597,6 +14981,29 @@ @end example +@node Agent Caveats +@subsection Agent Caveats + +The Gnus Agent doesn't seem to work like most other offline +newsreaders. Here are some common questions that some imaginary people +may ask: + +@table @dfn +@item If I read an article while plugged, do they get entered into the +Agent? + +@strong{No.} + +@item If I read an article while plugged, and the article already exists +in the Agent, will it get downloaded once more? + +@strong{Yes.} + +@end table + +In short, when Gnus is unplugged, it only looks into the locally stored +articles; when it's plugged, it only talks to your ISP. + @node Scoring @chapter Scoring @@ -11763,10 +15170,10 @@ Score on the subject line. @item x -Score on the Xref line---i.e., the cross-posting line. +Score on the @code{Xref} line---i.e., the cross-posting line. @item r -Score on the References line. +Score on the @code{References} line. @item d Score on the date. @@ -11775,10 +15182,11 @@ Score on the number of lines. @item i -Score on the Message-ID. +Score on the @code{Message-ID} header. @item f -Score on followups. +Score on followups---this matches the author name, and adds scores to +the followups to this author. @item b Score on the body. @@ -11787,7 +15195,7 @@ Score on the head. @item t -Score on thead. +Score on thread. @end table @@ -11903,7 +15311,7 @@ @findex gnus-batch-score @cindex batch scoring @example -$ emacs -batch -l ~/.emacs -l gnus -f gnus-batch-score +$ emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-batch-score @end example @@ -11942,7 +15350,7 @@ @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 +score files. However, if this might make your 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 @@ -11955,6 +15363,10 @@ scoring, then you might set this variable to @code{t}. This will make Gnus save the scores into the @file{.newsrc.eld} file. +If you do not set this to @code{t}, then manual scores (like those set +with @kbd{V s} (@code{gnus-summary-set-score})) will not be preserved +across group visits. + @item gnus-score-interactive-default-score @vindex gnus-score-interactive-default-score Score used by all the interactive raise/lower commands to raise/lower @@ -12017,16 +15429,23 @@ @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}. +@file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE} for each +server. @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. +functions will be called with the group name as argument, 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. + +For example, to do hierarchical scoring but use a non-server-specific +overall score file, you could use the value +@example +(list (lambda (group) ("all.SCORE")) 'gnus-score-find-hierarchical) +@end example @item gnus-score-expiry-days @vindex gnus-score-expiry-days @@ -12226,13 +15645,14 @@ @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 +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 @@ -12514,6 +15934,12 @@ word scoring process will never bring down the score of an article to below this number. The default is @code{nil}. +@vindex gnus-adaptive-word-no-group-words +If @code{gnus-adaptive-word-no-group-words} is set to @code{t}, gnus +won't adaptively word score any of the words in the group name. Useful +for groups like @samp{comp.editors.emacs}, where most of the subject +lines contain the word @samp{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. @@ -12546,7 +15972,7 @@ groups. @item -A function. The result of this function will be used as the home score +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. @@ -12555,11 +15981,11 @@ @enumerate @item -@code{(@var{regexp} @var{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 +@code{(@var{regexp} @var{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 @@ -12706,7 +16132,7 @@ the matches. @item Marking as read -You will probably want to mark articles that has a score below a certain +You will probably want to mark articles that have scores below a certain number as read. This is most easily achieved by putting the following in your @file{all.SCORE} file: @lisp @@ -12922,7 +16348,7 @@ 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}. +@file{http://www.stud.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}. 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 @@ -13052,7 +16478,7 @@ @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 +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 @@ -13422,6 +16848,12 @@ summary buffer looks like. Set @code{gnus-summary-goto-unread} to @code{nil} for a more straightforward action. +Many commands do not use the process/prefix convention. All commands +that do explicitly say so in this manual. To apply the process/prefix +convention to commands that do not use it, you can use the @kbd{M-&} +command. For instance, to mark all the articles in the group as +expirable, you could say `M P b M-& E'. + @node Interactive @section Interactive @@ -13675,6 +17107,15 @@ @code{mouse-face} specs---you can say @samp{%3(hello%)} to have @samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}. +Text inside the @samp{%<} and @samp{%>} specifiers will get the special +@code{balloon-help} property set to @code{gnus-balloon-face-0}. If you +say @samp{%1<}, you'll get @code{gnus-balloon-face-1} and so on. The +@code{gnus-balloon-face-*} variables should be either strings or symbols +naming functions that return a string. Under @code{balloon-help-mode}, +when the mouse passes over text with this property set, a balloon window +will appear and display the string. Please refer to the doc string of +@code{balloon-help-mode} for more information on this. + Here's an alternative recipe for the group buffer: @lisp @@ -13713,6 +17154,9 @@ 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: @@ -13882,16 +17326,8 @@ 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}. +The list of all possible keys for @code{gnus-buffer-configuration} can +be found in its default value. Note that the @code{message} key is used for both @code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If @@ -13907,6 +17343,20 @@ (group 1.0))))) @end lisp +One common desire for a multiple frame split is to have a separate frame +for composing mail and news while leaving the original frame intact. To +accomplish that, something like the following can be done: + +@lisp +(message (frame 1.0 + (if (not (buffer-live-p gnus-summary-buffer)) + (car (cdr (assoc 'group gnus-buffer-configuration))) + (car (cdr (assoc 'summary gnus-buffer-configuration)))) + (vertical ((user-position . t) (top . 1) (left . 1) + (name . "Message")) + (message 1.0 point)))) +@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 @@ -13931,6 +17381,48 @@ ``right'' window configuration, you can set @code{gnus-always-force-window-configuration} to non-@code{nil}. +If you're using tree displays (@pxref{Tree Display}), and the tree +window is displayed vertically next to another window, you may also want +to fiddle with @code{gnus-tree-minimize-window} to avoid having the +windows resized. + +@subsection Example Window Configurations + +@itemize @bullet +@item +Narrow left hand side occupied by group buffer. Right hand side split +between summary buffer (top one-sixth) and article buffer (bottom). + +@ifinfo +@example ++---+---------+ +| G | Summary | +| r +---------+ +| o | | +| u | Article | +| p | | ++---+---------+ +@end example +@end ifinfo + +@lisp +(gnus-add-configuration + '(article + (horizontal 1.0 + (vertical 25 (group 1.0)) + (vertical 1.0 + (summary 0.16 point) + (article 1.0))))) + +(gnus-add-configuration + '(summary + (horizontal 1.0 + (vertical 25 (group 1.0)) + (vertical 1.0 (summary 1.0 point))))) +@end lisp + +@end itemize + @node Faces and Fonts @section Faces and Fonts @@ -14218,10 +17710,6 @@ 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: @@ -14295,32 +17783,11 @@ @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 +"clewis@@ferret.ocunix.on.ca" "cosmo.roadkill" "SpamHippo" +"hweede@@snafu.de")}; fine, upstanding citizens all of them. + +Known despammers that you can put in this list are listed at +@uref{http://www.xs4all.nl/~rosalind/nocemreg/nocemreg.html}. 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 @@ -14328,10 +17795,10 @@ 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 -@code{(@var{issuer} @var{conditions} @dots{})} 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. +@code{(@var{issuer} @var{conditions} @dots{})} 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 @var{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: @@ -14385,6 +17852,18 @@ The default is 15. If you make it shorter Gnus will be faster, but you might then see old spam. +@item gnus-nocem-check-from +@vindex gnus-nocem-check-from +Non-@code{nil} means check for valid issuers in message bodies. +Otherwise don't bother fetching articles unless their author matches a +valid issuer; that is much faster if you are selective about the +issuers. + +@item gnus-nocem-check-article-limit +@vindex gnus-nocem-check-article-limit +If non-@code{nil}, the maximum number of articles to check in any NoCeM +group. NoCeM groups can be huge and very slow to process. + @end table Using NoCeM could potentially be a memory hog. If you have many living @@ -14493,6 +17972,12 @@ @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. @@ -14511,6 +17996,12 @@ 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, @@ -14561,10 +18052,7 @@ @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) +(setq gnus-treat-display-picons t) @end lisp and make sure @code{gnus-picons-database} points to the directory @@ -14581,6 +18069,12 @@ @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, @@ -14629,33 +18123,30 @@ 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}. +in the @code{gnus-picons-display-where} buffer. @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 +Decodes and displays the X-Face header if present. + +@end table + @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. @@ -14714,11 +18205,18 @@ 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-setup-hook +@vindex gnus-picons-setup-hook +Hook run in the picon buffer, if that is displayed. + @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'. +If @code{nil}, display the picons in the @code{From} and +@code{Newsgroups} lines. This is the defailt. + @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 @@ -14728,12 +18226,25 @@ @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. @@ -14741,7 +18252,7 @@ @file{.gnus.el} file: @lisp -(add-hook 'gnus-article-display-hook 'gnus-smiley-display t) +(setq gnus-treat-display-smileys t) @end lisp Smiley maps text smiley faces---@samp{:-)}, @samp{:-=}, @samp{:-(} and @@ -14800,6 +18311,12 @@ @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 @@ -14848,6 +18365,12 @@ 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 @@ -15056,6 +18579,17 @@ @vindex gnus-shell-command-separator String used to separate two shell commands. The default is @samp{;}. +@item gnus-invalid-group-regexp +@vindex gnus-invalid-group-regexp + +Regexp to match ``invalid'' group names when querying user for a group +name. The default value catches some @strong{really} invalid group +names who could possibly mess up Gnus internally (like allowing +@samp{:} in a group name, which is normally used to delimit method and +group). + +IMAP users might want to allow @samp{/} in group names though. + @end table @@ -15095,10 +18629,11 @@ @menu * History:: How Gnus got where it is today. +* On Writing Manuals:: Why this is not a beginner's guide. * Terminology:: We use really difficult, like, words here. * Customization:: Tailoring Gnus to your needs. * Troubleshooting:: What you might try if things do not work. -* A Programmers Guide to Gnus:: Rilly, rilly technical stuff. +* Gnus Reference Guide:: Rilly, rilly technical stuff. * Emacs for Heathens:: A short introduction to Emacsian terms. * Frequently Asked Questions:: A question-and-answer session. @end menu @@ -15111,11 +18646,11 @@ @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. +If you want to investigate the person responsible for this outrage, +you can point your (feh!) web browser to +@file{http://quimby.gnus.org/~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 @@ -15129,6 +18664,27 @@ renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs. ``@sc{gnus}''. New vs. old. +@menu +* Gnus Versions:: What Gnus versions have been released. +* Other Gnus Versions:: Other Gnus versions that also have been released. +* Why?:: What's the point of Gnus? +* Compatibility:: Just how compatible is Gnus with @sc{gnus}? +* Conformity:: Gnus tries to conform to all standards. +* Emacsen:: Gnus can be run on a few modern Emacsen. +* Gnus Development:: How Gnus is developed. +* Contributors:: Oodles of people. +* New Features:: Pointers to some of the new stuff in Gnus. +* Newest Features:: Features so new that they haven't been written yet. +@end menu + + +@node Gnus Versions +@subsection Gnus Versions +@cindex Pterodactyl Gnus +@cindex ding Gnus +@cindex September Gnus +@cindex Quassia Gnus + 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). @@ -15139,8 +18695,12 @@ 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. +On September 13th 1997, Quassia Gnus was started and lasted 37 releases. +If was released as ``Gnus 5.6'' on March 8th 1998 (46 releases). + +Gnus 5.6 begat Pterodactyl Gnus on August 29th 1998 and was released as +``Gnus 5.8'' (after 99 releases and a CVS repository) on December 3rd +1999. If you happen upon a version of Gnus that has a prefixed name -- ``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'' -- @@ -15149,15 +18709,21 @@ 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 Other Gnus Versions +@subsection Other Gnus Versions +@cindex Semi-gnus + +In addition to the versions of Gnus which have had their releases +coordinated by Lars, one major development has been Semi-gnus from +Japan. It's based on a library called @sc{semi}, which provides +@sc{mime} capabilities. + +These Gnusae are based mainly on Gnus 5.6 and Pterodactyl Gnus. +Collectively, they are called ``Semi-gnus'', and different strains are +called T-gnus, ET-gnus, Nana-gnus and Chaos. These provide powerful +@sc{mime} and multilingualization things, especially important for +Japanese users. @node Why? @@ -15184,7 +18750,7 @@ 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 +May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs} and @kbd{C-u 100 M-x all-hail-xemacs}. @@ -15206,7 +18772,7 @@ All commands have kept their names. Some internal functions have changed their names. -The @code{gnus-uu} package has changed drastically. @xref{Decoding +The @code{gnus-uu} package has changed drastically. @xref{Decoding Articles}. One major compatibility question is the presence of several summary @@ -15283,17 +18849,21 @@ @table @emph -@item MIME -Gnus does no MIME handling, 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 +@itemx User-Agent +These are considered to be ``vanity headers'', while I consider them +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 @@ -15314,18 +18884,16 @@ @itemize @bullet @item -Emacs 19.32 and up. - -@item -XEmacs 19.14 and up. - -@item -Mule versions based on Emacs 19.32 and up. +Emacs 20.3 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. +This Gnus version will absolutely not work on any Emacsen older than +that. Not reliably, at least. Older versions of Gnus may work on older +Emacs versions. There are some vague differences between Gnus on the various platforms---XEmacs features more graphics (a logo and a toolbar)---but @@ -15333,6 +18901,44 @@ Emacsen. +@node Gnus Development +@subsection Gnus Development + +Gnus is developed in a two-phased cycle. The first phase involves much +discussion on the @samp{ding@@gnus.org} mailing list, where people +propose changes and new features, post patches and new backends. This +phase is called the @dfn{alpha} phase, since the Gnusae released in this +phase are @dfn{alpha releases}, or (perhaps more commonly in other +circles) @dfn{snapshots}. During this phase, Gnus is assumed to be +unstable and should not be used by casual users. Gnus alpha releases +have names like ``Red Gnus'' and ``Quassia Gnus''. + +After futzing around for 50-100 alpha releases, Gnus is declared +@dfn{frozen}, and only bug fixes are applied. Gnus loses the prefix, +and is called things like ``Gnus 5.6.32'' instead. Normal people are +supposed to be able to use these, and these are mostly discussed on the +@samp{gnu.emacs.gnus} newsgroup. + +@cindex Incoming* +@vindex nnmail-delete-incoming +Some variable defaults differ between alpha Gnusae and released Gnusae. +In particular, @code{nnmail-delete-incoming} defaults to @code{nil} in +alpha Gnusae and @code{t} in released Gnusae. This is to prevent +lossage of mail if an alpha release hiccups while handling the mail. + +The division of discussion between the ding mailing list and the Gnus +newsgroup is not purely based on publicity concerns. It's true that +having people write about the horrible things that an alpha Gnus release +can do (sometimes) in a public forum may scare people off, but more +importantly, talking about new experimental features that have been +introduced may confuse casual users. New features are frequently +introduced, fiddled with, and judged to be found wanting, and then +either discarded or totally rewritten. People reading the mailing list +usually keep up with these rapid changes, whille people on the newsgroup +can't be assumed to do so. + + + @node Contributors @subsection Contributors @cindex contributors @@ -15357,6 +18963,12 @@ Masanobu @sc{Umeda}---the writer of the original @sc{gnus}. @item +Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el, webmail.el, +nnwarchive and many, many other things connected with @sc{mime} and +other types of en/decoding, as well as general bug fixing, new +functionality and stuff. + +@item Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as well as numerous other things). @@ -15364,6 +18976,9 @@ Luis Fernandes---design and graphics. @item +Justin Sheehy--the FAQ maintainer. + +@item Erik Naggum---help, ideas, support, code and stuff. @item @@ -15446,12 +19061,15 @@ Peter Arius, Matt Armstrong, Marc Auslander, +Miles Bader, +Alexei V. Barantsev, Frank Bennett, Robert Bihlmeyer, Chris Bone, Mark Borges, Mark Boyns, Lance A. Brown, +Rob Browning, Kees de Bruin, Martin Buchholz, Joe Buehler, @@ -15464,8 +19082,13 @@ David Charlap, Dan Christensen, Kevin Christian, +Jae-you Chung, @c ? +James H. Cloos, Jr., +Laura Conrad, Michael R. Cook, Glenn Coombs, +Andrew J. Cosgriff, +Neil Crellin, Frank D. Cringle, Geoffrey T. Dairiki, Andre Deparade, @@ -15476,12 +19099,16 @@ Michael Welsh Duggan, Dave Edmondson, Paul Eggert, +Mark W. Eichin, +Karl Eichwalder, Enami Tsugutomo, @c Enami Michael Ernst, Luc Van Eycken, Sam Falkner, Nelson Jose dos Santos Ferreira, Sigbjorn Finne, +Sven Fischer, +Paul Fisher, Decklin Foster, Gary D. Foster, Paul Franklin, @@ -15489,6 +19116,7 @@ Arne Georg Gleditsch, David S. Goldberg, Michelangelo Grigni, +Dale Hagglund, D. Hall, Magnus Hammerin, Kenichi Handa, @c Handa @@ -15496,29 +19124,36 @@ Yoshiki Hayashi, @c ? P. E. Jareth Hein, Hisashige Kenji, @c Hisashige +Scott Hofmann, Marc Horowitz, Gunnar Horrigmo, Richard Hoskins, Brad Howes, +Miguel de Icaza, François Felix Ingrand, +Tatsuya Ichikawa, @c ? Ishikawa Ichiro, @c Ishikawa Lee Iverson, Iwamuro Motonori, @c Iwamuro Rajappa Iyer, Andreas Jaeger, +Adam P. Jenkins, Randell Jesup, Fred Johansen, Gareth Jones, Simon Josefsson, Greg Klanderman, Karl Kleinpaste, +Michael Klingbeil, Peter Skov Knudsen, Shuhei Kobayashi, @c Kobayashi +Petr Konecny, Koseki Yoshinori, @c Koseki Thor Kristoffersen, Jens Lautenbacher, Martin Larose, Seokchan Lee, @c Lee +Joerg Lenneis, Carsten Leonhardt, James LewisMoss, Christian Limpach, @@ -15545,11 +19180,13 @@ Ken Olstad, Masaharu Onishi, @c Onishi Hideki Ono, @c Ono +Ettore Perazzoli, William Perry, Stephen Peters, Jens-Ulrik Holger Petersen, Ulrich Pfeifer, Matt Pharr, +Andy Piper, John McClary Prevost, Bill Pringlemeir, Mike Pullen, @@ -15562,17 +19199,18 @@ Roland B. Roberts, Bart Robinson, Christian von Roques, +Markus Rost, 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, @@ -15583,26 +19221,34 @@ Richard Stallman, Greg Stark, Sam Steingold, +Paul Stevenson, +Jonas Steverud, Paul Stodghill, +Kiyokazu Suto, @c Suto Kurt Swanson, Samuel Tardieu, Teddy, Chuck Thompson, +Tozawa Akihiko, @c Tozawa Philippe Troin, James Troup, Trung Tran-Duc, +Jack Twilley, Aaron M. Ucko, Aki Vehtari, Didier Verna, +Vladimir Volovich, Jan Vroonhof, Stefan Waldherr, Pete Ware, Barry A. Warsaw, Christoph Wedler, Joe Wells, -Katsumi Yamaoka, @c Yamaoka +Lee Willis, +Katsumi Yamaoka @c Yamaoka and -Shenghuo Zhu. @c Zhu +Lloyd Zusman. + For a full overview of what each person has done, the ChangeLogs included in the Gnus alpha distributions should give ample reading @@ -15751,6 +19397,12 @@ @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 @@ -15871,11 +19523,6 @@ @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}. @@ -15892,6 +19539,11 @@ @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}). @@ -15968,11 +19620,6 @@ @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. @@ -15987,6 +19634,12 @@ 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 @@ -16090,7 +19743,7 @@ Marks}). @item -A new mail-to-news backend makes it possible to post even when the NNTP +A new mail-to-news backend makes it possible to post even when the @sc{nntp} server doesn't allow posting (@pxref{Mail-To-News Gateways}). @item @@ -16110,6 +19763,11 @@ @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 @@ -16126,11 +19784,6 @@ @item Emphasized text can be properly fontisized: -@lisp -(add-hook 'gnus-article-display-hook - 'gnus-article-emphasize) -@end lisp - @end itemize @@ -16282,12 +19935,6 @@ @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. @@ -16397,8 +20044,6 @@ @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 @@ -16498,8 +20143,6 @@ @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 @@ -16857,7 +20500,7 @@ 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. + the slave dribble files should auto-save to the slave file names. @item a group parameter that says what articles to display on group entry, based on article marks. @@ -17331,7 +20974,7 @@ add a way to select which NoCeM type to apply -- spam, troll, etc. @item - nndraft-request-group should tally autosave files. + nndraft-request-group should tally auto-save files. @item implement nntp-retry-on-break and nntp-command-timeout. @@ -17405,7 +21048,7 @@ in the head or body. @item -Allow breaking lengthy NNTP commands. +Allow breaking lengthy @sc{nntp} commands. @item gnus-article-highlight-limit, to disable highlighting in big articles. @@ -17457,7 +21100,7 @@ @item Group parameters and summary commands for un/subscribing to mailing -lists. +lists. @item Introduce nnmail-home-directory. @@ -17467,6 +21110,116 @@ exits the group. @item +The jingle is only played on the second invocation of Gnus. + +@item +Bouncing articles should do MIME. + +@item +Crossposted articles should "inherit" the % or @ mark from the other +groups it has been crossposted to, or something. (Agent.) + +@item +If point is on a group that appears multiple times in topics, and +you press `l', point will move to the first instance of the group. + +@item +A spec for the group line format to display the number of +agent-downloaded articles in the group. + +@item +Some nntp servers never respond when posting, so there should be a +timeout for all commands. + +@item +When stading on a topic line and `t'-ing, point goes to the last line. +It should go somewhere else. + +@item +I'm having trouble accessing a newsgroup with a "+" in its name with +Gnus. There is a new newsgroup on msnews.microsoft.com named +"microsoft.public.multimedia.directx.html+time" that I'm trying to +access as +"nntp+msnews.microsoft.com:microsoft.public.multimedia.directx.html+time" +but it gives an error that it cant access the group. + +Is the "+" character illegal in newsgroup names? Is there any way in +Gnus to work around this? (gnus 5.6.45 - XEmacs 20.4) + +@item + +When `#F', do: + +@example +Subject: Answer to your mails 01.01.1999-01.05.1999 + --text follows this line-- +Sorry I killfiled you... + +Under the subject "foo", you wrote on 01.01.1999: +> bar +Under the subject "foo1", you wrote on 01.01.1999: +> bar 1 +@end example + +@item +Allow "orphan" scores in the Agent scoring. + +@item +@example + - Edit article's summary line. + - End edit + - Sort lines in buffer by subject + + --> the old subject line appears in Summary buffer, not the one that was + just changed to. +@end example + + +@item +Remove list identifiers from the subject in the summary when doing `^' +and the like. + +@item +Have the Agent write out articles, one by one, as it retrieves them, +to avoid having to re-fetch them all if Emacs should crash while +fetching. + +@item +Be able to forward groups of messages as MIME digests. + +@item +nnweb should include the "get whole article" article when getting articles. + +@item +When I type W W c (gnus-article-hide-citation) in the summary +buffer, the citations are revealed, but the [+] buttons don't turn +into [-] buttons. (If I click on one of the [+] buttons, it does +turn into a [-] button.) + +@item +Perhaps there should be a command to "attach" a buffer of comments to +a message? That is, `B WHATEVER', you're popped into a buffer, write +something, end with `C-c C-c', and then the thing you've written gets +to be the child of the message you're commenting. + +@item +Handle external-body parts. + +@item +When renaming a group name, nnmail-split-history does not get the group +name renamed. + +@item +Allow mail splitting on bodies when using advanced mail splitting. + +@lisp + (body "whatever.text") +@end lisp + +@item +Be able to run `J u' from summary buffers. + +@item Solve the halting problem. @c TODO @@ -17482,6 +21235,10 @@ 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: @@ -17518,10 +21275,40 @@ @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 +@node On Writing Manuals +@section On Writing Manuals + +I guess most manuals are written after-the-fact; documenting a program +that's already there. This is not how this manual is written. When +implementing something, I write the manual entry for that something +straight away. I then see that it's difficult to explain the +functionality, so I write how it's supposed to be, and then I change the +implementation. Writing the documentation and writing the code goes +hand in hand. + +This, of course, means that this manual has no, or little, flow. It +documents absolutely everything in Gnus, but often not where you're +looking for it. It is a reference manual, and not a guide to how to get +started with Gnus. + +That would be a totally different book, that should be written using the +reference manual as source material. It would look quite differently. + + @page @node Terminology @section Terminology @@ -17708,7 +21495,7 @@ @item digest @cindex digest A collection of messages in one file. The most common digest format is -specified by RFC1153. +specified by RFC 1153. @end table @@ -17774,13 +21561,11 @@ 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)) +(setq gnus-treat-hide-headers 'head + gnus-treat-hide-signature t + gnus-treat-hide-citation t) @end lisp @item gnus-use-full-window @@ -17814,6 +21599,12 @@ use any other newsreaders than Gnus. This variable is @code{t} by default. +@item gnus-read-newsrc-file +If this is @code{nil}, Gnus will never read @file{.newsrc}---it will +only read @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} @@ -17837,9 +21628,6 @@ @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 @@ -17887,7 +21675,7 @@ @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 +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. @@ -17919,8 +21707,8 @@ @page -@node A Programmers Guide to Gnus -@section A Programmer@'s Guide to Gnus +@node Gnus Reference Guide +@section Gnus Reference Guide 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 @@ -18058,7 +21846,7 @@ @lisp (gnus-check-backend-function "request-scan" "nnml:misc") -=> t +@result{} t @end lisp @item gnus-read-method @@ -18279,7 +22067,7 @@ 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} +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: @@ -18400,6 +22188,48 @@ There should be no result data from this function. +@item (nnchoke-request-set-mark GROUP ACTION &optional SERVER) + +Set/remove/add marks on articles. Normally Gnus handles the article +marks (such as read, ticked, expired etc) internally, and store them in +@code{~/.newsrc.eld}. Some backends (such as @sc{imap}) however carry +all information about the articles on the server, so Gnus need to +propagate the mark information to the server. + +ACTION is a list of mark setting requests, having this format: + +@example +(RANGE ACTION MARK) +@end example + +Range is a range of articles you wish to update marks on. Action is +@code{set}, @code{add} or @code{del}, respectively used for removing all +existing marks and setting them as specified, adding (preserving the +marks not mentioned) mark and removing (preserving the marks not +mentioned) marks. Mark is a list of marks; where each mark is a symbol. +Currently used marks are @code{read}, @code{tick}, @code{reply}, +@code{expire}, @code{killed}, @code{dormant}, @code{save}, +@code{download} and @code{unsend}, but your backend should, if possible, +not limit itself to these. + +Given contradictory actions, the last action in the list should be the +effective one. That is, if your action contains a request to add the +@code{tick} mark on article 1 and, later in the list, a request to +remove the mark on the same article, the mark should in fact be removed. + +An example action list: + +@example +(((5 12 30) 'del '(tick)) + ((10 . 90) 'add '(read expire)) + ((92 94) 'del '(read))) +@end example + +The function should return a range of articles it wasn't able to set the +mark on (currently not used for anything). + +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 @@ -18917,7 +22747,7 @@ 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., +RFC 1036 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'', @@ -18926,12 +22756,12 @@ 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{xref}, and @code{extra}. 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. +All these slots contain strings, except the @code{extra} slot, which +contains an alist of header/value pairs (@pxref{To From Newsgroups}). @node Ranges @@ -19025,7 +22855,7 @@ second is a more complex one: @example -("no.group" 5 (1 . 54324)) +("no.group" 5 ((1 . 54324))) ("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55)) ((tick (15 . 19)) (replied 3 6 (19 . 3))) @@ -19423,11 +23253,14 @@ @chapter Key Index @printindex ky -@setchapternewpage odd @summarycontents @contents @bye +@iftex +@iflatex +\end{document} +@end iflatex +@end iftex @c End: -