bug#55761: 28.1; improvement on doc string

bug#55761: 28.1; improvement on doc string

[Ikumi Keita]

[-- Attachment #1: Type: text/plain, Size: 627 bytes --]


I'd like to propose the attached patch.

Here is a portion of output of C-h f find-file RET:
,----
| Switch to a buffer visiting file FILENAME,
| [...]
| type M-x next-history-element to pull it into the minibuffer.
| 
| The first time M-x next-history-element is used after Emacs prompts for
| [...]
| current directory to be available on first M-x next-history-element
| request.
`----
The appearances of "M-x next-history-element" don't look nice to me. I
hope the attached patch to be a starting point for revising the doc
strings of `find-file' and its cousins.

Regards,
Ikumi Keita
#StandWithUkraine #StopWarInUkraine


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: tentative porposal for revising doc srings --]
[-- Type: text/x-diff, Size: 1655 bytes --]

diff --git a/lisp/files.el b/lisp/files.el
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -1706,7 +1706,7 @@
 
 (defun find-file (filename &optional wildcards)
   "Edit file FILENAME.
-Switch to a buffer visiting file FILENAME,
+\\<minibuffer-local-map>Switch to a buffer visiting file FILENAME,
 creating one if none already exists.
 Interactively, the default if you just type RET is the current directory,
 but the visited file name is available through the minibuffer history:
@@ -1731,7 +1731,7 @@
 expand wildcards (if any) and visit multiple files.  You can
 suppress wildcard expansion by setting `find-file-wildcards' to nil.
 
-To visit a file without any kind of conversion and without
+\\<global-map>To visit a file without any kind of conversion and without
 automatically choosing a major mode, use \\[find-file-literally]."
   (interactive
    (find-file-read-args "Find file: "
@@ -1747,6 +1747,7 @@
 Like \\[find-file] (which see), but creates a new window or reuses
 an existing one.  See the function `display-buffer'.
 
+\\<minibuffer-local-map>\
 Interactively, the default if you just type RET is the current directory,
 but the visited file name is available through the minibuffer history:
 type \\[next-history-element] to pull it into the minibuffer.
@@ -1779,6 +1780,7 @@
 Like \\[find-file] (which see), but creates a new frame or reuses
 an existing one.  See the function `display-buffer'.
 
+\\<minibuffer-local-map>\
 Interactively, the default if you just type RET is the current directory,
 but the visited file name is available through the minibuffer history:
 type \\[next-history-element] to pull it into the minibuffer.

[-- Attachment #3: Type: text/plain, Size: 5070 bytes --]



In GNU Emacs 28.1 (build 1, x86_64-unknown-freebsd13.0, GTK+ Version 3.24.33, cairo version 1.17.4)
 of 2022-05-10 built on freebsd.vmware
Windowing system distributor 'The X.Org Foundation', version 11.0.12014000
System Description: 13.1-RELEASE

Configured using:
 'configure --with-canna --with-canna-includes=/usr/local/canna/include
--with-canna-libraries=/usr/local/canna/lib --without-xim
--disable-largefile --without-modules --with-sound=yes
--with-file-notification=yes CFLAGS=-O3'

Configured features:
ACL CAIRO DBUS FREETYPE GIF GLIB GNUTLS GSETTINGS HARFBUZZ JPEG JSON
LCMS2 LIBXML2 NOTIFY KQUEUE PDUMPER PNG RSVG SOUND THREADS TIFF
TOOLKIT_SCROLL_BARS X11 XDBE XIM XPM GTK3 ZLIB

Important settings:
  value of $EMACSLOADPATH: /home/keita/elisp:
  value of $LANG: ja_JP.eucJP
  locale-coding-system: japanese-iso-8bit-unix

Major mode: Lisp Interaction

Minor modes in effect:
  global-git-commit-mode: t
  magit-auto-revert-mode: t
  shell-dirtrack-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  show-paren-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t

Load-path shadows:
/home/keita/.emacs.d/elpa/transient-20220406.1156/transient hides /usr/local/share/emacs/28.1/lisp/transient
~/elisp/reftex-parse hides /usr/local/share/emacs/28.1/lisp/textmodes/reftex-parse
/home/keita/.emacs.d/elpa/soap-client-3.2.1/soap-inspect hides /usr/local/share/emacs/28.1/lisp/net/soap-inspect
/home/keita/.emacs.d/elpa/soap-client-3.2.1/soap-client hides /usr/local/share/emacs/28.1/lisp/net/soap-client

Features:
(shadow emacsbug misearch multi-isearch vc-dispatcher vc-hg
bug-reference face-remap magit-submodule magit-obsolete magit-blame
magit-stash magit-reflog magit-bisect magit-push magit-pull magit-fetch
magit-clone magit-remote magit-commit magit-sequence magit-notes
magit-worktree magit-tag magit-merge magit-branch magit-reset
magit-files magit-refs magit-status magit magit-repos magit-apply
magit-wip magit-log magit-diff smerge-mode diff diff-mode git-commit rx
log-edit easy-mmode pcvs-util add-log magit-core magit-autorevert
autorevert filenotify magit-margin magit-transient magit-process
with-editor shell pcomplete comint ring server ansi-color magit-mode
transient cl-extra help-mode magit-git magit-base magit-section
format-spec dash mh-thread mh-identity mh-letter mh-comp sendmail
mh-search smiley qp mm-archive mail-extr mh-mime mh-gnus mh-alias
multi-prompt crm mh-show goto-addr thingatpt gnus-cite gnus-art mm-uu
mml2015 mm-view mml-smime smime dig gnus-sum shr kinsoku svg dom
gnus-group gnus-undo gnus-start gnus-dbus dbus xml gnus-cloud nnimap
nnmail mail-source utf7 netrc nnoo parse-time iso8601 gnus-spec gnus-int
message rmc puny dired dired-loaddefs rfc822 mml mml-sec epa derived epg
rfc6068 epg-config mm-decode mm-bodies mm-encode mail-parse rfc2231
gmm-utils mailheader gnus-win gnus-range gnus nnheader wid-edit mh-seq
mh-inc hl-line mh-tool-bar mh-xface mh-utils mh-folder which-func imenu
gnus-util rmail rmail-loaddefs rfc2047 rfc2045 ietf-drums mm-util
mail-prsvr mail-utils text-property-search time-date mh-scan mh-e
mh-compat mailabbrev mh-buffers mh-loaddefs edmacro kmacro preview-latex
auto-loads tex-site canna-im info package browse-url url url-proxy
url-privacy url-expand url-methods url-history url-cookie url-domsuf
url-util mailcap url-handlers url-parse auth-source cl-seq eieio
eieio-core cl-macs eieio-loaddefs password-cache json subr-x map
url-vars seq byte-opt gv bytecomp byte-compile cconv cl-loaddefs cl-lib
japan-util iso-transl tooltip eldoc paren electric uniquify ediff-hook
vc-hooks lisp-float-type elisp-mode mwheel term/x-win x-win
term/common-win x-dnd tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode lisp-mode prog-mode register
page tab-bar menu-bar rfn-eshadow isearch easymenu timer select
scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors
frame minibuffer cl-generic cham georgian utf-8-lang misc-lang
vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms cp51932
hebrew greek romanian slovak czech european ethiopic indian cyrillic
chinese composite emoji-zwj charscript charprop case-table epa-hook
jka-cmpr-hook help simple abbrev obarray cl-preloaded nadvice button
loaddefs faces cus-face macroexp files window text-properties overlay
sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote threads dbusbind kqueue lcms2
dynamic-setting system-font-setting font-render-setting cairo
move-toolbar gtk x-toolkit x multi-tty make-network-process emacs)

Memory information:
((conses 16 205085 24404)
 (symbols 48 20631 1)
 (strings 32 71045 3014)
 (string-bytes 1 2427748)
 (vectors 16 46873)
 (vector-slots 8 1135485 57410)
 (floats 8 231 166)
 (intervals 56 674 176)
 (buffers 992 18))

bug#55761: 28.1; improvement on doc string

[Lars Ingebrigtsen]

Ikumi Keita <ikumi@ikumi.que.jp> writes:

> I'd like to propose the attached patch.
>
> Here is a portion of output of C-h f find-file RET:
> ,----
> | Switch to a buffer visiting file FILENAME,
> | [...]
> | type M-x next-history-element to pull it into the minibuffer.
> | 
> | The first time M-x next-history-element is used after Emacs prompts for
> | [...]
> | current directory to be available on first M-x next-history-element
> | request.
> `----
> The appearances of "M-x next-history-element" don't look nice to me. I
> hope the attached patch to be a starting point for revising the doc
> strings of `find-file' and its cousins.

Thanks; applied to Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no