bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Stefan Kangas]

Severity: minor

"<ns-show-prefs>" is displayed instead of "M-x customize" for the
docstring command substitution \\[customize] on macOS (current master
branch).  For example:

    calendar-date-style is a variable defined in ‘calendar.el’.
    [... snip ...]
    Setting this variable directly does not take effect (if the
    calendar package is already loaded).  Rather, use either
    <ns-show-prefs> or the function ‘calendar-set-date-style’.

I have no idea how to press the key "<ns-show-prefs>" - I don't think
there is such a button?  There is also the keybinding "s-," which is
slightly more useful (but not as useful as showing just "M-x
customize", IMHO.)

Please consider showing "s-," or "M-x customize" instead of
"<ns-show-prefs>" here.

Steps to reproduce:
0. emacs -Q
1. C-h v calendar-date-style RET


In GNU Emacs 29.0.50 (build 1, x86_64-apple-darwin17.7.0, NS
appkit-1561.61 Version 10.13.6 (Build 17G14042))
 of 2022-06-01 built on SK-MacBook-Pro
Repository revision: bb20d4f96d1cd309e569a801708987a8a5ebe9d8
Repository branch: master
Windowing system distributor 'Apple', version 10.3.1561
System Description:  Mac OS X 10.13.6

Configured using:
 'configure --with-native-compilation'

Configured features:
ACL GIF GLIB GMP GNUTLS JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY KQUEUE NS PDUMPER PNG RSVG SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS WEBP XIM ZLIB

Important settings:
  value of $LC_CTYPE: UTF-8
  locale-coding-system: utf-8-unix

Major mode: Help

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  isearch-fold-quotes-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  buffer-read-only: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message mailcap yank-media rmc puny
dired dired-loaddefs rfc822 mml mml-sec password-cache epa derived epg
rfc6068 epg-config gnus-util time-date mm-decode mm-bodies mm-encode
mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047
rfc2045 ietf-drums mm-util mail-prsvr mail-utils cus-edit pp cus-start
cus-load wid-edit xref project ring cl-print shortdoc
text-property-search cal-coptic cal-julian cal-move cal-x comp comp-cstr
warnings rx cl-seq cl-macs cl-extra holidays holiday-loaddefs solar
cal-dst cal-menu calendar cal-loaddefs thingatpt help-fns radix-tree
help-mode seq gv subr-x byte-opt bytecomp byte-compile cconv cl-loaddefs
cl-lib iso-transl tooltip eldoc paren electric uniquify ediff-hook
vc-hooks lisp-float-type elisp-mode mwheel term/ns-win ns-win
ucs-normalize mule-util term/common-win 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 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 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 kqueue cocoa ns lcms2 multi-tty make-network-process
native-compile emacs)

Memory information:
((conses 16 130492 8496)
 (symbols 48 9996 0)
 (strings 32 29658 2799)
 (string-bytes 1 937957)
 (vectors 16 20855)
 (vector-slots 8 399291 11781)
 (floats 8 378 57)
 (intervals 56 284 0)
 (buffers 992 13))

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

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

Stefan Kangas <stefan@marxist.se> writes:

> Severity: minor
>
> "<ns-show-prefs>" is displayed instead of "M-x customize" for the
> docstring command substitution \\[customize] on macOS (current master
> branch).  For example:
>
>     calendar-date-style is a variable defined in ‘calendar.el’.
>     [... snip ...]
>     Setting this variable directly does not take effect (if the
>     calendar package is already loaded).  Rather, use either
>     <ns-show-prefs> or the function ‘calendar-set-date-style’.
>
> I have no idea how to press the key "<ns-show-prefs>" - I don't think
> there is such a button?  There is also the keybinding "s-," which is
> slightly more useful (but not as useful as showing just "M-x
> customize", IMHO.)

I think ns-show-prefs means the "Preferences" item in the "Emacs" menu.
That is probably documented in the "Mac / GNUstep Events" node of the
Emacs manual, but if it isn't, I can correct that.

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> I think ns-show-prefs means the "Preferences" item in the "Emacs" menu.
> That is probably documented in the "Mac / GNUstep Events" node of the
> Emacs manual, but if it isn't, I can correct that.

Aha, thanks.  I can't find it in '(emacs) Mac / GNUstep Events' but I
might be missing something.  (Also: The other events there seem to be
missing index entries; maybe we would want to add such entries.)

Adding this event to the manual is useful, but I still think that, for
the purposes of command substitution, it would be better to display an
actual keybinding rather than an event.

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> I have no idea how to press the key "<ns-show-prefs>" - I don't think
> there is such a button?  There is also the keybinding "s-," which is
> slightly more useful (but not as useful as showing just "M-x
> customize", IMHO.)

That is pretty obscure.  Do we have some mechanism for making
`substitute-command-keys' avoid such "keys"?  I vaguely remember a
similar problem with a different event like this showing up in doc
strings...

On the other hand, as Po says -- "<ns-show-prefs>" is an actual key
binding in NS builds, apparently?  So...  Uhm...

> Please consider showing "s-," or "M-x customize" instead of
> "<ns-show-prefs>" here.
>
> Steps to reproduce:
> 0. emacs -Q
> 1. C-h v calendar-date-style RET

I see that the \\=`...' syntax doesn't allow saying \\=`M-x foo' (it has
to be a valid key stroke).  I think it would make sense to allow
explicit M-x commands like this, so I've added this to Emacs 29.

But I've not amended the calendar-date-style doc string, because this
should be fixed in a more general way for `M-x customize', which I'm
sure is in a whole bunch of doc strings.  I'm not sure what the solution
here would be, though.  It would be easy enough to add a block-list
mechanism for `substitute-command-keys', but it seems a bit hacky.

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

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> It would be easy enough to add a block-list
> mechanism for `substitute-command-keys', but it seems a bit hacky.

Does it make sense to just never show any such events with \\[foo]
substitutions?  I think we want "real" keybindings, not events.here.
If only event "keys" are available, I think we should better display
"M-x foo" instead.

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Does it make sense to just never show any such events with \\[foo]
> substitutions?  I think we want "real" keybindings, not events.here.
> If only event "keys" are available, I think we should better display
> "M-x foo" instead.

Ah, yes -- I didn't notice that this was one of those event thingies.  I
thought we already filtered those out somewhere?  I'm pretty sure we had
a similar thing with some other events that was fixed, but I'm blanking
on that now.  Anybody remember?

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

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

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

Stefan Kangas <stefan@marxist.se> writes:

> Aha, thanks.  I can't find it in '(emacs) Mac / GNUstep Events' but I
> might be missing something.  (Also: The other events there seem to be
> missing index entries; maybe we would want to add such entries.)

Done.

> Adding this event to the manual is useful, but I still think that, for
> the purposes of command substitution, it would be better to display an
> actual keybinding rather than an event.

I have no opinion towards that, since I don't actually use Mac OS.

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Po Lu <luangruo@yahoo.com> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> Aha, thanks.  I can't find it in '(emacs) Mac / GNUstep Events' but I
>> might be missing something.  (Also: The other events there seem to be
>> missing index entries; maybe we would want to add such entries.)
>
> Done.
>
>> Adding this event to the manual is useful, but I still think that, for
>> the purposes of command substitution, it would be better to display an
>> actual keybinding rather than an event.
>
> I have no opinion towards that, since I don't actually use Mac OS.

I think it's fine to only update the documentation.  We can expand the
text a bit and say that <ns-open-prefs> is usually sent by the OS when
Emacs is the front process and the user presses `Cmd-,' (comma).  This
is officially documented, at least for macOS
(https://support.apple.com/en-us/HT201236).  Similarly, we already say
that the fonts panel event is sent with `Cmd-t`.

If we had common events indexed in the manuals, users could ask Emacs
about any of them with C-h S, for example.  Improving the
self-documenting features in Emacs is an alternative that I like more
compared to changing the displayed text depending on if there's only
events and no keybindings bound to a function, for example.

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

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

Daniel Martín <mardani29@yahoo.es> writes:

> I think it's fine to only update the documentation.  We can expand the
> text a bit and say that <ns-open-prefs> is usually sent by the OS when
> Emacs is the front process and the user presses `Cmd-,' (comma).  This
> is officially documented, at least for macOS
> (https://support.apple.com/en-us/HT201236).

I did not know that, I only knew about the "Preferences" menu item.  I
guess it should be mentioned in the documentation.

> Similarly, we already say that the fonts panel event is sent with
> `Cmd-t`.

It is?

> If we had common events indexed in the manuals, users could ask Emacs
> about any of them with C-h S, for example.  Improving the
> self-documenting features in Emacs is an alternative that I like more
> compared to changing the displayed text depending on if there's only
> events and no keybindings bound to a function, for example.

I already indexed the NS-specific events.

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Stefan Kangas]

Po Lu <luangruo@yahoo.com> writes:

> Daniel Martín <mardani29@yahoo.es> writes:
>
> > I think it's fine to only update the documentation.  We can expand the
> > text a bit and say that <ns-open-prefs> is usually sent by the OS when
> > Emacs is the front process and the user presses `Cmd-,' (comma).  This
> > is officially documented, at least for macOS
> > (https://support.apple.com/en-us/HT201236).
>
> I did not know that, I only knew about the "Preferences" menu item.  I
> guess it should be mentioned in the documentation.

On my macOS 10.13 machine, `Cmd-,` translates to `s-,' using emacs -Q.

> > Similarly, we already say that the fonts panel event is sent with
> > `Cmd-t`.
>
> It is?

Here, it translates to `s-t'.

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Po Lu via "Bug reports for GNU Emacs, the Swiss army knife of text
editors" <bug-gnu-emacs@gnu.org> writes:

> Daniel Martín <mardani29@yahoo.es> writes:
>
>> I think it's fine to only update the documentation.  We can expand the
>> text a bit and say that <ns-open-prefs> is usually sent by the OS when
>> Emacs is the front process and the user presses `Cmd-,' (comma).  This
>> is officially documented, at least for macOS
>> (https://support.apple.com/en-us/HT201236).
>
> I did not know that, I only knew about the "Preferences" menu item.  I
> guess it should be mentioned in the documentation.
>
>> Similarly, we already say that the fonts panel event is sent with
>> `Cmd-t`.
>
> It is?

Yes, that is true for document apps on macOS (and Emacs is one of them).
You can read the documentation at
https://support.apple.com/en-us/HT201236

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Ah, yes -- I didn't notice that this was one of those event thingies.  I
> thought we already filtered those out somewhere?  I'm pretty sure we had
> a similar thing with some other events that was fixed, but I'm blanking
> on that now.  Anybody remember?

I think I'm just misremembering here.

`where-is-internal' should never return these "synthetic" events (that
are only created to have a way to have Emacs process them in the normal
event loop).  So perhaps we should just mark these symbols with a
special property to make `where-is-internal' ignore them?

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

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> `where-is-internal' should never return these "synthetic" events (that
> are only created to have a way to have Emacs process them in the normal
> event loop).  So perhaps we should just mark these symbols with a
> special property to make `where-is-internal' ignore them?

Sounds good to me.

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

>> `where-is-internal' should never return these "synthetic" events (that
>> are only created to have a way to have Emacs process them in the normal
>> event loop).  So perhaps we should just mark these symbols with a
>> special property to make `where-is-internal' ignore them?
>
> Sounds good to me.

These "keys" are added in places like:

      (when (featurep 'ns)
	(setq system-key-alist
	      (list
	       ;; These are special "keys" used to pass events from C to lisp.
	       (cons  1 'ns-power-off)
	       (cons  2 'ns-open-file)
	       (cons  3 'ns-open-temp-file)
	       (cons  4 'ns-drag-file)
	       (cons  5 'ns-drag-color)
	       (cons  6 'ns-drag-text)
	       (cons  8 'ns-open-file-line)
;;;	       (cons  9 'ns-insert-working-text)
;;;	       (cons 10 'ns-delete-working-text)
	       (cons 11 'ns-spi-service-call)
	       (cons 12 'ns-new-frame)
	       (cons 13 'ns-toggle-toolbar)
	       (cons 14 'ns-show-prefs)
	       ))))

Adding a symbol property like `non-key-event' to these symbols would be
easy enough, but perhaps we should have a bit of infrastructure to make
this easier to do.  Uhm...  Just adding a little helper function here
does the trick, I think.

Now pushed to Emacs 29.

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

bug#55940: macOS: <ns-show-prefs> displayed as keybinding for \\[customize]

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Now pushed to Emacs 29.

Thanks, works great here.