doc string of insert-default-directory is unclear

doc string of insert-default-directory is unclear

[Drew Adams]

Don't ask me why it's unclear to me, if it's clear to you. In that
case, just take it that at least one user finds this unclear.
 
In previous releases, the doc string said only what its first line
says. The rest was presumably added in Emacs 22 to clarify the meaning
and use. But I find it totally confusing.
 
In particular, the second sentence is not clear, I think:
 
 "If the initial minibuffer contents are non-empty,
  you can usually request a default filename by typing
  RETURN without editing."
 
Please consider rephrasing the entire doc string. A good starting
point could be to explain the significance of the initial contents
being non-empty. The doc string should give you an idea when you might
want to bind this to nil or non-nil. That is not the case now, IMO.
 

In GNU Emacs 22.1.1 (i386-mingw-nt5.1.2600)
 of 2007-06-02 on RELEASE
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/gnuwin32/include'
 

Re: doc string of insert-default-directory is unclear

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Sat, 2 Feb 2008 17:31:49 -0800
> 
> Don't ask me why it's unclear to me, if it's clear to you. In that
> case, just take it that at least one user finds this unclear.
>  
> In previous releases, the doc string said only what its first line
> says. The rest was presumably added in Emacs 22 to clarify the meaning
> and use.

Not just clarify, to document its different semantics.

> Please consider rephrasing the entire doc string. A good starting
> point could be to explain the significance of the initial contents
> being non-empty.

I took a shot at this.  The new doc string is this:

    *Non-nil means when reading a filename start with default dir in minibuffer.

    When the initial minibuffer contents show a name of a file or a directory,
    typing RETURN without editing the initial contents is equivalent to typing
    the default file name.

    If this variable is non-nil, the minibuffer contents are always
    initially non-empty, and typing RETURN without editing will fetch the
    default name, if one is provided.  Note however that this default name
    is not necessarily the same as initial contents inserted in the minibuffer,
    if the initial contents is just the default directory.

    If this variable is nil, the minibuffer often starts out empty.  In
    that case you may have to explicitly fetch the next history element to
    request the default name; typing RETURN without editing will leave
    the minibuffer empty.

    For some commands, exiting with an empty minibuffer has a special meaning,
    such as making the current buffer visit no file in the case of
    `set-visited-file-name'.

RE: doc string of insert-default-directory is unclear

[Drew Adams]

> > In previous releases, the doc string said only what its first line
> > says. The rest was presumably added in Emacs 22 to clarify 
> > the meaning and use.
> 
> Not just clarify, to document its different semantics.

That semantic difference is not clear to me from the new doc string you
propose. Sorry. Could you point out the difference?

> > Please consider rephrasing the entire doc string. A good starting
> > point could be to explain the significance of the initial contents
> > being non-empty.
> 
> I took a shot at this.  

Thanks.

> The new doc string is this:
> 
>     *Non-nil means when reading a filename start with default 
>      dir in minibuffer.
> 
>     When the initial minibuffer contents show a name of a 
>     file or a directory, typing RETURN without editing the
>     initial contents is equivalent to typing
>     the default file name.
> 
>     If this variable is non-nil, the minibuffer contents are always
>     initially non-empty, and typing RETURN without editing 
>     will fetch the default name, if one is provided.  Note however
>     that this default name is not necessarily the same as initial
>     contents inserted in the minibuffer,
>     if the initial contents is just the default directory.
> 
>     If this variable is nil, the minibuffer often starts out 
>     empty.  In that case you may have to explicitly fetch the next 
>     history element to request the default name; typing RETURN
>     without editing will leave the minibuffer empty.
> 
>     For some commands, exiting with an empty minibuffer has a 
>     special meaning, such as making the current buffer visit no
>     file in the case of `set-visited-file-name'.

Here's some additional feedback. If it makes sense to you, fine; if not,
ignore.

The variable controls the behavior of one or more functions, but it is not
clear which. It's not necessarily the case that every time a file name is
read in Emacs the behavior is controlled by this variable. And even if that
is true of vanilla Emacs, it might not be true in general. Isn't this only
about `read-file-name'? If so, then it should say "when a file name is read
with `read-file-name'". 

If it is mainly about `read-file-name' but there are some other cases, it
still might be better to mention "when read by functions such as
`read-file-name'."

