emacs-27 692ad40: Improve the documentation of tab-bar and tab-line

[Juri Linkov]

branch: emacs-27
commit 692ad40539805e435a16b90067fa5917e4fea9f8
Author: Juri Linkov <address@hidden>
Commit: Juri Linkov <address@hidden>

    Improve the documentation of tab-bar and tab-line
    
    * doc/emacs/frames.texi (Tab Bars): Add xref to "Tab Line".
    Document more commands.
    
    * doc/emacs/windows.texi (Windows):
    * doc/emacs/emacs.texi (Top): Add "Tab Line" menu.
    
    * doc/emacs/windows.texi (Window Convenience):
    Move tab-line documentation to new node "Tab Line".
    (Tab Line): New node.
    
    * doc/emacs/glossary.texi (Glossary):
    * doc/emacs/modes.texi (Minor Modes):
    * doc/emacs/display.texi (Standard Faces): Add xref to "Tab Line".
---
 doc/emacs/display.texi  |  1 +
 doc/emacs/emacs.texi    |  1 +
 doc/emacs/frames.texi   | 62 ++++++++++++++++++++++++++++++++++++++-----------
 doc/emacs/glossary.texi |  2 +-
 doc/emacs/misc.texi     |  2 +-
 doc/emacs/modes.texi    |  2 +-
 doc/emacs/windows.texi  | 37 +++++++++++++++++++++--------
 etc/NEWS                | 12 ++++++++--
 8 files changed, 90 insertions(+), 29 deletions(-)

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 4273357..d98441b 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -735,6 +735,7 @@ in a way that does not interact well with @code{highlight}.
 @cindex @code{tab-line} face
 Similar to @code{mode-line} for a window's tab line, which appears
 at the top of a window with tabs representing window buffers.
+@xref{Tab Line}.
 @item vertical-border
 @cindex @code{vertical-border} face
 This face is used for the vertical divider between windows on text
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 60f2be9..6b82aeb 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -517,6 +517,7 @@ Multiple Windows
 * Displaying Buffers::  How Emacs picks a window for displaying a buffer.
 * Temporary Displays::  Displaying non-editable buffers.
 * Window Convenience::  Convenience functions for window handling.
+* Tab Line::            Window tab line.
 
 Displaying a Buffer in a Window
 
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 9421842..d9373b8 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -1262,6 +1262,12 @@ sessions (@pxref{Saving Emacs Sessions}), the tabs from 
the Tab Bar are
 recorded in the desktop file, together with their associated window
 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.
+
 @findex tab-bar-mode
   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
@@ -1275,9 +1281,11 @@ is turned on automatically.  If the value is @code{t}, 
then
 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
-use persistent named window configurations without using the tab bar
-by typing the related commands: @kbd{M-x tab-new}, @kbd{M-x tab-next},
-@kbd{M-x tab-close}, @kbd{M-x tab-switcher}, etc.
+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.
 
 @kindex C-x t
   The prefix key @kbd{C-x t} is analogous to @kbd{C-x 5}.
@@ -1286,7 +1294,8 @@ Whereas each @kbd{C-x 5} command pops up a buffer in a 
different frame
 tab with a different window configuration in the selected frame.
 
   The various @kbd{C-x t} commands differ in how they find or create the
-buffer to select:
+buffer to select.  The following commands can be used to select a buffer
+in a new tab:
 
 @table @kbd
 @item C-x t 2
@@ -1295,19 +1304,18 @@ buffer to select:
 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}.
+
 @item C-x t b @var{bufname} @key{RET}
 Select buffer @var{bufname} in another tab.  This runs
 @code{switch-to-buffer-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}.
+
 @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}.
-@item C-x t r @var{tabname} @key{RET}
-Renames 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}.
 @end table
 
 @vindex tab-bar-new-tab-choice
@@ -1316,7 +1324,7 @@ current before calling the command that adds a new tab.
 To start a new tab with other buffers, customize the variable
 @code{tab-bar-new-tab-choice}.
 
-  The following commands are used to delete and operate on tabs:
+  The following commands can be used to delete tabs:
 
 @table @kbd
 @item C-x t 0
@@ -1325,19 +1333,45 @@ To start a new tab with other buffers, customize the 
variable
 Close the selected tab (@code{tab-close}).  It has no effect if there
 is only one tab.
 
+@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.
+@end table
+
+  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 another tab.  If you repeat this command, it cycles through
+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
 N, it switches to the next Nth tab; with a negative argument −N, it
 switches back to the previous Nth tab.
 
-@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 S-C-@key{TAB}
+@kindex S-C-TAB
+@findex tab-previous
+Switch to the previous tab.  With a positive numeric argument N, it
+switches to the previous Nth tab; with a negative argument −N, it
+switches back to the next Nth tab.
+@end table
+
+  The following commands can be used to operate on tabs:
+
+@table @kbd
+@item C-x t r @var{tabname} @key{RET}
+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 m
+Move the current tab N positions to the right with a positive numeric
+argument N.  With a negative argument −N, it moves the current tab
+N positions to the left.
 @end table
 
 @node Dialog Boxes
diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi
index 416431b..4d622ec 100644
--- a/doc/emacs/glossary.texi
+++ b/doc/emacs/glossary.texi
@@ -1367,7 +1367,7 @@ configurations.  @xref{Tab Bars}.
 
 @item Tab Line
 The tab line is a line of tabs at the top of an Emacs window.
