bug#51236: 27.2/28 small typos/faq correction?

[Eli Zaretskii]

> From: Ian Nehera <delta29@shaw.ca>
> Date: Sat, 16 Oct 2021 15:01:22 -0700
> Cc: 51236@debbugs.gnu.org
> 
> > On Oct 16, 2021, at 12:46 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> > "Data" is plural, so I think using plural form here is non incorrect.
> 
> It’s not incorrect, it just jumped out to me when I read it. Similar to:
>       - There is no data on the disk.
> as opposed to:
>       - There are no data on the disk.
> "Data is” and “data are" are both technically correct so I guess this
> one's more of a style choice than a typo.

Yes.

> > What would you suggest to update and how?  Both C-y and M-y are
> > mentioned in the manual, and the manual is always more detailed than
> > any other documentation.  Could you state the problem you see with the
> > current text?
> 
> The cross-referenced manual page (Isearch Yanking) doesn’t mention that
> `isearch-yank-pop’ (27.2) can yank text when the previous command wasn’t
> a yank. The only place it gets mentioned is in a comment in the source:
> 
>       ;; Fall back on `isearch-yank-kill' for the benefits of people
>       ;; who are used to the old behavior of `M-y' in isearch mode. In
>       ;; future, this fallback may be changed if we ever change
>       ;; `yank-pop' to do something like the kill-ring-browser.
> 
> A separate function was made for the `kill-ring-browser’ functionality in 28.1
> (isearch-yank-pop) but the old behaviour is still the default 
> (isearch-yank-pop-only).
> If that’s going to be the case long term, there should be a note of it in the 
> manual.
> Maybe something like:
> 
>       …usual ‘M-y’ (‘yank-pop’) command (see Yanking).  [However unlike the 
> usual
>       ‘M-y’, ‘isearch-yank-pop’ will act like ‘C-y’ when the previous command 
> wasn’t
>       a yank. That is, it will yank the most recent kill.]  Clicking 
> ‘mouse-2’ in the…

I see no reason to have those details in the manual.  Many Emacs
commands have some DWIM-ish aspects, and we don't always document all
of them in such detail.

Does anyone else think it's important to have those details in the
manual?