master a3de486: Add documentation about bug-reference auto-setup.

[Tassilo Horn]

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

    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.
---
 doc/emacs/maintaining.texi      | 77 +++++++++++++++++++++++++++++++++++++----
 lisp/progmodes/bug-reference.el |  4 +--
 2 files changed, 73 insertions(+), 8 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index d385e88..8b0f65d 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 fc9627c..141e97c 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