Improve documentation of some tab-bar features

* lisp/tab-bar.el (tab-bar-show, toggle-frame-tab-bar): Doc
fixes.

* etc/NEWS: Update the corresponding entries.

diff --git a/etc/NEWS b/etc/NEWS
index 406a73b0ae587b2a4406c58294d177a15639f4fe..ca269aabaa466d34f805f1c3706a39fd79180489 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -419,14 +419,17 @@ 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.
-You can show/hide the tab bar independently for each frame, according
-to the value of 'tab-bar-show'.
+*** Frame-specific appearance of the tab bar when 'tab-bar-show' is a number.
+When 'tab-bar-show' is a number, the tab bar on different frames can
+be shown or hidden independently, as determined by the number of tabs
+on each frame compared to the numerical value of 'tab-bar-show'.
 
 ---
 *** New command 'toggle-frame-tab-bar'.
 It can be used to enable/disable the tab bar on the currently selected
 frame regardless of the values of 'tab-bar-mode' and 'tab-bar-show'.
+This allows to enable/disable the tab bar independently on different
+frames.
 
 ---
 *** New user option 'tab-bar-format' defines a list of tab bar items.

diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index faa155c53fafcb3be5c20ed2065a591e47873202..ab6595e45e80b9666c1b01c55704da098c4e3854 100644 (file)
--- a/lisp/tab-bar.el
+++ b/lisp/tab-bar.el
@@ -303,9 +303,9 @@ See `tab-bar-mode' for more information."
   "Toggle tab bar of the selected frame.
 When calling from Lisp, use the optional argument FRAME to toggle
 the tab bar on that frame.
-This is useful when you want to enable the tab bar individually
+This is useful if you want to enable the tab bar individually
 on each new frame when the global `tab-bar-mode' is disabled,
-or when you want to disable the tab bar individually on each
+or if you want to disable the tab bar individually on each
 new frame when the global `tab-bar-mode' is enabled, by using
 
   (add-hook 'after-make-frame-functions 'toggle-frame-tab-bar)"
@@ -354,14 +354,17 @@ and to bind mouse events to the commands."
 \f
 (defcustom tab-bar-show t
   "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 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 t, the default, enable `tab-bar-mode' automatically upon using
+the commands that create new window configurations (e.g., `tab-new').
+If a non-negative integer, show the tab bar only if the number of
+the tabs exceeds 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.
+non-negative integer also makes the tab bar appearance be different
+on different frames: the tab bar can be shown on some frames and
+hidden on others, depending on how many tab-bar tabs are on that
+frame, and whether that number is greater than the numerical value
+of this variable.
 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.