-\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*- -*- coding: iso-latin-1 -*-
@setfilename gnus
-@settitle Semi-gnus 6.10.059 Manual
+@settitle T-gnus 6.14 Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
-@c @direntry
-@c * Gnus: (gnus). The newsreader Gnus.
-@c @end direntry
+@dircategory Editors
+@direntry
+* Gnus: (gnus). The newsreader Gnus.
+@end direntry
@iftex
@finalout
@end iftex
\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}{\$}
\thispagestyle{empty}
-Copyright \copyright{} 1995,96,97,98,99 Free Software Foundation, Inc.
+Copyright \copyright{} 1995,96,97,98,99,2000 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, 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.
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
+(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
-@ifinfo
+@ifnottex
This file documents gnus, the GNU Emacs newsreader.
-Copyright (C) 1995,96,97,98,99 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.
+Copyright (C) 1995,96,97,98,99,2000 Free Software Foundation, Inc.
-@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).
+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.
-@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.
+(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.''
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
-@end ifinfo
+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 Semi-gnus 6.10.059 Manual
+@title T-gnus 6.14 Manual
@author by Lars Magne Ingebrigtsen
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1995,96,97,98,99 Free Software Foundation, Inc.
+Copyright @copyright{} 1995,96,97,98,99,2000 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, 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.
-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.
+(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.''
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
+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
spool or your mbox file. All at the same time, if you want to push your
luck.
-Semi-gnus provides MIME features based on SEMI API. So Semi-gnus
-supports your right to read strange messages including big images or
-other various kinds of formats. Semi-gnus also supports
+T-gnus provides MIME features based on SEMI API. So T-gnus supports
+your right to read strange messages including big images or other
+various kinds of formats. T-gnus also supports
internationalization/localization and multiscript features based on MULE
-API. So Semi-gnus does not discriminate various language communities.
+API. So T-gnus does not discriminate various language communities.
Oh, if you are a Klingon, please wait Unicode Next Generation.
-This manual corresponds to Semi-gnus 6.10.059.
+This manual corresponds to T-gnus 6.14.
@end ifinfo
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
@end iftex
-
@menu
* Starting Up:: Finding news can be a pain.
* The Group Buffer:: Selecting, subscribing and killing groups.
* 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
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.
@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
Now, you all know about the @file{.newsrc} file. All subscription
information is traditionally stored in this file.
-Things got a bit more complicated with @sc{GNUS}. In addition to
+Things got a bit more complicated with @sc{gnus}. In addition to
keeping the @file{.newsrc} file updated, it also used a file called
@file{.newsrc.el} for storing all the information that didn't fit into
the @file{.newsrc} file. (Actually, it also duplicated everything in
-the @file{.newsrc} file.) @sc{GNUS} would read whichever one of these
+the @file{.newsrc} file.) @sc{gnus} would read whichever one of these
files was the most recently saved, which enabled people to swap between
@sc{gnus} and other newsreaders.
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
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
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.
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.
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
@vindex gnus-group-highlight
Highlighting in the group buffer is controlled by the
@code{gnus-group-highlight} variable. This is an alist with elements
-that look like @var{(form . face)}. If @var{form} evaluates to
+that look like @code{(@var{form} . @var{face})}. If @var{form} evaluates to
something non-@code{nil}, the @var{face} will be used on the line.
Here's an example value for this variable that might look nice if the
background is dark:
@lisp
-(face-spec-set 'my-group-face-1
- '((t (:foreground "Red" :bold t))))
-(face-spec-set 'my-group-face-2
- '((t (:foreground "SeaGreen" :bold t))))
-(face-spec-set 'my-group-face-3
- '((t (:foreground "SpringGreen" :bold t))))
-(face-spec-set 'my-group-face-4
- '((t (:foreground "SteelBlue" :bold t))))
-(face-spec-set 'my-group-face-5
- '((t (:foreground "SkyBlue" :bold t))))
+(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)
group from the server. If you give a numerical prefix @var{N}, @var{N}
determines the number of articles gnus will fetch. If @var{N} is
positive, gnus fetches the @var{N} newest articles, if @var{N} is
-negative, gnus fetches the @var{abs(N)} oldest articles.
+negative, Gnus fetches the @code{abs(@var{N})} oldest articles.
@item RET
@kindex RET (Group)
It is recommended that you keep all your mail groups (if any) on quite
low levels (e.g. 1 or 2).
+Maybe the following description of the default behavior of Gnus helps to
+understand what these levels are all about. By default, Gnus shows you
+subscribed nonempty groups, but by hitting @kbd{L} you can have it show
+empty subscribed groups and unsubscribed groups, too. Type @kbd{l} to
+go back to showing nonempty subscribed groups again. Thus, unsubscribed
+groups are hidden, in a way.
+
+Zombie and killed groups are similar to unsubscribed groups in that they
+are hidden by default. But they are different from subscribed and
+unsubscribed groups in that Gnus doesn't ask the news server for
+information (number of messages, number of unread messages) on zombie
+and killed groups. Normally, you use @kbd{C-k} to kill the groups you
+aren't interested in. If most groups are killed, Gnus is faster.
+
+Why does Gnus distinguish between zombie and killed groups? Well, when
+a new group arrives on the server, Gnus by default makes it a zombie
+group. This means that you are normally not bothered with new groups,
+but you can type @kbd{A z} to get a list of all new groups. Subscribe
+the ones you like and kill the ones you don't want. (@kbd{A k} shows a
+list of killed groups.)
+
If you want to play with the level variables, you should show some care.
Set them once, and don't touch them ever again. Better yet, don't touch
them at all unless you know exactly what you're doing.
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
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
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)
(@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
@end table
-@xref{Select Methods} for more information on the various select
+@xref{Select Methods}, for more information on the various select
methods.
@vindex gnus-activate-foreign-newsgroups
@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")
@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
@code{iso-8859-1} the default charset; that is, the charset that will be
used for all articles that do not specify a charset.
-@item @var{(variable form)}
+@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
@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
+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
+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,
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
@end table
-All the commands below obeys the process/prefix convention
+All the commands below obey the process/prefix convention
(@pxref{Process/Prefix}).
When given a symbolic prefix (@pxref{Symbolic Prefixes}), all these
(@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
(@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
@end table
-@xref{Sorting Groups} for more information about group sorting.
+@xref{Sorting Groups}, for more information about group sorting.
@node Topic Topology
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
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
* 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.
@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.
@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
@item gnus-summary-highlight
@vindex gnus-summary-highlight
Summary lines are highlighted according to this variable, which is a
-list where the elements are of the format @var{(FORM . FACE)}. If you
-would, for instance, like ticked articles to be italic and high-scored
-articles to be bold, you could set this variable to something like
+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
@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)
@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
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
@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
@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
@item F
@vindex gnus-souped-mark
-@sc{SOUP}ed article (@code{gnus-souped-mark}). @xref{SOUP}.
+@sc{soup}ed article (@code{gnus-souped-mark}). @xref{SOUP}.
@item Q
@vindex gnus-sparse-mark
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
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
@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
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)
@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
@item / M
@kindex / M (Summary)
@findex gnus-summary-limit-exclude-marks
-Exclude all marked articles (@code{gnus-summary-limit-exclude-marks}).
+Exclude all marked articles (@code{gnus-summary-limit-exclude-marks}).
@item / T
@kindex / T (Summary)
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
@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}).
(setq gnus-thread-sort-functions
'(gnus-thread-sort-by-number
gnus-thread-sort-by-subject
- (reverse 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
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
@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
(@code{gnus-uu-decode-uu-and-save}).
All this is very much different from how @code{gnus-uu} worked with
-@sc{GNUS 4.1}, where you had explicit keystrokes for everything under
+@sc{gnus 4.1}, where you had explicit keystrokes for everything under
the sun. This version of @code{gnus-uu} generally assumes that you mark
articles in some way (@pxref{Setting Process Marks}) and then press
@kbd{X u}.
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.
* 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
@vindex gnus-header-face-alist
Highlight the headers (@code{gnus-article-highlight-headers}). The
highlighting will be done according to the @code{gnus-header-face-alist}
-variable, which is a list where each element has the form @var{(regexp
-name content)}. @var{regexp} is a regular expression for matching the
+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
@end table
-@xref{Customizing Articles} for how to highlight articles automatically.
+@xref{Customizing Articles}, for how to highlight articles automatically.
@node Article Fontisizing
@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
("\\*\\(\\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
(copy-face 'red 'gnus-emphasis-italic)
@end lisp
-@xref{Customizing Articles} for how to fontize articles automatically.
+@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.
@node Article Hiding
@item W W h
@kindex W W h (Summary)
-@findex gnus-article-hide-headers
-Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
+@findex gnus-article-toggle-headers
+Toggle hiding of headers (@code{gnus-article-toggle-headers}). @xref{Hiding
Headers}.
@item W W b
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
@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 regulax expression matching text to be
+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.
+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)
@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
Also @pxref{Article Highlighting} for further variables for
citation customization.
-@xref{Customizing Articles} for how to hide article elements
+@xref{Customizing Articles}, for how to hide article elements
automatically.
@kindex W l (Summary)
@findex gnus-summary-stop-page-breaking
Remove page breaks from the current article
-(@code{gnus-summary-stop-page-breaking}). @xref{Misc Article} for page
+(@code{gnus-summary-stop-page-breaking}). @xref{Misc Article}, for page
delimiters.
@item W r
is rumored to have employed this form of, uh, somewhat weak encryption.
@item W t
+@item t
@kindex W t (Summary)
-@findex gnus-summary-toggle-header
+@kindex t (Summary)
+@findex gnus-article-toggle-headers
Toggle whether to display all headers in the article buffer
-(@code{gnus-summary-toggle-header}).
+(@code{gnus-article-toggle-headers}).
@item W v
@kindex W v (Summary)
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
+@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-sentencse
+@findex gnus-article-capitalize-sentences
Capitalize the first word in each sentence
(@code{gnus-article-capitalize-sentences}).
CRs into LF (this takes care of Mac line endings)
(@code{gnus-article-remove-cr}).
+@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)
@cindex x-face
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.
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
@end table
-@xref{Customizing Articles} for how to wash articles automatically.
+@xref{Customizing Articles}, for how to wash articles automatically.
@node Article Buttons
(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
@end table
-@xref{Customizing Articles} for how to buttonize articles automatically.
+@xref{Customizing Articles}, for how to buttonize articles automatically.
@node Article Date
@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)
@end table
-@xref{Customizing Articles} for how to display the date in your
+@xref{Customizing Articles}, for how to display the date in your
preferred format automatically.
@vindex gnus-signature-limit
@code{gnus-signature-limit} provides a limit to what is considered a
-signature.
+signature when displaying articles.
@enumerate
@item
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 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
@item W M w
@kindex W M w (Summary)
-Decode RFC2047-encoded words in the article headers
+Decode RFC 2047-encoded words in the article headers
(@code{gnus-article-decode-mime-words}).
@item W M c
'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
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
@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
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
(@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.)
@item gnus-tree-brackets
@vindex gnus-tree-brackets
This is used for differentiating between ``real'' articles and
-``sparse'' articles. The format is @var{((real-open . real-close)
-(sparse-open . sparse-close) (dummy-open . dummy-close))}, and the
+``sparse'' articles. The format is @code{((@var{real-open} . @var{real-close})
+(@var{sparse-open} . @var{sparse-close}) (@var{dummy-open} . @var{dummy-close}))}, and the
default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}) (?< . ?>))}.
@item gnus-tree-parent-child-edges
@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)
@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)
@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
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
@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)
@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
Edit the group parameters (@pxref{Group Parameters}) of the current
group (@code{gnus-summary-edit-parameters}).
-@item M-C-g
-@kindex M-C-g (Summary)
+@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}).
@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
@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
@menu
* Hiding Headers:: Deciding what headers should be displayed.
-* Using MIME:: Pushing to mime articles as @sc{mime} messages.
+* 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.
non-@code{nil} every-time, then you can push button in the article
buffer when there are nobody else.
+Also see @pxref{MIME Commands}.
+
@node Customizing Articles
@section Customizing Articles
@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.
than this number.
@item
-A list:
+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},
(typep "text/x-vcard"))
@end lisp
+@item
+@code{mime}: Do this treatment if the value of @code{gnus-show-mime}' is
+non-nil.
+
@end enumerate
You may have noticed that the word @dfn{part} is used here. This refers
The following treatment options are available. The easiest way to
customize this is to examine the @code{gnus-article-treat} customization
-group.
+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
-@item gnus-treat-buttonize
-@item gnus-treat-buttonize-head
-@item gnus-treat-emphasize
-@item gnus-treat-fill-article
-@item gnus-treat-strip-cr
-@item gnus-treat-hide-headers
-@item gnus-treat-hide-boring-headers
-@item gnus-treat-hide-signature
-@item gnus-treat-hide-citation
-@item gnus-treat-strip-pgp
-@item gnus-treat-strip-pem
-@item gnus-treat-highlight-headers
-@item gnus-treat-highlight-citation
-@item gnus-treat-highlight-signature
-@item gnus-treat-date-ut
-@item gnus-treat-date-local
-@item gnus-treat-date-lapsed
-@item gnus-treat-date-original
-@item gnus-treat-strip-trailing-blank-lines
-@item gnus-treat-strip-leading-blank-lines
-@item gnus-treat-strip-multiple-blank-lines
-@item gnus-treat-strip-blank-lines
-@item gnus-treat-overstrike
-@item gnus-treat-display-xface
-@item gnus-treat-display-smileys
-@item gnus-treat-display-picons
+@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
+@item gnus-treat-decode-article-as-default-mime-charset
@end table
@vindex gnus-part-display-hook
@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. However, you shouldn't delete any headers. Instead make
-them invisible if you want to make them go away.
+everything.
@node Article Keymap
@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
@cindex reply
@cindex followup
@cindex post
+@cindex using gpg
@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.
* 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?
+* Using GPG:: How to use GPG and MML to sign and encrypt messages
@end menu
Also see @pxref{Canceling and Superseding} for information on how to
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
(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
@itemize @bullet
@item a string
Messages will be saved in that group.
+
+Note that you can include a select method in the group name, then the
+message will not be stored in the select method given by
+@code{gnus-message-archive-method}, but in the select method specified
+by the group name, instead. Suppose @code{gnus-message-archive-method}
+has the default value shown above. Then setting
+@code{gnus-message-archive-group} to @code{"foo"} means that outgoing
+messages are stored in @samp{nnfolder+archive:foo}, but if you use the
+value @code{"nnml:foo"}, then outgoing messages will be stored in
+@samp{nnml:foo}.
@item a list of strings
Messages will be saved in all those groups.
@item an alist of regexps, functions and forms
(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
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 @var{(name . 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.
+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 (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 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}.
+of the @code{message-news-p} and @code{message-mail-p} functions.
-@vindex message-this-is-mail
-@vindex message-this-is-news
+@findex message-mail-p
+@findex message-news-p
So here's a new example:
(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.")
(@pxref{Drafts}). When the server comes back up again, you'd then
typically enter that group and send all the articles off.
+@node Using GPG
+@section Using GPG
+@cindex using gpg
+
+Gnus has an ALPHA support to GPG that's provided by @file{gpg.el} and
+@file{mml2015.el}. When viewing signed or encrypted messages, Gnus automatically
+asks if you want to verify or decrypt them.
+
+To use this correctly with GPG, you'll need the following lisp code in your
+@file{~/.emacs} or @file{~/.gnus}:
+
+@lisp
+(setq mml2015-use 'gpg)
+(setq gpg-temp-directory "~/.gnupg/tmp")
+@end lisp
+
+The @code{gpg-temp-directory} need to point to a directory with permissions set
+to 700, for your own safety.
+
+If you want to benefit of PGP2.6 compatibility, you might create a script named
+@file{gpg-2comp} with these instructions:
+
+@code{
+#!/bin/sh
+exec gpg --rfc1991 "$@@"
+}
+
+If you don't want to use such compatibility, you can add the following line to
+your @file{~/.emacs} or @file{~/.gnus}:
+
+@lisp
+(setq gpg-command-default-alist (quote ((gpg . "gpg") (gpg-2comp . "gpg"))))
+@end lisp
+
+To sign or encrypt your message you may choose to use the MML Security menu or
+@kbd{M-m s p} to sign your message using PGP/MIME, @kbd{M-m s s} to sign your
+message using S/MIME. There's also @kbd{M-m c p} to encrypt your message with
+PGP/MIME and @kbd{M-m c s} to encrypt using S/MIME.
+
+Gnus will ask for your passphrase three times and then it will send your
+message, if you've typed it correctly.
+
@node Select Methods
@chapter 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.
will.
After these two elements, there may be an arbitrary number of
-@var{(variable form)} pairs.
+@code{(@var{variable} @var{form})} pairs.
To go back to the first example---imagine that you want to read from
port 15 on that machine. This is what the select method should
(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.
The file contains one or more line, each of which define one server.
@item
-Each line may contain an arbitrary number of token/value pairs. The
-valid tokens include @samp{machine}, @samp{login}, @samp{password},
-@samp{default} and @samp{force}. (The latter is not a valid
-@file{.netrc}/@code{ftp} token, which is the only way the
-@file{.authinfo} file format deviates from the @file{.netrc} file
-format.)
-
+Each line may contain an arbitrary number of token/value pairs.
@end enumerate
+The valid tokens include @samp{machine}, @samp{login}, @samp{password},
+@samp{default}. Gnus introduce two new tokens, not present in the
+original @file{.netrc}/@code{ftp} syntax, namely @samp{port} and
+@samp{force}. (This is the only way the @file{.authinfo} file format
+deviates from the @file{.netrc} file format.) @samp{port} is used to
+indicate what port on the server the credentials apply to, @samp{force}
+is explained below.
+
Here's an example file:
@example
Port number to connect to when using the @code{nntp-open-network-stream}
connect function.
+@item nntp-list-options
+@vindex nntp-list-options
+List of newsgroup name used for a option of the LIST command to restrict
+the listing output to only the specified newsgroups. Each newsgroup name
+can be a shell-style wildcard, for instance, @dfn{fj.*}, @dfn{japan.*},
+etc. Fortunately, if the server can accept such a option, it will
+probably make gnus run faster. You may use it as a server variable as
+follows:
+
+@lisp
+(setq gnus-select-method
+ '(nntp "news.somewhere.edu"
+ (nntp-list-options ("fj.*" "japan.*"))))
+@end lisp
+
+@item nntp-options-subscribe
+@vindex nntp-options-subscribe
+Regexp matching the newsgroup names which will be subscribed
+unconditionally. Use @dfn{ } instead of @dfn{$} for a regexp string.
+It may be effective as well as @code{nntp-list-options} even though the
+server could not accept a shell-style wildcard as a option of the LIST
+command. You may use it as a server variable as follows:
+
+@lisp
+(setq gnus-select-method
+ '(nntp "news.somewhere.edu"
+ (nntp-options-subscribe "^fj\\.\\|^japan\\.")))
+@end lisp
+
+@item nntp-options-not-subscribe
+@vindex nntp-options-not-subscribe
+Regexp matching the newsgroup names which will not be subscribed
+unconditionally. Use @dfn{ } instead of @dfn{$} for a regexp string.
+It may be effective as well as @code{nntp-list-options} even though the
+server could not accept a shell-style wildcard as a option of the LIST
+command. You may use it as a server variable as follows:
+
+@lisp
+(setq gnus-select-method
+ '(nntp "news.somewhere.edu"
+ (nntp-options-not-subscribe "\\.binaries\\.")))
+@end lisp
+
@item nntp-buggy-select
@vindex nntp-buggy-select
Set this to non-@code{nil} if your select routine is buggy.
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.
+* 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.
@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
@code{nnmail-crosspost-link-function} to @code{copy-file}. (This
variable is @code{add-name-to-file} by default.)
-@findex nnmail-split-header-length-limit
-Header lines may be arbitrarily long. However, the longer a line is,
-the longer it takes to match them. Very long lines may lead to Gnus
-taking forever to split the mail, so Gnus excludes lines that are longer
-than @code{nnmail-split-header-length-limit} (which defaults to 1024).
-
@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
@subsection Mail Sources
Mail can be gotten from many different sources---the mail spool, from a
-POP mail server, or from a procmail directory, for instance.
+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.
@cindex mail spool
@cindex mail source
-You tell Gnus how to fetch mail by creating a @dfn{mail source
-specifier}.
+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:
(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.
+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:
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:
@code{MAILHOST} environment variable.
@item :port
-The port number of the POP server. The default is @samp{pop3}.
+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
and says what authentication scheme to use. The default is
@code{password}.
-@end table
+@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.
-If the @code{:program} and @code{:function} keywords aren't specified,
-@code{pop3-movemail} will be used.
+Keywords:
-Here are some examples. Fetch from the default POP server, using the
-default user name, and default fetcher:
+@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}.
-@lisp
-(pop)
-@end lisp
+@item :user
+The user name to give to the webmail server. The default is the login
+name.
-Fetch from a named server with a named user and password:
+@item :password
+The password to give to the webmail server. If not specified, the user is
+prompted.
-@lisp
-(pop :server "my.pop.server"
- :user "user-name" :password "secret")
-@end lisp
+@item :dontexpunge
+If non-nil, only fetch unread articles and don't move them to trash
+folder after finishing the fetch.
-Use @samp{movemail} to move the mail:
+@end table
+
+An example webmail source:
@lisp
-(pop :program "movemail"
- :args (format "po:%s %s %s" user mail-source-crash-box password))
+(webmail :subtype 'hotmail :user "user-name" :password "secret")
@end lisp
+@end table
-@item maildir
-Get mail from a maildir. This is a type of mailbox currently only
-supported by qmail, where each file in a special directory contains
-exactly one mail.
+@table @dfn
+@item Common Keywords
+Common keywords can be used in any type of mail source.
Keywords:
@table @code
-@item :path
-The path of the directory where the mails are stored. The default is
-@samp{~/Maildir/new}.
+@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
-If you sometimes look at your mail through a pop3 daemon before fetching
-them with Gnus, you may also have to fetch your mails from the
-@code{cur} directory inside the maildir, like in the following example.
+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
-An example maildir mail source:
+@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
-(maildir :path "/home/user-name/Maildir/cur")
+(setq mail-sources '((pop :user "jrl"
+ :server "pophost" :function fetchfunc)))
@end lisp
-@end table
+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
variables.
@table @code
-@item mail-source-movemail-program
-@vindex mail-source-movemail-program
-A command to be executed to move mail from the inbox. 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 file, and the file
-to be moved to.
-
-@item mail-source-movemail-args
-@vindex mail-source-movemail-args
-Extra arguments to give to the command described above.
-
@item mail-source-crash-box
@vindex mail-source-crash-box
File where mail will be stored while processing it. The default is
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.
@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{nnmail-spool-file} to a list of mail source specifiers
+@code{mail-sources} to a list of mail source specifiers
(@pxref{Mail Source Specifiers}).
-If this variable is @code{nil}, the mail backends will never attempt to
-fetch mail by themselves.
+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 nnmail-spool-file
+(setq mail-sources
'((file)
(pop :server "pop3.mail.server"
:password "secret")))
Or, if you don't want to use any of the keyword defaults:
@lisp
-(setq nnmail-spool-file
+(setq mail-sources
'((file :path "/var/spool/mail/user-name")
(pop :server "pop3.mail.server"
:user "user-name"
@vindex nnmail-split-hook
@item nnmail-split-hook
@findex article-decode-encoded-words
-@findex RFC1522 decoding
-@findex RFC2047 decoding
+@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
;; 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.
examples.
@item
-@var{(FIELD VALUE SPLIT)}: If the split is a list, the first element of
-which is a string, then store the message as specified by SPLIT, if
-header FIELD (a regexp) contains VALUE (also a regexp).
+@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
-@var{(| SPLIT...)}: If the split is a list, and the first element is
-@code{|} (vertical bar), then process each SPLIT until one of them
-matches. A SPLIT is said to match if it will cause the mail message to
-be stored in one or more groups.
+@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
-@var{(& SPLIT...)}: If the split is a list, and the first element is
-@code{&}, then process all SPLITs in the list.
+@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.
+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
-@var{(: function arg1 arg2 ...)}: If the split is a list, and the first
-element is @code{:}, then the second element will be called as a
-function with @var{args} given as arguments. The function should return
-a SPLIT.
+@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
(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.
+@findex nnmail-split-fancy-with-parent
+@code{nnmail-split-fancy-with-parent} is a function which allows you to
+split followups into the same groups their parents are in. Sometimes
+you can't make splitting rules for all your mail. For example, your
+boss might send you personal mail regarding different projects you are
+working on, and as you can't tell your boss to put a distinguishing
+string into the subject line, you have to resort to manually moving the
+messages into the right group. With this function, you only have to do
+it once per thread.
+
+To use this feature, you have to set @code{nnmail-treat-duplicates} to a
+non-nil value. And then you can include
+@code{nnmail-split-fancy-with-parent} using the colon feature, like so:
+@lisp
+(setq nnmail-split-fancy
+ '(| (: nnmail-split-fancy-with-parent)
+ ;; other splits go here
+ ))
+@end lisp
+
+This feature works as follows: when @code{nnmail-treat-duplicates} is
+non-nil, Gnus records the message id of every message it sees in the
+file specified by the variable @code{nnmail-message-id-cache-file},
+together with the group it is in (the group is omitted for non-mail
+messages). When mail splitting is invoked, the function
+@code{nnmail-split-fancy-with-parent} then looks at the References (and
+In-Reply-To) header of each message to split and searches the file
+specified by @code{nnmail-message-id-cache-file} for the message ids.
+When it has found a parent, it returns the corresponding group name. It
+is recommended that you set @code{nnmail-message-id-cache-length} to a
+somewhat higher number than the default so that the message ids are
+still in the cache. (A value of 5000 appears to create a file some
+300 kBytes in size.)
+
+
+@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
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
@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:
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:
'("(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.
@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
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
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
@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:
@end table
-@node Mail Folders
-@subsubsection Mail Folders
-@cindex nnfolder
-@cindex mbox folders
-@cindex mail folders
+@node Mail Folders
+@subsubsection Mail Folders
+@cindex nnfolder
+@cindex mbox folders
+@cindex mail folders
+
+@code{nnfolder} is a backend for storing each mail group in a separate
+file. Each file is in the standard Un*x mbox format. @code{nnfolder}
+will add extra headers to keep track of article numbers and arrival
+dates.
+
+Virtual server settings:
+
+@table @code
+@item nnfolder-directory
+@vindex nnfolder-directory
+All the @code{nnfolder} mail boxes will be stored under this directory.
+
+@item nnfolder-active-file
+@vindex nnfolder-active-file
+The name of the active file.
+
+@item nnfolder-newsgroups-file
+@vindex nnfolder-newsgroups-file
+The name of the group descriptions file. @xref{Newsgroups File Format}.
+
+@item nnfolder-get-new-mail
+@vindex nnfolder-get-new-mail
+If non-@code{nil}, @code{nnfolder} will read incoming mail.
+
+@item nnfolder-save-buffer-hook
+@vindex nnfolder-save-buffer-hook
+@cindex backup files
+Hook run before saving the folders. Note that Emacs does the normal
+backup renaming of files even with the @code{nnfolder} buffers. If you
+wish to switch this off, you could say something like the following in
+your @file{.emacs} file:
+
+@lisp
+(defun turn-off-backup ()
+ (set (make-local-variable 'backup-inhibited) t))
+
+(add-hook 'nnfolder-save-buffer-hook 'turn-off-backup)
+@end lisp
+
+@item nnfolder-delete-mail-hook
+@vindex nnfolder-delete-mail-hook
+Hook run in a buffer narrowed to the message that is to be deleted.
+This function can be used to copy the message to somewhere else, or to
+extract some information from it before removing it.
+
+@end table
+
+
+@findex nnfolder-generate-active-file
+@kindex M-x nnfolder-generate-active-file
+If you have lots of @code{nnfolder}-like files you'd like to read with
+@code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
+command to make @code{nnfolder} aware of all likely files in
+@code{nnfolder-directory}. 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
+
+
-@code{nnfolder} is a backend for storing each mail group in a separate
-file. Each file is in the standard Un*x mbox format. @code{nnfolder}
-will add extra headers to keep track of article numbers and arrival
-dates.
+@node Ultimate
+@subsection Ultimate
+@cindex nnultimate
+@cindex Ultimate Bulletin Board
-Virtual server settings:
+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.
-@table @code
-@item nnfolder-directory
-@vindex nnfolder-directory
-All the @code{nnfolder} mail boxes will be stored under this directory.
+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.
-@item nnfolder-active-file
-@vindex nnfolder-active-file
-The name of the active file.
+The following @code{nnultimate} variables can be altered:
-@item nnfolder-newsgroups-file
-@vindex nnfolder-newsgroups-file
-The name of the group descriptions file. @xref{Newsgroups File Format}.
+@table @code
+@item nnultimate-directory
+@vindex nnultimate-directory
+The directory where @code{nnultimate} stores its files. The default is
+@samp{~/News/ultimate/}.
+@end table
-@item nnfolder-get-new-mail
-@vindex nnfolder-get-new-mail
-If non-@code{nil}, @code{nnfolder} will read incoming mail.
-@item nnfolder-save-buffer-hook
-@vindex nnfolder-save-buffer-hook
-@cindex backup files
-Hook run before saving the folders. Note that Emacs does the normal
-backup renaming of files even with the @code{nnfolder} buffers. If you
-wish to switch this off, you could say something like the following in
-your @file{.emacs} file:
+@node Web Archive
+@subsection Web Archive
+@cindex nnwarchive
+@cindex Web Archive
-@lisp
-(defun turn-off-backup ()
- (set (make-local-variable 'backup-inhibited) t))
+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.
-(add-hook 'nnfolder-save-buffer-hook 'turn-off-backup)
-@end lisp
+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}.
-@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.
+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
-@findex nnfolder-generate-active-file
-@kindex M-x nnfolder-generate-active-file
-If you have lots of @code{nnfolder}-like files you'd like to read with
-@code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
-command to make @code{nnfolder} aware of all likely files in
-@code{nnfolder-directory}. This only works if you use long file names,
-though.
+@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
* Directory Groups:: You can read a directory as if it was a newsgroup.
* Anything Groups:: Dired? Who needs dired?
* Document Groups:: Single files can be the basis of a group.
-* SOUP:: Reading @sc{SOUP} packets ``offline''.
-* Web Searches:: Creating groups from articles that match a string.
+* 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.
@end menu
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
@item forward
Forwarded articles.
+@item nsmail
+Netscape mail boxes.
+
@item mime-parts
MIME multipart messages.
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{standard-digest},
-@code{slack-digest}, @code{clari-briefs} or @code{guess}.
+@code{slack-digest}, @code{clari-briefs}, @code{nsmail} or @code{guess}.
@item nndoc-post-type
@vindex nndoc-post-type
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.
@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
@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
+@node Mail-To-News Gateways
+@subsection Mail-To-News Gateways
+@cindex mail-to-news gateways
+@cindex gateways
-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.
+If your local @code{nntp} server doesn't allow posting, for some reason
+or other, you can post using one of the numerous mail-to-news gateways.
+The @code{nngateway} backend provides the interface.
-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.
+Note that you can't read anything from this backend---it can only be
+used to post with.
-@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.
+Server variables:
-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.
+@table @code
+@item nngateway-address
+@vindex nngateway-address
+This is the address of the mail-to-news gateway.
-You must have the @code{url} and @code{w3} package installed to be able
-to use @code{nnweb}.
+@item nngateway-header-transformation
+@vindex nngateway-header-transformation
+News headers often have to be transformed in some odd way or other
+for the mail-to-news gateway to accept it. This variable says what
+transformation should be called, and defaults to
+@code{nngateway-simple-header-transformation}. The function is called
+narrowed to the headers to be transformed and with one parameter---the
+gateway address.
+
+This default function just inserts a new @code{To} header based on the
+@code{Newsgroups} header and the gateway address.
+For instance, an article with this @code{Newsgroups} header:
+
+@example
+Newsgroups: alt.religion.emacs
+@end example
+
+will get this @code{From} header inserted:
+
+@example
+To: alt-religion-emacs@@GATEWAY
+@end example
+
+The following pre-defined functions exist:
+
+@findex nngateway-simple-header-transformation
+@table @code
+
+@item nngateway-simple-header-transformation
+Creates a @code{To} header that looks like
+@var{newsgroup}@@@code{nngateway-address}.
+
+@findex nngateway-mail2news-header-transformation
+
+@item nngateway-mail2news-header-transformation
+Creates a @code{To} header that looks like
+@code{nngateway-address}.
+
+Here's an example:
+
+@lisp
+(setq gnus-post-method
+ '(nngateway "mail2news@@replay.com"
+ (nngateway-header-transformation
+ nngateway-mail2news-header-transformation)))
+@end lisp
+
+@end table
+
+
+@end table
+
+So, to use this, simply say something like:
+
+@lisp
+(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS"))
+@end lisp
+
+
+
+@node 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 - although 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
-Virtual server variables:
+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.
-@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}.
+Nnmail equivalent: @code{nnmail-crosspost}.
-@item nnweb-search
-@vindex nnweb-search
-The search string to feed to the search engine.
+@item nnimap-split-inbox
+@cindex splitting, inbox
+@cindex inbox
+@vindex nnimap-split-inbox
-@item nnweb-max-hits
-@vindex nnweb-max-hits
-Advisory maximum number of hits per search to display. The default is
-100.
+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!
-@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:
+@lisp
+(setq nnimap-split-inbox
+ '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap"))
+@end lisp
-@table @code
-@item article
-Function to decode the article and provide something that Gnus
-understands.
+No nnmail equivalent.
-@item map
-Function to create an article number to message header and URL alist.
+@item nnimap-split-rule
+@cindex Splitting, rules
+@vindex nnimap-split-rule
-@item search
-Function to send the search string to the search engine.
+New mail found in @code{nnimap-split-inbox} will be split according to
+this variable.
-@item address
-The address the aforementioned function should send the search string
-to.
+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.
-@item id
-Format string URL to fetch an article by @code{Message-ID}.
-@end table
+@lisp
+(setq nnimap-split-rule
+ '(("INBOX.nnimap" "^Sender: owner-nnimap@@vic20.globalcom.se")
+ ("INBOX.junk" "^Subject:.*MAKE MONEY")
+ ("INBOX.private" "")))
+@end lisp
-@end table
+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
-@node Mail-To-News Gateways
-@subsection Mail-To-News Gateways
-@cindex mail-to-news gateways
-@cindex gateways
+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.
-If your local @code{nntp} server doesn't allow posting, for some reason
-or other, you can post using one of the numerous mail-to-news gateways.
-The @code{nngateway} backend provides the interface.
+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.)
-Note that you can't read anything from this backend---it can only be
-used to post with.
+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".
-Server variables:
+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}.
-@table @code
-@item nngateway-address
-@vindex nngateway-address
-This is the address of the mail-to-news gateway.
+The splitting code tries to create mailboxes if it need too.
-@item nngateway-header-transformation
-@vindex nngateway-header-transformation
-News headers often have to be transformed in some odd way or other
-for the mail-to-news gateway to accept it. This variable says what
-transformation should be called, and defaults to
-@code{nngateway-simple-header-transformation}. The function is called
-narrowed to the headers to be transformed and with one parameter---the
-gateway address.
+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:
-This default function just inserts a new @code{To} header based on the
-@code{Newsgroups} header and the gateway address.
-For instance, an article with this @code{Newsgroups} header:
+@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
-@example
-Newsgroups: alt.religion.emacs
-@end example
+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.
-will get this @code{From} header inserted:
+Nnmail equivalent: @code{nnmail-split-methods}.
-@example
-To: alt-religion-emacs@@GATEWAY
-@end example
+@item nnimap-split-predicate
+@cindex splitting
+@vindex nnimap-split-predicate
-The following pre-defined functions exist:
+Mail matching this predicate in @code{nnimap-split-inbox} will be
+splitted, it is a string and the default is @samp{UNSEEN UNDELETED}.
-@findex nngateway-simple-header-transformation
-@table @code
+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 nngateway-simple-header-transformation
-Creates a @code{To} header that looks like
-@var{newsgroup}@@@code{nngateway-address}.
+@item nnimap-split-fancy
+@cindex splitting, fancy
+@findex nnimap-split-fancy
+@vindex nnimap-split-fancy
-@findex nngateway-mail2news-header-transformation
+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}.
-@item nngateway-mail2news-header-transformation
-Creates a @code{To} header that looks like
-@code{nngateway-address}.
+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}.
-Here's an example:
+Example:
@lisp
-(setq gnus-post-method
- '(nngateway "mail2news@@replay.com"
- (nngateway-header-transformation
- nngateway-mail2news-header-transformation)))
+(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
-@end table
+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.
-So, to use this, simply say something like:
+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.
-@lisp
-(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS"))
-@end lisp
@node Combined Groups
* 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.
@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}.)
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.
@end enumerate
A predicate in its simplest form can be a single predicate such as
-@code{true} or @code{false}. These two will download every available
-article or nothing respectively. In the case of these two special
+@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
@lisp
(defun my-article-old-p ()
"Say whether an article is old."
- (< (time-to-day (date-to-time (mail-header-date gnus-headers)))
- (- (time-to-day (current-time)) gnus-agent-expire-days)))
+ (< (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:
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
+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
+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:
(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.
+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:
(agent-score "~/News/agent.SCORE")
@end lisp
-Additional score files can be specified as above. Need I say anything
-about parenthesis.
+Additional score files can be specified as above. Need I say anything
+about parenthesis?
@end itemize
@item
@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)
(@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
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
@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 "")))
@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
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
@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
@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
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.
@enumerate
@item
-@var{(regexp file-name)}. If the @var{regexp} matches the group name,
-the @var{file-name} will will be used as the home score file.
+@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
+A function. If the function returns non-nil, the result will be used as
the home score file.
@item
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
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
@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
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
Ignoring is done first; then cutting; then maxing; and then as the very
last operation, padding.
-If you use lots of these advanced thingies, you'll find that Gnus gets
-quite slow. This can be helped enormously by running @kbd{M-x
-gnus-compile} when you are satisfied with the look of your lines.
+@vindex gnus-compile-user-specs
+If @code{gnus-compile-user-specs} is set to @code{nil} (@code{t} by
+default) with your strong personality, and use a lots of these advanced
+thingies, you'll find that Gnus gets quite slow. This can be helped
+enormously by running @kbd{M-x gnus-compile} when you are satisfied with
+the look of your lines.
@xref{Compilation}.
@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},
+@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
+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:
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
Remember all those line format specification variables?
@code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
-on. Now, Gnus will of course heed whatever these variables are, but,
+on. By default, T-gnus will use the byte-compiled codes of these
+variables and we can keep a slow-down to a minimum. However, if you set
+@code{gnus-compile-user-specs} to @code{nil} (@code{t} by default),
unfortunately, changing them will mean a quite significant slow-down.
(The default values of these variables have byte-compiled functions
associated with them, while the user-generated versions do not, of
To help with this, you can run @kbd{M-x gnus-compile} after you've
fiddled around with the variables and feel that you're (kind of)
satisfied. This will result in the new specs being byte-compiled, and
-you'll get top speed again. Gnus will save these compiled specs in the
-@file{.newsrc.eld} file. (User-defined functions aren't compiled by
-this function, though---you should compile them yourself by sticking
-them into the @code{.gnus.el} file and byte-compiling that file.)
+you'll get top speed again. Note that T-gnus will not save these
+compiled specs in the @file{.newsrc.eld} file.
+
+@table @code
+@item gnus-compile-user-specs
+@vindex gnus-compile-user-specs
+If it is non-nil, the user-defined format specs will be byte-compiled
+automatically. The default value of this variable is @code{t}. It has
+an effect on the values of @code{gnus-*-line-format-spec}.
+@end table
@node Mode Lines
@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.
+"clewis@@ferret.ocunix.on.ca" "cosmo.roadkill" "SpamHippo"
+"hweede@@snafu.de")}; fine, upstanding citizens all of them.
-@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
+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
header that gives the message a (more or less, usually less) rigorous
definition. Common types are @samp{spam}, @samp{spew}, @samp{mmf},
@samp{binary}, and @samp{troll}. To specify this, you have to use
-@var{(issuer conditions ...)} elements in the list. Each condition is
-either a string (which is a regexp that matches types you want to use)
-or a list on the form @code{(not STRING)}, where @var{string} is a
-regexp that matches types you don't want to use.
+@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:
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
@file{.gnus.el} file:
@lisp
-(setq gnus-treat-display-smiley t)
+(setq gnus-treat-display-smileys t)
@end lisp
Smiley maps text smiley faces---@samp{:-)}, @samp{:-=}, @samp{:-(} and
@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
@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.
@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
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).
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'' --
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?
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}.
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
Emacs 20.3 and up.
@item
-XEmacs 20.4 and up.
+XEmacs 21.1.1 and up.
@end itemize
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.
+Emacs versions. However, T-gnus does support ``Mule 2.3 based on Emacs
+19.34'' and possibly the versions of XEmacs prior to 21.1.1, e.g. 20.4.
+See the file ``README'' in the T-gnus distribution for more details.
There are some vague differences between Gnus on the various
platforms---XEmacs features more graphics (a logo and a toolbar)---but
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 mail-source-delete-incoming
+Some variable defaults differ between alpha Gnusae and released Gnusae.
+In particular, @code{mail-source-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
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).
Luis Fernandes---design and graphics.
@item
-Erik Naggum---help, ideas, support, code and stuff.
+Justin Sheehy--the FAQ maintainer.
@item
-Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el and many other things
-connected with @sc{mime} and other types of en/decoding.
+Erik Naggum---help, ideas, support, code and stuff.
@item
Wes Hardaker---@file{gnus-picon.el} and the manual section on
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,
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,
Michael Welsh Duggan,
Dave Edmondson,
Paul Eggert,
+Mark W. Eichin,
Karl Eichwalder,
Enami Tsugutomo, @c Enami
Michael Ernst,
Sam Falkner,
Nelson Jose dos Santos Ferreira,
Sigbjorn Finne,
+Sven Fischer,
Paul Fisher,
Decklin Foster,
Gary D. Foster,
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,
Ken Olstad,
Masaharu Onishi, @c Onishi
Hideki Ono, @c Ono
+Ettore Perazzoli,
William Perry,
Stephen Peters,
Jens-Ulrik Holger Petersen,
Philippe Schnoebelen,
Andreas Schwab,
Randal L. Schwartz,
-Justin Sheehy,
Danny Siu,
Matt Simmons,
Paul D. Smith,
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,
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
@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
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.
groups it has been crossposted to, or something. (Agent.)
@item
-`S D r' should allow expansion of aliases.
-
-@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
-The documentation should mention pop3.el, fetchmail, smtpmail and why
-po:username often fails.
+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
-Fetch by Message-ID from dejanews.
+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.
-<URL:http://search.dejanews.com/msgid.xp?MID=%3C62h9l9$hm4@@basement.replay.com%3E&fmt=raw>
+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
-A spec for the group line format to display the number of
-agent-downloaded articles in the group.
+
+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
-Some nntp servers never respond when posting, so there should be a
-timeout for all commands.
+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.
@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
@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
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}
@item
Try doing an @kbd{M-x gnus-version}. If you get something that looks
-like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
-on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
-flee}, you have some old @file{.el} files lying around. Delete these.
+like @samp{T-gnus 6.14.* (based on Pterodactyl Gnus v0.*; for SEMI 1.1*,
+FLIM 1.1*)} you have the right files loaded. If, on the other hand, you
+get something like @samp{NNTP 3.x} or @samp{nntp flee}, you have some
+old @file{.el} files lying around. Delete these.
@item
Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
@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.
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:
@item (nnchoke-request-set-mark GROUP ACTION &optional SERVER)
-Set/remove/add marks on articles. Normally Gnus handles the article
+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 IMAP) however carry all
-information about the articles on the server, so Gnus need to propagate
-the mark information to the server.
+@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:
(RANGE ACTION MARK)
@end example
-Range is a range of articles you wish to update marks on. Action is
+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},
+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 theese.
+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
+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.
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'',
projects / elisp / gnus.git- / blobdiff