From 62e2dce3a99cffb174240eed633196058e3c18a2 Mon Sep 17 00:00:00 2001 From: Tassilo Horn Date: Sat, 22 May 2021 19:06:57 +0200 Subject: [PATCH] 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 d20081137a5..a91bfacb9ea 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 141e97c3b00..f1ec5224c77 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)))) -- 2.39.5