master ae6af0b: Improve documentation of some tab-bar features

[Eli Zaretskii]

branch: master
commit ae6af0ba333ae02c872006af4e771f287c25447f
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    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.
---
 etc/NEWS        |  9 ++++++---
 lisp/tab-bar.el | 19 +++++++++++--------
 2 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 406a73b..ca269aa 100644
--- 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 faa155c..ab6595e 100644
--- 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."
 
 (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.