[elpa] externals/gnorb 0c20b7d 397/449: Provide Org tagging for Gnus messages

[Stefan Monnier]

branch: externals/gnorb
commit 0c20b7d15c136dd68d2748ab00cdd8682bf33dac
Author: Eric Abrahamsen <eric@ericabrahamsen.net>
Commit: Stefan Monnier <monnier@iro.umontreal.ca>

    Provide Org tagging for Gnus messages
    
    * packages/gnorb/gnorb-gnus.el (gnorb-gnus-tag-message): New command
      for tagging messages.
      (gnorb-gnus-insert-tagged-messages): New command for inserting
      tagged messages into the Summary buffer.
      (gnorb-gnus-insert-format-tags): New function for displaying tags as
      part of a group format.
      (gnorb-gnus-summary-tags-format-letter): Option allowing the user to
      specify the format spec for tags.
      (gnorb-gnus-auto-tag-messages): Option governing the auto-tagging of
      messages.
      (gnorb-gnus-incoming-do-todo, gnorb-gnus-quick-reply): Possibly
      auto-tag messages.
    * packages/gnorb/gnorb-org.el (gnorb-org-munge-agenda-query-string):
      New function, with query string munging pulled out.
    * packages/gnorb/gnorb-registry.el
      (gnorb-registry-org-tag-search,gnorb-registry-tagged-messages,
      gnorb-registry-tracked-tags): New functions for retrieving tags and
      messages.
    * packages/gnorb/gnorb-utils.el (gnorb-install-defaults): Provide
      default keybindings for `gnorb-gnus-tag-message' and
      `gnorb-gnus-insert-tagged-messages'.
    * packages/gnorb/gnorb.org: Document.
---
 gnorb-gnus.el     | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 gnorb-org.el      |  56 ++++++++++++++------------
 gnorb-registry.el |  13 ++++++
 gnorb-utils.el    |   2 +
 gnorb.info        | 112 +++++++++++++++++++++++++++++----------------------
 gnorb.org         |  38 +++++++++++++-----
 gnorb.texi        |  46 ++++++++++++++-------
 7 files changed, 283 insertions(+), 102 deletions(-)

diff --git a/gnorb-gnus.el b/gnorb-gnus.el
index ce60199..27226ac 100644
--- a/gnorb-gnus.el
+++ b/gnorb-gnus.el
@@ -38,7 +38,7 @@
                  (group newsgroups message-id x-no-archive))
 (declare-function org-gnus-follow-link "org-gnus"
                  (group article))
