bug#24095: 25.1; Insufficient documentation of minibuffer-related variables

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

+1 to everything Eli said.  I think (but am not sure) that these
variables were added by Stefan.  Perhaps he can explain them.
If not, hopefully someone else can.

Here is some of what I understand about these things, in case it
helps:

For `minibuffer-default': I believe that its value auguments
whatever default value (or list of default values) is provided
directly to the function reading from the minibuffer (e.g.
`read-from-minibuffer').

For `minibuffer-default-add-function': I believe that its value
is a function of no args that returns a list of default values
that overrides `minibuffer-default'.

So, for example, if the value of `minibuffer-default-add-function'
is  `minibuffer-default-add-dired-shell-commands' then the result
of invoking that function is to return a list of default values
that includes those from `minibuffer-default' but adds also some
shell commands from mailcap.

For `minibuffer-default-add-completions': It is the default value
of variable `minibuffer-default-add-function'.  I belive that it
adds the list of all possible completions of empty input ("") for
`completing-read' to the list of default values, so that you can
treat completions as default values (e.g. cycle using `M-n').

For example, `read-extended-command' (used by `M-x'), using
`minibuffer-with-setup-hook', sets `minibuffer-default-add-function'
to a function that picks up a command name at point (if there is
one).  This means that that command name gets added (by
`minibuffer-default-add-completions', which is the value of
`minibuffer-default-add-function') to the list of default values.
And this means that if you use `M-x' with point on a command name
then that command name is inserted in the minibuffer.

For `minibuffer-avoid-prompt': It seems that it tries to make
point-motion commands not put point in the prompt area.  So,
for example, `C-a' will not move point into the prompt area
(but `C-b' will).

For `minibuffer-history-case-insensitive-variables': This seems
to be a list of history variables for which history-list matching
ignores case.  The doc string seems pretty clear in this case,
except perhaps that it should say that the matching involved is
matching against elements of the current history list.  The rest
of the doc string makes this clear, by mentioning
`(next|previous)-history-element', which do just that: match
against the history list.

HTH.  And I hope that someone more knowledgable corrects any
misunderstandings on my part, and improves the doc as Eli
requested.