Re: doc string of `local-variable-if-set-p'

[Luc Teirlinck]

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;
============================================================