Why does help-fns--first-release not key on `' delimiters?

Why does help-fns--first-release not key on `' delimiters?

[Robin Tarsiger]

So, for some context first:

Recently, I went to check when the tagged record type had been added to
Emacs, and typed C-h f record, only to see:

 > (record TYPE &rest SLOTS)
 >
 >   Probably introduced at or before Emacs version 1.9.

This didn't seem right at all, and unfortunately, the NEWS.1-17 line it
linked to was part of the following paragraph:

 > ** write-kbd-macro and append-kbd-macro are used to save
 >  a kbd macro definition in a file (as Lisp code to
 >  redefine the macro when the file is loaded).
 >  These commands differ in that write-kbd-macro
 >  discards the previous contents of the file.
 >  If given a prefix argument, both commands
 >  record the keys which invoke the macro as well as the
    ^^^^^^
 >  macro's definition.

This is a very silly result. (For the, er, record, the _actual_ NEWS
entry for record types is at NEWS.26:1507, under the section for Lisp
changes in Emacs 26.1.)

Looking at the function help-fns--first-release that generates this
text, it looks like it just searches for the symbol name. However, it
seems to be conventional in these NEWS files for important symbols to
be surrounded by `' pseudo-quotes, just like in e.g. elisp docstrings.

Is there a reason help-fns--first-release doesn't already expect these?
Presumably the matching is best-effort to begin with, and this seems
like it could eliminate a lot of false positives.

It's not costless, of course; one counterexample I saw is that Emacs 17's
section on renaming `dot' to `point' in various symbols doesn't use those
delimiters around each of the indvidual names:

 > ** `dot' renamed `point'.
 >
 > The word `dot' has been replaced with `point' in all
 > function and variable names, including:
 >
 >   point, point-min, point-max,
 >   point-marker, point-min-marker, point-max-marker,
 >   window-point, set-window-point,
 >   point-to-register, register-to-point,
 >   exchange-point-and-mark.
 >
 > The old names are still supported, for now.

but at first glance this seems like an acceptable tradeoff.

Thoughts?

-RTT

Re: Why does help-fns--first-release not key on `' delimiters?

[Stefan Monnier]

FWIW, here's what we should do:

- Require '...' delimiters.
- Fix the etc/NEWS* files accordingly.

Fixing them all is likely to be a lot of work, but we can probably make
this work very tractable in the following way:

- Use a `mapatoms` loop to collect for all the builtin
  functions&variables the position that the current code
  finds in the etc/NEWS* files.

- Change the code to require '...' delimiters and re-run that
  `mapatoms` loop.

- Compare the outputs: whenever they're different, check the
  etc/NEWS* to see where's the "real" position and fix the
  etc/NEWS* so the new code finds it.


        Stefan


Robin Tarsiger [2022-01-06 10:58:35] wrote:

> So, for some context first:
>
> Recently, I went to check when the tagged record type had been added to
> Emacs, and typed C-h f record, only to see:
>
>> (record TYPE &rest SLOTS)
>>
>>   Probably introduced at or before Emacs version 1.9.
>
> This didn't seem right at all, and unfortunately, the NEWS.1-17 line it
> linked to was part of the following paragraph:
>
>> ** write-kbd-macro and append-kbd-macro are used to save
>>  a kbd macro definition in a file (as Lisp code to
>>  redefine the macro when the file is loaded).
>>  These commands differ in that write-kbd-macro
>>  discards the previous contents of the file.
>>  If given a prefix argument, both commands
>>  record the keys which invoke the macro as well as the
>    ^^^^^^
>>  macro's definition.
>
> This is a very silly result. (For the, er, record, the _actual_ NEWS
> entry for record types is at NEWS.26:1507, under the section for Lisp
> changes in Emacs 26.1.)
>
> Looking at the function help-fns--first-release that generates this
> text, it looks like it just searches for the symbol name. However, it
> seems to be conventional in these NEWS files for important symbols to
> be surrounded by `' pseudo-quotes, just like in e.g. elisp docstrings.
>
> Is there a reason help-fns--first-release doesn't already expect these?
> Presumably the matching is best-effort to begin with, and this seems
> like it could eliminate a lot of false positives.
>
> It's not costless, of course; one counterexample I saw is that Emacs 17's
> section on renaming `dot' to `point' in various symbols doesn't use those
> delimiters around each of the indvidual names:
>
>> ** `dot' renamed `point'.
>>
>> The word `dot' has been replaced with `point' in all
>> function and variable names, including:
>>
>>   point, point-min, point-max,
>>   point-marker, point-min-marker, point-max-marker,
>>   window-point, set-window-point,
>>   point-to-register, register-to-point,
>>   exchange-point-and-mark.
>>
>> The old names are still supported, for now.
>
> but at first glance this seems like an acceptable tradeoff.
>
> Thoughts?
>
> -RTT