From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#24095: 25.1; Insufficient documentation of minibuffer-related variables Date: Thu, 28 Jul 2016 18:00:29 +0300 Message-ID: <83shutrenm.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: ger.gmane.org 1469719062 16595 80.91.229.3 (28 Jul 2016 15:17:42 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 28 Jul 2016 15:17:42 +0000 (UTC) To: 24095@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Jul 28 17:17:31 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1bSn3y-0005lD-60 for geb-bug-gnu-emacs@m.gmane.org; Thu, 28 Jul 2016 17:17:30 +0200 Original-Received: from localhost ([::1]:53891 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bSn3x-0003Ts-8g for geb-bug-gnu-emacs@m.gmane.org; Thu, 28 Jul 2016 11:17:29 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46028) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bSmo8-0004mM-TG for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2016 11:01:13 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bSmo2-0005Pc-Sa for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2016 11:01:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:52091) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bSmo2-0005PV-PR for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2016 11:01:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1bSmo2-0003CZ-JP for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2016 11:01:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Jul 2016 15:01:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 24095 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.146971805412282 (code B ref -1); Thu, 28 Jul 2016 15:01:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 28 Jul 2016 15:00:54 +0000 Original-Received: from localhost ([127.0.0.1]:49388 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bSmnt-0003C1-Is for submit@debbugs.gnu.org; Thu, 28 Jul 2016 11:00:53 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:54949) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bSmns-0003Bl-8a for submit@debbugs.gnu.org; Thu, 28 Jul 2016 11:00:52 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bSmnl-0005ND-Im for submit@debbugs.gnu.org; Thu, 28 Jul 2016 11:00:47 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:33911) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bSmnl-0005Mw-FO for submit@debbugs.gnu.org; Thu, 28 Jul 2016 11:00:45 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45902) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bSmni-0004OT-MA for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2016 11:00:44 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bSmnc-0005LS-N5 for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2016 11:00:41 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:45851) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bSmnc-0005LA-Is for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2016 11:00:36 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:4000 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1bSmnb-0004Dx-Pc for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2016 11:00:36 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:121621 Archived-At: 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))