GNU bug report logs - #45438
27.1; please fix misleading documentation for assoc-delete-all

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 45438 in the body.
You can then email your comments to 45438 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: Hendrik Tews <hendrik.tews <at> kernkonzept.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.1; please fix misleading documentation for assoc-delete-all
Date: Fri, 25 Dec 2020 23:13:04 +0100

Hi,

assoc-delete-all was introduced in emacs 26.2, however,
describe-function says "Probably introduced at or before Emacs
version 21.1.". Please fix this to report the right version
number where assoc-delete-all was introduced. With this kind of
misleading information, it is very difficult to write code that
is backward compatible to a number of different emacs major
versions.

Thanks,

Hendrik

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Hendrik Tews <hendrik.tews <at> kernkonzept.com>
Cc: 45438 <at> debbugs.gnu.org
Subject: Re: bug#45438: 27.1; please fix misleading documentation for
 assoc-delete-all
Date: Fri, 25 Dec 2020 23:32:05 +0100

Hendrik Tews <hendrik.tews <at> kernkonzept.com> writes:

> assoc-delete-all was introduced in emacs 26.2, however,
> describe-function says "Probably introduced at or before Emacs
> version 21.1.". Please fix this to report the right version
> number where assoc-delete-all was introduced. With this kind of
> misleading information, it is very difficult to write code that
> is backward compatible to a number of different emacs major
> versions.

Indeed, but Emacs does not have a history of when functions are
introduced -- we only have guesswork.  Which is why it says "probably".

assoc-delete-all has a convoluted history -- it was introduced in 1999,
and then renamed to assq-delete-all, before being reintroduced in 2018
again.  Here the guesser guesses wrong.

Closing.

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

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

From: Richard Stallman <rms <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: hendrik.tews <at> kernkonzept.com, 45438 <at> debbugs.gnu.org
Subject: Re: bug#45438: 27.1;
 please fix misleading documentation for assoc-delete-all
Date: Sat, 26 Dec 2020 05:28:00 -0500

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Indeed, but Emacs does not have a history of when functions are
  > introduced -- we only have guesswork.  Which is why it says "probably".

Every new function is listed in the ChangeLog files.
_We_ know when it was introduced.

What this means

  > > assoc-delete-all was introduced in emacs 26.2, however,
  > > describe-function says "Probably introduced at or before Emacs
  > > version 21.1.".

is that the data that describe-function consults does not have all the
information that we have.

Whether it is worth doing the work to make it better, I have no
opinion.  Maybe it is better to do other work instead.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: larsi <at> gnus.org, hendrik.tews <at> kernkonzept.com, 45438 <at> debbugs.gnu.org
Subject: Re: bug#45438: 27.1;
 please fix misleading documentation for assoc-delete-all
Date: Sat, 26 Dec 2020 12:58:23 +0200

> From: Richard Stallman <rms <at> gnu.org>
> Date: Sat, 26 Dec 2020 05:28:00 -0500
> Cc: hendrik.tews <at> kernkonzept.com, 45438 <at> debbugs.gnu.org
> 
> Every new function is listed in the ChangeLog files.
> _We_ know when it was introduced.
> 
> What this means
> 
>   > > assoc-delete-all was introduced in emacs 26.2, however,
>   > > describe-function says "Probably introduced at or before Emacs
>   > > version 21.1.".
> 
> is that the data that describe-function consults does not have all the
> information that we have.

If the suggestion is to use ChangeLog data for this feature, then I
think it won't be easy, because it isn't easy to parse the ChangeLog
text for gleaning this more accurate information.  For starters, we
sometimes say "New function", sometimes just "New", and sometimes have
lists of functions (all of which are new) with a single "New" entry.

It would be better to have a DB of this data, which we would update
with each major release, than to try to parse ChangeLog files, IMO.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, rms <at> gnu.org
Cc: larsi <at> gnus.org, hendrik.tews <at> kernkonzept.com, 45438 <at> debbugs.gnu.org
Subject: RE: bug#45438: 27.1; please fix misleading documentation for
 assoc-delete-all
Date: Sat, 26 Dec 2020 10:59:47 -0800 (PST)

> It would be better to have a DB of this data, which we would update
> with each major release, than to try to parse ChangeLog files, IMO.

+1.  And a transparent/automatic way to feed both
the DB and the ChangeLog files when making changes.

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

