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