This is gnus, produced by makeinfo version 4.5 from gnus.texi.
Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
2004, 2005, 2006, 2007 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.2 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being "A GNU Manual", and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
"GNU Free Documentation License" in the Emacs manual.
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by
the Free Software Foundation raise funds for GNU development."
This document is part of a collection distributed under the GNU
Free Documentation License. If you want to distribute this
document separately from the collection, you can do so by adding a
copy of the license to the document, as described in section 6 of
the license.
Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
2004, 2005, 2006, 2007 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.2 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being "A GNU Manual", and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
"GNU Free Documentation License" in the Emacs manual.
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by
the Free Software Foundation raise funds for GNU development."
This document is part of a collection distributed under the GNU
Free Documentation License. If you want to distribute this
document separately from the collection, you can do so by adding a
copy of the license to the document, as described in section 6 of
the license.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Gnus: (gnus). The newsreader Gnus.
END-INFO-DIR-ENTRY
File: gnus, Node: Optional Back End Functions, Next: Error Messaging, Prev: Required Back End Functions, Up: Back End Interface
Optional Back End Functions
...........................
`(nnchoke-retrieve-groups GROUPS &optional SERVER)'
GROUPS is a list of groups, and this function should request data
on all those groups. How it does it is of no concern to Gnus, but
it should attempt to do this in a speedy fashion.
The return value of this function can be either `active' or
`group', which says what the format of the result data is. The
former is in the same format as the data from
`nnchoke-request-list', while the latter is a buffer full of lines
in the same format as `nnchoke-request-group' gives.
group-buffer = *active-line / *group-status
`(nnchoke-request-update-info GROUP INFO &optional SERVER)'
A Gnus group info (*note Group Info::) is handed to the back end
for alterations. This comes in handy if the back end really
carries all the information (as is the case with virtual and imap
groups). This function should destructively alter the info to
suit its needs, and should return a non-`nil' value (exceptionally,
`nntp-request-update-info' always returns `nil' not to waste the
network resources).
There should be no result data from this function.
`(nnchoke-request-type GROUP &optional ARTICLE)'
When the user issues commands for "sending news" (`F' in the
summary buffer, for instance), Gnus has to know whether the
article the user is following up on is news or mail. This
function should return `news' if ARTICLE in GROUP is news, `mail'
if it is mail and `unknown' if the type can't be decided. (The
ARTICLE parameter is necessary in `nnvirtual' groups which might
very well combine mail groups and news groups.) Both GROUP and
ARTICLE may be `nil'.
There should be no result data from this function.
`(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 `~/.newsrc.eld'. Some back ends (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:
(RANGE ACTION MARK)
RANGE is a range of articles you wish to update marks on. ACTION
is `add' or `del', used to add marks or remove marks (preserving
all marks not mentioned). MARK is a list of marks; where each
mark is a symbol. Currently used marks are `read', `tick',
`reply', `expire', `killed', `dormant', `save', `download',
`unsend', `forward' and `recent', but your back end should, if
possible, not limit itself to these.
Given contradictory actions, the last action in the list should be
the effective one. That is, if your action contains a request to
add the `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:
(((5 12 30) 'del '(tick))
((10 . 90) 'add '(read expire))
((92 94) 'del '(read)))
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.
`(nnchoke-request-update-mark GROUP ARTICLE MARK)'
If the user tries to set a mark that the back end doesn't like,
this function may change the mark. Gnus will use whatever this
function returns as the mark for ARTICLE instead of the original
MARK. If the back end doesn't care, it must return the original
MARK, and not `nil' or any other type of garbage.
The only use for this I can see is what `nnvirtual' does with
it--if a component group is auto-expirable, marking an article as
read in the virtual group should result in the article being
marked as expirable.
There should be no result data from this function.
`(nnchoke-request-scan &optional GROUP SERVER)'
This function may be called at any time (by Gnus or anything else)
to request that the back end check for incoming articles, in one
way or another. A mail back end will typically read the spool
file or query the POP server when this function is invoked. The
GROUP doesn't have to be heeded--if the back end decides that it
is too much work just scanning for a single group, it may do a
total scan of all groups. It would be nice, however, to keep
things local if that's practical.
There should be no result data from this function.
`(nnchoke-request-group-description GROUP &optional SERVER)'
The result data from this function should be a description of
GROUP.
description-line = name <TAB> description eol
name = <string>
description = <text>
`(nnchoke-request-list-newsgroups &optional SERVER)'
The result data from this function should be the description of all
groups available on the server.
description-buffer = *description-line
`(nnchoke-request-newgroups DATE &optional SERVER)'
The result data from this function should be all groups that were
created after `date', which is in normal human-readable date format
(i.e., the date format used in mail and news headers, and returned
by the function `message-make-date' by default). The data should
be in the active buffer format.
It is okay for this function to return "too many" groups; some
back ends might find it cheaper to return the full list of groups,
rather than just the new groups. But don't do this for back ends
with many groups. Normally, if the user creates the groups
herself, there won't be too many groups, so `nnml' and the like
are probably safe. But for back ends like `nntp', where the
groups have been created by the server, it is quite likely that
there can be many groups.
`(nnchoke-request-create-group GROUP &optional SERVER)'
This function should create an empty group with name GROUP.
There should be no return data.
`(nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)'
This function should run the expiry process on all articles in the
ARTICLES range (which is currently a simple list of article
numbers.) It is left up to the back end to decide how old articles
should be before they are removed by this function. If FORCE is
non-`nil', all ARTICLES should be deleted, no matter how new they
are.
This function should return a list of articles that it did not/was
not able to delete.
There should be no result data returned.
`(nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM &optional LAST)'
This function should move ARTICLE (which is a number) from GROUP
by calling ACCEPT-FORM.
This function should ready the article in question for moving by
removing any header lines it has added to the article, and
generally should "tidy up" the article. Then it should `eval'
ACCEPT-FORM in the buffer where the "tidy" article is. This will
do the actual copying. If this `eval' returns a non-`nil' value,
the article should be removed.
If LAST is `nil', that means that there is a high likelihood that
there will be more requests issued shortly, so that allows some
optimizations.
The function should return a cons where the `car' is the group
name and the `cdr' is the article number that the article was
entered as.
There should be no data returned.
`(nnchoke-request-accept-article GROUP &optional SERVER LAST)'
This function takes the current buffer and inserts it into GROUP.
If LAST in `nil', that means that there will be more calls to this
function in short order.
The function should return a cons where the `car' is the group
name and the `cdr' is the article number that the article was
entered as.
The group should exist before the back end is asked to accept the
article for that group.
There should be no data returned.
`(nnchoke-request-replace-article ARTICLE GROUP BUFFER)'
This function should remove ARTICLE (which is a number) from GROUP
and insert BUFFER there instead.
There should be no data returned.
`(nnchoke-request-delete-group GROUP FORCE &optional SERVER)'
This function should delete GROUP. If FORCE, it should really
delete all the articles in the group, and then delete the group
itself. (If there is such a thing as "the group itself".)
There should be no data returned.
`(nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)'
This function should rename GROUP into NEW-NAME. All articles in
GROUP should move to NEW-NAME.
There should be no data returned.
File: gnus, Node: Error Messaging, Next: Writing New Back Ends, Prev: Optional Back End Functions, Up: Back End Interface
Error Messaging
...............
The back ends should use the function `nnheader-report' to report
error conditions--they should not raise errors when they aren't able to
perform a request. The first argument to this function is the back end
symbol, and the rest are interpreted as arguments to `format' if there
are multiple of them, or just a string if there is one of them. This
function must always returns `nil'.
(nnheader-report 'nnchoke "You did something totally bogus")
(nnheader-report 'nnchoke "Could not request group %s" group)
Gnus, in turn, will call `nnheader-get-report' when it gets a `nil'
back from a server, and this function returns the most recently
reported message for the back end in question. This function takes one
argument--the server symbol.
Internally, these functions access BACK-END`-status-string', so the
`nnchoke' back end will have its error message stored in
`nnchoke-status-string'.
File: gnus, Node: Writing New Back Ends, Next: Hooking New Back Ends Into Gnus, Prev: Error Messaging, Up: Back End Interface
Writing New Back Ends
.....................
Many back ends are quite similar. `nnml' is just like `nnspool',
but it allows you to edit the articles on the server. `nnmh' is just
like `nnml', but it doesn't use an active file, and it doesn't maintain
overview databases. `nndir' is just like `nnml', but it has no concept
of "groups", and it doesn't allow editing articles.
It would make sense if it were possible to "inherit" functions from
back ends when writing new back ends. And, indeed, you can do that if
you want to. (You don't have to if you don't want to, of course.)
All the back ends declare their public variables and functions by
using a package called `nnoo'.
To inherit functions from other back ends (and allow other back ends
to inherit functions from the current back end), you should use the
following macros:
`nnoo-declare'
This macro declares the first parameter to be a child of the
subsequent parameters. For instance:
(nnoo-declare nndir
nnml nnmh)
`nndir' has declared here that it intends to inherit functions from
both `nnml' and `nnmh'.
`defvoo'
This macro is equivalent to `defvar', but registers the variable as
a public server variable. Most state-oriented variables should be
declared with `defvoo' instead of `defvar'.
In addition to the normal `defvar' parameters, it takes a list of
variables in the parent back ends to map the variable to when
executing a function in those back ends.
(defvoo nndir-directory nil
"Where nndir will look for groups."
nnml-current-directory nnmh-current-directory)
This means that `nnml-current-directory' will be set to
`nndir-directory' when an `nnml' function is called on behalf of
`nndir'. (The same with `nnmh'.)
`nnoo-define-basics'
This macro defines some common functions that almost all back ends
should have.
(nnoo-define-basics nndir)
`deffoo'
This macro is just like `defun' and takes the same parameters. In
addition to doing the normal `defun' things, it registers the
function as being public so that other back ends can inherit it.
`nnoo-map-functions'
This macro allows mapping of functions from the current back end to
functions from the parent back ends.
(nnoo-map-functions nndir
(nnml-retrieve-headers 0 nndir-current-group 0 0)
(nnmh-request-article 0 nndir-current-group 0 0))
This means that when `nndir-retrieve-headers' is called, the first,
third, and fourth parameters will be passed on to
`nnml-retrieve-headers', while the second parameter is set to the
value of `nndir-current-group'.
`nnoo-import'
This macro allows importing functions from back ends. It should
be the last thing in the source file, since it will only define
functions that haven't already been defined.
(nnoo-import nndir
(nnmh
nnmh-request-list
nnmh-request-newgroups)
(nnml))
This means that calls to `nndir-request-list' should just be passed
on to `nnmh-request-list', while all public functions from `nnml'
that haven't been defined in `nndir' yet should be defined now.
Below is a slightly shortened version of the `nndir' back end.
;;; nndir.el -- single directory newsgroup access for Gnus
;; Copyright (C) 1995,96 Free Software Foundation, Inc.
;;; Code:
(require 'nnheader)
(require 'nnmh)
(require 'nnml)
(require 'nnoo)
(eval-when-compile (require 'cl))
(nnoo-declare nndir
nnml nnmh)
(defvoo nndir-directory nil
"Where nndir will look for groups."
nnml-current-directory nnmh-current-directory)
(defvoo nndir-nov-is-evil nil
"*Non-nil means that nndir will never retrieve NOV headers."
nnml-nov-is-evil)
(defvoo nndir-current-group ""
nil
nnml-current-group nnmh-current-group)
(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)
(defvoo nndir-status-string "" nil nnmh-status-string)
(defconst nndir-version "nndir 1.0")
;;; Interface functions.
(nnoo-define-basics nndir)
(deffoo nndir-open-server (server &optional defs)
(setq nndir-directory
(or (cadr (assq 'nndir-directory defs))
server))
(unless (assq 'nndir-directory defs)
(push `(nndir-directory ,server) defs))
(push `(nndir-current-group
,(file-name-nondirectory
(directory-file-name nndir-directory)))
defs)
(push `(nndir-top-directory
,(file-name-directory (directory-file-name nndir-directory)))
defs)
(nnoo-change-server 'nndir server defs))
(nnoo-map-functions nndir
(nnml-retrieve-headers 0 nndir-current-group 0 0)
(nnmh-request-article 0 nndir-current-group 0 0)
(nnmh-request-group nndir-current-group 0 0)
(nnmh-close-group nndir-current-group 0))
(nnoo-import nndir
(nnmh
nnmh-status-message
nnmh-request-list
nnmh-request-newgroups))
(provide 'nndir)
File: gnus, Node: Hooking New Back Ends Into Gnus, Next: Mail-like Back Ends, Prev: Writing New Back Ends, Up: Back End Interface
Hooking New Back Ends Into Gnus
...............................
Having Gnus start using your new back end is rather easy--you just
declare it with the `gnus-declare-backend' functions. This will enter
the back end into the `gnus-valid-select-methods' variable.
`gnus-declare-backend' takes two parameters--the back end name and
an arbitrary number of "abilities".
Here's an example:
(gnus-declare-backend "nnchoke" 'mail 'respool 'address)
The above line would then go in the `nnchoke.el' file.
The abilities can be:
`mail'
This is a mailish back end--followups should (probably) go via
mail.
`post'
This is a newsish back end--followups should (probably) go via
news.
`post-mail'
This back end supports both mail and news.
`none'
This is neither a post nor mail back end--it's something completely
different.
`respool'
It supports respooling--or rather, it is able to modify its source
articles and groups.
`address'
The name of the server should be in the virtual server name. This
is true for almost all back ends.
`prompt-address'
The user should be prompted for an address when doing commands like
`B' in the group buffer. This is true for back ends like `nntp',
but not `nnmbox', for instance.
File: gnus, Node: Mail-like Back Ends, Prev: Hooking New Back Ends Into Gnus, Up: Back End Interface
Mail-like Back Ends
...................
One of the things that separate the mail back ends from the rest of
the back ends is the heavy dependence by most of the mail back ends on
common functions in `nnmail.el'. For instance, here's the definition
of `nnml-request-scan':
(deffoo nnml-request-scan (&optional group server)
(setq nnml-article-file-alist nil)
(nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group))
It simply calls `nnmail-get-new-mail' with a few parameters, and
`nnmail' takes care of all the moving and splitting of the mail.
This function takes four parameters.
METHOD
This should be a symbol to designate which back end is responsible
for the call.
EXIT-FUNCTION
This function should be called after the splitting has been
performed.
TEMP-DIRECTORY
Where the temporary files should be stored.
GROUP
This optional argument should be a group name if the splitting is
to be performed for one group only.
`nnmail-get-new-mail' will call BACK-END`-save-mail' to save each
article. BACK-END`-active-number' will be called to find the article
number assigned to this article.
The function also uses the following variables:
BACK-END`-get-new-mail' (to see whether to get new mail for this back
end); and BACK-END`-group-alist' and BACK-END`-active-file' to generate
the new active file. BACK-END`-group-alist' should be a group-active
alist, like this:
(("a-group" (1 . 10))
("some-group" (34 . 39)))
File: gnus, Node: Score File Syntax, Next: Headers, Prev: Back End Interface, Up: Gnus Reference Guide
Score File Syntax
-----------------
Score files are meant to be easily parseable, but yet extremely
mallable. It was decided that something that had the same read syntax
as an Emacs Lisp list would fit that spec.
Here's a typical score file:
(("summary"
("win95" -10000 nil s)
("Gnus"))
("from"
("Lars" -1000))
(mark -100))
BNF definition of a score file:
score-file = "" / "(" *element ")"
element = rule / atom
rule = string-rule / number-rule / date-rule
string-rule = "(" quote string-header quote space *string-match ")"
number-rule = "(" quote number-header quote space *number-match ")"
date-rule = "(" quote date-header quote space *date-match ")"
quote = <ascii 34>
string-header = "subject" / "from" / "references" / "message-id" /
"xref" / "body" / "head" / "all" / "followup"
number-header = "lines" / "chars"
date-header = "date"
string-match = "(" quote <string> quote [ "" / [ space score [ "" /
space date [ "" / [ space string-match-t ] ] ] ] ] ")"
score = "nil" / <integer>
date = "nil" / <natural number>
string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
"r" / "regex" / "R" / "Regex" /
"e" / "exact" / "E" / "Exact" /
"f" / "fuzzy" / "F" / "Fuzzy"
number-match = "(" <integer> [ "" / [ space score [ "" /
space date [ "" / [ space number-match-t ] ] ] ] ] ")"
number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
date-match = "(" quote <string> quote [ "" / [ space score [ "" /
space date [ "" / [ space date-match-t ] ] ] ] ")"
date-match-t = "nil" / "at" / "before" / "after"
atom = "(" [ required-atom / optional-atom ] ")"
required-atom = mark / expunge / mark-and-expunge / files /
exclude-files / read-only / touched
optional-atom = adapt / local / eval
mark = "mark" space nil-or-number
nil-or-number = "nil" / <integer>
expunge = "expunge" space nil-or-number
mark-and-expunge = "mark-and-expunge" space nil-or-number
files = "files" *[ space <string> ]
exclude-files = "exclude-files" *[ space <string> ]
read-only = "read-only" [ space "nil" / space "t" ]
adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ]
adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
local = "local" *[ space "(" <string> space <form> ")" ]
eval = "eval" space <form>
space = *[ " " / <TAB> / <NEWLINE> ]
Any unrecognized elements in a score file should be ignored, but not
discarded.
As you can see, white space is needed, but the type and amount of
white space is irrelevant. This means that formatting of the score
file is left up to the programmer--if it's simpler to just spew it all
out on one looong line, then that's ok.
The meaning of the various atoms are explained elsewhere in this
manual (*note Score File Format::).
File: gnus, Node: Headers, Next: Ranges, Prev: Score File Syntax, Up: Gnus Reference Guide
Headers
-------
Internally Gnus uses a format for storing article headers that
corresponds to the NOV format in a mysterious fashion. One could
almost suspect that the author looked at the NOV specification and just
shamelessly _stole_ the entire thing, and one would be right.
"Header" is a severely overloaded term. "Header" is used in RFC
1036 to talk about lines in the head of an article (e.g., `From'). It
is used by many people as a synonym for "head"--"the header and the
body". (That should be avoided, in my opinion.) And Gnus uses a
format internally that it calls "header", which is what I'm talking
about here. This is a 9-element vector, basically, with each header
(ouch) having one slot.
These slots are, in order: `number', `subject', `from', `date',
`id', `references', `chars', `lines', `xref', and `extra'. There are
macros for accessing and setting these slots--they all have predictable
names beginning with `mail-header-' and `mail-header-set-',
respectively.
All these slots contain strings, except the `extra' slot, which
contains an alist of header/value pairs (*note To From Newsgroups::).
File: gnus, Node: Ranges, Next: Group Info, Prev: Headers, Up: Gnus Reference Guide
Ranges
------
GNUS introduced a concept that I found so useful that I've started
using it a lot and have elaborated on it greatly.
The question is simple: If you have a large amount of objects that
are identified by numbers (say, articles, to take a _wild_ example)
that you want to qualify as being "included", a normal sequence isn't
very useful. (A 200,000 length sequence is a bit long-winded.)
The solution is as simple as the question: You just collapse the
sequence.
(1 2 3 4 5 6 10 11 12)
is transformed into
((1 . 6) (10 . 12))
To avoid having those nasty `(13 . 13)' elements to denote a
lonesome object, a `13' is a valid element:
((1 . 6) 7 (10 . 12))
This means that comparing two ranges to find out whether they are
equal is slightly tricky:
((1 . 5) 7 8 (10 . 12))
and
((1 . 5) (7 . 8) (10 . 12))
are equal. In fact, any non-descending list is a range:
(1 2 3 4 5)
is a perfectly valid range, although a pretty long-winded one. This
is also valid:
(1 . 5)
and is equal to the previous range.
Here's a BNF definition of ranges. Of course, one must remember the
semantic requirement that the numbers are non-descending. (Any number
of repetition of the same number is allowed, but apt to disappear in
range handling.)
range = simple-range / normal-range
simple-range = "(" number " . " number ")"
normal-range = "(" start-contents ")"
contents = "" / simple-range *[ " " contents ] /
number *[ " " contents ]
Gnus currently uses ranges to keep track of read articles and article
marks. I plan on implementing a number of range operators in C if The
Powers That Be are willing to let me. (I haven't asked yet, because I
need to do some more thinking on what operators I need to make life
totally range-based without ever having to convert back to normal
sequences.)
File: gnus, Node: Group Info, Next: Extended Interactive, Prev: Ranges, Up: Gnus Reference Guide
Group Info
----------
Gnus stores all permanent info on groups in a "group info" list.
This list is from three to six elements (or more) long and exhaustively
describes the group.
Here are two example group infos; one is a very simple group while
the second is a more complex one:
("no.group" 5 ((1 . 54324)))
("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
((tick (15 . 19)) (replied 3 6 (19 . 3)))
(nnml "")
((auto-expire . t) (to-address . "ding@gnus.org")))
The first element is the "group name"--as Gnus knows the group,
anyway. The second element is the "subscription level", which normally
is a small integer. (It can also be the "rank", which is a cons cell
where the `car' is the level and the `cdr' is the score.) The third
element is a list of ranges of read articles. The fourth element is a
list of lists of article marks of various kinds. The fifth element is
the select method (or virtual server, if you like). The sixth element
is a list of "group parameters", which is what this section is about.
Any of the last three elements may be missing if they are not
required. In fact, the vast majority of groups will normally only have
the first three elements, which saves quite a lot of cons cells.
Here's a BNF definition of the group info format:
info = "(" group space ralevel space read
[ "" / [ space marks-list [ "" / [ space method [ "" /
space parameters ] ] ] ] ] ")"
group = quote <string> quote
ralevel = rank / level
level = <integer in the range of 1 to inf>
rank = "(" level "." score ")"
score = <integer in the range of 1 to inf>
read = range
marks-lists = nil / "(" *marks ")"
marks = "(" <string> range ")"
method = "(" <string> *elisp-forms ")"
parameters = "(" *elisp-forms ")"
Actually that `marks' rule is a fib. A `marks' is a `<string>'
consed on to a `range', but that's a bitch to say in pseudo-BNF.
If you have a Gnus info and want to access the elements, Gnus offers
a series of macros for getting/setting these elements.
`gnus-info-group'
`gnus-info-set-group'
Get/set the group name.
`gnus-info-rank'
`gnus-info-set-rank'
Get/set the group rank (*note Group Score::).
`gnus-info-level'
`gnus-info-set-level'
Get/set the group level.
`gnus-info-score'
`gnus-info-set-score'
Get/set the group score (*note Group Score::).
`gnus-info-read'
`gnus-info-set-read'
Get/set the ranges of read articles.
`gnus-info-marks'
`gnus-info-set-marks'
Get/set the lists of ranges of marked articles.
`gnus-info-method'
`gnus-info-set-method'
Get/set the group select method.
`gnus-info-params'
`gnus-info-set-params'
Get/set the group parameters.
All the getter functions take one parameter--the info list. The
setter functions take two parameters--the info list and the new value.
The last three elements in the group info aren't mandatory, so it
may be necessary to extend the group info before setting the element.
If this is necessary, you can just pass on a non-`nil' third parameter
to the three final setter functions to have this happen automatically.
File: gnus, Node: Extended Interactive, Next: Emacs/XEmacs Code, Prev: Group Info, Up: Gnus Reference Guide
Extended Interactive
--------------------
Gnus extends the standard Emacs `interactive' specification slightly
to allow easy use of the symbolic prefix (*note Symbolic Prefixes::).
Here's an example of how this is used:
(defun gnus-summary-increase-score (&optional score symp)
(interactive (gnus-interactive "P\ny"))
...
)
The best thing to do would have been to implement `gnus-interactive'
as a macro which would have returned an `interactive' form, but this
isn't possible since Emacs checks whether a function is interactive or
not by simply doing an `assq' on the lambda form. So, instead we have
`gnus-interactive' function that takes a string and returns values that
are usable to `interactive'.
This function accepts (almost) all normal `interactive' specs, but
adds a few more.
`y'
The current symbolic prefix--the `gnus-current-prefix-symbol'
variable.
`Y'
A list of the current symbolic prefixes--the
`gnus-current-prefix-symbol' variable.
`A'
The current article number--the `gnus-summary-article-number'
function.
`H'
The current article header--the `gnus-summary-article-header'
function.
`g'
The current group name--the `gnus-group-group-name' function.
File: gnus, Node: Emacs/XEmacs Code, Next: Various File Formats, Prev: Extended Interactive, Up: Gnus Reference Guide
Emacs/XEmacs Code
-----------------
While Gnus runs under Emacs, XEmacs and Mule, I decided that one of
the platforms must be the primary one. I chose Emacs. Not because I
don't like XEmacs or Mule, but because it comes first alphabetically.
This means that Gnus will byte-compile under Emacs with nary a
warning, while XEmacs will pump out gigabytes of warnings while
byte-compiling. As I use byte-compilation warnings to help me root out
trivial errors in Gnus, that's very useful.
I've also consistently used Emacs function interfaces, but have used
Gnusey aliases for the functions. To take an example: Emacs defines a
`run-at-time' function while XEmacs defines a `start-itimer' function.
I then define a function called `gnus-run-at-time' that takes the same
parameters as the Emacs `run-at-time'. When running Gnus under Emacs,
the former function is just an alias for the latter. However, when
running under XEmacs, the former is an alias for the following function:
(defun gnus-xmas-run-at-time (time repeat function &rest args)
(start-itimer
"gnus-run-at-time"
`(lambda ()
(,function ,@args))
time repeat))
This sort of thing has been done for bunches of functions. Gnus does
not redefine any native Emacs functions while running under XEmacs--it
does this `defalias' thing with Gnus equivalents instead. Cleaner all
over.
In the cases where the XEmacs function interface was obviously
cleaner, I used it instead. For example `gnus-region-active-p' is an
alias for `region-active-p' in XEmacs, whereas in Emacs it is a
function.
Of course, I could have chosen XEmacs as my native platform and done
mapping functions the other way around. But I didn't. The performance
hit these indirections impose on Gnus under XEmacs should be slight.
File: gnus, Node: Various File Formats, Prev: Emacs/XEmacs Code, Up: Gnus Reference Guide
Various File Formats
--------------------
* Menu:
* Active File Format:: Information on articles and groups available.
* Newsgroups File Format:: Group descriptions.
File: gnus, Node: Active File Format, Next: Newsgroups File Format, Up: Various File Formats
Active File Format
..................
The active file lists all groups available on the server in
question. It also lists the highest and lowest current article numbers
in each group.
Here's an excerpt from a typical active file:
soc.motss 296030 293865 y
alt.binaries.pictures.fractals 3922 3913 n
comp.sources.unix 1605 1593 m
comp.binaries.ibm.pc 5097 5089 y
no.general 1000 900 y
Here's a pseudo-BNF definition of this file:
active = *group-line
group-line = group spc high-number spc low-number spc flag <NEWLINE>
group = <non-white-space string>
spc = " "
high-number = <non-negative integer>
low-number = <positive integer>
flag = "y" / "n" / "m" / "j" / "x" / "=" group
For a full description of this file, see the manual pages for
`innd', in particular `active(5)'.
File: gnus, Node: Newsgroups File Format, Prev: Active File Format, Up: Various File Formats
Newsgroups File Format
......................
The newsgroups file lists groups along with their descriptions. Not
all groups on the server have to be listed, and not all groups in the
file have to exist on the server. The file is meant purely as
information to the user.
The format is quite simple; a group name, a tab, and the description.
Here's the definition:
newsgroups = *line
line = group tab description <NEWLINE>
group = <non-white-space string>
tab = <TAB>
description = <string>
File: gnus, Node: Emacs for Heathens, Next: Frequently Asked Questions, Prev: Gnus Reference Guide, Up: Appendices
Emacs for Heathens
==================
Believe it or not, but some people who use Gnus haven't really used
Emacs much before they embarked on their journey on the Gnus Love Boat.
If you are one of those unfortunates whom "`C-M-a'", "kill the region",
and "set `gnus-flargblossen' to an alist where the key is a regexp that
is used for matching on the group name" are magical phrases with little
or no meaning, then this appendix is for you. If you are already
familiar with Emacs, just ignore this and go fondle your cat instead.
* Menu:
* Keystrokes:: Entering text and executing commands.
* Emacs Lisp:: The built-in Emacs programming language.
File: gnus, Node: Keystrokes, Next: Emacs Lisp, Up: Emacs for Heathens
Keystrokes
----------
* Q: What is an experienced Emacs user?
* A: A person who wishes that the terminal had pedals.
Yes, when you use Emacs, you are apt to use the control key, the
shift key and the meta key a lot. This is very annoying to some people
(notably `vi'le users), and the rest of us just love the hell out of
it. Just give up and submit. Emacs really does stand for
"Escape-Meta-Alt-Control-Shift", and not "Editing Macros", as you may
have heard from other disreputable sources (like the Emacs author).
The shift keys are normally located near your pinky fingers, and are
normally used to get capital letters and stuff. You probably use it all
the time. The control key is normally marked "CTRL" or something like
that. The meta key is, funnily enough, never marked as such on any
keyboard. The one I'm currently at has a key that's marked "Alt",
which is the meta key on this keyboard. It's usually located somewhere
to the left hand side of the keyboard, usually on the bottom row.
Now, us Emacs people don't say "press the meta-control-m key",
because that's just too inconvenient. We say "press the `C-M-m' key".
`M-' is the prefix that means "meta" and "C-" is the prefix that means
"control". So "press `C-k'" means "press down the control key, and
hold it down while you press `k'". "Press `C-M-k'" means "press down
and hold down the meta key and the control key and then press `k'".
Simple, ay?
This is somewhat complicated by the fact that not all keyboards have
a meta key. In that case you can use the "escape" key. Then `M-k'
means "press escape, release escape, press `k'". That's much more work
than if you have a meta key, so if that's the case, I respectfully
suggest you get a real keyboard with a meta key. You can't live without
it.
File: gnus, Node: Emacs Lisp, Prev: Keystrokes, Up: Emacs for Heathens
Emacs Lisp
----------
Emacs is the King of Editors because it's really a Lisp interpreter.
Each and every key you tap runs some Emacs Lisp code snippet, and since
Emacs Lisp is an interpreted language, that means that you can configure
any key to run any arbitrary code. You just, like, do it.
Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
functions. (These are byte-compiled for speed, but it's still
interpreted.) If you decide that you don't like the way Gnus does
certain things, it's trivial to have it do something a different way.
(Well, at least if you know how to write Lisp code.) However, that's
beyond the scope of this manual, so we are simply going to talk about
some common constructs that you normally use in your `~/.gnus.el' file
to customize Gnus. (You can also use the `~/.emacs' file, but in order
to set things of Gnus up, it is much better to use the `~/.gnus.el'
file, *Note Startup Files::.)
If you want to set the variable `gnus-florgbnize' to four (4), you
write the following:
(setq gnus-florgbnize 4)
This function (really "special form") `setq' is the one that can set
a variable to some value. This is really all you need to know. Now
you can go and fill your `~/.gnus.el' file with lots of these to change
how Gnus works.
If you have put that thing in your `~/.gnus.el' file, it will be
read and `eval'ed (which is Lisp-ese for "run") the next time you start
Gnus. If you want to change the variable right away, simply say `C-x
C-e' after the closing parenthesis. That will `eval' the previous
"form", which is a simple `setq' statement here.
Go ahead--just try it, if you're located at your Emacs. After you
`C-x C-e', you will see `4' appear in the echo area, which is the
return value of the form you `eval'ed.
Some pitfalls:
If the manual says "set `gnus-read-active-file' to `some'", that
means:
(setq gnus-read-active-file 'some)
On the other hand, if the manual says "set `gnus-nntp-server' to
`nntp.ifi.uio.no'", that means:
(setq gnus-nntp-server "nntp.ifi.uio.no")
So be careful not to mix up strings (the latter) with symbols (the
former). The manual is unambiguous, but it can be confusing.
File: gnus, Node: Frequently Asked Questions, Prev: Emacs for Heathens, Up: Appendices
Frequently Asked Questions
==========================
* Menu:
* FAQ - Changes::
* FAQ - Introduction:: About Gnus and this FAQ.
* FAQ 1 - Installation FAQ:: Installation of Gnus.
* FAQ 2 - Startup / Group buffer:: Start up questions and the
first buffer Gnus shows you.
* FAQ 3 - Getting Messages:: Making Gnus read your mail
and news.
* FAQ 4 - Reading messages:: How to efficiently read
messages.
* FAQ 5 - Composing messages:: Composing mails or Usenet
postings.
* FAQ 6 - Old messages:: Importing, archiving,
searching and deleting messages.
* FAQ 7 - Gnus in a dial-up environment:: Reading mail and news while
offline.
* FAQ 8 - Getting help:: When this FAQ isn't enough.
* FAQ 9 - Tuning Gnus:: How to make Gnus faster.
* FAQ - Glossary:: Terms used in the FAQ
explained.
Abstract
--------
This is the new Gnus Frequently Asked Questions list. If you have a
Web browser, the official hypertext version is at
`http://my.gnus.org/FAQ/', the Docbook source is available from
http://sourceforge.net (http://sourceforge.net/projects/gnus/).
Please submit features and suggestions to the FAQ discussion list
<faq-discuss@my.gnus.org>. The list is protected against junk mail with
qconfirm (http://smarden.org/qconfirm/index.html). As a subscriber,
your submissions will automatically pass. You can also subscribe to
the list by sending a blank email to faq-discuss-subscribe@my.gnus.org
<faq-discuss-subscribe@my.gnus.org> and browse the archive (BROKEN)
(http://mail1.kens.com/cgi-bin/ezmlm-browse?command=monthbythread%26list=faq-discuss).
File: gnus, Node: FAQ - Changes, Next: FAQ - Introduction, Up: Frequently Asked Questions
Changes
-------
* Updated FAQ to reflect release of Gnus 5.10 and start of No Gnus
development.
File: gnus, Node: FAQ - Introduction, Next: FAQ 1 - Installation FAQ, Prev: FAQ - Changes, Up: Frequently Asked Questions
Introduction
------------
This is the Gnus Frequently Asked Questions list.
Gnus is a Usenet Newsreader and Electronic Mail User Agent
implemented as a part of Emacs. It's been around in some form for
almost a decade now, and has been distributed as a standard part of
Emacs for much of that time. Gnus 5 is the latest (and greatest)
incarnation. The original version was called GNUS, and was written by
Masanobu UMEDA. When autumn crept up in '94, Lars Magne Ingebrigtsen
grew bored and decided to rewrite Gnus.
Its biggest strength is the fact that it is extremely customizable.
It is somewhat intimidating at first glance, but most of the complexity
can be ignored until you're ready to take advantage of it. If you
receive a reasonable volume of e-mail (you're on various mailing
lists), or you would like to read high-volume mailing lists but cannot
keep up with them, or read high volume newsgroups or are just bored,
then Gnus is what you want.
This FAQ was maintained by Justin Sheehy until March 2002. He would
like to thank Steve Baur and Per Abrahamsen for doing a wonderful job
with this FAQ before him. We would like to do the same - thanks, Justin!
If you have a Web browser, the official hypertext version is at:
`http://my.gnus.org/FAQ/'. This version is much nicer than the
unofficial hypertext versions that are archived at Utrecht, Oxford,
Smart Pages, Ohio State, and other FAQ archives. See the resources
question below if you want information on obtaining it in another
format.
The information contained here was compiled with the assistance of
the Gnus development mailing list, and any errors or misprints are the
my.gnus.org team's fault, sorry.
File: gnus, Node: FAQ 1 - Installation FAQ, Next: FAQ 2 - Startup / Group buffer, Prev: FAQ - Introduction, Up: Frequently Asked Questions
Installation FAQ
----------------
* Menu:
* [1.1]:: What is the latest version of Gnus?
* [1.2]:: What's new in 5.10?
* [1.3]:: Where and how to get Gnus?
* [1.4]:: What to do with the tarball now?
* [1.5]:: I sometimes read references to No Gnus and Oort Gnus, what
are those?
* [1.6]:: Which version of Emacs do I need?
* [1.7]:: How do I run Gnus on both Emacs and XEmacs?
File: gnus, Node: [1.1], Next: [1.2], Up: FAQ 1 - Installation FAQ
Question 1.1
............
What is the latest version of Gnus?
Answer
......
Jingle please: Gnus 5.10 is released, get it while it's hot! As well
as the step in version number is rather small, Gnus 5.10 has tons of
new features which you shouldn't miss. The current release (5.10.8)
should be at least as stable as the latest release of the 5.8 series.
File: gnus, Node: [1.2], Next: [1.3], Prev: [1.1], Up: FAQ 1 - Installation FAQ
Question 1.2
............
What's new in 5.10?
Answer
......
First of all, you should have a look into the file GNUS-NEWS in the
toplevel directory of the Gnus tarball, there the most important
changes are listed. Here's a short list of the changes I find especially
important/interesting:
* Major rewrite of the Gnus agent, Gnus agent is now active by
default.
* Many new article washing functions for dealing with ugly formatted
articles.
* Anti Spam features.
* Message-utils now included in Gnus.
* New format specifiers for summary lines, e.g. %B for a complex
trn-style thread tree.
File: gnus, Node: [1.3], Next: [1.4], Prev: [1.2], Up: FAQ 1 - Installation FAQ
Question 1.3
............
Where and how to get Gnus?
Answer
......
Gnus is released independent from releases of Emacs and XEmacs.
Therefore, the version bundled with Emacs or the version in XEmacs'
package system might not be up to date (e.g. Gnus 5.9 bundled with Emacs
20 is outdated). You can get the latest released version of Gnus from
`http://www.gnus.org/dist/gnus.tar.gz' or via anonymous FTP from
`ftp://ftp.gnus.org/pub/gnus/gnus.tar.gz'.
File: gnus, Node: [1.4], Next: [1.5], Prev: [1.3], Up: FAQ 1 - Installation FAQ
Question 1.4
............
What to do with the tarball now?
Answer
......
Untar it via `tar xvzf gnus.tar.gz' and do the common `./configure;
make; make install' circle. (under MS-Windows either get the Cygwin
environment from `http://www.cygwin.com' which allows you to do what's
described above or unpack the tarball with some packer (e.g. Winace from
`http://www.winace.com') and use the batch-file make.bat included in
the tarball to install Gnus.) If you don't want to (or aren't allowed
to) install Gnus system-wide, you can install it in your home directory
and add the following lines to your ~/.xemacs/init.el or ~/.emacs:
(add-to-list 'load-path "/path/to/gnus/lisp")
(if (featurep 'xemacs)
(add-to-list 'Info-directory-list "/path/to/gnus/texi/")
(add-to-list 'Info-default-directory-list "/path/to/gnus/texi/"))
Make sure that you don't have any Gnus related stuff before this line,
on MS Windows use something like "C:/path/to/lisp" (yes, "/").
File: gnus, Node: [1.5], Next: [1.6], Prev: [1.4], Up: FAQ 1 - Installation FAQ
Question 1.5
............
I sometimes read references to No Gnus and Oort Gnus, what are those?
Answer
......
Oort Gnus was the name of the development version of Gnus, which
became Gnus 5.10 in autumn 2003. No Gnus is the name of the current
development version which will once become Gnus 5.12 or Gnus 6. (If
you're wondering why not 5.11, the odd version numbers are normally
used for the Gnus versions bundled with Emacs)
File: gnus, Node: [1.6], Next: [1.7], Prev: [1.5], Up: FAQ 1 - Installation FAQ
Question 1.6
............
Which version of Emacs do I need?
Answer
......
Gnus 5.10 requires an Emacs version that is greater than or equal to
Emacs 20.7 or XEmacs 21.1. The development versions of Gnus (aka No
Gnus) requires Emacs 21 or XEmacs 21.4.
File: gnus, Node: [1.7], Prev: [1.6], Up: FAQ 1 - Installation FAQ
Question 1.7
............
How do I run Gnus on both Emacs and XEmacs?
Answer
......
You can't use the same copy of Gnus in both as the Lisp files are
byte-compiled to a format which is different depending on which Emacs
did the compilation. Get one copy of Gnus for Emacs and one for XEmacs.
File: gnus, Node: FAQ 2 - Startup / Group buffer, Next: FAQ 3 - Getting Messages, Prev: FAQ 1 - Installation FAQ, Up: Frequently Asked Questions
Startup / Group buffer
----------------------
* Menu:
* [2.1]:: Every time I start Gnus I get a message "Gnus auto-save
file exists. Do you want to read it?", what does this mean and
how to prevent it?
* [2.2]:: Gnus doesn't remember which groups I'm subscribed to,
what's this?
* [2.3]:: How to change the format of the lines in Group buffer?
* [2.4]:: My group buffer becomes a bit crowded, is there a way to
sort my groups into categories so I can easier browse through
them?
* [2.5]:: How to manually sort the groups in Group buffer? How to
sort the groups in a topic?
File: gnus, Node: [2.1], Next: [2.2], Up: FAQ 2 - Startup / Group buffer
Question 2.1
............
Every time I start Gnus I get a message "Gnus auto-save file exists.
Do you want to read it?", what does this mean and how to prevent it?
Answer
......
This message means that the last time you used Gnus, it wasn't
properly exited and therefor couldn't write its informations to disk
(e.g. which messages you read), you are now asked if you want to
restore those informations from the auto-save file.
To prevent this message make sure you exit Gnus via `q' in group
buffer instead of just killing Emacs.
File: gnus, Node: [2.2], Next: [2.3], Prev: [2.1], Up: FAQ 2 - Startup / Group buffer
Question 2.2
............
Gnus doesn't remember which groups I'm subscribed to, what's this?
Answer
......
You get the message described in the q/a pair above while starting
Gnus, right? It's an other symptom for the same problem, so read the
answer above.