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

["Drew Adams" <drew.adams@oracle.com>]

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