Some of the statements are too general: "If this variable is non-nil, the
minibuffer contents are always initially non-empty". That's certainly not
true of the minibuffer in general (e.g. `M-x'). This would be cleared up by
saying that we are talking only of the context of `read-file-name' (or
whatever).

Readers can be confused by the concept of "default file name", which can
depend on the particular command. I think that should be clarified. And
references to the default directory should refer to `default-directory', so
users can look up what that means.

More generally, for information about different behaviors and special cases,
the doc string should refer to the functions and variables whose doc strings
explain those cases in context.

"Typing RETURN without editing will leave the minibuffer empty." No, it will
exit the minibuffer, returning the empty string. RETURN doesn't empty the
minibuffer or just leave it empty (no-op).

I hate to say it, but I think that, in general, the added text just adds
confusion. So far, I think it is clearest to say simply that non-nil means
that `default-directory' is inserted initially in the minibuffer when a name
is read by `read-file-name'. It is the doc of `read-file-name' etc. that
should explain what happens if you empty the minibuffer or if you hit RETURN
without typing anything.

What is the problem that adding this text is intended to solve? If you tell
me what the problem we are solving is, perhaps I can help some more with the
wording.

Re: doc string of insert-default-directory is unclear

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <bug-gnu-emacs@gnu.org>
> Date: Sat, 9 Feb 2008 07:59:15 -0800
> 
> > > In previous releases, the doc string said only what its first line
> > > says. The rest was presumably added in Emacs 22 to clarify 
> > > the meaning and use.
> > 
> > Not just clarify, to document its different semantics.
> 
> That semantic difference is not clear to me from the new doc string you
> propose. Sorry. Could you point out the difference?

I did not mean my changes, I meant the addition of the text that you
complained about: it was added when the effects of the value of this
variable were changed a few years ago.

> "Typing RETURN without editing will leave the minibuffer empty." No, it will
> exit the minibuffer

Well, that's ambiguity of the work "leave": it also means "exit",
which was my intent.

> I hate to say it, but I think that, in general, the added text just adds
> confusion.

If you mean my changes, then I didn't add anything.  I just rearranged
the text a bit and made some minor wording changes.

> What is the problem that adding this text is intended to solve? If you tell
> me what the problem we are solving is, perhaps I can help some more with the
> wording.

I didn't have enough time for researching all the users of this
variable's value, unfortunately.  So I simply don't know.  Perhaps Luc
Teirlinck (cc'ed), who is the author of the doc string, could help.

RE: doc string of insert-default-directory is unclear

[Drew Adams]

> > > > In previous releases, the doc string said only what its 
> > > > first line says. The rest was presumably added in Emacs 22 
> > > > to clarify the meaning and use.
> > > 
> > > Not just clarify, to document its different semantics.
> > 
> > That semantic difference is not clear to me from the new 
> > doc string you propose. Sorry. Could you point out the difference?
> 
> I did not mean my changes, I meant the addition of the text that you
> complained about: it was added when the effects of the value of this
> variable were changed a few years ago.

I understood that. I should have said that the semantic difference is not
clear to me from either the Emacs 22 doc string or your proposed text. What
is the semantic difference from pre-Emacs 22? What behavior has changed?

> > "Typing RETURN without editing will leave the minibuffer 
> > empty." No, it will exit the minibuffer
> 
> Well, that's ambiguity of the work "leave": it also means "exit",
> which was my intent.

Right. Exit is less ambiguous.

> > I hate to say it, but I think that, in general, the added 
> > text just adds confusion.
> 
> If you mean my changes, then I didn't add anything.  I just rearranged
> the text a bit and made some minor wording changes.

I meant both the Emacs 22 text and your proposed text. I don't think either
clarifies things.

> > What is the problem that adding this text is intended to 
> > solve? If you tell me what the problem we are solving is, perhaps
> > I can help some more with the wording.
> 
> I didn't have enough time for researching all the users of this
> variable's value, unfortunately.  So I simply don't know.  Perhaps Luc
> Teirlinck (cc'ed), who is the author of the doc string, could help.

OK, understood; I appreciate your trying to help. If someone lets me know,
I'll try to suggest an improvement. For the moment, IMO, we were better off
with just the one-liner.