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

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

[Boruch Baum]

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

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

[Filipp Gunbin]

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?

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

[Boruch Baum]

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

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

[Eli Zaretskii]

> Date: Thu, 6 May 2021 22:47:17 -0400
> From: Boruch Baum <boruch_baum@gmx.com>
> Cc: 48269@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.

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

[Boruch Baum]

On 2021-05-07 09:20, Eli Zaretskii wrote:
> > Date: Thu, 6 May 2021 22:47:17 -0400
> > From: Boruch Baum <boruch_baum@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

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

[Eli Zaretskii]

> Date: Sun, 9 May 2021 12:55:15 -0400
> From: Boruch Baum <boruch_baum@gmx.com>
> Cc: fgunbin@fastmail.fm, 48269@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@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.

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

[Boruch Baum]

On 2021-05-09 20:15, Eli Zaretskii wrote:
> > Date: Sun, 9 May 2021 12:55:15 -0400
> > From: Boruch Baum <boruch_baum@gmx.com>
> > Cc: fgunbin@fastmail.fm, 48269@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@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

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

[Eli Zaretskii]

> Date: Sun, 9 May 2021 14:44:43 -0400
> From: Boruch Baum <boruch_baum@gmx.com>
> Cc: fgunbin@fastmail.fm, 48269@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.

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

[Filipp Gunbin]

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

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

[Boruch Baum]

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

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

[Lars Ingebrigtsen]

Filipp Gunbin <fgunbin@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