master c5bdb28: Improve documentation of tab bars in the Emacs manual

[Eli Zaretskii]

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

    Improve documentation of tab bars in the Emacs manual
    
    * doc/emacs/frames.texi (Tab Bars): Improve wording, indexing, and
    cross-references.  Make sure each command is mentioned by its name
    when it is called out by the key sequence.  Index entries should
    precede @item lines in a @table.
---
 doc/emacs/frames.texi | 192 +++++++++++++++++++++++++++++++-------------------
 1 file changed, 118 insertions(+), 74 deletions(-)

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index a32181e..e238966 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -1281,19 +1281,22 @@ displayed by moving the mouse pointer to the top of the 
screen.
 @section Tab Bars
 @cindex tab bar mode
 @cindex mode, Tab Bar
-@cindex tabs, tabbar
+@cindex tabs, on the Tab Bar
 
   On graphical displays and on text terminals, Emacs can optionally
 display a @dfn{Tab Bar} at the top of each frame, just below the menu
-bar.  The Tab Bar is a row of @dfn{tabs}---buttons that you can click
-to switch between window configurations on that frame.
+bar (@pxref{Menu Bars}) and above the tool bar (@pxref{Tool Bars}).
+The Tab Bar is a row of @dfn{tabs}---buttons that you can click to
+switch between window configurations.
 
   Each tab on the Tab Bar represents a named persistent window
-configuration.  Its name is composed from the list of names of buffers
-visible in windows of that window configuration.  Clicking on the tab
-switches to the window configuration recorded by the tab; it is a
-configuration of windows and buffers which was previously used in the
-frame when that tab was the current tab.
+configuration of its frame, i.e., how that frame is partitioned into
+windows and which buffer is displayed in each window.  The tab's name
+is composed from the list of names of buffers shown in windows of that
+window configuration.  Clicking on the tab switches to the window
+configuration recorded by the tab; it is a configuration of windows
+and buffers which was previously used in the frame when that tab was
+the current tab.
 
   If you are using the desktop library to save and restore your
 sessions (@pxref{Saving Emacs Sessions}), the tabs from the Tab Bar are
@@ -1302,28 +1305,39 @@ configurations, and will be available after restoring 
the session.
 
 Note that the Tab Bar is different from the Tab Line (@pxref{Tab Line}).
 Whereas tabs on the Tab Line at the top of each window are used to
-switch between buffers, tabs on the Tab Bar at the top of each frame
-are used to switch between window configurations containing several
-windows with buffers.
+switch between buffers in the window, tabs on the Tab Bar at the top
+of each frame are used to switch between window configurations
+containing several windows showing one or more buffers.
 
 @findex tab-bar-mode
-  To toggle the use of tab bars, type @kbd{M-x tab-bar-mode}.  This
+  To toggle the use of Tab Bars, type @kbd{M-x tab-bar-mode}.  This
 command applies to all frames, including frames yet to be created.  To
 control the use of tab bars at startup, customize the variable
-@code{tab-bar-mode}.
+@code{tab-bar-mode} and save your customization.
+
+@findex toggle-frame-tab-bar
+  To toggle the use of the Tab Bar only on the selected frame, type
+@kbd{M-x toggle-frame-tab-bar}.  This command allows to enable the
+display of the Tab Bar on some frames and disable it on others.
 
 @vindex tab-bar-show
   The variable @code{tab-bar-show} controls whether the Tab Bar mode
 is turned on automatically.  If the value is @code{t}, then
 @code{tab-bar-mode} is enabled when using the commands that create new
 tabs.  The value @code{1} hides the tab bar when it has only one tab,
-and shows it again when more tabs are created.  The value @code{nil}
-always keeps the tab bar hidden; in this case it's still possible to
-switch between named window configurations without the tab bar by
-using @kbd{M-x tab-next}, @kbd{M-x tab-switcher}, and other commands
-that provide completion on tab names.  Also it's possible to create
-and close tabs without the tab bar by using commands @kbd{M-x
-tab-new}, @kbd{M-x tab-close}, etc.
+and shows it again when more tabs are created.  More generally, a
+value that is a non-negative integer causes the Tab Bar to be
+displayed only if the number of tabs is greater than that integer.
+The value @code{nil} always keeps the Tab Bar hidden; in this case
+it's still possible to switch between named window configurations
+without displaying the Tab Bar by using @kbd{M-x tab-next}, @kbd{M-x
+tab-switcher}, and other commands that provide completion on tab
+names.  Also it's possible to create and close tabs without the Tab
+Bar by using commands @kbd{M-x tab-new}, @kbd{M-x tab-close}, etc.
+
+  Note that a numerical value of @code{tab-bar-show} can cause the Tab
+Bar to be displayed on some frames, but not on others, depending on
+the number of tabs defined on each frame.
 
 @kindex C-x t
   The prefix key @kbd{C-x t} is analogous to @kbd{C-x 5}.
