bug#63399: 28.2; Documentation for yes-or-no-p wrong/different between docstring and lispref

[Tim Landscheidt]

The documentation for yes-or-no-p in Emacs 28.2 reads:

| yes-or-no-p is a built-in function in ‘C source code’.

| (yes-or-no-p PROMPT)

| Ask user a yes-or-no question.
| Return t if answer is yes, and nil if the answer is no.

| PROMPT is the string to display to ask the question; ‘yes-or-no-p’
| adds "(yes or no) " to it.  It does not need to end in space, but if
| it does up to one space will be removed.

| […]

This is wrong: (yes-or-no-p "Prompt? ") gives the prompt
"Prompt? (yes or no) ", but according to the docstring it
should be "Prompt?(yes or no) ".

With the big caveat that I have never looked deeper at
Emacs's C code, the source in src/fns.c does not appear to
change the prompt given as an argument in any way, but just
append yes-or-no-prompt to it.

Also, (elisp) Yes-or-No Queries reads (since 7f53446a10ea;
doc/lispref/minibuf.texi):

| […]

|      Here is an example:

|           (yes-or-no-p "Do you really want to remove everything?")

|           ;; After evaluation of the preceding expression,
|           ;;   the following prompt appears,
|           ;;   with an empty minibuffer:

|           ---------- Buffer: minibuffer ----------
|           Do you really want to remove everything? (yes or no)
|           ---------- Buffer: minibuffer ----------

| […]

This is not the actual result: (yes-or-no-p "Do you really
want to remove everything?") gives the prompt "Do you really
want to remove everything?(yes or no) ", i. e., the space
before the parenthesis is missing.

Finally, the behaviour is different when using
use-short-answers:

| (yes-or-no-p "Prompt?")

gives "Prompt?(yes or no) ", while:

| (let ((use-short-answers t)) (yes-or-no-p "Prompt?"))

gives "Prompt? (y or n) ".