Eli Zaretskii writes: >> From: Spencer Baugh >> Cc: 77834@debbugs.gnu.org, larsi@gnus.org, philipk@posteo.net, >> azeng@janestreet.com >> Date: Wed, 16 Apr 2025 12:29:26 -0400 >> >> >> -(defun read-string-from-buffer (prompt string) >> >> +(cl-defun read-string-from-buffer (prompt string >> >> + &key major-mode >> >> + read) >> > >> > I don't see any reasons to make this a cl-defun, just to add 2 more >> > optional arguments. >> >> It's to match the existing cl-defun for string-edit. string-edit takes >> keyword arguments - read-string-from-buffer probably should match it. > > But read-string-from-buffer is a public function, so any incompatible > changes in it should be avoided. > >> Alternatively, I could just not change read-string-from-buffer and only >> change string-edit. Then help-fns-edit-variable could call string-edit >> directly. That would duplicate a bit more code though. > > I think this will be better. string-edit is already a cl-defun, so we > just adding new optional arguments to it. OK, reverted the changes to read-string-from-buffer and switched help-fns-edit-variable to call string-edit directly. > But we also need a default for the :read argument if it is omitted. Good catch, done. >> >> "Switch to a new buffer to edit STRING in a recursive edit. >> >> -The user finishes editing with \\\\[string-edit-done], or aborts with \\\\[string-edit-abort]). >> >> + >> >> +When the user finishes editing with `string-edit-done', this function >> > >> > Why did you remove the keymap and command markup? That loses useful >> > features. >> > >> >> +If the user aborts with `string-edit-abort', this function signals an >> >> +error. >> > >> > Same here. >> >> I removed these because neither of these are user-facing functions; the >> docstrings are only read by Lisp hackers writing new packages using >> these functions. And it seems to me that for a Lisp programmer it's >> more useful to know the name of the commands which the user uses to >> finish editing, rather than the bindings for those commands. > > The original text shows both the command name and its binding. > >> But this is not an important change, if you prefer it to have the keymap >> markup instead. > > I'd prefer not to lose the information, indeed. OK, reverted. Also updated the docstrings to not use passive voice.