[Emacs-diffs] Changes to emacs/doc/misc/gnus.texi,v

[Miles Bader]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Miles Bader <miles>     08/09/21 04:22:45

Index: doc/misc/gnus.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/doc/misc/gnus.texi,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -b -r1.33 -r1.34
--- doc/misc/gnus.texi  9 Sep 2008 02:19:23 -0000       1.33
+++ doc/misc/gnus.texi  21 Sep 2008 04:22:42 -0000      1.34
@@ -827,6 +827,7 @@
 * 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.
 
@@ -22740,6 +22741,7 @@
 * 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 +26504,220 @@
 Save table: (spam-stat-save)
 @end smallexample
 
address@hidden The Gnus Registry
address@hidden The Gnus Registry
+
address@hidden registry
address@hidden split
address@hidden 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.
+
address@hidden
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden enumerate
+
+
address@hidden
+* Setup::                       
+* Fancy splitting to parent::   
+* Store custom flags and keywords::  
+* Store arbitrary data::        
address@hidden menu
+
address@hidden Setup
address@hidden Setup
+
+Fortunately, setting up the Gnus registry is pretty easy:
+
address@hidden
+(setq gnus-registry-max-entries 2500
+      gnus-registry-use-long-group-names t)
+
+(gnus-registry-initialize)
address@hidden 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
address@hidden for the gory details.
+
+Here are other settings used by the author of the registry (understand
+what they do before you copy them blindly).
+
address@hidden
+(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))
address@hidden 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.
+
address@hidden gnus-registry-unfollowed-groups
+The groups that will not be followed by
address@hidden  They will still be
+remembered by the registry.  This is a list of regular expressions.
address@hidden defvar
+
address@hidden 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).
address@hidden defvar
+
address@hidden gnus-registry-use-long-group-names
+Whether the registry will use long group names.  It's recommended to
+set this to @code{t}, although everything works if you don't.  Future
+functionality will require it.
address@hidden defvar
+
address@hidden gnus-registry-max-entries
+The number (an integer or @code{nil} for unlimited) of entries the
+registry will keep.
address@hidden defvar
+
address@hidden gnus-registry-cache-file
+The file where the registry will be stored between Gnus sessions.
address@hidden defvar
+
address@hidden Fancy splitting to parent
address@hidden 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:
+
address@hidden
+(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")
address@hidden lisp
+
+in your fancy split setup.  In addition, you may want to customize the
+following variables.
+
address@hidden 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 @code{nil}, but you may want to
+track @code{subject} and @code{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.
address@hidden defvar
+
address@hidden gnus-registry-split-strategy
+This is a symbol, so it's best to change it from the Customize
+interface.  By default it's @code{nil}, but you may want to set it to
address@hidden or @code{first} to split by sender or subject based on
+the majority of matches or on the first found.
address@hidden defvar
+
address@hidden Store custom flags and keywords
address@hidden 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.
+
address@hidden 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 @code{Important}, @code{Work},
address@hidden, @code{To-Do}, and @code{Later} marks.  They all have
+keyboard shortcuts like @kbd{M M i} for Important, using the first
+letter.
address@hidden defvar
+
address@hidden gnus-registry-mark-article
+Call this function to mark an article with a custom registry mark.  It
+will offer the available marks for completion.
address@hidden defun
+
address@hidden Store arbitrary data
address@hidden 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).
+
address@hidden gnus-registry-store-extra-entry (id key value)
+Store @code{value} in the extra data key @code{key} for message
address@hidden
address@hidden defun
+
address@hidden gnus-registry-delete-extra-entry (id key)
+Delete the extra data key @code{key} for message @code{id}.
address@hidden defun
+
address@hidden gnus-registry-fetch-extra (id key)
+Get the extra data key @code{key} for message @code{id}.
address@hidden defun
+
address@hidden 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.
address@hidden defvar
+
 @node Other modes
 @section Interaction with other modes