GNU bug report logs - #48269
27.1: log-edit-generate-changelog-from-diff FAILURE

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 48269 in the body.
You can then email your comments to 48269 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Boruch Baum <boruch_baum <at> gmx.com>
To: Emacs Bug Reporting <bug-gnu-emacs <at> gnu.org>
Subject: 27.1: log-edit-generate-changelog-from-diff FAILURE
Date: Thu, 6 May 2021 19:23:08 -0400

GNU Emacs 27.1 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.24,
cairo version 1.16.0) of 2021-03-27, modified by Debian

ref: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=47784#45

1] Attempting to run function log-edit-generate-changelog-from-diff
   returns an error message: 'Diff functionality has not been setup.'

2] The docstring for function log-edit-generate-changelog-from-diff
   gives no indication how to set up 'diff functionality' or otherwise
   guidance on how to use the function.

3] The source of the error message is function log-edit-show-diff. It,
   too, lacks a useful docstring.

4] The code in function log-edit-show-diff indicates that the
   configuration is performed via variable log-edit-diff-function.
   However:

   4.1] That variable lacks a docstring.

   4.2] Setting it to a 'reasonable' value of 'ediff returns an error
        (wrong-number-of-arguments (2 . 3) 0)

At this point, I stopped chasing down the issue. Counting three
documentation issues, one default configuration bug. If I'm the first
end-user world-wide trying to use this, do I get a valuable prize?

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

Message #8 received at 48269 <at> debbugs.gnu.org (full text, mbox):

From: Filipp Gunbin <fgunbin <at> fastmail.fm>
To: Boruch Baum <boruch_baum <at> gmx.com>
Cc: 48269 <at> debbugs.gnu.org
Subject: Re: bug#48269: 27.1: log-edit-generate-changelog-from-diff FAILURE
Date: Fri, 07 May 2021 04:26:29 +0300

On 06/05/2021 19:23 -0400, Boruch Baum wrote:

> GNU Emacs 27.1 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.24,
> cairo version 1.16.0) of 2021-03-27, modified by Debian
>
> ref: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=47784#45
>
> 1] Attempting to run function log-edit-generate-changelog-from-diff
>    returns an error message: 'Diff functionality has not been setup.'
>
> 2] The docstring for function log-edit-generate-changelog-from-diff
>    gives no indication how to set up 'diff functionality' or otherwise
>    guidance on how to use the function.
>
> 3] The source of the error message is function log-edit-show-diff. It,
>    too, lacks a useful docstring.
>
> 4] The code in function log-edit-show-diff indicates that the
>    configuration is performed via variable log-edit-diff-function.
>    However:
>
>    4.1] That variable lacks a docstring.
>
>    4.2] Setting it to a 'reasonable' value of 'ediff returns an error
>         (wrong-number-of-arguments (2 . 3) 0)

Give an emacs -Q recipe?

Message #11 received at 48269 <at> debbugs.gnu.org (full text, mbox):

From: Boruch Baum <boruch_baum <at> gmx.com>
To: Filipp Gunbin <fgunbin <at> fastmail.fm>
Cc: 48269 <at> debbugs.gnu.org
Subject: Re: bug#48269: 27.1: log-edit-generate-changelog-from-diff FAILURE
Date: Thu, 6 May 2021 22:47:17 -0400

On 2021-05-07 04:26, Filipp Gunbin wrote:
> Give an emacs -Q recipe?

Really? OK. Fine...
Revving up \emacs -Q -nw ...
Performing now C-x f on a pre-existing elisp file ...
Adding a few blank lines ...
M-x log-edit-generate-changelog-from-diff

Yep. Same result as reported.

You don't want me to check the docstrings with "\emacs -Q", do you?

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

Message #14 received at 48269 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Boruch Baum <boruch_baum <at> gmx.com>
Cc: 48269 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
Subject: Re: bug#48269: 27.1: log-edit-generate-changelog-from-diff FAILURE
Date: Fri, 07 May 2021 09:20:52 +0300

> Date: Thu, 6 May 2021 22:47:17 -0400
> From: Boruch Baum <boruch_baum <at> gmx.com>
> Cc: 48269 <at> debbugs.gnu.org
> 
> Revving up \emacs -Q -nw ...
> Performing now C-x f on a pre-existing elisp file ...

You mean, "C-x C-f", I presume?

> Adding a few blank lines ...
> M-x log-edit-generate-changelog-from-diff
> 
> Yep. Same result as reported.

So the problem seems to be that the doc strings don't say the command
should be invoked from a *vc-log* buffer, is that right?  The user
manual explains that, so next time when the doc string is not enough,
may I suggest to try looking up the command/variable in the manual?

> You don't want me to check the docstrings with "\emacs -Q", do you?

Please don't mock people when they ask clarifying questions about your
bug reports.  It probably means there's some misunderstanding or lack
of information, and clearing that would help use fix the problems you
report.

