From: Tassilo Horn Date: Fri, 21 May 2021 21:11:43 +0000 (+0200) Subject: Add documentation about bug-reference auto-setup. X-Git-Tag: emacs-28.0.90~2363 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a3de48687eb28121f3dbfc20be19bd06c4cd6e98;p=emacs.git Add documentation about bug-reference auto-setup. * doc/emacs/maintaining.texi (Bug Reference): Add documentation about the automatic setup. * lisp/progmodes/bug-reference.el (bug-reference-setup-from-irc-alist): Remove doubling in docstring. --- diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index d385e88ce3d..8b0f65d9679 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -3065,16 +3065,16 @@ the target should be built. @section Bug Reference @cindex bug reference - Most projects with a certain amount of users track bug reports in -some issue tracking software which assigns each report a unique and -short number or identifier. Those are used to reference a given bug, -e.g., in a source code comment above the code fixing some bug, in +Most projects with a certain amount of users track bug reports in some +issue tracking software which assigns each report a unique and short +number or identifier. Those are used to reference a given bug, e.g., +in a source code comment above the code fixing some bug, in documentation files, or in discussions on some mailinglist or IRC channel. @findex bug-reference-mode @findex bug-reference-prog-mode -The minor modes @code{bug-reference-mode} and + The minor modes @code{bug-reference-mode} and @code{bug-reference-prog-mode} highlight such bug references and make it possible to follow them to the corresponding bug report on the project's issue tracker. @code{bug-reference-prog-mode} is a variant @@ -3083,7 +3083,7 @@ inside source code comments and strings. @vindex bug-reference-bug-regexp @vindex bug-reference-url-format -For its working, bug reference mode needs to know the syntax of bug + For its working, bug reference mode needs to know the syntax of bug references (@code{bug-reference-bug-regexp}), and the URL of the tracker where bug reports can be looked up (@code{bug-reference-url-format}). Since those are typically @@ -3112,6 +3112,71 @@ the actual bug number has to be used to distinguish between issues and merge requests where each of them has a different URL. +@heading Automatic Setup + +@vindex bug-reference-auto-setup-functions +If @code{bug-reference-mode} is activated, +@code{bug-reference-mode-hook} has been run and still +@code{bug-reference-bug-regexp}, and @code{bug-reference-url-format} +aren't both set, it'll try to setup suitable values for these two +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. + + Right now, there are three types of setup functions. + +@enumerate +@item +Setup for version-controlled files configurable by the variable +@code{bug-reference-setup-from-vc-alist}. The default is able to +setup GNU projects where @url{https://debbugs.gnu.org} is used as +issue tracker, Github projects where both bugs and pull requests are +referenced using the @code{#42} notation, and GitLab projects where +bugs are references with @code{#17}, too, but merge requests use the +@code{!18} notation. + +@item +Setup for email guessing from mail folder/mbox names, and mail header +values configurable by the variable +@code{bug-reference-setup-from-mail-alist}. The built-in news- and +mailreader @ref{Gnus} and @ref{Rmail} are supported. + +@item +Setup for IRC channels configurable by the variable +@code{bug-reference-setup-from-irc-alist}. The built-in IRC clients +Rcirc, @xref{,,,Rcirc, Rcirc}, and ERC, @xref{,,,ERC, ERC}, are +supported. +@end enumerate + +For almost all of those modes, it's enough to simply enable +@code{bug-reference-mode}, only Rmail requires a slightly different +setup. + +@smallexample +;; Use VC-based setup if file is under version control. +(add-hook 'prog-mode-hook #'bug-reference-prog-mode) + +;; Gnus (summary & article buffers) +(add-hook 'gnus-mode-hook #'bug-reference-mode) + +;; Rmail +(add-hook 'rmail-show-message-hook #'bug-reference-mode-force-auto-setup) + +;; Rcirc +(add-hook 'rcirc-mode-hook #'bug-reference-mode) + +;; ERC +(add-hook 'erc-mode-hook #'bug-reference-mode) +@end smallexample + +In the Rmail case, instead of the mode hook, the +@code{rmail-show-message-hook} has to be used in combination with the +function @code{bug-reference-mode-force-auto-setup} which activates +@code{bug-reference-mode} and forces auto-setup. The reason is that +with Rmail all messages reside in the same buffer but the setup needs +to be performed whenever another messages is displayed. + + @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 fc9627c2728..141e97c3b00 100644 --- a/lisp/progmodes/bug-reference.el +++ b/lisp/progmodes/bug-reference.el @@ -372,8 +372,8 @@ From, and Cc against HEADER-REGEXP in "An alist for setting up `bug-reference-mode' in IRC modes. This takes action if `bug-reference-mode' is enabled in IRC -channels using one of Emacs' IRC clients (rcirc and ERC). -Currently, rcirc and ERC are supported. +channels using one of Emacs' IRC clients. Currently, rcirc and +ERC are supported. Each element has the form