GNU bug report logs - #41727
26.3; Doc of `define-minor-mode' and minor-mode commands

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Drew Adams <drew.adams <at> oracle.com>
Subject: bug#41727: closed (Re: bug#41727: 26.3; Doc of `define-minor-mode'
 and minor-mode commands)
Date: Sat, 25 Sep 2021 15:42:03 +0000

[Message part 1 (text/plain, inline)]

Your bug report

#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 41727 <at> debbugs.gnu.org.

-- 
41727: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=41727
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41727-done <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#41727: 26.3;
 Doc of `define-minor-mode' and minor-mode commands
Date: Sat, 25 Sep 2021 08:41:08 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Date: Sat, 6 Jun 2020 09:45:46 -0700 (PDT)
>> From: Drew Adams <drew.adams <at> oracle.com>
>> Cc: 41727 <at> debbugs.gnu.org
>>
>> > > The doc needs improvement when describing calling the mode from Lisp.
>> > >
>> > > 1. The doc string of `define-minor-mode' says this:
>> > >
>> > >      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).
>> >
>> > It actually says this:
>> >   Interactively with no prefix argument, it toggles the mode.
>> >   A prefix argument enables the mode if the argument is positive,
>> >   and disables it otherwise.
>> >
>> >   <snipped: verbatim quote of the text I cited about Lisp call>
>>
>> Yes, and?  The point was about what the doc says about
>> a call from Lisp.
>
> My point was that you take the text out of its context, and that
> context spells out what you say is missing.
>
> This is not the first time you raise this issue, and the argument
> always goes the same way.  I wish you'd stopped these repeated
> complaints about the same thing.
>
>> > Are you reading obsolete docs?
>>
>> I'm reading the 26.3 docs, as suggested by the report:
>
> The latest sources seem to be different.

This bug report is sprawling, and it is very hard to make heads or tails
of what is being discussed.  One initial issue is that the bug report
was made against the text in 26.3, which has changed significantly on
current master.

In any case, Eli seems to be of the opinion that no further change is
needed here.  I tend to agree, and I'm therefore closing this bug
report.

If there are still any outstanding issues, please carefully review the
text that we currently have on master and report any issues separately
based on that.  Otherwise, it will be very hard to make any progress.
Thanks in advance.

[Message part 3 (message/rfc822, inline)]

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.3; Doc of `define-minor-mode' and minor-mode commands
Date: Fri, 5 Jun 2020 13:39:27 -0700 (PDT)

The doc needs improvement when describing calling the mode from Lisp.

1. The doc string of `define-minor-mode' says this:

     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).

   This is wrong (incomplete).  It disables the mode if the
   `prefix-numeric-value' of ARG <= 0, not if ARG is a non-positive
   integer.  The code does this: (prefix-numeric-value arg).  So if you
   pass the symbol `-' as ARG then the mode is disabled.

1. The (default) doc string produced by `define-minor-mode' says this:

     If called from Lisp, enable the mode if ARG is omitted or nil, and
     toggle it if ARG is `toggle'.

   Again, this is wrong (incomplete).  It doesn't say that if ARG is
   non-nil other than `toggle' then disable the mode if the
   `prefix-numeric-value' of ARG <= 0, and enable it if the
   `prefix-numeric-value' of ARG > 0.

3. The Elisp manual doc says this (node `Defining Minor Modes'):

     From Lisp, an argument of 'toggle' toggles the mode, whereas an
     omitted or 'nil' argument enables the mode.

   Again, this is wrong (incomplete).

   * It says nothing about how the mode is disabled when called from
     Lisp.  It should say that an ARG whose `prefix-numeric-value' is
     non-positive disables the mode.

   * It should say that an ARG whose `prefix-numeric-value' is
     non-positive enables the mode.


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

Previous Next

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