Thanks.

Message #17 received at 48269 <at> debbugs.gnu.org (full text, mbox):

From: Boruch Baum <boruch_baum <at> gmx.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 48269 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
Subject: Re: bug#48269: 27.1: log-edit-generate-changelog-from-diff FAILURE
Date: Sun, 9 May 2021 12:55:15 -0400

On 2021-05-07 09:20, Eli Zaretskii wrote:
> > Date: Thu, 6 May 2021 22:47:17 -0400
> > From: Boruch Baum <boruch_baum <at> gmx.com>
>
> So the problem seems to be that the doc strings don't say the command
> should be invoked from a *vc-log* buffer, is that right?

There could be a sanity-check at the beginning of the function in the form:

    (unless (eq major-mode foo)
      (user-error "Not in foo buffer"))

> The user manual explains that, so next time when the doc string is
> not enough,

Umm... In this case, a mix of subjective 'not enough' and objective
non-existent. Important to make that distinction.

>  may I suggest to try looking up the command/variable in the manual?

For me personally that's a great suggestion, but if that's going to be
your position for all emacs users, you're taking a major step back from
a long strong precedent of emacs documentation standards and one of the
features that makes emacs such an attractive environment to work in.

And here's the content of the log-edit.el commentary (don't blink):

That was quick.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

Message #20 received at 48269 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Boruch Baum <boruch_baum <at> gmx.com>
Cc: 48269 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
Subject: Re: bug#48269: 27.1: log-edit-generate-changelog-from-diff FAILURE
Date: Sun, 09 May 2021 20:15:22 +0300

> Date: Sun, 9 May 2021 12:55:15 -0400
> From: Boruch Baum <boruch_baum <at> gmx.com>
> Cc: fgunbin <at> fastmail.fm, 48269 <at> debbugs.gnu.org
> 
> On 2021-05-07 09:20, Eli Zaretskii wrote:
> > > Date: Thu, 6 May 2021 22:47:17 -0400
> > > From: Boruch Baum <boruch_baum <at> gmx.com>
> >
> > So the problem seems to be that the doc strings don't say the command
> > should be invoked from a *vc-log* buffer, is that right?
> 
> There could be a sanity-check at the beginning of the function in the form:
> 
>     (unless (eq major-mode foo)
>       (user-error "Not in foo buffer"))

Yes, but my question was about the doc string: if it said the function
should be invoked from a *vc-log* buffer, would that have helped you?
Since your original report was against the doc string, I think it's
important to understand how we could improve it.

> >  may I suggest to try looking up the command/variable in the manual?
> 
> For me personally that's a great suggestion, but if that's going to
> be your position for all emacs users you're taking a major step back
> from a long strong precedent of emacs documentation standards and
> one of the features that makes emacs such an attractive environment
> to work in.

I was just trying to help you (and all the other Emacs users) to find
the information more efficiently next time.  No matter how hard we
work on it, there will always be deficiencies in Emacs documentation
(as in any other software documentation), so relying on the developers
to get everything 110% correct is impractical, assuming we all have
something else to do other than read the documentation.

Message #23 received at 48269 <at> debbugs.gnu.org (full text, mbox):

From: Boruch Baum <boruch_baum <at> gmx.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 48269 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
Subject: Re: bug#48269: 27.1: log-edit-generate-changelog-from-diff FAILURE
Date: Sun, 9 May 2021 14:44:43 -0400

On 2021-05-09 20:15, Eli Zaretskii wrote:
> > Date: Sun, 9 May 2021 12:55:15 -0400
> > From: Boruch Baum <boruch_baum <at> gmx.com>
> > Cc: fgunbin <at> fastmail.fm, 48269 <at> debbugs.gnu.org
> >
> > On 2021-05-07 09:20, Eli Zaretskii wrote:
> > > > Date: Thu, 6 May 2021 22:47:17 -0400
> > > > From: Boruch Baum <boruch_baum <at> gmx.com>
> > >
> > > So the problem seems to be that the doc strings don't say the command
> > > should be invoked from a *vc-log* buffer, is that right?
> >
> > There could be a sanity-check at the beginning of the function in the form:
> >
> >     (unless (eq major-mode foo)
> >       (user-error "Not in foo buffer"))
>
> Yes, but my question was about the doc string: if it said the function
> should be invoked from a *vc-log* buffer, would that have helped you?
> Since your original report was against the doc string, I think it's
> important to understand how we could improve it.

The short answer then, is yes. But the long answer, adding a sanity
check to the code, would avoid needing to look at the docstring.

>
> > >  may I suggest to try looking up the command/variable in the manual?
> >
> > For me personally that's a great suggestion, but if that's going to
> > be your position for all emacs users you're taking a major step back
> > from a long strong precedent of emacs documentation standards and
> > one of the features that makes emacs such an attractive environment
> > to work in.
>
> I was just trying to help you (and all the other Emacs users) to find
> the information more efficiently next time.  No matter how hard we
> work on it, there will always be deficiencies in Emacs documentation
> (as in any other software documentation), so relying on the developers
> to get everything 110% correct is impractical, assuming we all have
> something else to do other than read the documentation.