-Clicking on one of these tabs switches window buffers.
+Clicking on one of these tabs switches window buffers.  @xref{Tab Line}.
 
 @anchor{Glossary---Tags Table}
 @item Tags Table
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index a15aa17..dceb8d3 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -791,7 +791,7 @@ the same number of columns as provided by the shell.
 @vindex shell-command-prompt-show-cwd
   To make the above commands show the current directory in their
 prompts, customize the variable @code{shell-command-prompt-show-cwd}
-to a non-nil value.
+to a non-@code{nil} value.
 
 @kindex M-|
 @findex shell-command-on-region
diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index 92d60d2..f5fb6b1 100644
--- a/doc/emacs/modes.texi
+++ b/doc/emacs/modes.texi
@@ -299,7 +299,7 @@ Bars}.
 Tab Bar mode gives each frame a tab bar.  @xref{Tab Bars}.
 
 @item
-Tab Line mode gives each window a tab line.
+Tab Line mode gives each window a tab line.  @xref{Tab Line}.
 
 @item
 Transient Mark mode highlights the region, and makes many Emacs
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 910ef8f..cb5e9bc 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -21,6 +21,7 @@ one frame.
 * Change Window::       Deleting windows and changing their sizes.
 * Displaying Buffers::  How Emacs picks a window for displaying a buffer.
 * Window Convenience::  Convenience functions for window handling.
+* Tab Line::            Window tab line.
 @end menu
 
 @node Basic Window
@@ -542,16 +543,6 @@ Reference Manual}), and cannot exceed the size of the 
containing frame.
 @node Window Convenience
 @section Convenience Features for Window Handling
 
-@findex global-tab-line-mode
-@cindex tab line
-  The command @code{global-tab-line-mode} toggles the display of a
-@dfn{tab line} on the top screen line of each window.  The tab line
-shows special buttons (``tabs'') for each buffer that was displayed in
-a window, and allows switching to any of these buffers by clicking the
-corresponding button.  You can add a tab by clicking on the @kbd{+}
-icon and delete a tab by clicking on the @kbd{x} icon of a tab.  The
-mouse wheel on the tab line scrolls the tabs horizontally.
-
 @findex winner-mode
 @vindex winner-dont-bind-my-keys
 @vindex winner-ring-size
@@ -616,3 +607,29 @@ shown in different windows.  @xref{Comparing Files}.
   Scroll All mode (@kbd{M-x scroll-all-mode}) is a global minor mode
 that causes scrolling commands and point motion commands to apply to
 every single window.
+
+
+@node Tab Line
+@section Window Tab Line
+
+@findex global-tab-line-mode
+@cindex tab line
+  The command @code{global-tab-line-mode} toggles the display of
+a @dfn{tab line} on the top screen line of each window.  The Tab Line
+shows special buttons (``tabs'') for each buffer that was displayed in
+a window, and allows switching to any of these buffers by clicking the
+corresponding button.  Clicking on the @kbd{+} icon adds a new buffer
+to the window-local tab line of buffers, and clicking on the @kbd{x}
+icon of a tab deletes it.  The mouse wheel on the tab line scrolls
+the tabs horizontally.
+
+Selecting the previous window-local tab is the same as typing @kbd{C-x
+@key{LEFT}} (@code{previous-buffer}), selecting the next tab is the
+same as @kbd{C-x @key{RIGHT}} (@code{next-buffer}).  Both commands
+support a numeric prefix argument as a repeat count.
+
+Note that the Tab Line is different from the Tab Bar (@pxref{Tab Bars}).
+Whereas tabs on the Tab Bar at the top of each frame are used to
+switch between window configurations containing several windows,
+tabs on the Tab Line at the top of each window are used to switch
+between buffers.
diff --git a/etc/NEWS b/etc/NEWS
index 091c831..fe8a8d8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2720,8 +2720,8 @@ left to higher-level functions.
 +++
 *** Tab Bar mode
 The new command 'tab-bar-mode' enables the tab bar at the top of each
-frame, where you can use tabs to switch between named persistent
-window configurations.
+frame (including TTY frames), where you can use tabs to switch between
+named persistent window configurations.
 
 The 'C-x t' sequence is the new prefix key for tab-related commands:
 'C-x t 2' creates a new tab; 'C-x t 0' deletes the current tab;
@@ -2738,6 +2738,11 @@ when its value is "on", "yes" or "1".
 
 The user option 'tab-bar-position' specifies where to show the tab bar.
 
+Tab-related commands can be used even without the tab bar when
+'tab-bar-mode' is disabled by a nil value of the user option
+'tab-bar-show'.  Without the tab bar you can switch between tabs
+using completion on tab names, or using 'tab-switcher'.
+
 Read the new Info node "(emacs) Tab Bars" for full description
 of all related features.
 
@@ -2752,6 +2757,9 @@ a repeat count.  Clicking on the plus icon adds a new 
buffer to the
 window-local tab line of buffers.  Using the mouse wheel on the tab
 line scrolls tabs.
 
+Read the new Info node "(emacs) Tab Line" for full description
+of all related features.
+
 +++
 ** fileloop.el lets one setup multifile operations like search&replace.