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 description eol name = description = `(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 = string-header = "subject" / "from" / "references" / "message-id" / "xref" / "body" / "head" / "all" / "followup" number-header = "lines" / "chars" date-header = "date" string-match = "(" quote quote [ "" / [ space score [ "" / space date [ "" / [ space string-match-t ] ] ] ] ] ")" score = "nil" / date = "nil" / string-match-t = "nil" / "s" / "substring" / "S" / "Substring" / "r" / "regex" / "R" / "Regex" / "e" / "exact" / "E" / "Exact" / "f" / "fuzzy" / "F" / "Fuzzy" number-match = "(" [ "" / [ space score [ "" / space date [ "" / [ space number-match-t ] ] ] ] ] ")" number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<=" date-match = "(" quote quote [ "" / [ space score [ "" / space date [ "" / [ space date-match-t ] ] ] ] ")" date-match-t = "nil" / "at" / "before" / "after" atom = "(" [ required-atom / optional-atom ] ")" required-atom = mark / expunge / mark-and-expunge / files / exclude-files / read-only / touched optional-atom = adapt / local / eval mark = "mark" space nil-or-number nil-or-number = "nil" / expunge = "expunge" space nil-or-number mark-and-expunge = "mark-and-expunge" space nil-or-number files = "files" *[ space ] exclude-files = "exclude-files" *[ space ] read-only = "read-only" [ space "nil" / space "t" ] adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ] adapt-rule = "(" *[ *[ "(" ")" ] ")" local = "local" *[ space "(" space
")" ] eval = "eval" space space = *[ " " / / ] 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 quote ralevel = rank / level level = rank = "(" level "." score ")" score = read = range marks-lists = nil / "(" *marks ")" marks = "(" range ")" method = "(" *elisp-forms ")" parameters = "(" *elisp-forms ")" Actually that `marks' rule is a fib. A `marks' is a `' 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 group = spc = " " high-number = low-number = 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 group = tab = description =  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 . 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 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.