-
+(declare-function org-make-tags-matcher "org" (match))
 (defvar org-refile-targets)
 
 (defgroup gnorb-gnus nil
@@ -117,6 +117,14 @@ Ticks can be safely removed later."
   :group 'gnorb-gnus
   :type 'boolean)
 
+(defcustom gnorb-gnus-auto-tag-messages nil
+  "When non-nil, tag messages with associated heading tags.
+When creating associations between Org headings and messages,
+automatically copy the heading's tags on to the message, using
+the registry."
+  :group 'gnorb-gnus
+  :type 'boolean)
+
 (defcustom gnorb-gnus-summary-mark-format-letter "g"
   "Format letter to be used as part of your
   `gnus-summary-line-format', to indicate in the *Summary* buffer
@@ -128,6 +136,14 @@ Ticks can be safely removed later."
   :group 'gnorb-gnus
   :type 'string)
 
+(defcustom gnorb-gnus-summary-tags-format-letter "G"
+  "Format letter to be replaced with message tags.
+Add this format specification to your `gnus-summary-line-format'
+to show the tags which are currently applied to the message.
+Must be prefixed with \"u\", eg. \"%uG\"."
+  :group 'gnorb-gnus
+  :type 'string)
+
 (defcustom gnorb-gnus-summary-mark "¡"
   "Default mark to insert in the summary format line of articles
   that are likely relevant to existing TODO headings."
@@ -527,7 +543,7 @@ you'll stay in the Gnus summary buffer."
            ;; Specifically ask for zombies, so the user has chance to
            ;; flush them out.
            (gnorb-find-tracked-headings headers t)))
-        targ)
+        targ tags)
     (setq gnorb-gnus-message-info
          `(:subject ,subject :msg-id ,msg-id
                     :to ,to :from ,from
@@ -564,6 +580,7 @@ you'll stay in the Gnus summary buffer."
                  (save-window-excursion
                    (find-file (nth 1 targ))
                    (goto-char (nth 3 targ))
+                   (setq tags (org-get-tags))
                    (org-id-get-create))))
          ;; Either bulk associate multiple messages...
          (if (> (length articles) 1)
@@ -595,6 +612,10 @@ you'll stay in the Gnus summary buffer."
            (dolist (a articles)
              (when gnorb-gnus-tick-all-tracked-messages
                (gnus-summary-mark-article a gnus-ticked-mark))
+             (when gnorb-gnus-auto-tag-messages
+               (gnorb-gnus-tag-message
+                (mail-header-id (gnus-data-header (gnus-data-find a)))
+                tags))
              (gnus-summary-update-article a))))
       (error
        ;; If these are left populated after an error, it plays hell
@@ -637,10 +658,16 @@ reply."
          (move-marker gnorb-return-marker (point))
          (when gnorb-gnus-tick-all-tracked-messages
            (gnus-summary-mark-article art-no gnus-ticked-mark))
-         (gnus-summary-update-article art-no)
          ;; Assume the first heading is the one we want.
          (gnorb-registry-make-entry
           msg-id from subject targ group)
+         ;; Maybe tag the message.
+         (when gnorb-gnus-auto-tag-messages
+           (let ((tags (save-window-excursion
+                         (org-id-goto targ)
+                         (org-get-tags))))
+             (gnorb-gnus-tag-message msg-id tags)))
+         (gnus-summary-update-article art-no)
          (gnus-summary-wide-reply-with-original 1)
          (move-marker ret (point))
          (save-restriction
@@ -656,6 +683,75 @@ reply."
                   (gnorb-pretty-outline targ))))
       (message "No associated headings found"))))
 
+(with-eval-after-load 'gnus-registry
+  (add-to-list 'gnus-registry-extra-entries-precious 'org-tags)
+  (add-to-list 'gnus-registry-track-extra 'org-tags))
+
+;;;###autoload
+(defun gnorb-gnus-tag-message (arg &optional tags)
+  "Tag message or messages with TAGS.
+ARG is used to specify which messages to work on (according to
+Gnus' process prefix convention).  TAGS should be a list of Org
+tags.  The tags are stored under the `org-tags' key in the
+registry.  If called from a lisp program, TAGS are added to any
+existing tags.
+
+If multiple messages are to be tagged, only the first message's
+existing tags are offered as a default."
+  (interactive "P")
+  (let* ((articles (or (gnus-summary-work-articles arg)
+                      (user-error "This command must be used within Gnus")))
+        (first (mail-header-id
+                (gnus-data-header
+                 (gnus-data-find (car articles)))))
+        (crm-separator ":")
+        (current (gnus-registry-get-id-key first 'org-tags))
+        (default (when current
+                   (mapconcat #'identity current ":"))))
+    (setq tags
+         (if tags
+             (delete-dups (append current tags))
+           (completing-read-multiple
+            "Tags: "
+            (org-global-tags-completion-table) nil t default)))
+    (dolist (a articles)
+      (let ((msg-id (mail-header-id
+                    (gnus-data-header
+                     (gnus-data-find a)))))
+       (gnus-registry-set-id-key msg-id 'org-tags tags)
+       (gnus-summary-update-article a)))
+    (gnus-message 5 "%d message%s tagged: %s"
+                 (length articles)
+                 (if (= 1 (length articles)) "" "s")
+                 (mapconcat #'identity tags ":"))))
+
+;;;###autoload
+(defun gnorb-gnus-insert-tagged-messages (tags)
+  "Insert articles in this group with tags matching TAGS.
+TAGS is a string possibly containing multiple tags to include or
+exclude.  See Info node `(org)Matching tags and properties'."
+  (interactive "MTags: ")
+  (let ((matcher (cdr (org-make-tags-matcher tags)))
+       (tagged-messages (registry-search gnus-registry-db
+                                         :regex `((org-tags ".+"))
+                                         :member `((group 
,gnus-newsgroup-name))))
+       (old (sort (mapcar 'car gnus-newsgroup-data) '<))
+       selected-messages)
+    ;; Funcall the matcher with t, (list of tags), and 1.
+    (dolist (m tagged-messages)
+      (when (funcall matcher t (gnus-registry-get-id-key m 'org-tags) 1)
+       (push m selected-messages)))
+    (if selected-messages
+       ;; Turn message ids into article numbers.
+       (progn
+         (setq selected-messages
+               (mapcar (lambda (id) (cdr (gnus-request-head id 
gnus-newsgroup-name)))
+                       selected-messages))
+         (gnus-summary-insert-articles selected-messages)
+         (gnus-summary-limit (gnus-sorted-nunion old selected-messages))
+         (gnus-summary-position-point))
+      (message "No matching messages in this group"))))
+
 ;;;###autoload
 (defun gnorb-gnus-search-messages (str persist &optional head-text ret)
   "Initiate a search for gnus message links in an org subtree.
@@ -781,6 +877,22 @@ option `gnorb-gnus-hint-relevant-article' is non-nil."
       (lambda (header)
        (gnorb-gnus-insert-format-letter-maybe header)))
 
+(defun gnorb-gnus-insert-format-tags (header)
+  (let* ((id (mail-header-message-id header))
+        (entry (nth 1 (assoc id (registry-lookup
+                                 gnus-registry-db
+                                 (list id)))))
+        (tags (cdr-safe (assq 'org-tags entry))))
+    (if tags
+       (concat
+        ":" (mapconcat #'identity tags ":") ":")
+      "")))
+
+(fset (intern (concat "gnus-user-format-function-"
+                     gnorb-gnus-summary-tags-format-letter))
+      (lambda (header)
+       (gnorb-gnus-insert-format-tags header)))
+
 ;;;###autoload
 (defun gnorb-gnus-view ()
   "Display the first relevant TODO heading for the message under point"
diff --git a/gnorb-org.el b/gnorb-org.el
index 9cb5f0a..00b46d6 100644
--- a/gnorb-org.el
+++ b/gnorb-org.el
@@ -632,8 +632,6 @@ captured from onto the Org heading being captured.
        (with-current-buffer buf
          (when (memq major-mode '(gnus-summary-mode
                                   gnus-article-mode
-
-;;; Agenda/BBDB popup stuff
                                   bbdb-mode
                                   ebdb-mode))
            (call-interactively 'org-store-link))))))
@@ -698,6 +696,8 @@ captured from onto the Org heading being captured.
 (add-hook 'org-capture-prepare-finalize-hook
          'gnorb-org-capture-abort-cleanup)
 
+;;; Agenda/BBDB popup stuff
+
 (defcustom gnorb-org-agenda-popup-bbdb nil
   "Should Agenda tags search pop up a BBDB buffer with matching
   records?
@@ -716,17 +716,38 @@ customized with `gnorb-bbdb-org-tag-field'."
                 (const full-multi-line)
                 (symbol)))
 
-;;;###autoload
-(defun gnorb-org-popup-bbdb (&optional str)
-  "In an `org-tags-view' Agenda buffer, pop up a BBDB buffer
-showing records whose `org-tags' field matches the current tags
-search."
+(defun gnorb-org-munge-agenda-query-string (str)
+  "Remove all non-tag search terms from query string STR.
+Returns a lambda form used for matching a search string (ie, the
+`cdr' of `org-make-tags-matcher')."
   ;; I was hoping to use `org-make-tags-matcher' directly, then snag
   ;; the tagmatcher from the resulting value, but there doesn't seem
   ;; to be a reliable way of only getting the tag-related returns. But
   ;; I'd still like to use that function. So an ugly hack to first
   ;; remove non-tag contents from the query string, and then make a
   ;; new call to `org-make-tags-matcher'.
+  (let ((org--matcher-tags-todo-only nil)
+       (re 
"^&?\\([-+:]\\)?\\({[^}]+}\\|LEVEL\\([<=>]\\{1,2\\}\\)\\([0-9]+\\)\\|\\(\\(?:[[:alnum:]_]+\\(?:\\\\-\\)*\\)+\\)\\([<>=]\\{1,2\\}\\)\\({[^}]+}\\|\"[^\"]*\"\\|-?[.0-9]+\\(?:[eE][-+]?[0-9]+\\)?\\)\\|[[:alnum:]_@#%]+\\)")
+       (or-terms (org-split-string str "|"))
+       term rest out-or acc tag-clause)
+    (while (setq term (pop or-terms))
+      (setq acc nil)
+      (while (string-match re term)
+       (setq rest (substring term (match-end 0)))
+       (let ((sub-term (match-string 0 term)))
+         ;; This isn't a tag, we don't want it.
+         (unless (string-match-p "\\([<>=]\\)" sub-term)
+           (push sub-term acc))
+         (setq term rest)))
+      (push (mapconcat 'identity (nreverse acc) "") out-or))
+    (setq str (mapconcat 'identity (nreverse out-or) "|"))
+    (cdr (org-make-tags-matcher str))))
+
+;;;###autoload
+(defun gnorb-org-popup-bbdb (&optional str)
+  "In an `org-tags-view' Agenda buffer, pop up a BBDB buffer
+showing records whose `org-tags' field matches the current tags
+search."
   (interactive)
   (require 'gnorb-bbdb)
   (let (recs)
@@ -735,23 +756,8 @@ search."
                 (eq org-agenda-type 'tags))
            (or (called-interactively-p 'any)
                gnorb-org-agenda-popup-bbdb))
-          (let ((org--matcher-tags-todo-only nil)
-                (str (or str org-agenda-query-string))
-                (re 
"^&?\\([-+:]\\)?\\({[^}]+}\\|LEVEL\\([<=>]\\{1,2\\}\\)\\([0-9]+\\)\\|\\(\\(?:[[:alnum:]_]+\\(?:\\\\-\\)*\\)+\\)\\([<>=]\\{1,2\\}\\)\\({[^}]+}\\|\"[^\"]*\"\\|-?[.0-9]+\\(?:[eE][-+]?[0-9]+\\)?\\)\\|[[:alnum:]_@#%]+\\)")
-                or-terms term rest out-or acc tag-clause)
-            (setq or-terms (org-split-string str "|"))
-            (while (setq term (pop or-terms))
-              (setq acc nil)
-              (while (string-match re term)
-                (setq rest (substring term (match-end 0)))
-                (let ((sub-term (match-string 0 term)))
-                  (unless (save-match-data ; this isn't a tag, don't want it
-                            (string-match "\\([<>=]\\)" sub-term))
-                    (push sub-term acc))
-                  (setq term rest)))
-              (push (mapconcat 'identity (nreverse acc) "") out-or))
-            (setq str (mapconcat 'identity (nreverse out-or) "|"))
-            (setq tag-clause (cdr (org-make-tags-matcher str)))
+          (let ((tag-clause (gnorb-org-munge-agenda-query-string
+                             (or str org-agenda-query-string))))
             (unless (equal str "")
               (setq recs
                     (cl-remove-if-not
@@ -765,7 +771,7 @@ search."
                                     (case-fold-search t)
                                     (org-trust-scanner-tags t))
                                 ;; This is bad, we're lexically bound, now.
-                                (eval tag-clause)))))
+                                (funcall tag-clause t tags-list 1)))))
                      (bbdb-records))))))
          ((eq major-mode 'org-mode)
           (save-excursion
diff --git a/gnorb-registry.el b/gnorb-registry.el
index 375a5b5..cf437ee 100644
--- a/gnorb-registry.el
+++ b/gnorb-registry.el
@@ -182,15 +182,28 @@ archived headings as well."
 key."
   (registry-search gnus-registry-db :member `((gnorb-ids ,id))))
 
+(defun gnorb-registry-org-tag-search (tag)
+  "Find all messages that have the org TAG in `org-tags'."
+  (registry-search gnus-registry-db :member `((org-tags ,tag))))
+
 (defun gnorb-registry-tracked-messages ()
   "Return all message-ids that have non-empty 'gnorb-ids keys."
   (registry-search gnus-registry-db :regex `((gnorb-ids ".+"))))
 
+(defun gnorb-registry-tagged-messages ()
+  "Return all messages with non-empty `org-tags' keys."
+  (registry-search gnus-registry-db :regex `((org-tags ".+"))))
+
 (defun gnorb-registry-tracked-headings ()
   "Return all Org heading ids that are associated with messages."
   (hash-table-keys
    (registry-lookup-secondary gnus-registry-db 'gnorb-ids)))
 
+(defun gnorb-registry-tracked-tags ()
+  "Return all tags that have been used on tracked messages."
+  (hash-table-keys
+   (registry-lookup-secondary gnus-registry-db 'org-tags)))
+
 (defun gnorb-report-tracking-usage ()
   "Pop up a temporary window reporting on Gnorb usage of the Gnus
 registry to track message/heading associations.  Reports the
diff --git a/gnorb-utils.el b/gnorb-utils.el
index 050c3e3..30dec58 100644
--- a/gnorb-utils.el
+++ b/gnorb-utils.el
@@ -646,6 +646,8 @@ registry be in use, and should be called after the call to
        (define-key gnus-summary-mime-map "a" #'gnorb-gnus-article-org-attach)
        (define-key gnus-summary-mode-map (kbd "C-c t") 
#'gnorb-gnus-incoming-do-todo)
        (define-key gnus-summary-mode-map (kbd "C-c v") #'gnorb-gnus-view)
+       (define-key gnus-summary-mode-map (kbd "C-c C-t") 
#'gnorb-gnus-tag-message)
+       (define-key gnus-summary-limit-map (kbd "g") 
#'gnorb-gnus-insert-tagged-messages)
        (setq gnorb-gnus-capture-always-attach t)
        (push '("attach to org heading" . gnorb-gnus-mime-org-attach)
              gnus-mime-action-alist)
diff --git a/gnorb.info b/gnorb.info
index d37e31e..f83d046 100644
--- a/gnorb.info
+++ b/gnorb.info
@@ -19,8 +19,8 @@ Gnorb Manual
 * Email Tracking::
 * Restoring Window Layout::
 * Recent Mails From BBDB Contacts::
+* Tagging Messages and Contacts::
 * BBDB posting styles::
-* BBDB Org tagging::
 * Misc BBDB::
 * Misc Org::
 * Misc Gnus::
@@ -443,7 +443,7 @@ interactive function ‘gnorb-restore-layout’, by default 
bound to “C-c
 A”.
 
 
-File: gnorb.info,  Node: Recent Mails From BBDB Contacts,  Next: BBDB posting 
styles,  Prev: Restoring Window Layout,  Up: Top
+File: gnorb.info,  Node: Recent Mails From BBDB Contacts,  Next: Tagging 
Messages and Contacts,  Prev: Restoring Window Layout,  Up: Top
 
 6 Recent Mails From BBDB Contacts
 *********************************
@@ -465,9 +465,42 @@ open.  There are several options controlling how all this 
works; see the
 gnorb-bbdb user options section below for details.
 
 
-File: gnorb.info,  Node: BBDB posting styles,  Next: BBDB Org tagging,  Prev: 
Recent Mails From BBDB Contacts,  Up: Top
+File: gnorb.info,  Node: Tagging Messages and Contacts,  Next: BBDB posting 
styles,  Prev: Recent Mails From BBDB Contacts,  Up: Top
+
+7 Tagging Messages and Contacts
+*******************************
+
+It’s possible to use your defined Org tags to tag BBDB contacts and Gnus
+messages.
+
+   For BBDB contacts, tags are stored in an xfield named org-tags, by
+default (you can customize the name of this field using the
+‘gnorb-bbdb-org-tag-field’ option).  Once contacts are tagged, you can
+search for tags normally in the *BBDB* buffer.  You can also pop up a
+*BBDB* buffer alongside an Org Agenda tags search, with contacts
+matching the search terms.  You can have this happen automatically, by
+setting ‘gnorb-org-agenda-popup-bbdb’ to a non-nil value, or do it
+manually by calling ‘gnorb-org-popup-bbdb’.
+
+   Gnus messages can be tagged from a *Summary* buffer using the command
+‘gnorb-gnus-tag-message’ (bound to “C-c C-t” when using the default
+keybindings).  You can also search for tagged messages in a group using
+‘gnorb-gnus-insert-tagged-messages’ (bound to “/ g” when using the
+default keybindings).  The search string can be given as a more complex
+tags expression a la Org Agenda searches, ie “cat|bird-dog”.
+
+   If the option ‘gnorb-gnus-auto-tag-messages’ is non-nil, any time you
+trigger an Org heading from a Gnus message, the message will “inherit”
+the tags of the Org heading.
+
+   You can view Org tags on Gnus messages by adding the “%uG” spec code
+to your ‘gnus-group-line-format’ value.  That spec code can be
+customized using the ‘gnorb-gnus-summary-tags-format-letter’ option.
 
-7 BBDB posting styles
+
+File: gnorb.info,  Node: BBDB posting styles,  Next: Misc BBDB,  Prev: Tagging 
Messages and Contacts,  Up: Top
+
+8 BBDB posting styles
 *********************
 
 Gnorb comes with a BBDB posting-style system, inspired by (copied from)
@@ -484,24 +517,7 @@ If you want to use this feature regularly, you can remap 
‘bbdb-mail’ to
 ‘gnorb-bbdb-mail’ in the ‘bbdb-mode-map’.
 
 
-File: gnorb.info,  Node: BBDB Org tagging,  Next: Misc BBDB,  Prev: BBDB 
posting styles,  Up: Top
-
-8 BBDB Org tagging
-******************
-
-BBDB contacts can be tagged with the same tags you use in your Org
-files.  This allows you to pop up a *BBDB* buffer alongside your Org
-Agenda when searching for certain tags.  This can happen automatically
-for all Org tags-todo searches, if you set the option
-‘gnorb-org-agenda-popup-bbdb’ to t.  Or you can do it manually, by
-calling the command of the same name.  This command only shows TODOs by
-default: use a prefix argument to show all tagged headings.
-
-   Tags are stored in an xfield named org-tags, by default.  You can
-customize the name of this field using ‘gnorb-bbdb-org-tag-field’.
-
-
-File: gnorb.info,  Node: Misc BBDB,  Next: Misc Org,  Prev: BBDB Org tagging,  
Up: Top
+File: gnorb.info,  Node: Misc BBDB,  Next: Misc Org,  Prev: BBDB posting 
styles,  Up: Top
 
 9 Misc BBDB
 ***********
@@ -759,32 +775,32 @@ If you don’t like these defaults, you can always do your 
own setup.
 
 Tag Table:
 Node: Top194
-Node: Introduction989
-Node: Installation2314
-Node: Setup2692
-Node: Email Tracking3145
-Node: Likely Workflow4349
-Node: Tracking Setup7119
-Node: Beginning and Continuing the Tracking Process8399
-Node: Trigger Actions12591
-Node: Viewing Things13665
-Node: Hinting in Gnus15435
-Node: Message Attachments16500
-Node: Registry Usage17739
-Node: Restoring Window Layout18166
-Node: Recent Mails From BBDB Contacts18563
-Node: BBDB posting styles19559
-Node: BBDB Org tagging20475
-Node: Misc BBDB21221
-Node: Searching for messages from BBDB contacts21434
-Node: Citing BBDB contacts21880
-Node: User Options22201
-Node: Misc Org23724
-Node: Inserting BBDB links23899
-Node: User Options 124155
-Node: Misc Gnus27053
-Node: User Options 227215
-Node: Default Keybindings30357
+Node: Introduction1002
+Node: Installation2327
+Node: Setup2705
+Node: Email Tracking3158
+Node: Likely Workflow4362
+Node: Tracking Setup7132
+Node: Beginning and Continuing the Tracking Process8412
+Node: Trigger Actions12604
+Node: Viewing Things13678
+Node: Hinting in Gnus15448
+Node: Message Attachments16513
+Node: Registry Usage17752
+Node: Restoring Window Layout18179
+Node: Recent Mails From BBDB Contacts18576
+Node: Tagging Messages and Contacts19582
+Node: BBDB posting styles21233
+Node: Misc BBDB22140
+Node: Searching for messages from BBDB contacts22356
+Node: Citing BBDB contacts22802
+Node: User Options23123
+Node: Misc Org24646
+Node: Inserting BBDB links24821
+Node: User Options 125077
+Node: Misc Gnus27975
+Node: User Options 228137
+Node: Default Keybindings31279
 
 End Tag Table
 
diff --git a/gnorb.org b/gnorb.org
index 18f1d36..016b08e 100644
--- a/gnorb.org
+++ b/gnorb.org
@@ -342,6 +342,33 @@ Once some links are stored, `gnorb-bbdb-open-link' will 
open them: Use
 a prefix arg to the function call to select particular messages to
 open. There are several options controlling how all this works; see
 the gnorb-bbdb user options section below for details.
+* Tagging Messages and Contacts
+It's possible to use your defined Org tags to tag BBDB contacts and
+Gnus messages.
+
+For BBDB contacts, tags are stored in an xfield named org-tags, by
+default (you can customize the name of this field using the
+`gnorb-bbdb-org-tag-field' option). Once contacts are tagged, you can
+search for tags normally in the *BBDB* buffer. You can also pop up a
+*BBDB* buffer alongside an Org Agenda tags search, with contacts
+matching the search terms. You can have this happen automatically, by
+setting `gnorb-org-agenda-popup-bbdb' to a non-nil value, or do it
+manually by calling `gnorb-org-popup-bbdb'.
+
+Gnus messages can be tagged from a *Summary* buffer using the command
+`gnorb-gnus-tag-message' (bound to "C-c C-t" when using the default
+keybindings). You can also search for tagged messages in a group using
+`gnorb-gnus-insert-tagged-messages' (bound to "/ g" when using the
+default keybindings). The search string can be given as a more complex
+tags expression a la Org Agenda searches, ie "cat|bird-dog".
+
+If the option `gnorb-gnus-auto-tag-messages' is non-nil, any time you
+trigger an Org heading from a Gnus message, the message will "inherit"
+the tags of the Org heading.
+
+You can view Org tags on Gnus messages by adding the "%uG" spec code
+to your `gnus-group-line-format' value. That spec code can be
+customized using the `gnorb-gnus-summary-tags-format-letter' option.
 * BBDB posting styles
 :PROPERTIES:
 :END:
@@ -357,17 +384,6 @@ an alternate `gnorb-bbdb-mail', which does exactly the 
same thing, but
 first processes the new mail according to `gnorb-bbdb-posting-styles'.
 If you want to use this feature regularly, you can remap `bbdb-mail'
 to `gnorb-bbdb-mail' in the `bbdb-mode-map'.
-* BBDB Org tagging
-BBDB contacts can be tagged with the same tags you use in your Org
-files. This allows you to pop up a *BBDB* buffer alongside your Org
-Agenda when searching for certain tags. This can happen automatically
-for all Org tags-todo searches, if you set the option
-`gnorb-org-agenda-popup-bbdb' to t. Or you can do it manually, by
-calling the command of the same name. This command only shows TODOs by
-default: use a prefix argument to show all tagged headings.
-
-Tags are stored in an xfield named org-tags, by default. You can
-customize the name of this field using `gnorb-bbdb-org-tag-field'.
 * Misc BBDB
 ** Searching for messages from BBDB contacts
 :PROPERTIES:
diff --git a/gnorb.texi b/gnorb.texi
index 3fefce4..3d09c89 100644
--- a/gnorb.texi
+++ b/gnorb.texi
@@ -30,8 +30,8 @@
 * Email Tracking::
 * Restoring Window Layout::
 * Recent Mails From BBDB Contacts::
+* Tagging Messages and Contacts::
 * BBDB posting styles::
-* BBDB Org tagging::
 * Misc BBDB::
 * Misc Org::
 * Misc Gnus::
@@ -468,6 +468,36 @@ a prefix arg to the function call to select particular 
messages to
 open. There are several options controlling how all this works; see
 the gnorb-bbdb user options section below for details.
 
+@node Tagging Messages and Contacts
+@chapter Tagging Messages and Contacts
+
+It's possible to use your defined Org tags to tag BBDB contacts and
+Gnus messages.
+
+For BBDB contacts, tags are stored in an xfield named org-tags, by
+default (you can customize the name of this field using the
+`gnorb-bbdb-org-tag-field' option). Once contacts are tagged, you can
+search for tags normally in the *BBDB* buffer. You can also pop up a
+*BBDB* buffer alongside an Org Agenda tags search, with contacts
+matching the search terms. You can have this happen automatically, by
+setting `gnorb-org-agenda-popup-bbdb' to a non-nil value, or do it
+manually by calling `gnorb-org-popup-bbdb'.
+
+Gnus messages can be tagged from a *Summary* buffer using the command
+`gnorb-gnus-tag-message' (bound to ``C-c C-t'' when using the default
+keybindings). You can also search for tagged messages in a group using
+`gnorb-gnus-insert-tagged-messages' (bound to ``/ g'' when using the
+default keybindings). The search string can be given as a more complex
+tags expression a la Org Agenda searches, ie ``cat|bird-dog''.
+
+If the option `gnorb-gnus-auto-tag-messages' is non-nil, any time you
+trigger an Org heading from a Gnus message, the message will ``inherit''
+the tags of the Org heading.
+
+You can view Org tags on Gnus messages by adding the ``%uG'' spec code
+to your `gnus-group-line-format' value. That spec code can be
+customized using the `gnorb-gnus-summary-tags-format-letter' option.
+
 @node BBDB posting styles
 @chapter BBDB posting styles
 
@@ -484,20 +514,6 @@ first processes the new mail according to 
`gnorb-bbdb-posting-styles'.
 If you want to use this feature regularly, you can remap `bbdb-mail'
 to `gnorb-bbdb-mail' in the `bbdb-mode-map'.
 
-@node BBDB Org tagging
-@chapter BBDB Org tagging
-
-BBDB contacts can be tagged with the same tags you use in your Org
-files. This allows you to pop up a *BBDB* buffer alongside your Org
-Agenda when searching for certain tags. This can happen automatically
-for all Org tags-todo searches, if you set the option
-`gnorb-org-agenda-popup-bbdb' to t. Or you can do it manually, by
-calling the command of the same name. This command only shows TODOs by
-default: use a prefix argument to show all tagged headings.
-
-Tags are stored in an xfield named org-tags, by default. You can
-customize the name of this field using `gnorb-bbdb-org-tag-field'.
-
 @node Misc BBDB
 @chapter Misc BBDB