bug#70163: 29.3; hexl-mode incorrect docstring

bug#70163: 29.3; hexl-mode incorrect docstring

[Thierry Volpiatto]

Hexl-mode docstring specify "\<hexl-mode-map>" in its first line, this
to specify some keybinding related to this map at end, as a result the
documentation command returns a three line string, the first line beeing
a blank line until hexl.el is loaded.  I think docstrings generally
should not have this specification in their first line.

    (defun hexl-mode (&optional arg)
      "\\<hexl-mode-map>A mode for editing binary files in hex dump format.
      [...] 
      Most cursor movement bindings are the same: use \\[hexl-backward-char],
      [...]


In GNU Emacs 29.3 (build 1, x86_64-pc-linux-gnu, X toolkit, cairo
version 1.16.0, Xaw3d scroll bars) of 2024-03-24 built on IPad-S340
Windowing system distributor 'The X.Org Foundation', version 11.0.12101004
System Description: Linux Mint 21.3

Configured using:
 'configure CFLAGS=-O8 --bindir=/usr/local/sbin/emacs-29.1 --with-cairo
--with-x-toolkit=lucid --with-modules --without-tree-sitter
--without-native-compilation'

Configured features:
ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GPM GSETTINGS HARFBUZZ JPEG
JSON LCMS2 LIBOTF LIBSELINUX LIBSYSTEMD LIBXML2 M17N_FLT MODULES NOTIFY
INOTIFY PDUMPER PNG RSVG SECCOMP SOUND THREADS TIFF TOOLKIT_SCROLL_BARS
X11 XAW3D XDBE XIM XINPUT2 XPM LUCID ZLIB

Important settings:
  value of $LANG: fr_FR.UTF-8
  locale-coding-system: utf-8-unix

Major mode: 

Minor modes in effect:
  hexl-follow-ascii: t
  emms-mode-line-mode: t
  emms-playing-time-display-mode: t
  emms-playing-time-mode: t
  bug-reference-prog-mode: t
  server-mode: t
  psession-mode: t
  psession-savehist-mode: t
  register-preview-mode: t
  global-git-gutter-mode: t
  git-gutter-mode: t
  display-time-mode: t
  winner-mode: t
  tv-save-place-mode: t
  helm-epa-mode: t
  helm-descbinds-mode: t
  helm-top-poll-mode: t
  helm-adaptive-mode: t
  helm-mode: t
  helm-minibuffer-history-mode: t
  helm-ff-icon-mode: t
  shell-dirtrack-mode: t
  helm-popup-tip-mode: t
  async-bytecomp-package-mode: t
  dired-async-mode: t
  minibuffer-depth-indicate-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  show-paren-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  column-number-mode: t
  line-number-mode: t
  auto-fill-function: do-auto-fill
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
None found.

Features:
(shadow epa-mail face-remap emacsbug shortdoc hexl helm-command
helm-firefox gnus-async gnus-bcklg gnus-ml disp-table nndraft nnmh
nnfolder network-stream nsm gnus-agent gnus-srvr gnus-score score-mode
nnvirtual nntp gnus-cache helm-elisp helm-eval edebug debug helm-x-files
helm-for-files helm-bookmark helm-info cl-extra gnus-cite smiley
w3m-form w3m-symbol qp w3m doc-view jka-compr timezone w3m-hist
bookmark-w3m w3m-ems w3m-favicon w3m-image w3m-fb tab-line w3m-proc
w3m-util mm-archive mail-extr textsec uni-scripts idna-mapping
ucs-normalize uni-confusable textsec-check addressbook-bookmark
tv-mu4e-config config-w3m mu4e-contrib eshell esh-cmd esh-ext esh-opt
esh-proc esh-io esh-arg esh-module esh-groups esh-util mu4e-patch mu4e
mu4e-org org-config ob-gnuplot org-crypt org-protocol org ob ob-tangle
ob-ref ob-lob ob-table ob-exp org-macro org-src ob-comint org-pcomplete
org-list org-footnote org-faces org-entities ob-emacs-lisp ob-core
ob-eval org-cycle org-table ol org-fold org-fold-core org-keys oc
org-loaddefs org-version org-compat org-macs mu4e-notification
notifications mu4e-main smtpmail mu4e-view mu4e-mime-parts mu4e-headers
mu4e-thread mu4e-actions mu4e-compose gnus-msg gnus-art mm-uu mml2015
mm-view mml-smime smime gnutls dig gnus-sum gnus-group gnus-undo
gnus-start gnus-dbus gnus-cloud nnimap nnmail mail-source utf7 nnoo
gnus-spec gnus-int gnus-range gnus-win gnus nnheader range mu4e-search
mu4e-lists mu4e-bookmarks mu4e-mark mu4e-message shr pixel-fill kinsoku
url-file svg dom flow-fill hl-line mu4e-contacts mu4e-update
mu4e-folders mu4e-context mu4e-query-items mu4e-server mu4e-modeline
mu4e-vars mu4e-helpers mu4e-config mu4e-window bookmark ido message
sendmail puny rfc822 mml mml-sec gnus-util mm-decode mm-bodies mm-encode
mail-parse rfc2231 rfc2047 rfc2045 mm-util ietf-drums mail-prsvr
mailabbrev mail-utils gmm-utils mailheader mu4e-obsolete tramp-cmds
cl-print backtrace find-func tramp-sh epa-file char-fold image-file
image-converter emms-config emms-mpris emms-librefm-stream
emms-librefm-scrobbler emms-playlist-limit emms-i18n emms-history
emms-score emms-stream-info emms-metaplaylist-mode emms-bookmarks
emms-cue emms-mode-line-icon emms-browser sort emms-volume
emms-volume-sndioctl emms-volume-mixerctl emms-volume-pulse
emms-volume-amixer emms-playlist-sort emms-last-played emms-player-xine
emms-player-mpd tq emms-lyrics emms-url emms-streams emms-show-all
emms-tag-editor emms-tag-tracktag emms-mark emms-mode-line emms-cache
emms-info-native emms-info-native-spc emms-info-native-mp3
emms-info-native-ogg emms-info-native-opus emms-info-native-flac
emms-info-native-vorbis bindat emms-info-exiftool emms-info-tinytag
emms-info-metaflac emms-info-opusinfo emms-info-ogginfo
emms-info-mp3info emms-playlist-mode emms-player-vlc emms-player-mpv
emms-playing-time emms-info emms-later-do emms-player-mplayer
emms-player-simple emms-source-playlist emms-source-file locate
emms-setup emms emms-compat emms-auto helm-external helm-net
tramp-archive tramp-gvfs tramp-cache time-stamp zeroconf dbus xml ffap
helm-ls-git vc-git emacs-news-mode vc vc-dispatcher cc-mode cc-fonts
cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine cc-vars cc-defs
sly sly-completion sly-buttons sly-messages sly-common apropos etags
fileloop generator xref arc-mode archive-mode hyperspec add-log
conf-mode yank-media markdown-mode color noutline outline
flymake-shellcheck cus-start flymake-proc flymake project warnings
thingatpt sh-script smie treesit executable diff-mode bug-reference
naquadah-theme view solar cal-dst holidays holiday-loaddefs appt
diary-lib diary-loaddefs cal-menu calendar cal-loaddefs server imenu
psession frameset register-preview pcase git-gutter mule-util
dired-extension time winner describe-variable help-fns radix-tree
help-mode tv-utils tv-save-place.el advice init-helm epa derived epg
rfc6068 epg-config helm-epa helm-descbinds cus-edit pp icons wid-edit
helm-sys popup helm-adaptive helm-mode helm-misc helm-files image-dired
image-dired-tags image-dired-external image-dired-util xdg image-mode
exif filenotify tramp tramp-loaddefs trampver tramp-integration files-x
tramp-compat rx shell pcomplete parse-time iso8601 time-date
helm-buffers all-the-icons all-the-icons-faces data-material
data-weathericons data-octicons data-fileicons data-faicons
data-alltheicons helm-occur helm-tags helm-locate helm-grep wgrep-helm
wgrep grep compile text-property-search comint ansi-osc ring helm-regexp
format-spec ansi-color helm-utils helm-help helm-types
helm-extensions-autoloads helm-autoloads helm helm-global-bindings
helm-easymenu edmacro kmacro helm-core easy-mmode async-bytecomp
helm-source helm-multi-match helm-lib dired-async async dired-aux dired
dired-loaddefs mb-depth avoid cus-load all-the-icons-autoloads
ledger-mode-autoloads markdown-mode-autoloads info sly-autoloads
w3m-load w3m-autoloads yaml-mode-autoloads package browse-url url
url-proxy url-privacy url-expand url-methods url-history url-cookie
generate-lisp-file url-domsuf url-util mailcap url-handlers url-parse
auth-source cl-seq eieio eieio-core cl-macs password-cache json subr-x
map byte-opt gv bytecomp byte-compile url-vars cl-loaddefs cl-lib rmc
iso-transl tooltip cconv 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 nadvice seq simple cl-generic indonesian philippine
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 abbrev obarray oclosure
cl-preloaded button loaddefs theme-loaddefs faces cus-face macroexp
files window text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget keymap hashtable-print-readable backquote
threads dbusbind inotify lcms2 dynamic-setting system-font-setting
font-render-setting cairo x-toolkit xinput2 x multi-tty
make-network-process emacs)

Memory information:
((conses 16 1047939 87992)
 (symbols 48 45461 6)
 (strings 32 290729 21565)
 (string-bytes 1 8633540)
 (vectors 16 116847)
 (vector-slots 8 2373836 49968)
 (floats 8 4939 8125)
 (intervals 56 33276 4050)
 (buffers 976 147))
<#secure method=pgpmime mode=sign>

-- 
Thierry

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Thierry Volpiatto <thievol@posteo.net>
> Date: Wed, 03 Apr 2024 15:02:52 +0000
> 
> 
> Hexl-mode docstring specify "\<hexl-mode-map>" in its first line, this
> to specify some keybinding related to this map at end, as a result the
> documentation command returns a three line string, the first line beeing
> a blank line until hexl.el is loaded.  I think docstrings generally
> should not have this specification in their first line.
> 
>     (defun hexl-mode (&optional arg)
>       "\\<hexl-mode-map>A mode for editing binary files in hex dump format.
>       [...] 
>       Most cursor movement bindings are the same: use \\[hexl-backward-char],
>       [...]

What do you suggest to do instead?

bug#70163: 29.3; hexl-mode incorrect docstring

[Andreas Schwab]

On Apr 03 2024, Eli Zaretskii wrote:

>> From: Thierry Volpiatto <thievol@posteo.net>
>> Date: Wed, 03 Apr 2024 15:02:52 +0000
>> 
>> 
>> Hexl-mode docstring specify "\<hexl-mode-map>" in its first line, this
>> to specify some keybinding related to this map at end, as a result the
>> documentation command returns a three line string, the first line beeing
>> a blank line until hexl.el is loaded.  I think docstrings generally
>> should not have this specification in their first line.
>> 
>>     (defun hexl-mode (&optional arg)
>>       "\\<hexl-mode-map>A mode for editing binary files in hex dump format.
>>       [...] 
>>       Most cursor movement bindings are the same: use \\[hexl-backward-char],
>>       [...]
>
> What do you suggest to do instead?

Customary is to put it directly before the (first) keymap reference.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

bug#70163: 29.3; hexl-mode incorrect docstring

[Thierry Volpiatto]

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

Andreas Schwab <schwab@linux-m68k.org> writes:

> On Apr 03 2024, Eli Zaretskii wrote:
>
>>> From: Thierry Volpiatto <thievol@posteo.net>
>>> Date: Wed, 03 Apr 2024 15:02:52 +0000
>>> 
>>> 
>>> Hexl-mode docstring specify "\<hexl-mode-map>" in its first line, this
>>> to specify some keybinding related to this map at end, as a result the
>>> documentation command returns a three line string, the first line beeing
>>> a blank line until hexl.el is loaded.  I think docstrings generally
>>> should not have this specification in their first line.
>>> 
>>>     (defun hexl-mode (&optional arg)
>>>       "\\<hexl-mode-map>A mode for editing binary files in hex dump format.
>>>       [...] 
>>>       Most cursor movement bindings are the same: use \\[hexl-backward-char],
>>>       [...]
>>
>> What do you suggest to do instead?
>
> Customary is to put it directly before the (first) keymap reference.

Exactly.

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

bug#70163: 29.3; hexl-mode incorrect docstring

[Thierry Volpiatto]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Thierry Volpiatto <thievol@posteo.net>
>> Date: Wed, 03 Apr 2024 15:02:52 +0000
>> 
>> 
>> Hexl-mode docstring specify "\<hexl-mode-map>" in its first line, this
>> to specify some keybinding related to this map at end, as a result the
>> documentation command returns a three line string, the first line beeing
>> a blank line until hexl.el is loaded.  I think docstrings generally
>> should not have this specification in their first line.
>> 
>>     (defun hexl-mode (&optional arg)
>>       "\\<hexl-mode-map>A mode for editing binary files in hex dump format.
>>       [...] 
>>       Most cursor movement bindings are the same: use \\[hexl-backward-char],
>>       [...]
>
> What do you suggest to do instead?

Something like this?

diff --git a/lisp/hexl.el b/lisp/hexl.el
index 1288cf4d7fb..a10c1b35536 100644
--- a/lisp/hexl.el
+++ b/lisp/hexl.el
@@ -256,7 +256,7 @@ as that will override any bit grouping options set here."
 
 ;;;###autoload
 (defun hexl-mode (&optional arg)
-  "\\<hexl-mode-map>A mode for editing binary files in hex dump format.
+  "A mode for editing binary files in hex dump format.
 This is not an ordinary major mode; it alters some aspects
 of the current mode's behavior, but not all; also, you can exit
 Hexl mode and return to the previous mode using `hexl-mode-exit'.
@@ -295,7 +295,7 @@ A sample format:
   000000c0: 7265 6769 6f6e 2e0a                      region..
 
 Movement is as simple as movement in a normal Emacs text buffer.
-Most cursor movement bindings are the same: use \\[hexl-backward-char], \\[hexl-forward-char], \\[hexl-next-line], and \\[hexl-previous-line]
+Most cursor movement bindings are the same: use \\<hexl-mode-map>\\[hexl-backward-char], \\[hexl-forward-char], \\[hexl-next-line], and \\[hexl-previous-line]
 to move the cursor left, right, down, and up.
 
 Advanced cursor movement commands (ala \\[hexl-beginning-of-line], \\[hexl-end-of-line], \\[hexl-beginning-of-buffer], and \\[hexl-end-of-buffer]) are

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Thierry Volpiatto <thievol@posteo.net>
> Cc: Eli Zaretskii <eliz@gnu.org>,  Stefan Monnier
>  <monnier@iro.umontreal.ca>,  70163@debbugs.gnu.org
> Date: Wed, 03 Apr 2024 17:04:04 +0000
> 
> 
> Andreas Schwab <schwab@linux-m68k.org> writes:
> 
> > On Apr 03 2024, Eli Zaretskii wrote:
> >
> >>> From: Thierry Volpiatto <thievol@posteo.net>
> >>> Date: Wed, 03 Apr 2024 15:02:52 +0000
> >>> 
> >>> 
> >>> Hexl-mode docstring specify "\<hexl-mode-map>" in its first line, this
> >>> to specify some keybinding related to this map at end, as a result the
> >>> documentation command returns a three line string, the first line beeing
> >>> a blank line until hexl.el is loaded.  I think docstrings generally
> >>> should not have this specification in their first line.
> >>> 
> >>>     (defun hexl-mode (&optional arg)
> >>>       "\\<hexl-mode-map>A mode for editing binary files in hex dump format.
> >>>       [...] 
> >>>       Most cursor movement bindings are the same: use \\[hexl-backward-char],
> >>>       [...]
> >>
> >> What do you suggest to do instead?
> >
> > Customary is to put it directly before the (first) keymap reference.
> 
> Exactly.

So we don't want an empty line at the beginning of a doc string, but
are okay with having it farther into the doc string?  Any particular
reason why?  Or what am I missing?

bug#70163: 29.3; hexl-mode incorrect docstring

[Thierry Volpiatto]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Thierry Volpiatto <thievol@posteo.net>
>> Cc: Eli Zaretskii <eliz@gnu.org>,  Stefan Monnier
>>  <monnier@iro.umontreal.ca>,  70163@debbugs.gnu.org
>> Date: Wed, 03 Apr 2024 17:04:04 +0000
>> 
>> 
>> Andreas Schwab <schwab@linux-m68k.org> writes:
>> 
>> > On Apr 03 2024, Eli Zaretskii wrote:
>> >
>> >>> From: Thierry Volpiatto <thievol@posteo.net>
>> >>> Date: Wed, 03 Apr 2024 15:02:52 +0000
>> >>> 
>> >>> 
>> >>> Hexl-mode docstring specify "\<hexl-mode-map>" in its first line, this
>> >>> to specify some keybinding related to this map at end, as a result the
>> >>> documentation command returns a three line string, the first line beeing
>> >>> a blank line until hexl.el is loaded.  I think docstrings generally
>> >>> should not have this specification in their first line.
>> >>> 
>> >>>     (defun hexl-mode (&optional arg)
>> >>>       "\\<hexl-mode-map>A mode for editing binary files in hex dump format.
>> >>>       [...] 
>> >>>       Most cursor movement bindings are the same: use \\[hexl-backward-char],
>> >>>       [...]
>> >>
>> >> What do you suggest to do instead?
>> >
>> > Customary is to put it directly before the (first) keymap reference.
>> 
>> Exactly.
>
> So we don't want an empty line at the beginning of a doc string, but
> are okay with having it farther into the doc string?

Yes, this would avoid loading the whole file just for having the first line of
the documentation.

Actually, (documentation 'hexl-mode) returns:

"\nUses keymap `hexl-mode-map', which is not currently defined.\nA mode for editing binary files in hex dump format..."

But once it is loaded:

"A mode for editing binary files in hex dump format..."

I think it is a good practice to specify keymap just when needed as
specified in the manual:

   • In documentation strings for a major mode, you will want to refer
     to the key bindings of that mode’s local map, rather than global
     ones.  Therefore, use the construct ‘\\<...>’ once in the
     documentation string to specify which key map to use.  Do this
     before the first use of ‘\\[...]’.  The text inside the ‘\\<...>’
     should be the name of the variable containing the local keymap for
     the major mode.


-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Thierry Volpiatto <thievol@posteo.net>
> Cc: schwab@linux-m68k.org,  monnier@iro.umontreal.ca,  70163@debbugs.gnu.org
> Date: Thu, 04 Apr 2024 05:47:40 +0000
> 
> >> >>> Hexl-mode docstring specify "\<hexl-mode-map>" in its first line, this
> >> >>> to specify some keybinding related to this map at end, as a result the
> >> >>> documentation command returns a three line string, the first line beeing
> >> >>> a blank line until hexl.el is loaded.  I think docstrings generally
> >> >>> should not have this specification in their first line.
> >> >>> 
> >> >>>     (defun hexl-mode (&optional arg)
> >> >>>       "\\<hexl-mode-map>A mode for editing binary files in hex dump format.
> >> >>>       [...] 
> >> >>>       Most cursor movement bindings are the same: use \\[hexl-backward-char],
> >> >>>       [...]
> >> >>
> >> >> What do you suggest to do instead?
> >> >
> >> > Customary is to put it directly before the (first) keymap reference.
> >> 
> >> Exactly.
> >
> > So we don't want an empty line at the beginning of a doc string, but
> > are okay with having it farther into the doc string?
> 
> Yes, this would avoid loading the whole file just for having the first line of
> the documentation.
> 
> Actually, (documentation 'hexl-mode) returns:
> 
> "\nUses keymap `hexl-mode-map', which is not currently defined.\nA mode for editing binary files in hex dump format..."
> 
> But once it is loaded:
> 
> "A mode for editing binary files in hex dump format..."
> 
> I think it is a good practice to specify keymap just when needed as
> specified in the manual:
> 
>    • In documentation strings for a major mode, you will want to refer
>      to the key bindings of that mode’s local map, rather than global
>      ones.  Therefore, use the construct ‘\\<...>’ once in the
>      documentation string to specify which key map to use.  Do this
>      before the first use of ‘\\[...]’.  The text inside the ‘\\<...>’
>      should be the name of the variable containing the local keymap for
>      the major mode.

Does the patch below gives any better results?  It doesn't look better
to me: the "Uses keymap..." blurb gets in the way and makes the
documentation text wrong.  And it will happen regardless of where you
stuff the \\<..> thing, just in different places of the test.  It
looks like this feature was not meant to be used with libraries that
aren't loaded, or maybe the intent is to use the RAW argument in those
cases.

Stefan, why do we inject this ugly blurb into the text we return when
the library is not loaded? why not simply return the same as RAW does
in those cases?

diff --git a/lisp/hexl.el b/lisp/hexl.el
index 1288cf4..938b218 100644
--- a/lisp/hexl.el
+++ b/lisp/hexl.el
@@ -256,10 +256,10 @@ hexl-line-displen
 
 ;;;###autoload
 (defun hexl-mode (&optional arg)
-  "\\<hexl-mode-map>A mode for editing binary files in hex dump format.
+  "A mode for editing binary files in hex dump format.
 This is not an ordinary major mode; it alters some aspects
 of the current mode's behavior, but not all; also, you can exit
-Hexl mode and return to the previous mode using `hexl-mode-exit'.
+Hexl mode and return to the previous mode using \\<hexl-mode-map>\\[hexl-mode-exit].
 
 This function automatically converts a buffer into the hexl format
 using the function `hexlify-buffer'.

bug#70163: 29.3; hexl-mode incorrect docstring

[Andreas Schwab]

On Apr 04 2024, Eli Zaretskii wrote:

> Does the patch below gives any better results?  It doesn't look better
> to me: the "Uses keymap..." blurb gets in the way and makes the
> documentation text wrong.

C-h f hexl-mode triggers the autoload and uses the substituted doc
string (thus no blurb).  M-x apropos hexl-mode does not trigger the
autoload and uses the substituted first line of the doc string
(including the blurb if present).  C-h a hexl-mode uses the first line
of the raw doc string.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

bug#70163: 29.3; hexl-mode incorrect docstring

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> Stefan, why do we inject this ugly blurb into the text we return when
> the library is not loaded? why not simply return the same as RAW does
> in those cases?

Good question.  AFAIK this predates me, so we'd have to ask Richard.
Maybe \<hexl-mode-map> should simply never expand to anything else than the
empty string.


        Stefan

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: Thierry Volpiatto <thievol@posteo.net>,  monnier@iro.umontreal.ca,
>   70163@debbugs.gnu.org
> Date: Thu, 04 Apr 2024 14:45:14 +0200
> 
> On Apr 04 2024, Eli Zaretskii wrote:
> 
> > Does the patch below gives any better results?  It doesn't look better
> > to me: the "Uses keymap..." blurb gets in the way and makes the
> > documentation text wrong.
> 
> C-h f hexl-mode triggers the autoload and uses the substituted doc
> string (thus no blurb).  M-x apropos hexl-mode does not trigger the
> autoload and uses the substituted first line of the doc string
> (including the blurb if present).  C-h a hexl-mode uses the first line
> of the raw doc string.

Thanks, but I thought the complaint was about what the 'documentation'
function returns.  That doesn't change much depending on where the
\\<..> thing is.  Help commands that only show the first line will, of
course, depend on where we have the \\<..> thing.

bug#70163: 29.3; hexl-mode incorrect docstring

[Andreas Schwab]

On Apr 04 2024, Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" wrote:

> Maybe \<hexl-mode-map> should simply never expand to anything else than the
> empty string.

That would hide typos.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

bug#70163: 29.3; hexl-mode incorrect docstring

[Andreas Schwab]

On Apr 04 2024, Eli Zaretskii wrote:

>> From: Andreas Schwab <schwab@linux-m68k.org>
>> Cc: Thierry Volpiatto <thievol@posteo.net>,  monnier@iro.umontreal.ca,
>>   70163@debbugs.gnu.org
>> Date: Thu, 04 Apr 2024 14:45:14 +0200
>> 
>> On Apr 04 2024, Eli Zaretskii wrote:
>> 
>> > Does the patch below gives any better results?  It doesn't look better
>> > to me: the "Uses keymap..." blurb gets in the way and makes the
>> > documentation text wrong.
>> 
>> C-h f hexl-mode triggers the autoload and uses the substituted doc
>> string (thus no blurb).  M-x apropos hexl-mode does not trigger the
>> autoload and uses the substituted first line of the doc string
>> (including the blurb if present).  C-h a hexl-mode uses the first line
>> of the raw doc string.
>
> Thanks, but I thought the complaint was about what the 'documentation'
> function returns.

That's exactly what I have described.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Thierry Volpiatto <thievol@posteo.net>,  schwab@linux-m68k.org,
>   70163@debbugs.gnu.org
> Date: Thu, 04 Apr 2024 08:54:24 -0400
> 
> > Stefan, why do we inject this ugly blurb into the text we return when
> > the library is not loaded? why not simply return the same as RAW does
> > in those cases?
> 
> Good question.  AFAIK this predates me, so we'd have to ask Richard.
> Maybe \<hexl-mode-map> should simply never expand to anything else than the
> empty string.

Maybe.  But meanwhile, the best I can suggest is this:

diff --git a/lisp/hexl.el b/lisp/hexl.el
index 1288cf4..28441a2 100644
--- a/lisp/hexl.el
+++ b/lisp/hexl.el
@@ -256,10 +256,10 @@ hexl-line-displen
 
 ;;;###autoload
 (defun hexl-mode (&optional arg)
-  "\\<hexl-mode-map>A mode for editing binary files in hex dump format.
-This is not an ordinary major mode; it alters some aspects
+  "A mode for editing binary files in hex dump format.
+\\<hexl-mode-map>This is not an ordinary major mode; it alters some aspects
 of the current mode's behavior, but not all; also, you can exit
-Hexl mode and return to the previous mode using `hexl-mode-exit'.
+Hexl mode and return to the previous mode using \\[hexl-mode-exit].
 
 This function automatically converts a buffer into the hexl format
 using the function `hexlify-buffer'.

bug#70163: 29.3; hexl-mode incorrect docstring

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> Maybe.  But meanwhile, the best I can suggest is this:

LGTM,


        Stefan

bug#70163: 29.3; hexl-mode incorrect docstring

[Thierry Volpiatto]

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

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Maybe.  But meanwhile, the best I can suggest is this:
>
> LGTM,

Seems good to me as well.

>
>         Stefan

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Thierry Volpiatto <thievol@posteo.net>
> Cc: Eli Zaretskii <eliz@gnu.org>,  schwab@linux-m68k.org,
>   70163@debbugs.gnu.org
> Date: Thu, 04 Apr 2024 18:41:03 +0000
> 
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
> 
> >> Maybe.  But meanwhile, the best I can suggest is this:
> >
> > LGTM,
> 
> Seems good to me as well.

Thanks, installed on master, and closing the bug.

bug#70163: 29.3; hexl-mode incorrect docstring

[Thierry Volpiatto]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Thierry Volpiatto <thievol@posteo.net>
>> Cc: Eli Zaretskii <eliz@gnu.org>,  schwab@linux-m68k.org,
>>   70163@debbugs.gnu.org
>> Date: Thu, 04 Apr 2024 18:41:03 +0000
>> 
>> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> 
>> >> Maybe.  But meanwhile, the best I can suggest is this:
>> >
>> > LGTM,
>> 
>> Seems good to me as well.
>
> Thanks, installed on master, and closing the bug.

Thanks, here some more places:

edmacro-mode                       => edmacro.el
Info-mouse-follow-nearest-node     => info.el
org-use-fast-todo-selection        => org.el
org-babel-no-eval-on-ctrl-c-ctrl-c => ob-core.el

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Thierry Volpiatto <thievol@posteo.net>
> Cc: monnier@iro.umontreal.ca,  schwab@linux-m68k.org,
>   70163-done@debbugs.gnu.org
> Date: Fri, 05 Apr 2024 06:29:49 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Thanks, installed on master, and closing the bug.
> 
> Thanks, here some more places:
> 
> edmacro-mode                       => edmacro.el
> Info-mouse-follow-nearest-node     => info.el
> org-use-fast-todo-selection        => org.el
> org-babel-no-eval-on-ctrl-c-ctrl-c => ob-core.el

I fixed the first two, but IMO they are not really relevant to this
bug: the functions are not autoloaded, so you don't see that "Uses a
keymap..." blurb.

As for the other two: they are in Org, so I leave it to the Org
developers to DTRT.

bug#70163: 29.3; hexl-mode incorrect docstring

[Thierry Volpiatto]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Thierry Volpiatto <thievol@posteo.net>
>> Cc: monnier@iro.umontreal.ca,  schwab@linux-m68k.org,
>>   70163-done@debbugs.gnu.org
>> Date: Fri, 05 Apr 2024 06:29:49 +0000
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> > Thanks, installed on master, and closing the bug.
>> 
>> Thanks, here some more places:
>> 
>> edmacro-mode                       => edmacro.el
>> Info-mouse-follow-nearest-node     => info.el
>> org-use-fast-todo-selection        => org.el
>> org-babel-no-eval-on-ctrl-c-ctrl-c => ob-core.el
>
> I fixed the first two, but IMO they are not really relevant to this
> bug: the functions are not autoloaded, so you don't see that "Uses a
> keymap..." blurb.

Sure, but it is much cleaner like this, thanks.

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

bug#70163: 29.3; hexl-mode incorrect docstring

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> Thanks, here some more places:
>>  ...
>> org-use-fast-todo-selection        => org.el
>> org-babel-no-eval-on-ctrl-c-ctrl-c => ob-core.el
>
> I fixed the first two, but IMO they are not really relevant to this
> bug: the functions are not autoloaded, so you don't see that "Uses a
> keymap..." blurb.
>
> As for the other two: they are in Org, so I leave it to the Org
> developers to DTRT.

`org-use-fast-todo-selection' and `org-babel-no-eval-on-ctrl-c-ctrl-c'
are also not autoloaded.

And I do not see how to use the proposed approach to them - they both
use \[...] in the first line of the docstring:

(defcustom org-babel-no-eval-on-ctrl-c-ctrl-c nil
  "\\<org-mode-map>\
Remove code block evaluation from the `\\[org-ctrl-c-ctrl-c]' key binding."

(defcustom org-use-fast-todo-selection 'auto
  "\\<org-mode-map>\
Non-nil means use the fast todo selection scheme with `\\[org-todo]'.

Moving \<org-mode-map> to the second line is thus not an option.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

bug#70163: 29.3; hexl-mode incorrect docstring

[Andreas Schwab]

On Apr 06 2024, Ihor Radchenko wrote:

> And I do not see how to use the proposed approach to them - they both
> use \[...] in the first line of the docstring:
>
> (defcustom org-babel-no-eval-on-ctrl-c-ctrl-c nil
>   "\\<org-mode-map>\
> Remove code block evaluation from the `\\[org-ctrl-c-ctrl-c]' key binding."
>
> (defcustom org-use-fast-todo-selection 'auto
>   "\\<org-mode-map>\
> Non-nil means use the fast todo selection scheme with `\\[org-todo]'.

(defcustom org-babel-no-eval-on-ctrl-c-ctrl-c nil
  "Remove code block evaluation from the \\<org-mode-map>`\\[org-ctrl-c-ctrl-c]' key binding."

(defcustom org-use-fast-todo-selection 'auto
  "Non-nil means use the fast todo selection scheme with \\<org-mode-map>`\\[org-todo]'.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  Thierry Volpiatto <thievol@posteo.net>,
>   monnier@iro.umontreal.ca,  70163@debbugs.gnu.org
> Date: Sat, 06 Apr 2024 16:05:47 +0200
> 
> On Apr 06 2024, Ihor Radchenko wrote:
> 
> > And I do not see how to use the proposed approach to them - they both
> > use \[...] in the first line of the docstring:
> >
> > (defcustom org-babel-no-eval-on-ctrl-c-ctrl-c nil
> >   "\\<org-mode-map>\
> > Remove code block evaluation from the `\\[org-ctrl-c-ctrl-c]' key binding."
> >
> > (defcustom org-use-fast-todo-selection 'auto
> >   "\\<org-mode-map>\
> > Non-nil means use the fast todo selection scheme with `\\[org-todo]'.
> 
> (defcustom org-babel-no-eval-on-ctrl-c-ctrl-c nil
>   "Remove code block evaluation from the \\<org-mode-map>`\\[org-ctrl-c-ctrl-c]' key binding."
> 
> (defcustom org-use-fast-todo-selection 'auto
>   "Non-nil means use the fast todo selection scheme with \\<org-mode-map>`\\[org-todo]'.

The reference to the map should not be in the middle of a sentence.

bug#70163: 29.3; hexl-mode incorrect docstring

[Andreas Schwab]

On Apr 06 2024, Eli Zaretskii wrote:

> The reference to the map should not be in the middle of a sentence.

Why?  It's just a marker.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Cc: yantar92@posteo.net,  thievol@posteo.net,  monnier@iro.umontreal.ca,
>   70163@debbugs.gnu.org
> Date: Sat, 06 Apr 2024 17:05:18 +0200
> 
> On Apr 06 2024, Eli Zaretskii wrote:
> 
> > The reference to the map should not be in the middle of a sentence.
> 
> Why?  It's just a marker.

Because when it's expanded, it produces a complete sentence.

bug#70163: 29.3; hexl-mode incorrect docstring

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> Thanks, here some more places:
>
> edmacro-mode                       => edmacro.el
> Info-mouse-follow-nearest-node     => info.el
> org-use-fast-todo-selection        => org.el
> org-babel-no-eval-on-ctrl-c-ctrl-c => ob-core.el

Maybe the better fix is to change \<...> so that the extra "\n...\n"
sentence gets added at a more appropriate place rather thn right where
the \<...> was encountered.


        Stefan

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Eli Zaretskii <eliz@gnu.org>,  schwab@linux-m68k.org,
>   70163@debbugs.gnu.org
> Date: Sat, 06 Apr 2024 11:49:26 -0400
> 
> > Thanks, here some more places:
> >
> > edmacro-mode                       => edmacro.el
> > Info-mouse-follow-nearest-node     => info.el
> > org-use-fast-todo-selection        => org.el
> > org-babel-no-eval-on-ctrl-c-ctrl-c => ob-core.el
> 
> Maybe the better fix is to change \<...> so that the extra "\n...\n"
> sentence gets added at a more appropriate place rather thn right where
> the \<...> was encountered.

What is "the more appropriate place", and how will you find it, given
that some doc strings are auto-generated, either in part or in full?

bug#70163: 29.3; hexl-mode incorrect docstring

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> What is "the more appropriate place", and how will you find it, given
> that some doc strings are auto-generated, either in part or in full?

Right after the next \n ?


        Stefan

bug#70163: 29.3; hexl-mode incorrect docstring

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> What is "the more appropriate place", and how will you find it, given
>> that some doc strings are auto-generated, either in part or in full?
> Right after the next \n ?

As in the patch below.


        Stefan


diff --git a/lisp/help.el b/lisp/help.el
index 1ef46e394f3..c2a278bc0a0 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1380,6 +1380,7 @@ substitute-command-keys
     ;; itself.
     (let ((keymap overriding-local-map)
           (inhibit-modification-hooks t)
+          (delayed ())
           (orig-buf (current-buffer)))
       (with-temp-buffer
         (insert string)
@@ -1496,11 +1497,17 @@ substitute-command-keys
                                              (symbol-value name)))))
                   (cond
                    ((null this-keymap)
-                    (insert "\nUses keymap "
-                            (substitute-quotes "`")
-                            (symbol-name name)
-                            (substitute-quotes "'")
-                            ", which is not currently defined.\n")
+                    ;; Insert a warning on the next line (bug#70163).
+                    (let ((pos (copy-marker (line-beginning-position 2))))
+                      (push (lambda ()
+                              (goto-char pos)
+                              (unless (bolp) (insert "\n"))
+                              (insert "Uses keymap "
+                                      (substitute-quotes "`")
+                                      (symbol-name name)
+                                      (substitute-quotes "'")
+                                      ", which is not currently defined.\n"))
+                            delayed))
                     (unless generate-summary
                       (setq keymap nil)))
                    ((not generate-summary)
@@ -1527,6 +1534,7 @@ substitute-command-keys
               (delete-char 1))
              ;; 3. Nothing to do -- next character.
              (t (forward-char 1)))))
+        (mapc #'funcall delayed)
         (buffer-string)))))
 
 (defun substitute-quotes (string)

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: thievol@posteo.net,  schwab@linux-m68k.org,  70163@debbugs.gnu.org
> Date: Sat, 06 Apr 2024 16:01:49 -0400
> 
> > What is "the more appropriate place", and how will you find it, given
> > that some doc strings are auto-generated, either in part or in full?
> 
> Right after the next \n ?

That could be in the middle of a sentence.

bug#70163: 29.3; hexl-mode incorrect docstring

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> > What is "the more appropriate place", and how will you find it, given
>> > that some doc strings are auto-generated, either in part or in full?
>> Right after the next \n ?
> That could be in the middle of a sentence.

Then insert at point if (and (bolp) (not (bobp)))?


        Stefan

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: thievol@posteo.net,  schwab@linux-m68k.org,  70163@debbugs.gnu.org
> Date: Sun, 07 Apr 2024 10:48:11 -0400
> 
> >> > What is "the more appropriate place", and how will you find it, given
> >> > that some doc strings are auto-generated, either in part or in full?
> >> Right after the next \n ?
> > That could be in the middle of a sentence.
> 
> Then insert at point if (and (bolp) (not (bobp)))?

But that again could be in the middle of a sentence.

Shouldn't we look for the end of the sentence, and insert after that
instead?  Or what am I missing?

bug#70163: 29.3; hexl-mode incorrect docstring

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> >> > What is "the more appropriate place", and how will you find it, given
>> >> > that some doc strings are auto-generated, either in part or in full?
>> >> Right after the next \n ?
>> > That could be in the middle of a sentence.
>> Then insert at point if (and (bolp) (not (bobp)))?
> But that again could be in the middle of a sentence.

It could.

> Shouldn't we look for the end of the sentence, and insert after that
> instead?  Or what am I missing?

I don't believe in the ability of machines to find the end of
a sentence. 🙂


        Stefan

bug#70163: 29.3; hexl-mode incorrect docstring

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: thievol@posteo.net,  schwab@linux-m68k.org,  70163@debbugs.gnu.org
> Date: Sun, 07 Apr 2024 12:07:42 -0400
> 
> >> >> > What is "the more appropriate place", and how will you find it, given
> >> >> > that some doc strings are auto-generated, either in part or in full?
> >> >> Right after the next \n ?
> >> > That could be in the middle of a sentence.
> >> Then insert at point if (and (bolp) (not (bobp)))?
> > But that again could be in the middle of a sentence.
> 
> It could.
> 
> > Shouldn't we look for the end of the sentence, and insert after that
> > instead?  Or what am I missing?
> 
> I don't believe in the ability of machines to find the end of
> a sentence. 🙂

Then maybe we shouldn't try to be too smart here?  I already added to
Tips the recommendation to have this not in the middle of a sentence,
so maybe we should leave the rest to the programmer?