Re: doc improvements for bug-reference.el

[Stephen Leake <stephen_leake@stephe-leake.org>]

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