bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

[Hendrik Tews]

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

bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

[Lars Ingebrigtsen]

Hendrik Tews <hendrik.tews@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

bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

[Richard Stallman]

[[[ 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)

bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sat, 26 Dec 2020 05:28:00 -0500
> Cc: hendrik.tews@kernkonzept.com, 45438@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.

bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

[Drew Adams]

> 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.

bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

[Hendrik Tews]

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

bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

[Hendrik Tews]

Lars Ingebrigtsen <larsi@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

bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@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

bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

[Richard Stallman]

[[[ 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)

bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: larsi@gnus.org, hendrik.tews@kernkonzept.com,
> 	45438@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.

bug#45438: 27.1; please fix misleading documentation for assoc-delete-all

[Richard Stallman]

[[[ 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)