doc improvements for bug-reference.el

doc improvements for bug-reference.el

[Stephen Leake]

[-- Attachment #1: Type: text/plain, Size: 215 bytes --]

I just customized bug-reference-mode for emacs debbugs. I had to read
the code to figure out what to set, so I have some suggestions for
improving the documentation; see attached patch.

Ok to commit?
-- 
-- Stephe

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: bug-ref.diff --]
[-- Type: text/x-patch, Size: 1297 bytes --]

diff --git a/lisp/progmodes/bug-reference.el b/lisp/progmodes/bug-reference.el
index f1ec5224c7..cec77119de 100644
--- a/lisp/progmodes/bug-reference.el
+++ b/lisp/progmodes/bug-reference.el
@@ -25,10 +25,12 @@
 
 ;; This file provides minor modes for putting clickable overlays on
 ;; references to bugs.  A bug reference is text like "PR foo/29292";
-;; this is mapped to a URL using a user-supplied format.
+;; this is mapped to a URL using a user-supplied format; see
+;; `bug-reference-url-format' and `bug-reference-bug-regexp'.
 
 ;; Two minor modes are provided.  One works on any text in the buffer;
-;; the other operates only on comments and strings.
+;; the other operates only on comments and strings. By default, the
+;; URL link is followed by invoking C-c RET or mouse-2.
 
 ;;; Code:
 
@@ -126,6 +128,9 @@ bug-reference-push-button
   "Open URL corresponding to the bug reference at POS."
   (interactive
    (list (if (integerp last-command-event) (point) last-command-event)))
+  (when (null bug-reference-url-format)
+    (user-error
+     "You must customize `bug-reference-url-format', then restart bug-reference-mode."))
   (if (and (not (integerp pos)) (eventp pos))
       ;; POS is a mouse event; switch to the proper window/buffer
       (let ((posn (event-start pos)))

Re: doc improvements for bug-reference.el

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Sat, 26 Jun 2021 16:04:09 -0700
> 
> I just customized bug-reference-mode for emacs debbugs. I had to read
> the code to figure out what to set, so I have some suggestions for
> improving the documentation; see attached patch.

Thanks.

> -;; the other operates only on comments and strings.
> +;; the other operates only on comments and strings. By default, the
> +;; URL link is followed by invoking C-c RET or mouse-2.

Two spaces between sentences, please.

> +  (when (null bug-reference-url-format)
> +    (user-error
> +     "You must customize `bug-reference-url-format', then restart bug-reference-mode."))

Is this really a user-error?

Also, does anything need to be improved in maintaining.texi?

Re: doc improvements for bug-reference.el

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stephen Leake <stephen_leake@stephe-leake.org>
>> Date: Sat, 26 Jun 2021 16:04:09 -0700
>> 
>> I just customized bug-reference-mode for emacs debbugs. I had to read
>> the code to figure out what to set, so I have some suggestions for
>> improving the documentation; see attached patch.
>
> Thanks.
>
>> -;; the other operates only on comments and strings.
>> +;; the other operates only on comments and strings. By default, the
>> +;; URL link is followed by invoking C-c RET or mouse-2.
>
> Two spaces between sentences, please.
>
>> +  (when (null bug-reference-url-format)
>> +    (user-error
>> + "You must customize `bug-reference-url-format', then restart
>> bug-reference-mode."))
>
> Is this really a user-error?

From the doc string of user-error:

    is intended to report errors on the part of the
    user, rather than errors in the code itself

I think that fits here; the user must take some action to make this
work; it's not a bug to be reported.

> Also, does anything need to be improved in maintaining.texi?

I was not aware of that; I'll add a reference to it in bug-reference.el,
and change the user-error message to refer to it instead.

maintaining.texi does not mention the default key-binding; perhaps it
should? I'm not sure what the emacs manual convention on this is.
Otherwise it looks ok.

Also, I'll try to create a function for
bug-reference-auto-setup-functions to handle references in the
emacs-devel mailing list.

-- 
-- Stephe

Re: doc improvements for bug-reference.el

[Stephen Leake]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> Also, I'll try to create a function for
> bug-reference-auto-setup-functions to handle references in the
> emacs-devel mailing list.

Actually, that's already there, but it only works if you invoke
bug-reference-mode from the summary buffer. If I had done that,
everything would have worked.

--
-- Stephe

Re: doc improvements for bug-reference.el

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Cc: emacs-devel@gnu.org
> Date: Sun, 27 Jun 2021 08:39:19 -0700
> 
> >> +  (when (null bug-reference-url-format)
> >> +    (user-error
> >> + "You must customize `bug-reference-url-format', then restart
> >> bug-reference-mode."))
> >
> > Is this really a user-error?
> 
> >From the doc string of user-error:
> 
>     is intended to report errors on the part of the
>     user, rather than errors in the code itself
> 
> I think that fits here; the user must take some action to make this
> work; it's not a bug to be reported.

Even if the code is called from a Lisp program?

> maintaining.texi does not mention the default key-binding; perhaps it
> should?

If they are important enough to document.

Thanks.

Re: doc improvements for bug-reference.el

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Sun, 27 Jun 2021 08:54:42 -0700
> Cc: emacs-devel@gnu.org
> 
> Stephen Leake <stephen_leake@stephe-leake.org> writes:
> 
> > Also, I'll try to create a function for
> > bug-reference-auto-setup-functions to handle references in the
> > emacs-devel mailing list.
> 
> Actually, that's already there, but it only works if you invoke
> bug-reference-mode from the summary buffer. If I had done that,
> everything would have worked.

Maybe that should be documented?

Re: doc improvements for bug-reference.el

[Tassilo Horn]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> Also, I'll try to create a function for
> bug-reference-auto-setup-functions to handle references in the
> emacs-devel mailing list.

That should work out-of-the box already, at least for Gnus, Rmail, and
mu4e.  There is an entry in `bug-reference-setup-from-mail-alist' which
should match the List-ID of emacs-devel and other emacs-related lists.

However, the auto-setup is not performed if regexp and url-format have
already been set.  Maybe you've set them globally?

Bye,
Tassilo

Re: doc improvements for bug-reference.el

[Tassilo Horn]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

>> Also, I'll try to create a function for
>> bug-reference-auto-setup-functions to handle references in the
>> emacs-devel mailing list.
>
> Actually, that's already there, but it only works if you invoke
> bug-reference-mode from the summary buffer. If I had done that,
> everything would have worked.

Ah, sorry for the reply to your other message, I've read this mail
later.  Feel free to improve that it also works when activated only in
the article buffer.  I guess you are more qualified to do that than
myself since I'm using mu4e these days.

Bye,
Tassilo