@@ -1336,29 +1350,41 @@ buffer to select.  The following commands can be used 
to select a buffer
 in a new tab:
 
 @table @kbd
-@item C-x t 2
 @kindex C-x t 2
 @findex tab-new
+@vindex tab-bar-tab-name-function
+@item C-x t 2
 Add a new tab (@code{tab-new}).  You can control the choice of the
 buffer displayed in a new tab by customizing the variable
-@code{tab-bar-new-tab-choice}.
+@code{tab-bar-new-tab-choice}.  You can control the names given by
+default to new tabs by customizing the variable
+@code{tab-bar-tab-name-function}.
 
+@kindex C-x t b
+@findex switch-to-buffer-other-tab
 @item C-x t b @var{bufname} @key{RET}
 Select buffer @var{bufname} in another tab.  This runs
 @code{switch-to-buffer-other-tab}.
 
+@kindex C-x t f
+@findex find-file-other-tab
 @item C-x t f @var{filename} @key{RET}
-Visit file @var{filename} and select its buffer in another tab.  This
-runs @code{find-file-other-tab}.  @xref{Visiting}.
+Visit the file @var{filename} (@pxref{Visiting}) and select its buffer
+in another tab.  This runs @code{find-file-other-tab}.
 
+@kindex C-x t d
+@findex dired-other-tab
 @item C-x t d @var{directory} @key{RET}
-Select a Dired buffer for directory @var{directory} in another tab.
-This runs @code{dired-other-tab}.  @xref{Dired}.
+Edit the specified @var{directory} (@pxref{Dired}) in another tab.
+This runs @code{dired-other-tab}.
 
+@kindex C-x t t
+@findex other-tab-prefix
 @item C-x t t
-A more general prefix command affects the buffer displayed by the next
-command invoked immediately after this prefix command.  It requests
-the buffer of the next command to be displayed in another tab.
+This is a prefix command (@code{other-tab-prefix}) that affects the
+next command invoked immediately after this prefix command.  It
+requests the buffer displayed by the next command to be shown in
+another tab.
 @end table
 
 @vindex tab-bar-new-tab-choice
@@ -1374,17 +1400,18 @@ By default, a new tab is added on the right side of the 
current tab.
   The following commands can be used to delete tabs:
 
 @table @kbd
-@item C-x t 0
 @kindex C-x t 0
 @findex tab-close
-Close the selected tab (@code{tab-close}).  It has no effect if there
+@vindex tab-bar-close-last-tab-choice
+@item C-x t 0
+Close the selected tab (@code{tab-close}).  This has no effect if there
 is only one tab, unless the variable @code{tab-bar-close-last-tab-choice}
 is customized to a non-default value.
 
-@item C-x t 1
 @kindex C-x t 1
 @findex tab-close-other
-Close all tabs on the selected frame, except the selected one.
+@item C-x t 1
+Close all tabs, except the selected tab, on the selected frame.
 @end table
 
 @vindex tab-bar-close-tab-select
@@ -1398,75 +1425,92 @@ a recently used tab.
   The following commands can be used to switch between tabs:
 
 @table @kbd
-@item C-x t o
-@itemx C-@key{TAB}
 @kindex C-x t o
 @kindex C-TAB
 @findex tab-next
-Switch to the next tab.  If you repeat this command, it cycles through
-all the tabs on the selected frame.  With a positive numeric argument
-@var{n}, it switches to the next @var{n}th tab; with a negative
-argument @minus{}@var{n}, it switches back to the previous @var{n}th
-tab.
+@item C-x t o
+@itemx C-@key{TAB}
+Switch to the next tab (@code{tab-next}).  If you repeat this command,
+it cycles through all the tabs on the selected frame.  With a positive
+numeric argument @var{n}, it switches to the @var{n}th next tab; with
+a negative argument @minus{}@var{n}, it switches back to the @var{n}th
+previous tab.
 
-@item S-C-@key{TAB}
 @kindex S-C-TAB
 @findex tab-previous
