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

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

[Eli Zaretskii]

This is a call for people who know their ways around the internals of
completion to please improve the documentation of the related
functions and variables.  I find their current doc strings inadequate,
and their documentation in the ELisp manual simply doesn't exist.

Here's a case in point.  This is a fragment from dired-diff:

  (interactive
   (let* (...
     ...
     (list
      (minibuffer-with-setup-hook
	  (lambda ()
	    (set (make-local-variable 'minibuffer-default-add-function) nil)
	    (setq minibuffer-default defaults))
	(read-file-name
	 (format "Diff %s with%s: " current
		 (if default (format " (default %s)" default) ""))
	 target-dir default t))

Suppose you want to figure out what does the minibuffer-setup-hook try
to accomplish.  Here's the doc string of the 2 variables it uses:

minibuffer-default-add-function:

  Function run by ‘goto-history-element’ before consuming default values.
  This is useful to dynamically add more elements to the list of default values
  when ‘goto-history-element’ reaches the end of this list.
  Before calling this function ‘goto-history-element’ sets the variable
  ‘minibuffer-default-add-done’ to t, so it will call this function only
  once.  In special cases, when this function needs to be called more
  than once, it can set ‘minibuffer-default-add-done’ to nil explicitly,
  overriding the setting of this variable to t in ‘goto-history-element’.

minibuffer-default:

  The current default value or list of default values in the minibuffer.
  The functions ‘read-from-minibuffer’ and ‘completing-read’ bind
  this variable locally.

If you can glean from these doc string (a) what is the significance of
minibuffer-default-add-function being nil, and (b) how the list in
minibuffer-default is used by the completion functions (so you could
decide, for example, what to put there), you are much smarter than I
am.  (The ELisp manual doesn't mention these variables at all.)

Other functions/variables that IMO should be considered for
documentation in the manual:

 minibuffer-avoid-prompt, minibuffer-history-case-insensitive-variables,
 minibuffer-default-add-completions

TIA




In GNU Emacs 25.1.1 (i686-pc-mingw32)
 of 2016-07-24 built on HOME-C4E4A596F7
Windowing system distributor 'Microsoft Corp.', version 5.1.2600
Configured using:
 'configure --prefix=/d/usr --enable-checking=yes,glyphs
 --with-wide-int --with-modules 'CFLAGS=-O2 -gdwarf-4 -g3''

Configured features:
XPM JPEG TIFF GIF PNG RSVG SOUND NOTIFY ACL GNUTLS LIBXML2 ZLIB
TOOLKIT_SCROLL_BARS MODULES

Important settings:
  value of $LANG: ENU
  locale-coding-system: cp1255

Major mode: RMAIL

Minor modes in effect:
  shell-dirtrack-mode: t
  diff-auto-refine-mode: t
  desktop-save-mode: t
  save-place-mode: t
  show-paren-mode: t
  display-time-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  temp-buffer-resize-mode: t
  buffer-read-only: t
  line-number-mode: t

Recent messages:
Auto-saving...done
next-line: End of buffer
Mark set
Sending...
Added to d:/usr/eli/rmail/SENT.MAIL
Sending email 
Sending email done
Sending...done
Showing message 2141...done
Modification-flag cleared

Load-path shadows:
d:/usr/share/emacs/site-lisp/soap-inspect hides d:/usr/share/emacs/25.1/lisp/net/soap-inspect
d:/usr/share/emacs/site-lisp/soap-client hides d:/usr/share/emacs/25.1/lisp/net/soap-client

Features:
(shadow emacsbug tar-mode pulse etags shell grep compile misearch
multi-isearch shr-color color url-util url-parse url-vars shr seq dom
browse-url eieio-opt speedbar sb-image ezimage dframe thingatpt
dabbrev rfc2104 network-stream nsm starttls tls gnutls mail-extr
smtpmail auth-source mailalias sendmail rmailout conf-mode arc-mode
archive-mode org-element org-rmail org-mhe org-irc org-info org-gnus
org-docview doc-view subr-x jka-compr image-mode org-bibtex bibtex
org-bbdb org-w3m org advice org-macro org-footnote org-pcomplete
pcomplete org-list org-faces org-entities org-version ob-emacs-lisp ob
ob-tangle ob-ref ob-lob ob-table ob-exp org-src ob-keys ob-comint
comint ansi-color ob-core ob-eval org-compat org-macs org-loaddefs
find-func cal-menu calendar cal-loaddefs bat-mode make-mode
vc-dispatcher vc-svn parse-time generic vc-cvs vc-bzr bug-reference
add-log info vc-git diff-mode noutline outline easy-mmode flyspell qp
rmailsum rmailmm message dired-x dired format-spec rfc822 mml mml-sec
password-cache epg epg-config gnus-util mm-decode mm-bodies mm-encode
mailabbrev gmm-utils mailheader mail-parse rfc2231 rmail rfc2047
rfc2045 ietf-drums mm-util help-fns mail-prsvr mail-utils desktop
frameset server filecache mairix cus-edit cus-start cus-load wid-edit
saveplace midnight ispell derived generic-x cc-mode cc-fonts cc-guess
cc-menus cc-cmds cc-styles cc-align cc-engine cc-vars cc-defs paren
xref cl-seq project ring eieio byte-opt bytecomp byte-compile cl-extra
help-mode easymenu cconv eieio-core cl-macs gv cl-loaddefs pcase
cl-lib battery time time-date mule-util tooltip eldoc electric
uniquify ediff-hook vc-hooks lisp-float-type mwheel dos-w32 ls-lisp
disp-table w32-win w32-vars term/common-win tool-bar dnd fontset image
regexp-opt fringe tabulated-list newcomment elisp-mode lisp-mode
prog-mode register page menu-bar rfn-eshadow timer select scroll-bar
mouse jit-lock font-lock syntax facemenu font-core frame cl-generic
cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet
lao korean japanese eucjp-ms cp51932 hebrew greek romanian slovak
czech european ethiopic indian cyrillic chinese charscript case-table
epa-hook jka-cmpr-hook help simple abbrev minibuffer cl-preloaded
nadvice loaddefs button faces cus-face macroexp files text-properties
overlay sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote w32notify w32 multi-tty
make-network-process emacs)

Memory information:
((conses 16 2191512 214963)
 (symbols 56 42474 0)
 (miscs 48 4368 4900)
 (strings 16 119103 35184)
 (string-bytes 1 3269321)
 (vectors 16 43592)
 (vector-slots 8 1676003 227839)
 (floats 8 540 910)
 (intervals 40 413698 11919)
 (buffers 856 230))

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

[Drew Adams]

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