GNU bug report logs - #49843
28.0.50; Error in docstring after using define-globalized-minor-mode

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 49843 in the body.
You can then email your comments to 49843 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: dalanicolai <at> gmail.com
To: bug-gnu-emacs <at> gnu.org
Subject: 28.0.50; Error in docstring after using define-globalized-minor-mode
Date: Tue, 03 Aug 2021 06:51:35 +0200

When creating a global minor mode using `define-globalized-minor-mode',
some explanation in the default created docstring for the new global
minor mode reads (e.g. for `global-display-fill-column-indicator-mode')
:

"With prefix ARG, enable Global Display-Fill-Column-Indicator mode if
ARG is positive; otherwise, disable it.  If called from Lisp, enable
the mode if ARG is omitted or nil."

So it says that, when called from lisp, the mode is not enabled if any
ARG except nil is passed.

It is easy to verify that that statement is wrong by evaluating
(global-display-fill-column-indicator-mode
'with-any-non-negative-number-argument) directly after starting emacs
with -Q flag. Also the argument 'toggle can be uses for toggling it.

It looks like the docstring could just copy the explanation about
behavior when calling from lisp from the `define-minor-mode'
docstring. (I am not sure if the `define-globalized-minor-mode' macro
adds any logic for the behavior for (de)activating the global
mode; I think it only adds logic for the behavior i.c.w. its non-global
mode, for which the explanation is not clear to me also b.t.w., but I
am
still trying to track down how that behaves exactly).


In GNU Emacs 28.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
3.24.25, cairo version 1.16.0)
 of 2021-02-18 built on daniel-fedora
Repository revision: 185121da6978553d538d37d6d0e67dc52e13311f
Repository branch: feature/native-comp
Windowing system distributor 'The X.Org Foundation', version
11.0.12011000
System Description: Fedora 34 (Workstation Edition)

Configured using:
 'configure --with-nativecomp'

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

Important settings:
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: @im=none
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  global-display-fill-column-indicator-mode: t
  display-fill-column-indicator-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  electric-indent-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
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message rmc puny dired dired-loaddefs
rfc822 mml mml-sec epa derived epg epg-config gnus-util rmail
rmail-loaddefs auth-source cl-seq eieio eieio-core eieio-loaddefs
password-cache json map cl-macs text-property-search mm-decode mm-
bodies
mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail
rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils pp easy-mmode
display-fill-column-indicator time-date subr-x cl-extra seq byte-opt gv
bytecomp byte-compile cconv cl-print hl-line thingatpt help-fns
radix-tree help-mode easymenu cl-loaddefs cl-lib iso-transl tooltip
eldoc electric uniquify ediff-hook vc-hooks lisp-float-type 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 elisp-
mode
lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow isearch
timer select scroll-bar mouse jit-lock font-lock syntax facemenu
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 charscript charprop
case-table epa-hook jka-cmpr-hook help simple abbrev obarray
cl-preloaded nadvice button loaddefs faces cus-face pcase macroexp
files
window text-properties overlay sha1 md5 base64 format env code-pages
mule custom widget hashtable-print-readable backquote threads dbusbind
inotify lcms2 dynamic-setting system-font-setting font-render-setting
cairo move-toolbar gtk x-toolkit x multi-tty make-network-process
nativecomp emacs)

Memory information:
((conses 16 80391 7027)
 (symbols 48 7063 0)
 (strings 32 22435 1869)
 (string-bytes 1 727500)
 (vectors 16 13456)
 (vector-slots 8 294714 10744)
 (floats 8 35 31)
 (intervals 56 239 0)
 (buffers 992 12))

Message #8 received at 49843 <at> debbugs.gnu.org (full text, mbox):

From: Phil Sainty <psainty <at> orcon.net.nz>
To: dalanicolai <at> gmail.com
Cc: 49843 <at> debbugs.gnu.org
Subject: Re: bug#49843: 28.0.50; Error in docstring after using
 define-globalized-minor-mode
Date: Tue, 03 Aug 2021 20:37:50 +1200

On 2021-08-03 16:51, dalanicolai <at> gmail.com wrote:
> It looks like the docstring could just copy the explanation about
> behavior when calling from lisp from the `define-minor-mode'
> docstring.

I would use the more succinct explanation that `define-minor-mode'
generates (by default) for the docstring of the mode being defined.
E.g.:

"If called interactively, enable Eldoc mode if ARG is positive, and
disable it if ARG is zero or negative.  If called from Lisp, also
enable the mode if ARG is omitted or nil, and toggle it if ARG is
`toggle'; disable the mode otherwise."

This comes from the format variable `easy-mmode--arg-docstring'.


> (I am not sure if the `define-globalized-minor-mode' macro
> adds any logic for the behavior for (de)activating the global
> mode.

`define-globalized-minor-mode' uses `define-minor-mode' to define
the global mode, so there's no unusual behaviour.


> I think it only adds logic for the behavior i.c.w. its non-global
> mode, for which the explanation is not clear to me also b.t.w., but
> I am still trying to track down how that behaves exactly).

Which aspects are you unsure of?

Message #11 received at 49843 <at> debbugs.gnu.org (full text, mbox):

From: Phil Sainty <psainty <at> orcon.net.nz>
To: dalanicolai <at> gmail.com
Cc: 49843 <at> debbugs.gnu.org
Subject: Re: bug#49843: 28.0.50; Error in docstring after using
 define-globalized-minor-mode
Date: Tue, 03 Aug 2021 21:18:18 +1200

In fact I was looking in Emacs 27, and it's all changed in 28,
so apologies for my confusion.  We actually now have this template:

(defconst easy-mmode--arg-docstring
  "

This is a minor mode.  If called interactively, toggle the `%s'
mode.  If the prefix argument is positive, enable the mode, and
if it is zero or negative, disable the mode.

If called from Lisp, toggle the mode if ARG is `toggle'.
Enable the mode if ARG is nil, omitted, or is a positive number.
Disable the mode if ARG is a negative number.

To check whether the minor mode is enabled in the current buffer,
evaluate `%S'.

The mode's hook is called both when the mode is enabled and when
it is disabled.")


That description still doesn't specify what happens with other
values, and I realise you're saying that the docstring of
`define-minor-mode' itself has a different, more comprehensive
explanation:

"When called from Lisp, the mode command toggles the mode if the
argument is `toggle', disables the mode if the argument is a
non-positive integer, and enables the mode otherwise (including
if the argument is omitted or nil or a positive integer)."

https://debbugs.gnu.org/cgi/bugreport.cgi?bug=44341 is related.

I notice the commit message for 5cea77af41b59ba6f6386264812c36ec31ba2efc
says:

    * lisp/emacs-lisp/easy-mmode.el (easy-mmode--arg-docstring):
    Only document the values we want to support, not the ones we
    actually support.

So the failure to say what happens if you pass something other
than an integer or 'toggle seems intentional, as other kinds of
argument shouldn't ever be used.

I expect that globalized modes should also use the text of the
`easy-mmode--arg-docstring' template.

Message #14 received at 49843 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Phil Sainty <psainty <at> orcon.net.nz>
Cc: dalanicolai <at> gmail.com, 49843 <at> debbugs.gnu.org
Subject: Re: bug#49843: 28.0.50; Error in docstring after using
 define-globalized-minor-mode
Date: Wed, 04 Aug 2021 09:38:55 +0200

Phil Sainty <psainty <at> orcon.net.nz> writes:

> I expect that globalized modes should also use the text of the
> `easy-mmode--arg-docstring' template.

Yup.  Now done in Emacs 28.

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.