From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Luc Teirlinck Newsgroups: gmane.emacs.devel Subject: Re: doc string of `local-variable-if-set-p' Date: Wed, 13 Oct 2004 19:33:05 -0500 (CDT) Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Message-ID: <200410140033.i9E0X5Q12545@raven.dms.auburn.edu> References: <20041014.022254.179728295.jet@gyve.org> <200410131753.i9DHru529221@raven.dms.auburn.edu> <20041014.072407.115920551.jet@gyve.org> NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1097714087 16214 80.91.229.6 (14 Oct 2004 00:34:47 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 14 Oct 2004 00:34:47 +0000 (UTC) Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Oct 14 02:34:35 2004 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1CHtZi-00007f-00 for ; Thu, 14 Oct 2004 02:34:35 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CHtgn-0002Lv-2q for ged-emacs-devel@m.gmane.org; Wed, 13 Oct 2004 20:41:53 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1CHtgb-0002Ll-Lt for emacs-devel@gnu.org; Wed, 13 Oct 2004 20:41:41 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1CHtgb-0002LY-0F for emacs-devel@gnu.org; Wed, 13 Oct 2004 20:41:41 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1CHtga-0002LV-SS for emacs-devel@gnu.org; Wed, 13 Oct 2004 20:41:40 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.34) id 1CHtZM-0006Xo-VW for emacs-devel@gnu.org; Wed, 13 Oct 2004 20:34:13 -0400 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.12.10/8.12.10) with ESMTP id i9E0YBiU001080; Wed, 13 Oct 2004 19:34:11 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.7p1+Sun/8.11.7) id i9E0X5Q12545; Wed, 13 Oct 2004 19:33:05 -0500 (CDT) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: jet@gyve.org In-reply-to: <20041014.072407.115920551.jet@gyve.org> (message from Masatake YAMATO on Thu, 14 Oct 2004 07:24:07 +0900 (JST)) 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: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:28373 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:28373 Masatake YAMATO wrote: > ELISP> (make-variable-buffer-local 'var) > var > ELISP> (local-variable-p 'var) > nil > ELISP> (local-variable-if-set-p 'var) > t This example is very clear for me. Isn't it popular way to put ielm's session to doc strings? It is not very usual to put extended examples in docstrings, though it is usual in the Elisp or Emacs manuals. Maybe we could put an explicit reference to the Elisp manual in the docstring. Also maybe we might want to clarify the first sentence somewhat in the docstring itself and mention that this does not affect let-bindings made in BUFFER, which could easily be another source of confusion. The patch below does all of this. I could install if it looks OK. I believe that if the example above is to go anywhere, it would be in the Elisp manual. But maybe things are already explained clearly enough there. Note that the reference in the patch below is to the entire node, not to some anchor in the node. ===File ~/data.c-diff======================================= *** data.c 02 Aug 2004 15:31:33 -0500 1.242 --- data.c 13 Oct 2004 13:57:42 -0500 *************** *** 1794,1800 **** DEFUN ("local-variable-if-set-p", Flocal_variable_if_set_p, Slocal_variable_if_set_p, 1, 2, 0, ! doc: /* Non-nil if VARIABLE will be local in buffer BUFFER if it is set there. BUFFER defaults to the current buffer. */) (variable, buffer) register Lisp_Object variable, buffer; --- 1794,1804 ---- DEFUN ("local-variable-if-set-p", Flocal_variable_if_set_p, Slocal_variable_if_set_p, 1, 2, 0, ! doc: /* Non-nil if VARIABLE will be local in buffer BUFFER when set there. ! More precisely, this means that setting the variable \(with `set' or`setq'), ! while it does not have a `let'-style binding that was made in BUFFER, ! will produce a buffer local binding. See Info node ! `(elisp)Creating Buffer-Local'. BUFFER defaults to the current buffer. */) (variable, buffer) register Lisp_Object variable, buffer; ============================================================