From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: nljlistbox2@gmail.com (N. Jackson) Newsgroups: gmane.emacs.bugs Subject: bug#25428: 25.1; Incorrect doc string for `delete-selection-mode' Date: Wed, 16 Aug 2017 21:55:09 -0400 Message-ID: <87efsbrm9u.fsf@moondust.localdomain> References: NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1502934978 9589 195.159.176.226 (17 Aug 2017 01:56:18 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 17 Aug 2017 01:56:18 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.2 (gnu/linux) Cc: 25428@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Aug 17 03:56:13 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1diA2Y-0001nh-5B for geb-bug-gnu-emacs@m.gmane.org; Thu, 17 Aug 2017 03:56:06 +0200 Original-Received: from localhost ([::1]:44820 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1diA2e-0005zd-OV for geb-bug-gnu-emacs@m.gmane.org; Wed, 16 Aug 2017 21:56:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:33741) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1diA2X-0005yu-RS for bug-gnu-emacs@gnu.org; Wed, 16 Aug 2017 21:56:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1diA2U-0002Yn-OA for bug-gnu-emacs@gnu.org; Wed, 16 Aug 2017 21:56:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:33079) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1diA2U-0002YN-J5 for bug-gnu-emacs@gnu.org; Wed, 16 Aug 2017 21:56:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1diA2U-0002hu-39 for bug-gnu-emacs@gnu.org; Wed, 16 Aug 2017 21:56:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: nljlistbox2@gmail.com (N. Jackson) Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 17 Aug 2017 01:56:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 25428 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 25428-submit@debbugs.gnu.org id=B25428.150293492310362 (code B ref 25428); Thu, 17 Aug 2017 01:56:02 +0000 Original-Received: (at 25428) by debbugs.gnu.org; 17 Aug 2017 01:55:23 +0000 Original-Received: from localhost ([127.0.0.1]:41760 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1diA1r-0002h4-0d for submit@debbugs.gnu.org; Wed, 16 Aug 2017 21:55:23 -0400 Original-Received: from mail-it0-f65.google.com ([209.85.214.65]:36921) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1diA1p-0002gq-Bs for 25428@debbugs.gnu.org; Wed, 16 Aug 2017 21:55:21 -0400 Original-Received: by mail-it0-f65.google.com with SMTP id 77so3461850itj.4 for <25428@debbugs.gnu.org>; Wed, 16 Aug 2017 18:55:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=NC3VZsrWw3L59x3SnQ9EnAe9h9ODS3i4OYffGGuuho0=; b=rcJg/bFnp9SurXMzBmAse1Hhq4o2S33f8hnLA076KltFFuRGbF7cK44FpUxYvm7wuO bek9scmgz7yn0IoGXpCupYebXkpO/oIbv/MM9kmsR3K/wJEFVpvBCXoY8Lt24SDuEsVg exurBhVt5kR44fVeCxsmwlb2DleSV4mvBlpClMgrdGoyn732WaBQTgdo2Qj73D9u6DWl pB2/rnxfwP45vPTAePhqXbKrar+31RYL6kmLK6HcWYuPII9N9eE9Bo6r+nGv+sFbtn+y TGP3whhAyGRNifq6V6xAtdMfz52lKdThIVi8rzThsYRwODD67rB2VMeMHSWkY1kCQnl7 UV+w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=NC3VZsrWw3L59x3SnQ9EnAe9h9ODS3i4OYffGGuuho0=; b=pCCvhkGLUjsMshG6dhLOVIsIJVjzPvNAZsruIbNnN6YpZLIx82JFWBInITwD6qdcz6 xnnw8DMQ7VwK9dhoAcz9UV8oghCyR88crcXLzay4Zvza47l7/fpItwm760Ep42yldcia fx1tU8npn5KBxBn5Jq4/u9Q3uKXlfNiBIkRhtl4E/a8xjr/KHymCuVnO0Gn7cNT+bcgr 0GL6nNAg//JkX8GSIyOv6+eTbFvX4V4RwNYqHTIhgJWbqcTmKyD8C3c//mnV8ZUpQqGm m7wG4Y9rvsVDvEUsowbkM8YhPEECWGb02vO82TrrxLQjKSbldutDhqJv088Ybg1jl44S PgiQ== X-Gm-Message-State: AHYfb5gkM7BmSuagifXmbkmJHxH3t9MiGCg6AIRtpbxixZ7qaaPGB+VE Bv5xC0ebznNT1S3vl2c= X-Received: by 10.36.37.130 with SMTP id g124mr432320itg.114.1502934915567; Wed, 16 Aug 2017 18:55:15 -0700 (PDT) Original-Received: from moondust.localdomain.nodomain.none ([184.151.179.113]) by smtp.gmail.com with ESMTPSA id 193sm989096ioo.84.2017.08.16.18.55.14 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 16 Aug 2017 18:55:15 -0700 (PDT) In-Reply-To: (Drew Adams's message of "Thu, 12 Jan 2017 08:24:39 -0800 (PST)") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:135853 Archived-At: At 07:24 -0800 on Thursday 2017-01-12, Drew Adams wrote: > The doc string says this: > > If called from Lisp, enable the mode if ARG is omitted or nil. > > That is completely wrong. This is an ordinary minor mode, > defined using `define-minor-mode', whose doc string says this: > > When called from Lisp, the mode command toggles the mode if > the argument is =E2=80=98toggle=E2=80=99, disables the mode if the argu= ment is > a non-positive integer, and enables the mode otherwise > (including if the argument is omitted or nil or a positive > integer). Hi Drew, I do not see any contradiction between these two statements. Maybe one of us is misreading them? In particular, I find that the behaviour of `delete-selection-mode' (the function) when called from Lisp matches both statements in every particular, so I don't see what you mean by "completely wrong". > E.g., `(delete-selection-mode t)' ENABLES the mode, even though the > `delete-selection-mode' doc string says that it DISABLES it. Yes, this enables the mode, but no, the doc string does *not* say this disables it. (In fact, it is silent on how to disable it from Lisp.) Am I missing something? Admittedly, the part of its doc string that says how to use the `delete-selection-mode' function from Lisp seems inadequate: It doesn't say how to toggle the mode, it doesn't say how to disable the mode, and the methods it mentions for enabling the mode do not include the most straightforward one (passing it `t'). [Temporary minor rant: Personally it seems absurd to me that a `nil' argument doesn't turn a minor mode off; and that calling the minor mode function with no argument doesn't toggle it. But that is all history of course.] Anyway, does it make sense to re-document the canonical behaviour of minor mode commands in the doc string of every minor mode command? Maybe it would be better (as I think you might have suggested in another bug report back in January) if the doc string of the each minor mode command had a link to the documentation of the canonical behaviour. N.