From 686a03ee222071d7efdca07ccf09ddfff94aa87c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 17 Oct 2021 11:42:23 +0300 Subject: [PATCH] More documentation fixes in tab-bar.el * lisp/tab-bar.el (tab-bar-detach-tab, tab-bar-move-window-to-tab) (tab-bar-new-tab-to, tab-bar-new-tab, tab-bar-close-tab-select) (tab-bar-close-last-tab-choice, tab-bar-tab-pre-close-functions) (tab-bar-close-tab, tab-bar-close-tab-by-name) (tab-bar-close-other-tabs, tab-bar-rename-tab) (tab-bar-rename-tab-by-name, tab-bar-move-tab-to-group) (tab-bar-change-tab-group, tab-bar-close-group-tabs) (tab-switcher-next-line, tab-switcher-prev-line) (tab-switcher-unmark, tab-switcher-delete, tab-switcher-select) (tab-bar-get-buffer-tab, display-buffer-in-tab) (display-buffer-in-new-tab, switch-to-buffer-other-tab) (find-file-other-tab, find-file-read-only-other-tab): Doc fixes. --- lisp/tab-bar.el | 106 +++++++++++++++++++++++++++++------------------- 1 file changed, 65 insertions(+), 41 deletions(-) diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el index 63ab932ac0a..85f947f598c 100644 --- a/lisp/tab-bar.el +++ b/lisp/tab-bar.el @@ -1227,7 +1227,7 @@ to which to move the tab; ARG defaults to 1." (defun tab-bar-detach-tab (&optional from-number) "Move tab number FROM-NUMBER to a new frame. -Interactively or without argument, move the current tab." +FROM-NUMBER defaults to the current tab (which happens interactively." (interactive (list (1+ (tab-bar--current-tab-index)))) (let* ((tabs (funcall tab-bar-tabs-function)) (tab-index (1- (or from-number (1+ (tab-bar--current-tab-index tabs))))) @@ -1241,7 +1241,10 @@ Interactively or without argument, move the current tab." (tab-bar-close-tab)))) (defun tab-bar-move-window-to-tab () - "Detach the selected window to a new tab." + "Move the selected window to a new tab. +This command removes the selected window from the configuration stored +on the current tab, and makes a new tab with that window in its +configuration." (interactive) (let ((tab-bar-new-tab-choice 'window)) (tab-bar-new-tab)) @@ -1251,17 +1254,17 @@ Interactively or without argument, move the current tab." (defcustom tab-bar-new-tab-to 'right - "Defines where to create a new tab. + "Where to create a new tab. If `leftmost', create as the first tab. -If `left', create to the left from the current tab. -If `right', create to the right from the current tab. +If `left', create to the left of the current tab. +If `right', create to the right of the current tab. If `rightmost', create as the last tab. If the value is a function, it should return a number as a position on the tab bar specifying where to insert a new tab." - :type '(choice (const :tag "First tab" leftmost) - (const :tag "To the left" left) - (const :tag "To the right" right) - (const :tag "Last tab" rightmost) + :type '(choice (const :tag "Insert first" leftmost) + (const :tag "Insert left" left) + (const :tag "Insert right" right) + (const :tag "Insert last" rightmost) (function :tag "Function")) :group 'tab-bar :version "27.1") @@ -1280,7 +1283,7 @@ TAB-NUMBER counts from 1. If no TAB-NUMBER is specified, then add a new tab at the position specified by `tab-bar-new-tab-to'. Negative TAB-NUMBER counts tabs from the end of the tab bar, and -1 means the new tab will become the last one. -Argument addressing is absolute in contrast to `tab-bar-new-tab' +Argument addressing is absolute in contrast to `tab-bar-new-tab', where argument addressing is relative. After the tab is created, the hooks in `tab-bar-tab-post-open-functions' are run." @@ -1353,7 +1356,7 @@ If a negative ARG, create a new tab ARG positions to the left. If ARG is zero, create a new tab in place of the current tab. If no ARG is specified, then add a new tab at the position specified by `tab-bar-new-tab-to'. -Argument addressing is relative in contrast to `tab-bar-new-tab-to' +Argument addressing is relative in contrast to `tab-bar-new-tab-to', where argument addressing is absolute. If FROM-NUMBER is a tab number, a new tab is created from that tab." (interactive "P") @@ -1380,7 +1383,7 @@ ARG and FROM-NUMBER have the same meaning as in `tab-bar-new-tab'." "A list of closed tabs to be able to undo their closing.") (defcustom tab-bar-close-tab-select 'recent - "Defines what tab to select after closing the specified tab. + "Which tab to make current after closing the specified tab. If `left', select the adjacent left tab. If `right', select the adjacent right tab. If `recent', select the most recently visited tab." @@ -1391,7 +1394,7 @@ If `recent', select the most recently visited tab." :version "27.1") (defcustom tab-bar-close-last-tab-choice nil - "Defines what to do when the last tab is closed. + "What to do when the last tab is closed. If nil, do nothing and show a message, like closing the last window or frame. If `delete-frame', delete the containing frame, as a web browser would do. If `tab-bar-mode-disable', disable `tab-bar-mode' so that tabs no longer show @@ -1416,9 +1419,8 @@ function returns a non-nil value, the tab will not be closed." (defcustom tab-bar-tab-pre-close-functions nil "List of functions to call before closing a tab. -The tab to be closed and a boolean indicating whether or not it -is the only tab in the frame are supplied as arguments, -respectively." +Each function is called with two arguments: the tab to be closed +and a boolean indicating whether or not it is the only tab on its frame." :type '(repeat function) :group 'tab-bar :version "27.1") @@ -1427,6 +1429,7 @@ respectively." "Close the tab specified by its absolute position TAB-NUMBER. If no TAB-NUMBER is specified, then close the current tab and switch to the tab specified by `tab-bar-close-tab-select'. +Interactively, TAB-NUMBER is the prefix numeric argument, and defaults to 1. TAB-NUMBER counts from 1. Optional TO-NUMBER could be specified to override the value of `tab-bar-close-tab-select' programmatically with a position @@ -1500,7 +1503,8 @@ for the last tab on a frame is determined by (message "Deleted tab and switched to %s" tab-bar-close-tab-select)))))) (defun tab-bar-close-tab-by-name (name) - "Close the tab by NAME." + "Close the tab given its NAME. +Interactively, prompt for NAME." (interactive (list (completing-read "Close tab by name: " (mapcar (lambda (tab) @@ -1509,8 +1513,9 @@ for the last tab on a frame is determined by (tab-bar-close-tab (1+ (tab-bar--tab-index-by-name name)))) (defun tab-bar-close-other-tabs (&optional tab-number) - "Close all tabs on the selected frame, except TAB-NUMBER. -TAB-NUMBER counts from 1 and defaults to the current tab." + "Close all tabs on the selected frame, except the tab TAB-NUMBER. +TAB-NUMBER counts from 1 and defaults to the current tab (which +happens interactively)." (interactive) (let* ((tabs (funcall tab-bar-tabs-function)) (current-index (tab-bar--current-tab-index tabs)) @@ -1576,9 +1581,12 @@ TAB-NUMBER counts from 1 and defaults to the current tab." (defun tab-bar-rename-tab (name &optional tab-number) - "Rename the tab specified by its absolute position TAB-NUMBER. + "Give the tab specified by its absolute position TAB-NUMBER a new NAME. If no TAB-NUMBER is specified, then rename the current tab. +Interactively, TAB-NUMBER is the prefix numeric argument, and defaults +to the current tab. TAB-NUMBER counts from 1. +Interactively, prompt for the new NAME. If NAME is the empty string, then use the automatic name function `tab-bar-tab-name-function'." (interactive @@ -1606,7 +1614,8 @@ function `tab-bar-tab-name-function'." (message "Renamed tab to '%s'" tab-new-name)))) (defun tab-bar-rename-tab-by-name (tab-name new-name) - "Rename the tab named TAB-NAME. + "Rename the tab named TAB-NAME to NEW-NAME. +Interactively, prompt for TAB-NAME and NEW-NAME. If NEW-NAME is the empty string, then use the automatic name function `tab-bar-tab-name-function'." (interactive @@ -1623,7 +1632,7 @@ function `tab-bar-tab-name-function'." ;;; Tab groups (defun tab-bar-move-tab-to-group (&optional tab) - "Relocate TAB (or the current tab) closer to its group." + "Relocate TAB (default: the current tab) closer to its group." (interactive) (let* ((tabs (funcall tab-bar-tabs-function)) (tab (or tab (tab-bar--current-tab-find tabs))) @@ -1661,6 +1670,8 @@ The current tab is supplied as an argument." (defun tab-bar-change-tab-group (group-name &optional tab-number) "Add the tab specified by its absolute position TAB-NUMBER to GROUP-NAME. If no TAB-NUMBER is specified, then set the GROUP-NAME for the current tab. +Interactively, TAB-NUMBER is the prefix numeric argument, and the command +prompts for GROUP-NAME. TAB-NUMBER counts from 1. If GROUP-NAME is the empty string, then remove the tab from any group. While using this command, you might also want to replace @@ -1698,7 +1709,8 @@ While using this command, you might also want to replace (message "Set tab group to '%s'" group-new-name)))) (defun tab-bar-close-group-tabs (group-name) - "Close all tabs that belong to GROUP-NAME on the selected frame." + "Close all tabs that belong to GROUP-NAME on the selected frame. +Interactively, prompt for GROUP-NAME." (interactive (let ((group-name (funcall tab-bar-tab-group-function (tab-bar--current-tab-find)))) @@ -1745,7 +1757,7 @@ While using this command, you might also want to replace (defun tab-bar--history-pre-change () (setq tab-bar-history-old-minibuffer-depth (minibuffer-depth)) - ;; Store wc before possibly entering the minibuffer + ;; Store window-configuration before possibly entering the minibuffer. (when (zerop tab-bar-history-old-minibuffer-depth) (setq tab-bar-history-old `((wc . ,(current-window-configuration)) @@ -1754,7 +1766,8 @@ While using this command, you might also want to replace (defun tab-bar--history-change () (when (and (not tab-bar-history-omit) tab-bar-history-old - ;; Store wc before possibly entering the minibuffer + ;; Store window-configuration before possibly entering + ;; the minibuffer. (zerop tab-bar-history-old-minibuffer-depth)) (puthash (selected-frame) (seq-take (cons tab-bar-history-old @@ -1946,12 +1959,16 @@ Letters do not insert themselves; instead, they are commands. nil)))) (defun tab-switcher-next-line (&optional arg) + "Move to ARGth next line in the list of tabs. +Interactively, ARG is the prefix numeric argument and defaults to 1." (interactive "p") (forward-line arg) (beginning-of-line) (move-to-column tab-switcher-column)) (defun tab-switcher-prev-line (&optional arg) + "Move to ARGth previous line in the list of tabs. +Interactively, ARG is the prefix numeric argument and defaults to 1." (interactive "p") (forward-line (- arg)) (beginning-of-line) @@ -1959,7 +1976,7 @@ Letters do not insert themselves; instead, they are commands. (defun tab-switcher-unmark (&optional backup) "Cancel requested operations on window configuration on this line and move down. -Optional prefix arg means move up." +With prefix arg, move up instead." (interactive "P") (beginning-of-line) (move-to-column tab-switcher-column) @@ -1979,7 +1996,7 @@ Optional prefix arg means move up." (defun tab-switcher-delete (&optional arg) "Mark window configuration on this line to be deleted by \\\\[tab-switcher-execute] command. -Prefix arg is how many window configurations to delete. +Prefix arg says how many window configurations to delete. Negative arg means delete backwards." (interactive "p") (let ((buffer-read-only nil)) @@ -2032,8 +2049,8 @@ Then move up one line. Prefix arg means move that many lines." (defun tab-switcher-select () "Select this line's window configuration. -This command deletes and replaces all the previously existing windows -in the selected frame." +This command replaces all the existing windows in the selected frame +with those specified by the selected window configuration." (interactive) (let* ((to-tab (tab-switcher-current-tab t))) (kill-buffer (current-buffer)) @@ -2059,8 +2076,8 @@ in the selected frame." (t (list (selected-frame))))) (defun tab-bar-get-buffer-tab (buffer-or-name &optional all-frames ignore-current-tab) - "Return a tab owning a window whose buffer is BUFFER-OR-NAME. -BUFFER-OR-NAME may be a buffer or a buffer name and defaults to + "Return the tab that owns the window whose buffer is BUFFER-OR-NAME. +BUFFER-OR-NAME may be a buffer or a buffer name, and defaults to the current buffer. The optional argument ALL-FRAMES specifies the frames to consider: @@ -2108,7 +2125,7 @@ Otherwise, prefer buffers of the current tab." (tab-bar--reusable-frames all-frames))))) (defun display-buffer-in-tab (buffer alist) - "Display BUFFER in a tab. + "Display BUFFER in a tab using display actions in ALIST. ALIST is an association list of action symbols and values. See Info node `(elisp) Buffer Display Action Alists' for details of such alists. @@ -2116,8 +2133,8 @@ such alists. If ALIST contains a `tab-name' entry, it creates a new tab with that name and displays BUFFER in a new tab. If a tab with this name already exists, it switches to that tab before displaying BUFFER. The `tab-name' entry can be -a function, then it is called with two arguments: BUFFER and ALIST, and -should return the tab name. When a `tab-name' entry is omitted, create +a function, in which case it is called with two arguments: BUFFER and ALIST, +and should return the tab name. When a `tab-name' entry is omitted, create a new tab without an explicit name. The ALIST entry `tab-group' (string or function) defines the tab group. @@ -2167,7 +2184,7 @@ indirectly called by the latter." (display-buffer-in-new-tab buffer alist)))))) (defun display-buffer-in-new-tab (buffer alist) - "Display BUFFER in a new tab. + "Display BUFFER in a new tab using display actions in ALIST. ALIST is an association list of action symbols and values. See Info node `(elisp) Buffer Display Action Alists' for details of such alists. @@ -2177,9 +2194,9 @@ without checking if a suitable tab already exists. If ALIST contains a `tab-name' entry, it creates a new tab with that name and displays BUFFER in a new tab. The `tab-name' entry can be a function, -then it is called with two arguments: BUFFER and ALIST, and should return -the tab name. When a `tab-name' entry is omitted, create a new tab without -an explicit name. +in which case it is called with two arguments: BUFFER and ALIST, and should +return the tab name. When a `tab-name' entry is omitted, create a new tab +without an explicit name. The ALIST entry `tab-group' (string or function) defines the tab group. @@ -2203,7 +2220,8 @@ indirectly called by the latter." (defun switch-to-buffer-other-tab (buffer-or-name &optional norecord) "Switch to buffer BUFFER-OR-NAME in another tab. -Like \\[switch-to-buffer-other-frame] (which see), but creates a new tab." +Like \\[switch-to-buffer-other-frame] (which see), but creates a new tab. +Interactively, prompt for the buffer to switch to." (interactive (list (read-buffer-to-switch "Switch to buffer in other tab: "))) (display-buffer (window-normalize-buffer-to-switch-to buffer-or-name) @@ -2213,7 +2231,10 @@ Like \\[switch-to-buffer-other-frame] (which see), but creates a new tab." (defun find-file-other-tab (filename &optional wildcards) "Edit file FILENAME, in another tab. -Like \\[find-file-other-frame] (which see), but creates a new tab." +Like \\[find-file-other-frame] (which see), but creates a new tab. +Interactively, prompt for FILENAME. +If WILDCARDS is non-nil, FILENAME can include widcards, and all matching +files will be visited." (interactive (find-file-read-args "Find file in other tab: " (confirm-nonexistent-file-or-buffer))) @@ -2230,7 +2251,10 @@ Like \\[find-file-other-frame] (which see), but creates a new tab." "Edit file FILENAME, in another tab, but don't allow changes. Like \\[find-file-other-frame] (which see), but creates a new tab. Like \\[find-file-other-tab], but marks buffer as read-only. -Use \\[read-only-mode] to permit editing." +Use \\[read-only-mode] to permit editing. +Interactively, prompt for FILENAME. +If WILDCARDS is non-nil, FILENAME can include widcards, and all matching +files will be visited." (interactive (find-file-read-args "Find file read-only in other tab: " (confirm-nonexistent-file-or-buffer))) -- 2.39.2