From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.emacs.gnus.general/67382 Path: news.gmane.org!not-for-mail From: Ted Zlatanov Newsgroups: gmane.emacs.gnus.general Subject: registry doc patch (was: bugs and features) Date: Mon, 15 Sep 2008 16:00:20 -0500 Organization: =?utf-8?B?0KLQtdC+0LTQvtGAINCX0LvQsNGC0LDQvdC+0LI=?= @ Cienfuegos Message-ID: <86vdwxnmzf.fsf_-_@lifelogs.com> References: <87abfkmuko.fsf@jondo.cante.net> <86bpzlt5cq.fsf@lifelogs.com> <87prnut63f.fsf@catnip.gol.com> <86vdxlfdtn.fsf@lifelogs.com> <87zlmwoyvs.fsf@marauder.physik.uni-ulm.de> <86zlmvkg8p.fsf_-_@lifelogs.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: ger.gmane.org 1221512463 8630 80.91.229.12 (15 Sep 2008 21:01:03 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 15 Sep 2008 21:01:03 +0000 (UTC) To: ding@gnus.org Original-X-From: ding-owner+M15833@lists.math.uh.edu Mon Sep 15 23:01:59 2008 Return-path: Envelope-to: ding-account@gmane.org Original-Received: from util0.math.uh.edu ([129.7.128.18]) by lo.gmane.org with esmtp (Exim 4.50) id 1KfLCj-0007Rd-QK for ding-account@gmane.org; Mon, 15 Sep 2008 23:01:54 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.math.uh.edu) by util0.math.uh.edu with smtp (Exim 4.63) (envelope-from ) id 1KfLBd-0007n3-SJ; Mon, 15 Sep 2008 16:00:45 -0500 Original-Received: from mx2.math.uh.edu ([129.7.128.33]) by util0.math.uh.edu with esmtps (TLSv1:AES256-SHA:256) (Exim 4.63) (envelope-from ) id 1KfLBc-0007mi-AF for ding@lists.math.uh.edu; Mon, 15 Sep 2008 16:00:44 -0500 Original-Received: from quimby.gnus.org ([80.91.231.51]) by mx2.math.uh.edu with esmtp (Exim 4.69) (envelope-from ) id 1KfLBZ-0006v7-Cj for ding@lists.math.uh.edu; Mon, 15 Sep 2008 16:00:44 -0500 Original-Received: from main.gmane.org ([80.91.229.2] helo=ciao.gmane.org) by quimby.gnus.org with esmtp (Exim 3.36 #1 (Debian)) id 1KfLBd-0001bV-00 for ; Mon, 15 Sep 2008 23:00:45 +0200 Original-Received: from list by ciao.gmane.org with local (Exim 4.43) id 1KfLBS-0007dP-Tl for ding@gnus.org; Mon, 15 Sep 2008 21:00:35 +0000 Original-Received: from 38.98.147.130 ([38.98.147.130]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 15 Sep 2008 21:00:34 +0000 Original-Received: from tzz by 38.98.147.130 with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 15 Sep 2008 21:00:34 +0000 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 263 Original-X-Complaints-To: usenet@ger.gmane.org X-Gmane-NNTP-Posting-Host: 38.98.147.130 X-Face: bd.DQ~'29fIs`T_%O%C\g%6jW)yi[zuz6;d4V0`@y-~$#3P_Ng{@m+e4o<4P'#(_GJQ%TT= D}[Ep*b!\e,fBZ'j_+#"Ps?s2!4H2-Y"sx" User-Agent: Gnus/5.110011 (No Gnus v0.11) Emacs/23.0.60 (gnu/linux) Cancel-Lock: sha1:F4EF7ephdz+iiK4467bYr8unUJE= X-Spam-Score: -1.5 (-) List-ID: Precedence: bulk Xref: news.gmane.org gmane.emacs.gnus.general:67382 Archived-At: --=-=-= On Fri, 29 Aug 2008 10:12:06 -0500 Ted Zlatanov wrote: TZ> I also need to write the gnus-registry documentation sometime this century. The unthinkable has happened. Attached is a patch to the docs to document the Gnus registry. I didn't commit it because I'd like some comments (it's a very quick read) and because the menu update screwed up the Gnus menus in it (I edited that out of the patch), so I am not sure if the menus are correct. It's been many years since I edited Texinfo so any hints are welcome. Ted --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=registry.gnus.texi.patch Index: gnus.texi =================================================================== RCS file: /usr/local/cvsroot/gnus/texi/gnus.texi,v retrieving revision 7.305 diff -c -r7.305 gnus.texi *** gnus.texi 8 Sep 2008 21:29:47 -0000 7.305 --- gnus.texi 15 Sep 2008 20:50:27 -0000 *************** *** 22740,22745 **** --- 22209,22215 ---- * 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,26507 **** --- 25972,26190 ---- 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 previous, 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 --=-=-=--