master 62e2dce: Document bug-reference setup for 3rd-party packages

[Tassilo Horn]

branch: master
commit 62e2dce3a99cffb174240eed633196058e3c18a2
Author: Tassilo Horn <tsdh@gnu.org>
Commit: Tassilo Horn <tsdh@gnu.org>

    Document bug-reference setup for 3rd-party packages
    
    * doc/emacs/maintaining.texi (Bug Reference): Add section explaining
    adding support for third-party packages.
    * lisp/progmodes/bug-reference.el (bug-reference-maybe-setup-from-vc)
    (bug-reference-maybe-setup-from-mail)
    (bug-reference-maybe-setup-from-irc): Rename from
    bug-reference--maybe-setup-from-*, i.e., un-privatize them because
    they are advertised in the docs now.
---
 doc/emacs/maintaining.texi      |  36 ++++++++++++-
 lisp/progmodes/bug-reference.el | 116 +++++++++++++++++++---------------------
 2 files changed, 91 insertions(+), 61 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index d200811..a91bfac 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -3123,8 +3123,10 @@ variables itself by calling the functions in
 @code{bug-reference-auto-setup-functions} one after the other until
 one is able to set the variables.
 
+@vindex bug-reference-setup-from-vc-alist
+@vindex bug-reference-setup-from-mail-alist
+@vindex bug-reference-setup-from-irc-alist
   Right now, there are three types of setup functions.
-
 @enumerate
 @item
 Setup for version-controlled files configurable by the variable
@@ -3177,6 +3179,38 @@ with Rmail all messages reside in the same buffer but 
the setup needs
 to be performed whenever another messages is displayed.
 
 
+@heading Adding support for third-party packages
+
+@vindex bug-reference-auto-setup-functions
+Adding support for bug-reference' auto-setup is usually quite
+straight-forward: write a setup function of zero arguments which
+gathers the required information (e.g., List-Id/To/From/Cc mail header
+values in the case of a MUA), and then calls one of the following
+helper functions:
+@itemize @bullet
+@item
+@code{bug-reference-maybe-setup-from-vc} which does the setup
+according to @code{bug-reference-setup-from-vc-alist},
+
+@item
+@code{bug-reference-maybe-setup-from-mail} which does the setup
+according to @code{bug-reference-setup-from-mail-alist},
+
+@item
+and @code{bug-reference-maybe-setup-from-irc} which does the setup
+according to @code{bug-reference-setup-from-irc-alist}.
+@end itemize
+A setup function should return non-nil if it could setup bug-reference
+mode which is the case if the last thing the function does is calling
+one of the helper functions above.
+
+Finally, the setup function has to be added to
+@code{bug-reference-auto-setup-functions}.
+
+Note that these auto-setup functions should check as a first step if
+they are applicable, e.g., by checking the @code{major-mode} value.
+
+
 @heading Integration with the debbugs package
 
 @findex debbugs-browse-mode
diff --git a/lisp/progmodes/bug-reference.el b/lisp/progmodes/bug-reference.el
index 141e97c..f1ec522 100644
--- a/lisp/progmodes/bug-reference.el
+++ b/lisp/progmodes/bug-reference.el
@@ -138,7 +138,7 @@ The second subexpression should match the bug reference 
(usually a number)."
        (when url
          (browse-url url))))))
 