-Switch to the previous tab.  With a positive numeric argument @var{n},
-it switches to the previous @var{n}th tab; with a negative argument
-@minus{}@var{n}, it switches back to the next @var{n}th tab.
+@item S-C-@key{TAB}
+Switch to the previous tab (@code{tab-previous}).  With a positive
+numeric argument @var{n}, it switches to the @var{n}th previous tab;
+with a negative argument @minus{}@var{n}, it switches to the
+@var{n}th next tab.
 
+@kindex C-x t @key{RET}
+@findex tab-switch
 @item C-x t @key{RET} @var{tabname} @key{RET}
-Switch to the tab by its name, with completion on all tab names.
-Default values are tab names sorted by recency, so you can use
-@kbd{M-n} (@code{next-history-element}) to get the name of the last
-visited tab, the second last, and so on.
-
-@item @var{modifier}-@var{tabnumber}
+Switch to the tab by its name (@code{tab-switch}), with completion on
+all tab names.  History of used tab names is sorted by recency, so you
+can use @kbd{M-n} (@code{next-history-element}) to get the name of the
+last visited tab, the second last, and so on.
+
+@kindex C-1, tab bar
+@kindex C-9, tab bar
+@kindex M-1, tab bar
+@kindex M-9, tab bar
 @findex tab-select
-Switch to the tab by its number.  After customizing the variable
-@code{tab-bar-select-tab-modifiers} to specify a @var{modifier} key, you
-can select a tab by its ordinal number using the specified modifier in
-combination with the tab number to select.  To display the tab number
-alongside the tab name, you can customize another variable
-@code{tab-bar-tab-hints}.  This will help you to decide what key to press
-to select the tab by its number.
-
-@item @var{modifier}-@kbd{0}
+@vindex tab-bar-select-tab-modifiers
+@vindex tab-bar-tab-hints
+@item @var{modifier}-@var{tab-number}
+Switch to the tab by its number @var{tab-number} (@code{tab-select}).
+After customizing the variable @code{tab-bar-select-tab-modifiers} to
+specify one or more @var{modifier} keys, you can select a tab by its
+ordinal number using one of the specified modifiers in combination
+with the tab number to select.  You can select any modifiers supported
+by Emacs, @pxref{Modifier Keys}.  To display the tab number alongside
+the tab name, you can customize another variable
+@code{tab-bar-tab-hints}.  This will help you decide which numerical
+key to press to select the tab by its number.
+
+@kindex C-0, tab bar
+@kindex M-0, tab bar
 @findex tab-recent
-Switch to the recent tab.  The key combination is the modifier key
-defined by @code{tab-bar-select-tab-modifiers} and the key @kbd{0}.
-With a numeric argument @var{n}, switch to the @var{n}th recent tab.
+@item @var{modifier}-@kbd{0}
+Switch to the recent tab (@code{tab-recent}).  The key combination is
+the modifier key defined by @code{tab-bar-select-tab-modifiers} and
+the key @kbd{0}.  With a numeric argument @var{n}, switch to the
+@var{n}th recent tab.
 @end table
 
   The following commands can be used to operate on tabs:
 
 @table @kbd
-@item C-x t r @var{tabname} @key{RET}
+@kindex C-x t r
 @findex tab-rename
-Rename the current tab to @var{tabname}.  You can control the
-programmatic name given to a tab by default by customizing the
-variable @code{tab-bar-tab-name-function}.
+@item C-x t r @var{tabname} @key{RET}
+Rename the current tab to @var{tabname} (@code{tab-rename}).
 
-@item C-x t m
+@kindex C-x t m
 @findex tab-move
-Move the current tab @var{n} positions to the right with a positive
-numeric argument @var{n}.  With a negative argument @minus{}@var{n},
-move the current tab @var{n} positions to the left.
+@item C-x t m
+Move the current tab one position to the right (@code{tab-move}).
+With a positive numeric argument @var{n}, move it that many positions
+to the right; with a negative argument @minus{}@var{n}, move it
+@var{n} positions to the left.
 @end table
 
 @findex tab-bar-history-mode
   You can enable @code{tab-bar-history-mode} to remember window
-configurations used in every tab, and restore them.
+configurations used in every tab, and later restore them.
 
 @table @kbd
-@item tab-bar-history-back
+@findex tab-bar-history-back
+@item M-x tab-bar-history-back
 Restore a previous window configuration used in the current tab.
 This navigates back in the history of window configurations.
 
-@item tab-bar-history-forward
+@findex tab-bar-history-forward
+@item M-x tab-bar-history-forward
 Cancel restoration of the previous window configuration.
-This navigates forward in the history of window configurations.
+This moves forward in the history of window configurations.
 @end table
 
 @node Dialog Boxes