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: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41727 <at> debbugs.gnu.org
Subject: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands
Date: Sat, 6 Jun 2020 09:45:46 -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).
> 
> 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.

> > 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.
> 
> It actually says this:
>      The toggle command takes one optional (prefix) argument.  If called
>      interactively with no argument it toggles the mode on or off.  A
>      positive prefix argument enables the mode, any other prefix
>      argument disables it.
>
>      <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.

The bug report doesn't find fault with the description of
the interactive behavior.

And my follow-up message suggests text for the doc string
that I think is accurate and complete, and it improves the
description of the interactive handling as well.

The bug report is about the content/message/info, though,
not the wording.  If you don't like the wording of my
suggestion, some other wording that provides as accurate
and complete a description will be fine.  Thx.

> Are you reading obsolete docs?

I'm reading the 26.3 docs, as suggested by the report:

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.