From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#14875: 24.3.50; doc of :variable in `define-minor-mode' - lamentable Date: Mon, 15 Jul 2013 13:53:05 -0700 (PDT) Message-ID: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1373921662 22834 80.91.229.3 (15 Jul 2013 20:54:22 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 15 Jul 2013 20:54:22 +0000 (UTC) To: 14875@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jul 15 22:54:22 2013 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Uypmn-0002NV-5P for geb-bug-gnu-emacs@m.gmane.org; Mon, 15 Jul 2013 22:54:21 +0200 Original-Received: from localhost ([::1]:51090 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Uypmm-0005TC-Rm for geb-bug-gnu-emacs@m.gmane.org; Mon, 15 Jul 2013 16:54:20 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34562) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UypmW-0005Ci-AD for bug-gnu-emacs@gnu.org; Mon, 15 Jul 2013 16:54:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UypmV-0001kY-C2 for bug-gnu-emacs@gnu.org; Mon, 15 Jul 2013 16:54:04 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:34024) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UypmV-0001kS-7b for bug-gnu-emacs@gnu.org; Mon, 15 Jul 2013 16:54:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1UypmU-0005Fx-KI for bug-gnu-emacs@gnu.org; Mon, 15 Jul 2013 16:54:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 15 Jul 2013 20:54:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 14875 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.137392160220130 (code B ref -1); Mon, 15 Jul 2013 20:54:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 15 Jul 2013 20:53:22 +0000 Original-Received: from localhost ([127.0.0.1]:56572 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Uyplp-0005Eb-4C for submit@debbugs.gnu.org; Mon, 15 Jul 2013 16:53:21 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:60908) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Uyplk-0005E5-HX for submit@debbugs.gnu.org; Mon, 15 Jul 2013 16:53:17 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Uyple-0001e0-2t for submit@debbugs.gnu.org; Mon, 15 Jul 2013 16:53:11 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:48933) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Uypld-0001du-VI for submit@debbugs.gnu.org; Mon, 15 Jul 2013 16:53:09 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34373) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Uyplb-0004cs-QZ for bug-gnu-emacs@gnu.org; Mon, 15 Jul 2013 16:53:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Uypla-0001ck-He for bug-gnu-emacs@gnu.org; Mon, 15 Jul 2013 16:53:07 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:24064) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Uypla-0001bv-9h for bug-gnu-emacs@gnu.org; Mon, 15 Jul 2013 16:53:06 -0400 Original-Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r6FKr34Q002523 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 15 Jul 2013 20:53:04 GMT Original-Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by ucsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r6FKr3D9011152 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Mon, 15 Jul 2013 20:53:03 GMT Original-Received: from abhmt115.oracle.com (abhmt115.oracle.com [141.146.116.67]) by userz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r6FKr2aQ011147 for ; Mon, 15 Jul 2013 20:53:03 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.7 (607090) [OL 12.0.6668.5000 (x86)] X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:76372 Archived-At: 1. Both (elisp) `Defining Minor Modes' and the doc string say the same thing, verbatim. The manual should explain better. 2. The description/explanation is incomplete/confusing/gobbledygook, at best. It says that PLACE can be a "generalized variable", without giving any explanation of what a generalized variable is, and without cross-referencing any doc that describes such a thing. It says that PLACE can also be a cons (GET . SET). In this case, it says that "SET is a function that takes one argument, the new state, and sets it". Huh? It takes the NEW state as argument? If so, where did that new state come from? And then it "sets" the new state? Huh? Does it just set it to what it already was (the "new state" argument)? Or does "set" here perhaps imply setting the value to non-nil (as in setting a bit)? It's not clear at all what the SET of (GET . SET) (1) accepts as arg, (2) does as its main (standard) effect, or (3) returns as a value (if that matters). It says that if PLACE is specified as a variable then "this function does not define a MODE variable (nor any of the terms used in :variable)". Huh? Does "variable" here include the "generalized variable" case? Does "this function" refer to the SET function of the preceding sentence? Or does it refer to the minor-mode function? What on Earth does it mean for the function (either of those functions, or whatever function is meant) to not define "any of the terms used in :variable"? I honestly understand almost nothing here. :variable does not define any of the terms used in :variable? Huh? Please, please. Users deserve better. Give us a break. Please clear this up. 3. And as is too often the case, the "For example,..." at the end gives a too-trivial example that shows none of the things that someone might really have a question about. In GNU Emacs 24.3.50.1 (i686-pc-mingw32) of 2013-07-01 on LEG570 Bzr revision: 113246 lekktu@gmail.com-20130701165437-ea20s94hqwp3ttaj Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --prefix=3D/c/usr --enable-checking CFLAGS=3D'-O0 -g3' CPPFLAGS=3D'-DGLYPH_DEBUG=3D1 -I/c/usr/include''