The most efficent way seems to me to add the sanity-check to the code.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

Message #26 received at 48269 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Boruch Baum <boruch_baum <at> gmx.com>
Cc: 48269 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
Subject: Re: bug#48269: 27.1: log-edit-generate-changelog-from-diff FAILURE
Date: Sun, 09 May 2021 21:54:44 +0300

> Date: Sun, 9 May 2021 14:44:43 -0400
> From: Boruch Baum <boruch_baum <at> gmx.com>
> Cc: fgunbin <at> fastmail.fm, 48269 <at> debbugs.gnu.org
> 
> > > There could be a sanity-check at the beginning of the function in the form:
> > >
> > >     (unless (eq major-mode foo)
> > >       (user-error "Not in foo buffer"))
> >
> > Yes, but my question was about the doc string: if it said the function
> > should be invoked from a *vc-log* buffer, would that have helped you?
> > Since your original report was against the doc string, I think it's
> > important to understand how we could improve it.
> 
> The short answer then, is yes. But the long answer, adding a sanity
> check to the code, would avoid needing to look at the docstring.

Assuming the text of the user-error message could be detailed enough
to make sense.  A doc string doesn't have to be short, so it's easier
to explain complex stuff there.

Message #29 received at 48269 <at> debbugs.gnu.org (full text, mbox):

From: Filipp Gunbin <fgunbin <at> fastmail.fm>
To: Boruch Baum <boruch_baum <at> gmx.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 48269 <at> debbugs.gnu.org
Subject: Re: bug#48269: 27.1: log-edit-generate-changelog-from-diff FAILURE
Date: Mon, 10 May 2021 01:58:25 +0300

On 09/05/2021 14:44 -0400, Boruch Baum wrote:

>> I was just trying to help you (and all the other Emacs users) to find
>> the information more efficiently next time.  No matter how hard we
>> work on it, there will always be deficiencies in Emacs documentation
>> (as in any other software documentation), so relying on the developers
>> to get everything 110% correct is impractical, assuming we all have
>> something else to do other than read the documentation.
>
> The most efficent way seems to me to add the sanity-check to the code.

Frankly, I don't get it: the function we talk about starts with its
mode's prefix (log-edit), is bound to key in that (and derived) modes,
so why would a user just randomly call it in an unprepared buffer?  I
mean, the sanity check will be an over-defense, IMO.

Filipp

Message #32 received at 48269 <at> debbugs.gnu.org (full text, mbox):

From: Boruch Baum <boruch_baum <at> gmx.com>
To: Filipp Gunbin <fgunbin <at> fastmail.fm>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 48269 <at> debbugs.gnu.org
Subject: Re: bug#48269: 27.1: log-edit-generate-changelog-from-diff FAILURE
Date: Sun, 9 May 2021 20:13:52 -0400

On 2021-05-10 01:58, Filipp Gunbin wrote:
> Frankly, I don't get it: the function we talk about starts with its
> mode's prefix (log-edit), is bound to key in that (and derived) modes,
> so why would a user just randomly call it in an unprepared buffer?

Good point. Short answer: it was directly recommended in a another emacs
bug report thread that I do so.

Longer answer: I wasn't given instructions in that other thread about
'preparing a buffer', only that the command was an alternative to 'C-x 4
a' when operating on version-controlled file and there was no need or
desire for a Changelog file. That's also how I interpreted an excerpt
from the emacs NEWS file posted there. As I had the file under git,
using magit, and 'C-x 4 a' (from add-log.el) is known to work without
any 'buffer preparation', why shouldn't commands from log-edit.el?

> I mean, the sanity check will be an over-defense, IMO.

I'm not so sure, but as I've yet to read up on how to 'prepare a buffer'
and get the command working, I'm not yet in position to take a step back
and assess whether what happened in my case is reasonable to happen to
others.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

Message #35 received at 48269 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Filipp Gunbin <fgunbin <at> fastmail.fm>
Cc: Eli Zaretskii <eliz <at> gnu.org>, Boruch Baum <boruch_baum <at> gmx.com>,
 48269 <at> debbugs.gnu.org
Subject: Re: bug#48269: 27.1: log-edit-generate-changelog-from-diff FAILURE
Date: Tue, 11 May 2021 15:34:09 +0200

Filipp Gunbin <fgunbin <at> fastmail.fm> writes:

> Frankly, I don't get it: the function we talk about starts with its
> mode's prefix (log-edit), is bound to key in that (and derived) modes,
> so why would a user just randomly call it in an unprepared buffer?  I
> mean, the sanity check will be an over-defense, IMO.

I agree -- this doesn't seem to be a bug, and I'm closing this bug
report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.