\input texinfo @c -*-texinfo-*-
@setfilename gnus
-@settitle Semi-gnus 6.10.015 Manual
+@settitle Semi-gnus 6.10.034 Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
\thispagestyle{empty}
-Copyright \copyright{} 1995,96,97 Free Software Foundation, Inc.
+Copyright \copyright{} 1995,96,97,98 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@tex
@titlepage
-@title Semi-gnus 6.10.015 Manual
+@title Semi-gnus 6.10.034 Manual
@author by Lars Magne Ingebrigtsen
@page
API. So Semi-gnus does not discriminate various language communities.
Oh, if you are a Klingon, please wait Unicode Next Generation.
-This manual corresponds to Semi-gnus 6.10.015.
+This manual corresponds to Semi-gnus 6.10.034.
@end ifinfo
gnus-group-clear-data-on-native-groups} command to clear out all data
that you have on your native groups. Use with caution.
+After changing servers, you @strong{must} move the cache hierarchy away,
+since the cached articles will have wrong article numbers, which will
+affect which articles Gnus thinks are read.
+
@node Startup Files
@section Startup Files
@item best
Select the highest scored article in the group when entering the
group.
+
@end table
+This variable can also be a function. In that case, that function will
+be called to place point on a subject line, and/or select some article.
+Useful functions include:
+
+@table @code
+@item gnus-summary-first-unread-subject
+Place point on the subject line of the first unread article, but
+don't select the article.
+
+@item gnus-summary-first-unread-article
+Select the first unread article.
+
+@item gnus-summary-best-unread-article
+Select the highest-scored unread article.
+@end table
+
+
If you want to prevent automatic selection in some group (say, in a
binary group with Huge articles) you can set this variable to @code{nil}
in @code{gnus-select-group-hook}, which is called when a group is
@menu
* Summary Buffer Lines:: You can specify how summary lines should look.
+* To From Newsgroups:: How to not display your own name.
* Summary Buffer Mode Line:: You can say how the mode line should look.
* Summary Highlighting:: Making the summary buffer all pretty and nice.
@end menu
slower; and @code{std11-extract-address-components}, which works very
nicely, but is slower. The default function will return the wrong
answer in 5% of the cases. If this is unacceptable to you, use the
-other function instead.
-
+other function instead:
+
+@lisp
+(setq gnus-extract-address-components
+ 'mail-extract-address-components)
+@end lisp
+
@vindex gnus-summary-same-subject
@code{gnus-summary-same-subject} is a string indicating that the current
article has the same subject as the previous. This string will be used
Full @code{From} header.
@item n
The name (from the @code{From} header).
+@item f
+The name, code @code{To} header or the @code{Newsgroups} header
+(@pxref{To From Newsgroups}).
@item a
The name (from the @code{From} header). This differs from the @code{n}
spec in that it uses the function designated by the
This restriction may disappear in later versions of gnus.
+@node To From Newsgroups
+@subsection To From Newsgroups
+@cindex To
+@cindex Newsgroups
+
+In some groups (particularly in archive groups), the @code{From} header
+isn't very interesting, since all the articles there are written by
+you. To display the information in the @code{To} or @code{Newsgroups}
+headers instead, you need to decide three things: What information to
+gather; where to display it; and when to display it.
+
+@enumerate
+@item
+@vindex gnus-extra-headers
+The reading of extra header information is controlled by the
+@code{gnus-extra-headers}. This is a list of header symbols. For
+instance:
+
+@lisp
+(setq gnus-extra-headers
+ '(To Newsgroups X-Newsreader))
+@end lisp
+
+This will result in Gnus trying to obtain these three headers, and
+storing it in header structures for later easy retrieval.
+
+@item
+@findex gnus-extra-header
+The value of these extra headers can be accessed via the
+@code{gnus-extra-header} function. Here's a format line spec that will
+access the @code{X-Newsreader} header:
+
+@example
+"%~(form (gnus-extra-header 'X-Newsreader))@@"
+@end example
+
+@item
+@vindex gnus-ignored-from-addresses
+The @code{gnus-ignored-from-addresses} variable says when the @samp{%f}
+summary line spec returns the @code{To}, @code{Newsreader} or
+@code{From} header. If this regexp matches the contents of the
+@code{From} header, the value of the @code{To} or @code{Newsreader}
+headers are used instead.
+
+@end enumerate
+
+@vindex nnmail-extra-headers
+A related variable is @code{nnmail-extra-headers}, which controls when
+to include extra headers when generating overview (@sc{nov}) files.
+
+In summary, you'd typically do something like the following:
+
+@lisp
+(setq gnus-extra-headers
+ '(To Newsgroups))
+(setq nnmail-extra-headers gnus-extra-headers)
+(setq gnus-summary-line-format
+ "%U%R%z%I%(%[%4L: %-20,20f%]%) %s\n")
+(setq gnus-ignored-from-addresses
+ "Your Name Here")
+@end lisp
+
+
@node Summary Buffer Mode Line
@subsection Summary Buffer Mode Line
buffer, which might make it more inconvenient to read extremely long
threads.
+This variable can also be a number. In that case, center the window at
+the given number of lines from the top.
+
@end table
@kindex S W (Summary)
@findex gnus-summary-wide-reply-with-original
Mail a wide reply to the current article and include the original
-message (@code{gnus-summary-reply-with-original}). This command uses
+message (@code{gnus-summary-wide-reply-with-original}). This command uses
the process/prefix convention.
@item S o m
@item
@vindex gnus-cached-mark
Articles stored in the article cache will be marked with an @samp{*} in
-the second column (@code{gnus-cached-mark}). @xref{Article Caching}
+the second column (@code{gnus-cached-mark}). @xref{Article Caching}.
@item
@vindex gnus-saved-mark
@kindex M t (Summary)
@findex gnus-summary-tick-article-forward
Tick the current article (@code{gnus-summary-tick-article-forward}).
-@xref{Article Caching}
+@xref{Article Caching}.
@item M ?
@itemx ?
@kindex M ? (Summary)
@findex gnus-summary-mark-as-dormant
Mark the current article as dormant
-(@code{gnus-summary-mark-as-dormant}). @xref{Article Caching}
+(@code{gnus-summary-mark-as-dormant}). @xref{Article Caching}.
@item M d
@itemx d
@findex gnus-thread-sort-by-number
@vindex gnus-thread-sort-functions
If you are using a threaded summary display, you can sort the threads by
-setting @code{gnus-thread-sort-functions}, which is a list of functions.
+setting @code{gnus-thread-sort-functions}, which can be either a single
+function, a list of functions, or a list containing functions and
+@code{(not some-function)} elements.
+
By default, sorting is done on article numbers. Ready-made sorting
predicate functions include @code{gnus-thread-sort-by-number},
@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
Each function takes two threads and returns non-@code{nil} if the first
thread should be sorted before the other. Note that sorting really is
-normally done by looking only at the roots of each thread. If you use
-more than one function, the primary sort key should be the last function
-in the list. You should probably always include
+normally done by looking only at the roots of each thread.
+
+If you use more than one function, the primary sort key should be the
+last function in the list. You should probably always include
@code{gnus-thread-sort-by-number} in the list of sorting
functions---preferably first. This will ensure that threads that are
equal with respect to the other sort criteria will be displayed in
ascending article order.
-If you would like to sort by score, then by subject, and finally by
-number, you could do something like:
+If you would like to sort by reverse score, then by subject, and finally
+by number, you could do something like:
@lisp
(setq gnus-thread-sort-functions
'(gnus-thread-sort-by-number
gnus-thread-sort-by-subject
- gnus-thread-sort-by-total-score))
+ (reverse gnus-thread-sort-by-total-score)))
@end lisp
The threads that have highest score will be displayed first in the
@item W d
@kindex W d (Summary)
@findex gnus-article-treat-dumbquotes
-Treat M******** sm*rtq**t*s (@code{gnus-article-treat-dumbquotes}).
+@vindex gnus-article-dumbquotes-map
+@cindex Smartquotes
+@cindex M******** sm*rtq**t*s
+@cindex Latin 1
+Treat M******** sm*rtq**t*s according to
+@code{gnus-article-dumbquotes-map}
+(@code{gnus-article-treat-dumbquotes}).
@item W w
@kindex W w (Summary)
@item W c
@kindex W c (Summary)
@findex gnus-article-remove-cr
-Remove CR (i. e., @samp{^M}s on the end of the lines)
+Translate CRLF pairs (i. e., @samp{^M}s on the end of the lines) into LF
+(this takes care of DOS line endings), and then translate any remaining
+CRs into LF (this takes care of Mac line endings)
(@code{gnus-article-remove-cr}).
@item W f
@kindex W b (Summary)
@findex gnus-article-add-buttons
Add clickable buttons to the article (@code{gnus-article-add-buttons}).
-@xref{Article Buttons}
+@xref{Article Buttons}.
@item W B
@kindex W B (Summary)
MIME headers), you can set the @code{charset} group/topic parameter to
the required charset (@pxref{Group Parameters}).
+@item W M v
+@kindex W M v (Summary)
+View all the @sc{mime} parts in the current article
+(@code{gnus-mime-view-all-parts}).
+
+@end table
+
+Relevant variables:
+
+@table @code
+@item gnus-ignored-mime-types
+@vindex gnus-ignored-mime-types
+This is a list of regexps. @sc{mime} types that match a regexp from
+this list will be completely ignored by Gnus. The default value is
+@code{nil}.
+
+To have all Vcards be ignored, you'd say something like this:
+
+@lisp
+(setq gnus-ignored-mime-types
+ '("text/x-vcard"))
+@end lisp
+
@end table
(This is the default.) If @code{nil}, each group will have its own
article buffer.
+@vindex gnus-article-decode-hook
+@item gnus-article-decode-hook
+@cindex MIME
+Hook used to decode @sc{mime} articles. The default value is
+@code{(article-decode-charset article-decode-encoded-words)}
+
@vindex gnus-article-prepare-hook
@item gnus-article-prepare-hook
This hook is called right after the article has been inserted into the
insert sub-expressions from the matched text. For instance:
@lisp
-("list.\\1" "From:.*\\(.*\\)-list@@majordomo.com")
+("list.\\1" "From:.* \\(.*\\)-list@@majordomo.com")
@end lisp
The second element can also be a function. In that case, it will be
already exists, it will always be read (and incorporated) before any
other spool files.
-@vindex nnmail-prepare-incoming-hook
-@item nnmail-prepare-incoming-hook
-This is run in a buffer that holds all the new incoming mail, and can be
-used for, well, anything, really.
-
@vindex nnmail-split-hook
@item nnmail-split-hook
-@findex article-decode-rfc1522
+@findex article-decode-encoded-words
@findex RFC1522 decoding
+@findex RFC2047 decoding
Hook run in the buffer where the mail headers of each message is kept
just before the splitting based on these headers is done. The hook is
free to modify the buffer contents in any way it sees fit---the buffer
is discarded after the splitting has been done, and no changes performed
-in the buffer will show up in any files. @code{gnus-article-decode-rfc1522}
-is one likely function to add to this hook.
+in the buffer will show up in any files.
+@code{gnus-article-decode-encoded-words} is one likely function to add
+to this hook.
@vindex nnmail-pre-get-new-mail-hook
@vindex nnmail-post-get-new-mail-hook
@item nnmail-prepare-incoming-hook
@vindex nnmail-prepare-incoming-hook
This hook is called before doing anything with the mail and is meant for
-grand, sweeping gestures. Functions to be used include:
+grand, sweeping gestures. It is called in a buffer that contains all
+the new, incoming mail. Functions to be used include:
@table @code
@item nnheader-ms-strip-cr
* Agent Variables:: Customizing is fun.
* Example Setup:: An example @file{.gnus.el} file for offline people.
* Batching Agents:: How to fetch news from a @code{cron} job.
+* Agent Caveats:: What you think it'll do and what it does.
@end menu
primary select method, which is listed on the bottom in the buffer.
@item
-Decide on download policy. @xref{Agent Categories}
+Decide on download policy. @xref{Agent Categories}.
@item
Uhm... that's it.
In both of these places the @code{download score rule} can take one of
three forms:
-@table @code
@enumerate
@item
Score rule
@end lisp
@end itemize
@end enumerate
-@end table
@node The Category Buffer
@subsubsection The Category Buffer
@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-agent-fetch-session}). @xref{Drafts}.
@item J a
@kindex J a (Agent Group)
@node Agent Expiry
@subsection Agent Expiry
-@vindex gnus-agent-expiry-days
-@findex gnus-agent-expiry
-@kindex M-x gnus-agent-expiry
+@vindex gnus-agent-expire-days
+@findex gnus-agent-expire
+@kindex M-x gnus-agent-expire
@cindex Agent expiry
@cindex Gnus Agent expiry
@cindex expiry
@code{nnagent} doesn't handle expiry. Instead, there's a special
-@code{gnus-agent-expiry} command that will expire all read articles that
-are older than @code{gnus-agent-expiry-days} days. It can be run
+@code{gnus-agent-expire} command that will expire all read articles that
+are older than @code{gnus-agent-expire-days} days. It can be run
whenever you feel that you're running out of space. It's not
particularly fast or efficient, and it's not a particularly good idea to
interrupt it (with @kbd{C-g} or anything else) once you've started it.
@end example
+@node Agent Caveats
+@subsection Agent Caveats
+
+The Gnus Agent doesn't seem to work like most other offline
+newsreaders. Here are some common questions that some imaginary people
+may ask:
+
+@table @dfn
+@item If I read an article while plugged, do they get entered into the
+Agent?
+
+@strong{No.}
+
+@item If I read an article while plugged, and the article already exists
+in the Agent, will it get downloaded once more?
+
+@strong{Yes.}
+
+@end table
+
+In short, when Gnus is unplugged, it only looks into the locally stored
+articles; when it's plugged, it only talks to your ISP.
+
@node Scoring
@chapter Scoring
@findex gnus-batch-score
@cindex batch scoring
@example
-$ emacs -batch -l ~/.emacs -l gnus -f gnus-batch-score
+$ emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-batch-score
@end example
word scoring process will never bring down the score of an article to
below this number. The default is @code{nil}.
+@vindex gnus-adaptive-word-no-group-words
+If @code{gnus-adaptive-word-no-group-words} is set to @code{t}, gnus
+won't adaptively word score any of the words in the group name. Useful
+for groups like @samp{comp.editors.emacs}, where most of the subject
+lines contain the word @samp{emacs}.
+
After using this scheme for a while, it might be nice to write a
@code{gnus-psychoanalyze-user} command to go through the rules and see
what words you like and what words you don't like. Or perhaps not.
@code{mouse-face} specs---you can say @samp{%3(hello%)} to have
@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
+Text inside the @samp{%<} and @samp{%>} specifiers will get the special
+@code{balloon-help} property set to @code{gnus-balloon-face-0}. If you say
+@samp{%1<}, you'll get @code{gnus-balloon-face-1} and so on. The
+@code{gnus-balloon-face-*} variables should be either strings or
+symbols naming functions that return a string. Under @code{balloon-help-mode},
+when the mouse passes over text with this property set, a balloon window
+will appear and display the string. Please refer to the doc string of
+@code{balloon-help-mode} for more information on this.
+
Here's an alternative recipe for the group buffer:
@lisp
other windows and occupy the entire Emacs screen by itself. It is
@code{t} by default.
+Setting this variable to @code{nil} kinda works, but there are
+glitches. Use at your own peril.
+
@vindex gnus-buffer-configuration
@code{gnus-buffer-configuration} describes how much space each Gnus
buffer should be given. Here's an excerpt of this variable:
``right'' window configuration, you can set
@code{gnus-always-force-window-configuration} to non-@code{nil}.
+If you're using tree displays (@pxref{Tree Display}), and the tree
+window is displayed vertically next to another window, you may also want
+to fiddle with @code{gnus-tree-minimize-window} to avoid having the
+windows resized.
+
@node Faces and Fonts
@section Faces and Fonts
* Terminology:: We use really difficult, like, words here.
* Customization:: Tailoring Gnus to your needs.
* Troubleshooting:: What you might try if things do not work.
-* A Programmers Guide to Gnus:: Rilly, rilly technical stuff.
+* Gnus Reference Guide:: Rilly, rilly technical stuff.
* Emacs for Heathens:: A short introduction to Emacsian terms.
* Frequently Asked Questions:: A question-and-answer session.
@end menu
Erik Naggum---help, ideas, support, code and stuff.
@item
+Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el and many other things
+connected with @sc{mime} and other types of en/decoding.
+
+@item
Wes Hardaker---@file{gnus-picon.el} and the manual section on
@dfn{picons} (@pxref{Picons}).
Sam Falkner,
Nelson Jose dos Santos Ferreira,
Sigbjorn Finne,
+Paul Fisher,
Decklin Foster,
Gary D. Foster,
Paul Franklin,
Wolfgang Rupprecht,
Jay Sachs,
Dewey M. Sasser,
+Conrad Sauerwald,
Loren Schall,
Dan Schmidt,
Ralph Schleicher,
Pete Ware,
Barry A. Warsaw,
Christoph Wedler,
-Joe Wells,
-Katsumi Yamaoka, @c Yamaoka
+Joe Wells
and
-Shenghuo Zhu. @c Zhu
+Katsumi Yamaoka, @c Yamaoka.
For a full overview of what each person has done, the ChangeLogs
included in the Gnus alpha distributions should give ample reading
new group parameter -- `post-to-server' that says to post
using the current server. Also a variable to do the same.
@item
- the slave dribble files should autosave to the slave file names.
+ the slave dribble files should auto-save to the slave file names.
@item
a group parameter that says what articles to display on group entry, based
on article marks.
add a way to select which NoCeM type to apply -- spam, troll, etc.
@item
- nndraft-request-group should tally autosave files.
+ nndraft-request-group should tally auto-save files.
@item
implement nntp-retry-on-break and nntp-command-timeout.
The jingle is only played on the second invocation of Gnus.
@item
+Bouncing articles should do MIME.
+
+@item
+Crossposted articles should "inherit" the % or @ mark from the other
+groups it has been crossposted to, or something. (Agent.)
+
+@item
+`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.
+
+@item
+Fetch by Message-ID from dejanews.
+
+<URL:http://search.dejanews.com/msgid.xp?MID=%3C62h9l9$hm4@@basement.replay.com%3E&fmt=raw>
+
+@item
Solve the halting problem.
@c TODO
@page
-@node A Programmers Guide to Gnus
-@section A Programmer@'s Guide to Gnus
+@node Gnus Reference Guide
+@section Gnus Reference Guide
It is my hope that other people will figure out smart stuff that Gnus
can do, and that other people will write those smart things as well. To
@lisp
(gnus-check-backend-function "request-scan" "nnml:misc")
-=> t
+@result{} t
@end lisp
@item gnus-read-method
There should be no result data from this function.
+@item (nnchoke-request-set-mark GROUP ACTION &optional SERVER)
+
+Set/remove/add marks on articles. Normally Gnus handles the article
+marks (such as read, ticked, expired etc) internally, and store them in
+@code{~/.newsrc.eld}. Some backends (such as IMAP) however carry all
+information about the articles on the server, so Gnus need to propagate
+the mark information to the server.
+
+ACTION is a list of mark setting requests, having this format:
+
+@example
+(RANGE ACTION MARK)
+@end example
+
+Range is a range of articles you wish to update marks on. Action is
+@code{set}, @code{add} or @code{del}, respectively used for removing all
+existing marks and setting them as specified, adding (preserving the
+marks not mentioned) mark and removing (preserving the marks not
+mentioned) marks. Mark is a list of marks; where each mark is a
+symbol. Currently used marks are @code{read}, @code{tick}, @code{reply},
+@code{expire}, @code{killed}, @code{dormant}, @code{save},
+@code{download} and @code{unsend}, but your backend should, if possible,
+not limit itself to theese.
+
+Given contradictory actions, the last action in the list should be the
+effective one. That is, if your action contains a request to add the
+@code{tick} mark on article 1 and, later in the list, a request to
+remove the mark on the same article, the mark should in fact be removed.
+
+An example action list:
+
+@example
+(((5 12 30) 'del '(tick))
+ ((10 . 90) 'add '(read expire))
+ ((92 94) 'del '(read)))
+@end example
+
+The function should return a range of articles it wasn't able to set the
+mark on (currently not used for anything).
+
+There should be no result data from this function.
+
@item (nnchoke-request-update-mark GROUP ARTICLE MARK)
If the user tries to set a mark that the backend doesn't like, this
These slots are, in order: @code{number}, @code{subject}, @code{from},
@code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
-@code{xref}. There are macros for accessing and setting these
-slots---they all have predictable names beginning with
+@code{xref}, and @code{extra}. There are macros for accessing and
+setting these slots---they all have predictable names beginning with
@code{mail-header-} and @code{mail-header-set-}, respectively.
-The @code{xref} slot is really a @code{misc} slot. Any extra info will
-be put in there.
+All these slots contain strings, except the @code{extra} slot, which
+contains an alist of header/value pairs (@pxref{To From Newsgroups}).
@node Ranges
second is a more complex one:
@example
-("no.group" 5 (1 . 54324))
+("no.group" 5 ((1 . 54324)))
("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
((tick (15 . 19)) (replied 3 6 (19 . 3)))
projects / elisp / gnus.git- / blobdiff