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