Improve documentation of tab-bar functions and variables

* etc/NEWS: Improve wording of tab-bar related entries.

* lisp/tab-bar.el (tab-bar-show, tab-bar-select-tab-modifiers):
Improve and clarify the doc strings.

diff --git a/etc/NEWS b/etc/NEWS
index ff4908af47b3540550ee64c7a7653e2472d92b91..416a51bd6390e75a09fb114d02f5633f97384256 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -403,13 +403,6 @@ both modes are on).
 
 ** Tab Bars and Tab Lines
 
-*** The tab bar now supports more mouse commands.
-Clicking 'mouse-2' closes the tab, 'mouse-3' displays the context menu
-with items that operate on the clicked tab.  Dragging the tab with
-'mouse-1' moves it to another position on the tab bar.  Mouse wheel
-scrolling switches to the previous/next tab, and holding the Shift key
-during scrolling moves the tab to the left/right.
-
 *** The prefix key 'C-x t t' can be used to display a buffer in a new tab.
 Typing 'C-x t t' before a command will cause the buffer shown by that
 command to be displayed in a new tab.  'C-x t t" is bound to the
@@ -418,10 +411,17 @@ command 'other-tab-prefix'.
 +++
 *** New command 'C-x t C-r' to open file read-only in the other tab.
 
+*** The tab bar now supports more mouse commands.
+Clicking 'mouse-2' closes the tab, 'mouse-3' displays the context menu
+with items that operate on the clicked tab.  Dragging the tab with
+'mouse-1' moves it to another position on the tab bar.  Mouse wheel
+scrolling switches to the previous/next tab, and holding the Shift key
+during scrolling moves the tab to the left/right.
+
 ---
 *** The tab bar is frame-local when 'tab-bar-show' is a number.
-Show/hide the tab bar independently for each frame, according to the
-value of 'tab-bar-show'.
+You can show/hide the tab bar independently for each frame, according
+to the value of 'tab-bar-show'.
 
 ---
 *** New command 'toggle-frame-tab-bar'.
@@ -438,8 +438,14 @@ When 'tab-bar-format-tabs' is replaced with 'tab-bar-format-tabs-groups',
 the tab bar displays tab groups.
 
 ---
-*** 'Mod-9' bound to 'tab-last' now switches to the last tab.
-It also supports a negative argument.
+*** New optional key binding for 'tab-last'.
+If you customize the variable 'tab-bar-select-tab-modifiers' for
+selecting tabs using its index numbers, the '<MODIFIER>-9' key is
+bound to 'tab-last', and switches to the last tab.  Here <MODIFIER> is
+any of the modifiers in the list that is the value of
+'tab-bar-select-tab-modifiers'.  You can also use negative indices,
+which count from the last tab: -1 is the last tab, -2 the one before
+that, etc.
 
 ---
 *** New command 'tab-duplicate' bound to 'C-x t n'.

diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index 63b1f15e09988894a9104fff0896b22dd6b4c671..faa155c53fafcb3be5c20ed2065a591e47873202 100644 (file)
--- a/lisp/tab-bar.el
+++ b/lisp/tab-bar.el
@@ -89,10 +89,13 @@
 
 \f
 (defcustom tab-bar-select-tab-modifiers '()
-  "List of modifier keys for selecting a tab by its index digit.
+  "List of modifier keys for selecting tab-bar tabs by index numbers.
 Possible modifier keys are `control', `meta', `shift', `hyper', `super' and
-`alt'.  To help you to select a tab by its number, you can customize
-`tab-bar-tab-hints' that will show tab numbers alongside the tab name."
+`alt'.  Presiing one of the modifiers in the list and a digit selects
+the tab whose index equals the digit.  Negative numbers count from
+the end of the tab bar.  The digit 9 selects the last (rightmost) tab.
+For easier selection of tabs by their numbers, consider customizing
+`tab-bar-tab-hints', which will show tab numbers alongside the tab name."
   :type '(set :tag "Tab selection modifier keys"
               (const control)
               (const meta)
@@ -353,8 +356,12 @@ and to bind mouse events to the commands."
   "Defines when to show the tab bar.
 If t, enable `tab-bar-mode' automatically on using the commands that
 create new window configurations (e.g. `tab-new').
-If the value is `1', then hide the tab bar when it has only one tab,
-and show it again once more tabs are created.
+If a non-negative integer, hide the tab bar when the number of the
+tabs does not exceed the value of this variable.  In particular,
+if the value is 1, hide the tab bar when it has only one tab, and
+show it again once more tabs are created.  A value that is a
+non-negative integer also makes the tab bar frame-local: the tab
+bar can be shown or hidden independently for each frame.
 If nil, always keep the tab bar hidden.  In this case it's still
 possible to use persistent named window configurations by relying on
 keyboard commands `tab-new', `tab-close', `tab-next', `tab-switcher', etc.