From: Hendrik Tews <hendrik.tews <at> kernkonzept.com>
To: Richard Stallman <rms <at> gnu.org>, Lars Ingebrigtsen <larsi <at> gnus.org>,
 45438 <at> debbugs.gnu.org
Subject: Re: bug#45438: 27.1; please fix misleading documentation for
 assoc-delete-all
Date: Sat, 26 Dec 2020 22:04:00 +0100

Hi,

> Whether it is worth doing the work to make it better, I have no
> opinion.  Maybe it is better to do other work instead.

There is a connection to bug#45437, which see.

I agree that it is questionable to go back in time and annotate
all functions with precise information when they had been added.

However, I believe you should
- change your development process such that, in the future, version
  information for functions and variables is recorded
- not ignorantly closing issues such as 45437, when a couple of
  people spent several hours to debug a problem that takes you
  only 5 minutes to fix. Or how long will it take you to add one
  sentence to the documentation of make-temp-file? Or how many
  hours of other people do you want to waste by saving 5 minutes
  on your side?

I now and then contribute to Proof General, which aims to support
about 3 major emacs version. Please advise how one can develop
backward compatible elisp code when the version in the function
documentation is non-present, plain wrong or misleading.

Best regards,

Hendrik

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

From: Hendrik Tews <hendrik.tews <at> kernkonzept.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, 45438 <at> debbugs.gnu.org
Subject: Re: bug#45438: 27.1; please fix misleading documentation for
 assoc-delete-all
Date: Sat, 26 Dec 2020 22:17:29 +0100

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> assoc-delete-all has a convoluted history -- it was introduced in 1999,

The function introduced in July 1999 by Dave Love compared
elements with eq - it was definitely not assoc-delete-all, even
though it shared the same name for a couple of month.

Hendrik

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: hendrik.tews <at> kernkonzept.com, rms <at> gnu.org, 45438 <at> debbugs.gnu.org
Subject: Re: bug#45438: 27.1; please fix misleading documentation for
 assoc-delete-all
Date: Sat, 26 Dec 2020 22:56:55 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

> It would be better to have a DB of this data, which we would update
> with each major release, than to try to parse ChangeLog files, IMO.

A database would be nice, but I'm against adding yet more formalism in
this area -- it's already a pain getting people to adhere to our current
conventions.

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

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

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, hendrik.tews <at> kernkonzept.com, 45438 <at> debbugs.gnu.org
Subject: Re: bug#45438: 27.1;
 please fix misleading documentation for assoc-delete-all
Date: Sun, 27 Dec 2020 00:38:30 -0500

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > is that the data that describe-function consults does not have all the
  > > information that we have.

  > If the suggestion is to use ChangeLog data for this feature, then I
  > think it won't be easy, because it isn't easy to parse the ChangeLog
  > text for gleaning this more accurate information.

I'm not suggesting we do anything about this problem.  Do you see
any reason to?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: larsi <at> gnus.org, hendrik.tews <at> kernkonzept.com, 45438 <at> debbugs.gnu.org
Subject: Re: bug#45438: 27.1;
 please fix misleading documentation for assoc-delete-all
Date: Sun, 27 Dec 2020 19:47:06 +0200

> From: Richard Stallman <rms <at> gnu.org>
> Cc: larsi <at> gnus.org, hendrik.tews <at> kernkonzept.com,
> 	45438 <at> debbugs.gnu.org
> Date: Sun, 27 Dec 2020 00:38:30 -0500
> 
>   > If the suggestion is to use ChangeLog data for this feature, then I
>   > think it won't be easy, because it isn't easy to parse the ChangeLog
>   > text for gleaning this more accurate information.
> 
> I'm not suggesting we do anything about this problem.  Do you see
> any reason to?

We were asked to consider doing that by 2 different people.  I agree
that the problem is not an urgent one nor a grave one, but if someone
wants to work on making that part of documentation more accurate, I
think gleaning the info from ChangeLog is not the best approach.

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

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, hendrik.tews <at> kernkonzept.com, 45438 <at> debbugs.gnu.org
Subject: Re: bug#45438: 27.1;
 please fix misleading documentation for assoc-delete-all
Date: Mon, 28 Dec 2020 00:25:47 -0500

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > but if someone
  > wants to work on making that part of documentation more accurate, I
  > think gleaning the info from ChangeLog is not the best approach.

I agree.  I never meant to imply that we should try to scrape ChangeLog
for this -- though it might give correct results in most cases.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Previous Next

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