From: Teodor Zlatanov Date: Tue, 16 Sep 2008 13:38:59 +0000 (+0000) Subject: (The Gnus Registry): Document it. X-Git-Url: https://cgit.sxemacs.org/?a=commitdiff_plain;h=34364b4ed205832edbbc7765a19dc1bba6f7ad4d;p=gnus (The Gnus Registry): Document it. --- diff --git a/texi/ChangeLog b/texi/ChangeLog index 40c699cad..83b892649 100644 --- a/texi/ChangeLog +++ b/texi/ChangeLog @@ -1,3 +1,7 @@ +2008-09-16 Teodor Zlatanov + + * gnus.texi (The Gnus Registry): Document it. + 2008-09-08 David Engster * gnus.texi (nnmairix): Point out that nnml uses MH format. Clarify diff --git a/texi/gnus.texi b/texi/gnus.texi index 71d5e0825..c54930e0b 100644 --- a/texi/gnus.texi +++ b/texi/gnus.texi @@ -22740,6 +22740,7 @@ four days, Gnus will decay the scores four times, for instance. * Fuzzy Matching:: What's the big fuzz? * Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. * Spam Package:: A package for filtering and processing spam. +* The Gnus Registry:: A package for tracking messages by Message-ID. * Other modes:: Interaction with other modes. * Various Various:: Things that are really various. @end menu @@ -26502,6 +26503,219 @@ Reduce table size: (spam-stat-reduce-size) Save table: (spam-stat-save) @end smallexample +@node The Gnus Registry +@section The Gnus Registry + +@cindex registry +@cindex split +@cindex track + +The Gnus registry is a package that tracks messages by their +Message-ID across all backends. This allows Gnus users to do several +cool things, be the envy of the locals, get free haircuts, and be +experts on world issues. Well, maybe not all of those, but the +features are pretty cool. + +Although they will be explained in detail shortly, here's a quick list +of said features in case your attention span is... never mind. + +@enumerate + +@item Split messages to their parent +This keeps discussions in the same group. You can use the subject and +the sender in addition to the Message-ID. Several strategies are +available. + +@item Store custom flags and keywords +The registry can store custom flags and keywords for a message. For +instance, you can mark a message ``To-Do'' this way and the flag will +persist whether the message is in the nnimap, nnml, nnmaildir, +etc. backends. + +@item Store arbitrary data +Through a simple ELisp API, the registry can remember any data for a +message. A built-in inverse map, when activated, allows quick lookups +of all messages matching a particular set of criteria. + +@end enumerate + + +@menu +* Setup:: +* Fancy splitting to parent:: +* Store custom flags and keywords:: +* Store arbitrary data:: +@end menu + +@node Setup +@subsection Setup + +Fortunately, setting up the Gnus registry is pretty easy: + +@lisp +(setq gnus-registry-max-entries 2500 + gnus-registry-use-long-group-names t) + +(gnus-registry-initialize) +@end lisp + +This adds registry saves to Gnus newsrc saves (which happen on exit +and when you press @kbd{s} from the @code{*Group*} buffer. It also +adds registry calls to article actions in Gnus (copy, move, etc.) so +it's not easy to undo the initialization. See +@code{gnus-registry-initialize} for the gory details. + +Here are other settings used by the author of the registry (understand +what they do before you copy them blindly). + +@lisp +(setq + gnus-registry-split-strategy 'majority + gnus-registry-ignored-groups '(("nntp" t) + ("nnrss" t) + ("spam" t) + ("train" t)) + gnus-registry-max-entries 500000 + gnus-registry-use-long-group-names t + gnus-registry-track-extra '(sender subject)) +@end lisp + +They say: keep a lot of messages around, use long group names, track +messages by sender and subject (not just parent Message-ID), and when +the registry splits incoming mail, use a majority rule to decide where +messages should go if there's more than one possibility. In addition, +the registry should ignore messages in groups that match ``nntp'', +``nnrss'', ``spam'', or ``train.'' + +You are doubtless impressed by all this, but you ask: ``I am a Gnus +user, I customize to live. Give me more.'' Here you go, these are +the general settings. + +@defvar gnus-registry-unfollowed-groups +The groups that will not be followed by +@code{gnus-registry-split-fancy-with-parent}. They will still be +remembered by the registry. This is a list of regular expressions. +@end defvar + +@defvar gnus-registry-ignored-groups +The groups that will not be remembered by the registry. This is a +list of regular expressions, also available through Group/Topic +customization (so you can ignore or keep a specific group or a whole +topic). +@end defvar + +@defvar gnus-registry-use-long-group-names +Whether the registry will use long group names. It's recommended to +set this to t, although everything works if you don't. Future +functionality will require it. +@end defvar + +@defvar gnus-registry-max-entries +The number (an integer or nil for unlimited) of entries the registry +will keep. +@end defvar + +@defvar gnus-registry-cache-file +The file where the registry will be stored between Gnus sessions. +@end defvar + +@node Fancy splitting to parent +@subsection Fancy splitting to parent + +Simply put, this lets you put followup e-mail where it belongs. + +Every message has a Message-ID, which is unique, and the registry +remembers it. When the message is moved or copied, the registry will +notice this and offer the new group as a choice to the splitting +strategy. + +When a followup is made, usually it mentions the original message's +Message-ID in the headers. The registry knows this and uses that +mention to find the group where the original message lives. You only +have to put a rule like this: + +@lisp +(setq nnimap-my-split-fancy '(| + + ;; split to parent: you need this + (: gnus-registry-split-fancy-with-parent) + + ;; other rules, as an example + (: spam-split) + ;; default mailbox + "mail") +@end lisp + +in your fancy split setup. In addition, you may want to customize the +following variables. + +@defvar gnus-registry-track-extra +This is a list of symbols, so it's best to change it from the +Customize interface. By default it's nil, but you may want to track +subject and sender as well when splitting by parent. It may work +for you. It can be annoying if your mail flow is large and people +don't stick to the same groups. +@end defvar + +@defvar gnus-registry-split-strategy +This is a symbol, so it's best to change it from the Customize +interface. By default it's nil, but you may want to set it to +@code{'majority} or @code{'first} to split by sender or subject based +on the majority of matches or on the first found. +@end defvar + +@node Store custom flags and keywords +@subsection Store custom flags and keywords + +The registry lets you set custom flags and keywords per message. You +can use the Gnus->Registry Marks menu or the @kbd{M M x} keyboard +shortcuts, where @code{x} is the first letter of the mark's name. + +@defvar gnus-registry-marks +The custom marks that the registry can use. You can modify the +default list, if you like. If you do, you'll have to exit Emacs +before they take effect (you can also unload the registry and reload +it or evaluate the specific macros you'll need, but you probably don't +want to bother). Use the Customize interface to modify the list. + +By default this list has the Important, Work, Personal, To-Do, and +Later marks. They all have keyboard shortcuts like @kbd{M M i} for +Important, using the first letter. +@end defvar + +@defun gnus-registry-mark-article +Call this function to mark an article with a custom registry mark. It +will offer the available marks for completion. +@end defun + +@node Store arbitrary data +@subsection Store arbitrary data + +The registry has a simple API that uses a Message-ID as the key to +store arbitrary data (as long as it can be converted to a list for +storage). + +@defun gnus-registry-store-extra-entry (id key value) +Store @code{value} in the extra data key @code{key} for message +@code{id}. +@end defun + +@defun gnus-registry-delete-extra-entry (id key) +Delete the extra data key @code{key} for message @code{id}. +@end defun + +@defun gnus-registry-fetch-extra (id key) +Get the extra data key @code{key} for message @code{id}. +@end defun + +@defvar gnus-registry-extra-entries-precious +If any extra entries are precious, their presence will make the +registry keep the whole entry forever, even if there are no groups for +the Message-ID and if the size limit of the registry is reached. By +default this is just @code{'(marks)} so the custom registry marks are +precious. +@end defvar + @node Other modes @section Interaction with other modes