bug#10713: 24.0.93; doc of `local-variable-if-set-p'

bug#10713: 24.0.93; doc of `local-variable-if-set-p'

[Drew Adams]

1. The doc string says much more about this function than does the Elisp
manual (node Creating Buffer-Local).  The manual should say at least as
much as the doc string says - it is quite incomplete about this
function.
 
2. The doc string refers the reader to the manual (same node) for more
information!  AFAICT, there is not more info about this in that node -
there is less.  If there is more info to be given about this function
than what is in the doc string, please add it to the manual.
 

In GNU Emacs 24.0.93.1 (i386-mingw-nt5.1.2600)
 of 2012-01-29 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include --ldflags
 -LD:/devel/emacs/libs/gnutls-3.0.9/lib'
 

bug#10713: 24.0.93; doc of `local-variable-if-set-p'

[Drew Adams]

What's more, this sentence in the doc string (perhaps the most important
sentence) seems incorrect.  At a minimum it is not clear (to me at least).

"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."

First of all, why the qualification "with `set' or `setq'"?  Does it really
matter how the variable is _set_?  If you are trying to distinguish setting from
`let' binding (?) then say so.

More importantly, the phrase "while it does not have a `let'-style binding that
was made in BUFFER" makes no sense (to me at least).

`let' bindings are not made in buffers.  If this explanation is trying to say
something "more precisely" it is doing a poor job of it.

Are you perhaps really trying to say something like the following?

"The local value in BUFFER is set, provided the variable is not currently `let'
bound."

Please clarify this doc.  Try using more than one sentence to get your point
across, for a start.  That will likely help you say what you are really trying
to say (which is not clear to me).

bug#10713: 24.0.93; doc of `local-variable-if-set-p'

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> 1. The doc string says much more about this function than does the Elisp
> manual (node Creating Buffer-Local).  The manual should say at least as
> much as the doc string says - it is quite incomplete about this
> function.
>  
> 2. The doc string refers the reader to the manual (same node) for more
> information!  AFAICT, there is not more info about this in that node -
> there is less.  If there is more info to be given about this function
> than what is in the doc string, please add it to the manual.

Fixed in trunk.