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

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

[Masatake YAMATO]

Hi,

M-x descscribe-function `local-variable-if-set-p'
and I got *Help*:

    local-variable-if-set-p is a built-in function in `C source code'.
    (local-variable-if-set-p variable &optional buffer)

    Non-nil if variable will be local in buffer buffer if it is set there.
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    buffer defaults to the current buffer.

My english is poor but I guess something conjunction like `and' is need
between two if clauses. 

Masatake YAMATO

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

[Stefan]

>     local-variable-if-set-p is a built-in function in `C source code'.
>     (local-variable-if-set-p variable &optional buffer)

>     Non-nil if variable will be local in buffer buffer if it is set there.
>             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>     buffer defaults to the current buffer.

> My english is poor but I guess something conjunction like `and' is need
> between two if clauses. 

Most likely, it's the new fontification that struck you.
The original docstring is:

   Non-nil if VARIABLE will be local in buffer BUFFER if it is set there.
   BUFFER defaults to the current buffer.

but recently the code tries to mangle it to use italics instead of allcaps
for identifiers.  Most likely in your case the italics is lost somewhere.

Note also how even if the italics was kept the mangling has created an
ugliness in the second sentence: it starts with a lowercase.


        Stefan

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

[Masatake YAMATO]

> Most likely, it's the new fontification that struck you.
> The original docstring is:
> 
>    Non-nil if VARIABLE will be local in buffer BUFFER if it is set there.
>    BUFFER defaults to the current buffer.
> 
> but recently the code tries to mangle it to use italics instead of allcaps
> for identifiers.  Most likely in your case the italics is lost somewhere.
> 
> Note also how even if the italics was kept the mangling has created an
> ugliness in the second sentence: it starts with a lowercase.

I am not talking about fontification nor upper/lower case.
I'm talking about English. 

(1) Non-nil if VARIABLE will be local in buffer BUFFER if it is set there.
    BUFFER defaults to the current buffer. 

I thought this should be

(2) Non-nil if VARIABLE will be local in buffer BUFFER *and* if it is set there.
    BUFFER defaults to the current buffer. 

or 

(3) Non-nil if VARIABLE will be local in buffer BUFFER and if VARIABLE is set in BUFFER.
    BUFFER defaults to the current buffer. 

If you think (1) is ok as English, please ignore me; and I'll go back
to an English class room in a junior high school.

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

[Stefan]

> (1) Non-nil if VARIABLE will be local in buffer BUFFER if it is set there.

It may not be the clearest way to say it, but it sounds correct to me.
If I add parentheses to help parsing:

  Non-nil if (VARIABLE will be local in buffer BUFFER if it is set there)

I.e. in the case that VARIABLE is set in BUFFER, the VARIABLE will be local
iff the function returns non-nil.


        Stefan

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

[Luc Teirlinck]

Masatake YAMATO wrote:

   I thought this should be

   (2) Non-nil if VARIABLE will be local in buffer BUFFER *and* if it is set there.
       BUFFER defaults to the current buffer. 

   or 

   (3) Non-nil if VARIABLE will be local in buffer BUFFER and if VARIABLE is set in BUFFER.
       BUFFER defaults to the current buffer. 

   If you think (1) is ok as English, please ignore me; and I'll go back
   to an English class room in a junior high school.

I believe you are misunderstanding what the function does:

ELISP> (make-variable-buffer-local 'var)
var
ELISP> (local-variable-p 'var)
nil
ELISP> (local-variable-if-set-p 'var)
t

That said, the first line is 70 characters and the maximum allowed is
67.  English is not my native language, but I believe that the "double
if" is not invalid English.  It is probably not great style either.  I
believe that the following new first line fixes both length and style:

   Non-nil if VARIABLE will be local in buffer BUFFER when set there.

That is 66 characters.  I will commit this change if there are no
objections.

Sincerely,

Luc.

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

[David Kastrup]

Stefan <monnier@iro.umontreal.ca> writes:

>> (1) Non-nil if VARIABLE will be local in buffer BUFFER if it is set there.
>
> It may not be the clearest way to say it, but it sounds correct to me.
> If I add parentheses to help parsing:
>
>   Non-nil if (VARIABLE will be local in buffer BUFFER if it is set there)
>
> I.e. in the case that VARIABLE is set in BUFFER, the VARIABLE will be local
> iff the function returns non-nil.

Oh, come on, that is mathematician speak, working with parens.  Just
say:

Non-nil if after setting the VARIABLE in buffer BUFFER it will be
local, either because it is already so, or because it is automatic
buffer-local (see `make-variable-buffer-local').

However, can anybody tell me what the point of the BUFFER argument is?
It makes it hard to find out whether a variable that might already
have a local binding is automatic buffer-local.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

[Andreas Schwab]

Stefan <monnier@iro.umontreal.ca> writes:

>> (1) Non-nil if VARIABLE will be local in buffer BUFFER if it is set there.
>
> It may not be the clearest way to say it, but it sounds correct to me.
> If I add parentheses to help parsing:
>
>   Non-nil if (VARIABLE will be local in buffer BUFFER if it is set there)
>
> I.e. in the case that VARIABLE is set in BUFFER, the VARIABLE will be local
> iff the function returns non-nil.

Maybe it becomes clearer when the second if is replaced by when.
Something like this:

      Non-nil if VARIABLE becomes local in buffer BUFFER when set there.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Luc Teirlinck]

