GNU bug report logs - #25428
25.1; Incorrect doc string for `delete-selection-mode'

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#13926: closed (Re: bug#25428: 25.1; Incorrect doc string for
 `delete-selection-mode')
Date: Sat, 26 Aug 2017 09:04:04 +0000

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

Your bug report

#25428: 24.3.50; doc string of `visual-line-mode'

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 13926 <at> debbugs.gnu.org.

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 25428-done <at> debbugs.gnu.org, nljlistbox2 <at> gmail.com
Subject: Re: bug#25428: 25.1; Incorrect doc string for `delete-selection-mode'
Date: Sat, 26 Aug 2017 12:03:20 +0300

> Date: Wed, 16 Aug 2017 20:25:31 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 25428 <at> debbugs.gnu.org
> 
> Let's just say that the doc string is incomplete and can easily
> mislead.
> 
> If it says anything about interactive behavior (and it should)
> then it should say just what the description of `define-minor-mode'
> says for minor modes.
> 
> If it says anything about the behavior when called from
> Lisp (and it should) then it should say just what the d-m-m
> description says. This (i.e., _all_ of the d-m-m description)
> is missing from the d-s-m doc string:
> 
> * `toggle' toggles
> * non-positive integer disables
> * anything else enables

Thanks, I fixed the doc string to include the missing information.

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.3.50; doc string of `visual-line-mode'
Date: Mon, 11 Mar 2013 13:19:30 -0700

The doc string is misleading wrt the argument when called from Lisp.
 
 With a prefix argument ARG, enable Visual Line mode if ARG is
 positive, and disable it otherwise.  If called from Lisp, enable
 the mode if ARG is omitted or nil.
 
This makes no connection between the interactive prefix arg and the arg
when called from Lisp.  In particular, it can also give the incorrect
impression that the mode is enabled ONLY if ARG is omitted or nil.
There is nothing that suggests the behavior of a non-positive or
positive ARG when called from Lisp.
 
By way of contrast, the doc string of `define-minor-mode' correctly says
what the argument values do when called from Lisp:
 
 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 kind of careful description should probably be added automatically
to functions defined by `define-minor-mode', to prevent misleading doc
wrt the argument.

In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-03-04 on ODIEONE
Bzr revision: 111935 yamaoka <at> jpl.org-20130304102733-4qy111z41qwoh2as
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 

Previous Next

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