4:23 a.m.
APPROVE COMMIT 21.5
The commit also adds a closed branch due to a duplicated patch. If
somebody knows how to clean these things up safely in Mercurial,
please let me know.
diff -r 9764d52c3fd9 lisp/ChangeLog
--- a/lisp/ChangeLog Mon Nov 13 23:19:01 2017 +0000
+++ b/lisp/ChangeLog Tue Nov 14 13:15:39 2017 +0900
＠＠ -26,6 +26,21 ＠＠
the same symbol name as the let binding, delay shadowing until all
bindings are processed.
+2017-10-26 Stephen J. Turnbull <stephen(a)xemacs.org>
+
+ * gutter-items.el (buffers-tab-omit-function):
+ (buffers-tab-omit-list):
+ (buffers-tab-selection-function):
+ (buffers-tab-filter-functions):
+ (buffers-tab-sort-function):
+ (buffers-tab-grouping-regexp):
+ (buffers-tab-format-buffer-line-function):
+ (format-buffers-tab-line):
+ (buffers-tab-items):
+ (add-tab-to-gutter):
+ (update-tab-in-gutter):
+ Clarify docstrings.
+
2017-10-12 Aidan Kehoe <kehoea(a)parhasard.net>
* frame.el (frame-utmost-window-2): Made into a label.
diff -r 9764d52c3fd9 lisp/gutter-items.el
--- a/lisp/gutter-items.el Mon Nov 13 23:19:01 2017 +0000
+++ b/lisp/gutter-items.el Tue Nov 14 13:15:39 2017 +0900
＠＠ -69,18 +69,18 ＠＠
:group 'buffers-tab)
(defcustom buffers-tab-omit-function 'buffers-tab-omit-some-buffers
- "*If non-nil, a function specifying the buffers to omit from the buffers tab.
+ "*If non-nil, a predicate matching buffers to omit from the buffers tab.
This is passed a buffer and should return non-nil if the buffer should be
omitted. The default value `buffers-tab-omit-some-buffers' omits
-buffers based on the value of `buffers-tab-omit-list'."
+buffers with names matched by any regexp in `buffers-tab-omit-list'."
:type '(choice (const :tag "None" nil)
function)
:group 'buffers-tab)
(defcustom buffers-tab-omit-list '("\\` ")
- "*A list of types of buffers to omit from the buffers tab.
-This is only used if `buffers-tab-omit-function' is set to
-`buffers-tab-omit-some-buffers', its default value."
+ "*A list of regexps matching names of buffers to omit from the buffers tab.
+This is used by `buffers-tab-omit-some-buffers' \(the default value of
+`buffers-tab-omit-function')."
:type '(checklist
:greedy t
:format "%{Omit List%}: \n%v"
＠＠ -102,8 +102,9 ＠＠
:group 'buffers-tab)
(defvar buffers-tab-selection-function 'select-buffers-tab-buffers-by-mode
- "*If non-nil, a function specifying the buffers to select in the
-buffers tab. This is passed two buffers and should return non-nil if
+ "*If non-nil, a predicate selecting buffers eligible for the buffers tab.
+
+This is passed a buffer to test and a comparison buffer, returning non-nil if
the first buffer should be selected. The default value
`select-buffers-tab-buffers-by-mode' groups buffers by major mode and
by `buffers-tab-grouping-regexp'.")
＠＠ -112,12 +113,12 ＠＠
"Set `buffers-tab-filter-functions' instead.")
(defcustom buffers-tab-filter-functions (list 'select-buffers-tab-buffers-by-mode)
- "*A list of functions specifying buffers to display in the buffers tab.
+ "*A list of predicates selecting buffers eligible for the buffers tab.
If nil, all buffers are kept, up to `buffers-tab-max-size', in usual order.
Otherwise, each function in the list must take arguments (BUF1 BUF2).
-BUF1 is the candidate, and BUF2 is the current buffer (first in the buffers
-list). The function should return non-nil if BUF1 should be added to the
+BUF1 is the candidate, and BUF2 is a comparison buffer \(usually the current
+buffer). The function returns non-nil to request that BUF1 be added to the
buffers tab. BUF1 will be omitted if any of the functions returns nil.
Defaults to `select-buffers-tab-buffers-by-mode', which adds BUF1 if BUF1 and
＠＠ -127,10 +128,11 ＠＠
:group 'buffers-tab)
(defcustom buffers-tab-sort-function nil
- "*If non-nil, a function specifying the buffers to select from the
-buffers tab. This is passed the buffer list and returns the list in the
-order desired for the tab widget. The default value `nil' leaves the
-list in `buffer-list' order (usual most-recently-selected-first)."
+ "*If non-nil, a function specifying precedence of buffers in the buffers tab.
+
+This is passed the buffer list and returns the list in the order desired for
+the tab widget. The default value `nil' leaves the list in `buffer-list'
+order (usual most-recently-selected-first)."
:type '(choice (const :tag "None" nil)
function)
＠＠ -148,21 +150,20 ＠＠
'("^\\(gnus-\\|message-mode\\|mime/viewer-mode\\)"
"^\\(emacs-lisp-\\|lisp-\\)")
"*If non-nil, a list of regular expressions for buffer grouping.
-Each regular expression is applied to the current major-mode symbol
-name and mode-name, if it matches then any other buffers that match
-the same regular expression be added to the current group."
+
+If two buffers' modes or mode names both are matched by any regular expression
+in the list, they are considered equivalent when selecting buffers by major
+mode."
:type '(choice (const :tag "None" nil)
sexp)
:group 'buffers-tab)
(defcustom buffers-tab-format-buffer-line-function 'format-buffers-tab-line
- "*The function to call to return a string to represent a buffer in the
-buffers tab. The function is passed a buffer and should return a
-string. The default value `format-buffers-tab-line' just returns the
-name of the buffer, optionally truncated to
-`buffers-tab-max-buffer-line-length'. Also check out
-`slow-format-buffers-menu-line' which returns a whole bunch of info
-about a buffer."
+ "*A function returning a string representing the buffer passed.
+
+The default value `format-buffers-tab-line' returns the name of the buffer,
+truncated to `buffers-tab-max-buffer-line-length'. An alternative is
+`slow-format-buffers-menu-line' which returns more info about the buffer."
:type 'function
:group 'buffers-tab)
＠＠ -228,8 +229,9 ＠＠
(t nil))))
(defun format-buffers-tab-line (buffer)
- "For use as a value of `buffers-tab-format-buffer-line-function'.
-This just returns the buffer's name, optionally truncated."
+ "Return BUFFER's name, truncated to
`buffers-tab-default-buffer-line-length'.
+For use as a value of `buffers-tab-format-buffer-line-function'."
+
(let* ((len (specifier-instance buffers-tab-default-buffer-line-length))
(buffer-name (buffer-name buffer))
(length (length buffer-name)))
＠＠ -247,21 +249,27 ＠＠
;;; cumulative --andyp.
(defun buffers-tab-items (&optional in-deletion frame force-selection)
"Return a list of tab instantiators based on the current buffers list.
-This function is used as the tab filter for the top-level buffers
-\"Buffers\" tab. It dynamically creates a list of tab instantiators
-to use as the contents of the tab. The contents and order of the list
-is controlled by `buffers-tab-filter-functions' which by default
-groups buffers according to major mode and removes invisible buffers.
-You can control how many buffers will be shown by setting
-`buffers-tab-max-size'. You can control the text of the tab items by
-redefining the function `format-buffers-menu-line'."
+
+This is the tab filter for the top-level buffers \"Buffers\" tab.
+It dynamically creates a list of tab instantiators to use as the contents of
+the tab. The contents and order of the list is controlled by
+`buffers-tab-filter-functions' which by default groups buffers according to
+major mode and removes invisible buffers. At most `buffers-tab-max-size'
+tabs will be added to the control. The label for each tab is produced by
+`format-buffers-menu-line'.
+
+Optional IN-DELETION is an internal flag indicating a buffer is being deleted.
+Optional FRAME is the frame whose buffer list is used, defaulting to the
+selected frame.
+Optional FORCE-SELECTION makes the currently selected window first in list."
(save-match-data
;; NB it is too late if we run the omit function as part of the
;; filter functions because we need to know which buffer is the
;; context buffer before they get run.
(let* ((buffers (delete-if
buffers-tab-omit-function (buffer-list frame)))
- (first-buf (car buffers)) tail)
+ (first-buf (car buffers))
+ tail)
;; maybe force the selected window
(when (and force-selection
(not in-deletion)
＠＠ -309,7 +317,7 ＠＠
(build-buffers-tab-internal buffers)))))
(defun add-tab-to-gutter ()
- "Put a tab control in the gutter area to hold the most recent buffers."
+ "Put a tab control in the gutter area to select buffers."
(setq gutter-buffers-tab-orientation (default-gutter-position))
(let* ((gutter-string (copy-sequence "\n"))
(gutter-buffers-tab-extent (make-extent 0 1 gutter-string)))
＠＠ -344,8 +352,8 ＠＠
x)))))))
(defun update-tab-in-gutter (frame &optional force-selection)
- "Update the tab control in the gutter area."
- ;; dedicated frames don't get tabs
+ "Update the tab control in the gutter area.
+Optional FORCE-SELECTION makes the currently selected window first in list." ;;
dedicated frames don't get tabs
(unless (or (window-dedicated-p (frame-selected-window frame))
(frame-property frame 'popup))
(when (specifier-instance default-gutter-visible-p frame)