From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Juanma Barranquero" Newsgroups: gmane.emacs.devel Subject: Re: [drew.adams@oracle.com: RE: Customize doc strings and tagstrings do not respect \\<...> and \\[...]] Date: Thu, 15 Feb 2007 12:44:13 +0100 Message-ID: References: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1171539879 10604 80.91.229.12 (15 Feb 2007 11:44:39 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 15 Feb 2007 11:44:39 +0000 (UTC) Cc: Drew Adams , emacs-devel@gnu.org To: rms@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Feb 15 12:44:32 2007 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1HHf2O-0007Am-J9 for ged-emacs-devel@m.gmane.org; Thu, 15 Feb 2007 12:44:32 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HHf2O-0004Ek-4S for ged-emacs-devel@m.gmane.org; Thu, 15 Feb 2007 06:44:32 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1HHf29-0004Db-K8 for emacs-devel@gnu.org; Thu, 15 Feb 2007 06:44:17 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1HHf27-00049I-3Y for emacs-devel@gnu.org; Thu, 15 Feb 2007 06:44:16 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HHf26-00049F-UO for emacs-devel@gnu.org; Thu, 15 Feb 2007 06:44:14 -0500 Original-Received: from wr-out-0506.google.com ([64.233.184.232]) by monty-python.gnu.org with esmtp (Exim 4.52) id 1HHf26-0006iu-HJ for emacs-devel@gnu.org; Thu, 15 Feb 2007 06:44:14 -0500 Original-Received: by wr-out-0506.google.com with SMTP id 69so706457wri for ; Thu, 15 Feb 2007 03:44:14 -0800 (PST) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=beta; h=received:message-id:date:from:to:subject:cc:in-reply-to:mime-version:content-type:content-transfer-encoding:content-disposition:references; b=iR1HwYgHwynyhQ/+41rOF90As88mEkrK4/y+5MeclgtinHKyAXPziNL6uedsGyZpH6HBzPHVkVxMtokrIT6u6mITiJhCBxt6Uz+b9skupeDaZOGzCOse0d7NMUTWmwDsaqovSDudN6cJALsKjzkwgywG7d8aI3mSv91DHVTcmlo= Original-Received: by 10.114.60.19 with SMTP id i19mr895541waa.1171539853618; Thu, 15 Feb 2007 03:44:13 -0800 (PST) Original-Received: by 10.114.234.16 with HTTP; Thu, 15 Feb 2007 03:44:13 -0800 (PST) In-Reply-To: Content-Disposition: inline X-detected-kernel: Linux 2.4-2.6 (Google crawlbot) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:66417 Archived-At: [From a thread almost a year ago about where Drew and Andreas discussed (among other things) the behavior of `substitute-command-keys' when it finds a keymap not currently defined.] Richard said: > This could be the most useful behavior, since it provides a warning > that the keymap is not defined at the place where you expected it to > be. Any clueful user will realize it means the mode has a bug > and will report it, and then things will be fixed so they really work. Do you consider using \\ in the docstring of an autoloaded function a bug in the mode? > By contrast, if it did something else quieter, such as ignore the > specification of the nonexistent map, it would give a result that is > not what it ought to be but not so obviously wrong. A user would have > to be really on his toes to notice and report the bug. True in theory, but the current behavior can be confusing for a newbie. Witness checkdoc-minor-mode's docstring: Toggle Checkdoc minor mode, a mode for checking Lisp doc strings. With prefix arg, turn Checkdoc minor mode on iff arg is positive. In Checkdoc minor mode, the usual bindings for `eval-defun' which is bound to Uses keymap "checkdoc-minor-mode-map", which is not currently defined. M-x checkdoc-eval-defun and `checkdoc-eval-current-buffer' are overridden to include checking of documentation strings. Uses keymap "checkdoc-minor-mode-map", which is not currently defined. So, at least in the case of the output of `describe-function', `describe-variable', etc. a better answer IMHO would be to detect these cases, silently ignore them at the point where they happen, and add a prominent notice somewhere (preferibly at the top): NOTE: This documentation references the keymap "checkdoc-minor-mode-map", which is not currently defined. You can load the package `checkdoc' to fix the problem. Toggle Checkdoc minor mode, a mode for checking Lisp doc strings. With prefix arg, turn Checkdoc minor mode on iff arg is positive. In Checkdoc minor mode, the usual bindings for `eval-defun' which is bound to M-x checkdoc-eval-defun and `checkdoc-eval-current-buffer' are overridden to include checking of documentation strings. (The exact wording is irrelevant.) This probably requires adding args to `substitute-command-keys', or perhaps a new function, so I'm not suggesting any change right now, of course. Juanma