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

[Daniel Brockman <drlion@deepwood.net>]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> The space constraint is 67 characters or less, so it will not look
> bad in the apropos output. So 66 is perfectly acceptable.

You're right.  I was just being defensive:  If all the docstrings are
to be consistently worded, those extra seven characters might not fit
as easily the next time you're writing a docstring for a function that
takes a buffer but not a name.

> OK, so what about:
>
> 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 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 must be a buffer \(not a buffer name) and defaults to
> the current buffer.  */)

I think this is good.  I would just rearrange the clauses slightly:

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 when set there.
More precisely, this means that setting the variable (with `set' or `setq')
will produce a buffer-local binding, unless the variable already has
a `let'-style binding that was made in BUFFER.
See Info node `(elisp)Creating Buffer-Local'.
BUFFER must be a buffer \(not a buffer name) and defaults to
the current buffer.  */)

> Actually there is a convention in the Elisp manual to call the
> argument BUFFER if it has to be a buffer and BUFFER-OR-NAME if it
> can be a buffer or a buffer name.  That convention is consistently
> followed in the Elisp manual, but not in docstrings.  So one can not
> just rely on it in docstrings.

OK, so we'll at least be following the convention --- that's good. :-)

-- 
Daniel Brockman
drlion@deepwood.net