-(defun bug-reference--maybe-setup-from-vc (url url-rx bug-rx bug-url-fmt)
+(defun bug-reference-maybe-setup-from-vc (url url-rx bug-rx bug-url-fmt)
   (when (string-match url-rx url)
     (setq-local bug-reference-bug-regexp bug-rx)
     (setq-local bug-reference-url-format
@@ -224,7 +224,7 @@ and apply it if applicable."
         (when url
           (catch 'found
             (dolist (config bug-reference-setup-from-vc-alist)
-              (when (apply #'bug-reference--maybe-setup-from-vc
+              (when (apply #'bug-reference-maybe-setup-from-vc
                            url config)
                 (throw 'found t)))))))))
 
@@ -258,7 +258,7 @@ same `bug-reference-url-format' and 
`bug-reference-url-format'.")
 
 (defvar gnus-newsgroup-name)
 
-(defun bug-reference--maybe-setup-from-mail (group header-values)
+(defun bug-reference-maybe-setup-from-mail (group header-values)
   "Set up according to mail GROUP or HEADER-VALUES.
 Group is a mail group/folder name and HEADER-VALUES is a list of
 mail header values, e.g., the values of From, To, Cc, List-ID,
@@ -294,53 +294,51 @@ and set it if applicable."
     ;; article changes.
     (add-hook 'gnus-article-prepare-hook
               #'bug-reference--try-setup-gnus-article)
-    (bug-reference--maybe-setup-from-mail gnus-newsgroup-name nil)))
+    (bug-reference-maybe-setup-from-mail gnus-newsgroup-name nil)))
 
 (defvar gnus-article-buffer)
 (defvar gnus-original-article-buffer)
 (defvar gnus-summary-buffer)
 
 (defun bug-reference--try-setup-gnus-article ()
-  (with-demoted-errors
-      "Error in bug-reference--try-setup-gnus-article: %S"
-    (when (and bug-reference-mode ;; Only if enabled in article buffers.
-               (derived-mode-p
-                'gnus-article-mode
-                ;; Apparently, gnus-article-prepare-hook is run in the
-                ;; summary buffer...
-                'gnus-summary-mode)
-               gnus-article-buffer
-               gnus-original-article-buffer
-               (buffer-live-p (get-buffer gnus-article-buffer))
-               (buffer-live-p (get-buffer gnus-original-article-buffer)))
-      (with-current-buffer gnus-article-buffer
-        (catch 'setup-done
-          ;; Copy over the values from the summary buffer.
-          (when (and gnus-summary-buffer
-                     (buffer-live-p gnus-summary-buffer))
-            (setq-local bug-reference-bug-regexp
-                        (with-current-buffer gnus-summary-buffer
-                          bug-reference-bug-regexp))
-            (setq-local bug-reference-url-format
-                        (with-current-buffer gnus-summary-buffer
-                          bug-reference-url-format))
-            (when (and bug-reference-bug-regexp
-                       bug-reference-url-format)
-              (throw 'setup-done t)))
-          ;; If the summary had no values, try setting according to
-          ;; the values of the From, To, and Cc headers.
-          (let (header-values)
-            (with-current-buffer
-                (get-buffer gnus-original-article-buffer)
-              (save-excursion
-                (goto-char (point-min))
-                ;; The Newsgroup is omitted because we already matched
-                ;; based on group name in the summary buffer.
-                (dolist (field '("list-id" "to" "from" "cc"))
-                  (let ((val (mail-fetch-field field)))
-                    (when val
-                      (push val header-values))))))
-            (bug-reference--maybe-setup-from-mail nil header-values)))))))
+  (when (and bug-reference-mode ;; Only if enabled in article buffers.
+             (derived-mode-p
+              'gnus-article-mode
+              ;; Apparently, gnus-article-prepare-hook is run in the
+              ;; summary buffer...
+              'gnus-summary-mode)
+             gnus-article-buffer
+             gnus-original-article-buffer
+             (buffer-live-p (get-buffer gnus-article-buffer))
+             (buffer-live-p (get-buffer gnus-original-article-buffer)))
+    (with-current-buffer gnus-article-buffer
+      (catch 'setup-done
+        ;; Copy over the values from the summary buffer.
+        (when (and gnus-summary-buffer
+                   (buffer-live-p gnus-summary-buffer))
+          (setq-local bug-reference-bug-regexp
+                      (with-current-buffer gnus-summary-buffer
+                        bug-reference-bug-regexp))
+          (setq-local bug-reference-url-format
+                      (with-current-buffer gnus-summary-buffer
+                        bug-reference-url-format))
+          (when (and bug-reference-bug-regexp
+                     bug-reference-url-format)
+            (throw 'setup-done t)))
+        ;; If the summary had no values, try setting according to
+        ;; the values of the From, To, and Cc headers.
+        (let (header-values)
+          (with-current-buffer
+              (get-buffer gnus-original-article-buffer)
+            (save-excursion
+              (goto-char (point-min))
+              ;; The Newsgroup is omitted because we already matched
+              ;; based on group name in the summary buffer.
+              (dolist (field '("list-id" "to" "from" "cc"))
+                (let ((val (mail-fetch-field field)))
+                  (when val
+                    (push val header-values))))))
+          (bug-reference-maybe-setup-from-mail nil header-values))))))
 
 (defun bug-reference-try-setup-from-rmail ()
   "Try setting up `bug-reference-mode' from the current rmail mail.
@@ -349,19 +347,17 @@ Guesses suitable `bug-reference-bug-regexp' and
 file's name against GROUP-REGEXP and the values of List-Id, To,
 From, and Cc against HEADER-REGEXP in
 `bug-reference-setup-from-mail-alist'."
-  (with-demoted-errors
-      "Error in bug-reference-try-setup-from-rmail: %S"
-    (when (and bug-reference-mode
-               (derived-mode-p 'rmail-mode))
-      (let (header-values)
-        (save-excursion
-          (goto-char (point-min))
-          (dolist (field '("list-id" "to" "from" "cc"))
-            (let ((val (mail-fetch-field field)))
-              (when val
-                (push val header-values)))))
-        (bug-reference--maybe-setup-from-mail
-         (buffer-file-name) header-values)))))
+  (when (and bug-reference-mode
+             (derived-mode-p 'rmail-mode))
+    (let (header-values)
+      (save-excursion
+        (goto-char (point-min))
+        (dolist (field '("list-id" "to" "from" "cc"))
+          (let ((val (mail-fetch-field field)))
+            (when val
+              (push val header-values)))))
+      (bug-reference-maybe-setup-from-mail
+       (buffer-file-name) header-values))))
 
 (defvar bug-reference-setup-from-irc-alist
   `((,(concat "#" (regexp-opt '("emacs" "gnus" "org-mode" "rcirc"
@@ -386,7 +382,7 @@ If all given entries match, BUG-REGEXP is set as
 `bug-reference-bug-regexp' and URL-FORMAT is set as
 `bug-reference-url-format'.")
 
-(defun bug-reference--maybe-setup-from-irc (channel network)
+(defun bug-reference-maybe-setup-from-irc (channel network)
   "Set up according to IRC CHANNEL or NETWORK.
 CHANNEL is an IRC channel name (or generally a target, i.e., it
 could also be a user name) and NETWORK is that channel's network
@@ -422,7 +418,7 @@ corresponding BUG-REGEXP and URL-FORMAT are set."
 Test each configuration in `bug-reference-setup-from-irc-alist'
 and set it if applicable."
   (when (derived-mode-p 'rcirc-mode)
-    (bug-reference--maybe-setup-from-irc
+    (bug-reference-maybe-setup-from-irc
      rcirc-target
      (and rcirc-server-buffer
           (buffer-live-p rcirc-server-buffer)
@@ -437,7 +433,7 @@ and set it if applicable."
 Test each configuration in `bug-reference-setup-from-irc-alist'
 and set it if applicable."
   (when (derived-mode-p 'erc-mode)
-    (bug-reference--maybe-setup-from-irc
+    (bug-reference-maybe-setup-from-irc
      (erc-format-target)
      (erc-network-name))))