David Kastrup wrote:

   Oh, come on, that is mathematician speak, working with parens.  Just
   say:

   Non-nil if after setting the VARIABLE in buffer BUFFER it will be
   local, either because it is already so, or because it is automatic
   buffer-local (see `make-variable-buffer-local').

That first line is way too long (needs to be 67 characters or less).
I believe that the new first line I sent is clear.

   However, can anybody tell me what the point of the BUFFER argument is?
   It makes it hard to find out whether a variable that might already
   have a local binding is automatic buffer-local.

I believe you misunderstand the purpose of `local-variable-if-set-p'.

`(local-variable-p var)' tests whether VAR actually _has_ a buffer
local binding in BUFFER.

`(local-variable-if-set-p var)' tests whether VAR would have a
buffer-local binding in buffer if we would bind it right now.

See the ielm run I sent earlier.

Concerning the second paragraph quoted above: you want to check
whether variable is automatically buffer-local when set.
`describe-variable' does this as follows:

(when (and (local-variable-if-set-p variable)
	   (or (not (local-variable-p variable))
	       (with-temp-buffer
		 (local-variable-if-set-p variable))))
  (save-excursion
    (forward-line -1)
    (insert "Automatically becomes buffer-local when set in any fashion.\n")))

I do not know whether there is a better way to do it.  If there is a
one, then the above piece of code should be changed to use it.

Sincerely,

Luc.

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

[Masatake YAMATO]

Thank all of you for your comments.

> 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?

Masatake YAMATO

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

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

[Richard Stallman]

    The original docstring is:

       Non-nil if VARIABLE will be local in buffer BUFFER if it is set there.
       BUFFER defaults to the current buffer.

    but recently the code tries to mangle it to use italics instead of allcaps
    for identifiers.  Most likely in your case the italics is lost somewhere.

When I tried this on a tty it left the uppercase alone.
The code must try to check for conditions where italics can be used,
and there must be a problem in those criteria.

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

[Richard Stallman]

  Non-nil if VARIABLE becomes local in buffer BUFFER when set there.

That is clearer but not quite right.  If VARIABLE is already local in
BUFFER, the function returns t.

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

[Miles Bader]

Richard Stallman <rms@gnu.org> writes:
>   Non-nil if VARIABLE becomes local in buffer BUFFER when set there.
>
> That is clearer but not quite right.  If VARIABLE is already local in
> BUFFER, the function returns t.

ow about:

  Non-nil if VARIABLE would be buffer-local in BUFFER after being set there.

-Miles
-- 
Freedom's just another word, for nothing left to lose   --Janis Joplin

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

[Luc Teirlinck]

Richard Stallman wrote:

     Non-nil if VARIABLE becomes local in buffer BUFFER when set there.

   That is clearer but not quite right.  If VARIABLE is already local in
   BUFFER, the function returns t.

and Miles Bader wrote:

   Non-nil if VARIABLE would be buffer-local in BUFFER after being set there.

Seven characters too long.

In the docstring I proposed, I put:

   Non-nil if VARIABLE will be local in buffer BUFFER when set there.

This is completely correct.  Even if VARIABLE is already local in
BUFFER, it still will be local when set.

Entire previously proposed docstring:

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.  */)

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

[Daniel Brockman]

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

> Miles Bader wrote:
>
>    Non-nil if VARIABLE would be buffer-local in BUFFER after being set there.
>
> Seven characters too long.
>
> In the docstring I proposed, I put:
>
>    Non-nil if VARIABLE will be local in buffer BUFFER when set there.

I don't see why the word ``buffer'' needs to be doubled.  The
following reads better and is shorter:

   Non-nil if VARIABLE will be local in BUFFER when set there.

Or you can invest those extra characters in making it more like
Miles's version:

   Non-nil if VARIABLE will be buffer-local in BUFFER when set there.


-- 
Daniel Brockman
drlion@deepwood.net

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

[Luc Teirlinck]

Daniel Brockman wrote;

   I don't see why the word ``buffer'' needs to be doubled.  The
   following reads better and is shorter:

      Non-nil if VARIABLE will be local in BUFFER when set there.

BUFFER _must_ be a buffer however.  (In similar functions you can
often also use a buffer name.  Not here.)

Sincerely,

Luc.

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

[Daniel Brockman]

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

> Daniel Brockman wrote;
>
>    I don't see why the word ``buffer'' needs to be doubled.  The
>    following reads better and is shorter:
>
>       Non-nil if VARIABLE will be local in BUFFER when set there.
>
> BUFFER _must_ be a buffer however.  (In similar functions you can
> often also use a buffer name.  Not here.)

Ah, I didn't realize that.

Still, I think that's a detail that belongs somewhere after the
space-constrained first line.  Just doubling the word ``buffer'' isn't
going to make it clear that a buffer *name* won't do, so you might as
well spell it out clearly in the long description.

Or am I missing some long-established Emacs documentation convention?

-- 
Daniel Brockman
drlion@deepwood.net

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

[Luc Teirlinck]

Daniel Brockman wrote:

   Or am I missing some long-established Emacs documentation convention?

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.

   Still, I think that's a detail that belongs somewhere after the
   space-constrained first line.

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

   Just doubling the word ``buffer'' isn't going to make it clear that
   a buffer *name* won't do, so you might as well spell it out clearly
   in the long description.

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.  */)

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

[Daniel Brockman]

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

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

[Luc Teirlinck]

Daniel Brockman wrote:

   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.  */)

I am a little bit concerned that "unless the variable already has a
`let'-style binding that was made in BUFFER" seems to suggest that in
that case definitely no local binding will be made, whereas it
actually depends on the situation.

    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.

does not suggest that.

Moreover the "already" in "already has a let-style binding" sounds a
little bit strange, since let-bindings are temporary.

Sincerely,

Luc.