Update documentation for tabs.

* doc/emacs/frames.texi (Tab Bars): New node.

11 files changed, 94 insertions, 15 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index d3d7d97120a..25509878f9b 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2150,6 +2150,10 @@ The mouse was in a vertical scroll bar.  (This is the only kind of
 scroll bar Emacs currently supports.)
 @item menu-bar
 The mouse was in the menu bar.
+@item tab-bar
+The mouse was in a tab bar.
+@item tab-line
+The mouse was in a tab line.
 @item header-line
 The mouse was in a header line.
 @ignore
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 6fc99bd2716..84363d0f0d2 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -722,6 +722,10 @@ Similar to @code{highlight} and @code{mode-line-highlight}, but used
 for mouse-sensitive portions of text on header lines.  This is a
 separate face because the @code{header-line} face might be customized
 in a way that does not interact well with @code{highlight}.
+@item tab-line
+@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.
 @item vertical-border
 @cindex @code{vertical-border} face
 This face is used for the vertical divider between windows on text
@@ -763,6 +767,8 @@ This face determines the visual appearance of the scroll bar.
 @xref{Scroll Bars}.
 @item tool-bar
 This face determines the color of tool bar icons.  @xref{Tool Bars}.
+@item tab-bar
+This face determines the color of tab bar icons.  @xref{Tab Bars}.
 @item menu
 @cindex menu bar appearance
 @cindex @code{menu} face, no effect if customized
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index ad4be90aaf3..aef0e9b37e3 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -540,6 +540,7 @@ Frames and Graphical Displays
 * Drag and Drop::       Using drag and drop to open files and insert text.
 * Menu Bars::           Enabling and disabling the menu bar.
 * Tool Bars::           Enabling and disabling the tool bar.
+* Tab Bars::            Enabling and disabling the tab bar.
 * Dialog Boxes::        Controlling use of dialog boxes.
 * Tooltips::            Displaying information at the current mouse position.
 * Mouse Avoidance::     Preventing the mouse pointer from obscuring text.
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 367ac43a0a4..0003881fad1 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -58,6 +58,7 @@ for doing so on MS-DOS).  Menus are supported on all text terminals.
 * Drag and Drop::       Using drag and drop to open files and insert text.
 * Menu Bars::           Enabling and disabling the menu bar.
 * Tool Bars::           Enabling and disabling the tool bar.
+* Tab Bars::            Enabling and disabling the tab bar.
 * Dialog Boxes::        Controlling use of dialog boxes.
 * Tooltips::            Displaying information at the current mouse position.
 * Mouse Avoidance::     Preventing the mouse pointer from obscuring text.
@@ -1214,6 +1215,41 @@ Parameters,,, elisp, The Emacs Lisp Reference Manual}.  On macOS the
 tool bar is hidden when the frame is put into fullscreen, but can be
 displayed by moving the mouse pointer to the top of the screen.
 
+@node Tab Bars
+@section Tab Bars
+@cindex Tab Bar mode
+@cindex mode, Tab Bar
+@cindex tabs, tabbar
+
+  On graphical displays and on text terminals, Emacs puts a @dfn{tab bar}
+at the top of each frame, just below the menu bar.  This is a row of
+tabs which you can click on with the mouse to switch window configurations.
+
+  Each tab on the tab bar represents a named persistent window
+configuration.  Its name is composed from the names of buffers
+visible in windows of the window configuration.  Clicking on the
+tab name switches the current window configuration to the previously
+used configuration of windows and buffers.
+
+  If you are using the desktop library to save and restore your
+sessions, the tabs from the tab bar are recorded in the desktop file,
+together with their associated window configurations.
+
+@findex tab-bar-mode
+@vindex 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
+control the use of tab bars at startup, customize the variable
+@code{tab-bar-mode}.
+
+@vindex tab-bar-new-tab-choice
+@cindex Tab Bar new tab
+  By default, Emacs follows the same behavior as when creating frames,
+to start a new tab with the current buffer, i.e. the buffer
+that was 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}.
+
 @node Dialog Boxes
 @section Using Dialog Boxes
 @cindex dialog boxes
diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi
index ad16d72ddbf..30ddffab696 100644
--- a/doc/emacs/glossary.texi
+++ b/doc/emacs/glossary.texi
@@ -1360,6 +1360,15 @@ your buffers, unsaved edits, undo history, etc.  @xref{Exiting}.
 @key{TAB} is the tab character.  In Emacs it is typically used for
 indentation or completion.
 
+@item Tab Bar
+The tab bar is a row of tabs at the top of an Emacs frame.
+Clicking on one of these tabs switches named persistent window
+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.
+
 @anchor{Glossary---Tags Table}
 @item Tags Table
 A tags table is a file that serves as an index to the function
diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index e01dfa2677b..64034d71860 100644
--- a/doc/emacs/modes.texi
+++ b/doc/emacs/modes.texi
@@ -296,6 +296,12 @@ but the tool bar is only displayed on graphical terminals.  @xref{Tool
 Bars}.
 
 @item
+Tab Bar mode gives each frame a tab bar.  @xref{Tab Bars}.
+
+@item
+Tab Line mode gives each window a tab line.
+
+@item
 Transient Mark mode highlights the region, and makes many Emacs
 commands operate on the region when the mark is active.  It is enabled
 by default.  @xref{Mark}.
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 1fd56d02841..541a97f8add 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1348,7 +1348,7 @@ button.  @xref{Repeat Events}.
 @var{position} slot of a click event, you should typically use the
 functions documented in @ref{Accessing Mouse}.  The explicit format of
 the list depends on where the click occurred.  For clicks in the text
-area, mode line, header line, or in the fringe or marginal areas, the
+area, mode line, header line, tab line, or in the fringe or marginal areas, the
 mouse position list has the form
 
 @example
@@ -1368,7 +1368,7 @@ The window in which the click occurred.
 The buffer position of the character clicked on in the text area; or,
 if the click was outside the text area, the window area where it
 occurred.  It is one of the symbols @code{mode-line},
-@code{header-line}, @code{vertical-line}, @code{left-margin},
+@code{header-line}, @code{tab-line}, @code{vertical-line}, @code{left-margin},
 @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
 
 In one special case, @var{pos-or-area} is a list containing a symbol
@@ -1380,7 +1380,7 @@ by Emacs.  @xref{Key Sequence Input}.
 The relative pixel coordinates of the click.  For clicks in the text
 area of a window, the coordinate origin @code{(0 . 0)} is taken to be
 the top left corner of the text area.  @xref{Window Sizes}.  For
-clicks in a mode line or header line, the coordinate origin is the top
+clicks in a mode line, header line or tab line, the coordinate origin is the top
 left corner of the window itself.  For fringes, margins, and the
 vertical border, @var{x} does not have meaningful data.  For fringes
 and margins, @var{y} is relative to the bottom edge of the header
@@ -1407,7 +1407,7 @@ The position in the string where the click occurred.
 @item @var{text-pos}
 For clicks on a marginal area or on a fringe, this is the buffer
 position of the first visible character in the corresponding line in
-the window.  For clicks on the mode line or the header line, this is
+the window.  For clicks on the mode line, the header line or the tab line, this is
 @code{nil}.  For other events, it is the buffer position closest to
 the click.
 
@@ -1416,7 +1416,8 @@ These are the actual column and row coordinate numbers of the glyph
 under the @var{x}, @var{y} position.  If @var{x} lies beyond the last
 column of actual text on its line, @var{col} is reported by adding
 fictional extra columns that have the default character width.  Row 0
-is taken to be the header line if the window has one, or the topmost
+is taken to be the header line if the window has one, or Row 1
+if the window also has the tab line, or the topmost
 row of the text area otherwise.  Column 0 is taken to be the leftmost
 column of the text area for clicks on a window text area, or the
 leftmost mode line or header line column for clicks there.  For clicks
@@ -2094,7 +2095,7 @@ computed values.)
 
 Note that @var{row} is counted from the top of the text area.  If the
 window given by @var{position} possesses a header line (@pxref{Header
-Lines}), it is @emph{not} included in the @var{row} count.
+Lines}) or a tab line, they are @emph{not} included in the @var{row} count.
 @end defun
 
 @defun posn-actual-col-row position
@@ -2452,12 +2453,14 @@ button-down events entirely.  It also reshuffles focus events and
 miscellaneous window events so that they never appear in a key sequence
 with any other events.
 
+@cindex @code{tab-line} prefix key
 @cindex @code{header-line} prefix key
 @cindex @code{mode-line} prefix key
 @cindex @code{vertical-line} prefix key
 @cindex @code{horizontal-scroll-bar} prefix key
 @cindex @code{vertical-scroll-bar} prefix key
 @cindex @code{menu-bar} prefix key
+@cindex @code{tab-bar} prefix key
 @cindex mouse events, in special parts of frame
 When mouse events occur in special parts of a window, such as a mode
 line or a scroll bar, the event type shows nothing special---it is the
@@ -2465,8 +2468,8 @@ same symbol that would normally represent that combination of mouse
 button and modifier keys.  The information about the window part is kept
 elsewhere in the event---in the coordinates.  But
 @code{read-key-sequence} translates this information into imaginary
-prefix keys, all of which are symbols: @code{header-line},
-@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
+prefix keys, all of which are symbols: @code{tab-line}, @code{header-line},
+@code{horizontal-scroll-bar}, @code{menu-bar}, @code{tab-bar}, @code{mode-line},
 @code{vertical-line}, and @code{vertical-scroll-bar}.  You can define
 meanings for mouse clicks in special window parts by defining key
 sequences using these imaginary prefix keys.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 7c0a56dcad3..3b2049a2876 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2944,6 +2944,7 @@ If the text lies within the mode line of the selected window, Emacs
 applies the @code{mode-line} face.  For the mode line of a
 non-selected window, Emacs applies the @code{mode-line-inactive} face.
 For a header line, Emacs applies the @code{header-line} face.
+For a tab line, Emacs applies the @code{tab-line} face.
 
 @item
 If the text comes from an overlay string via @code{before-string} or
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 39d3960c9a2..f05a6db1761 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -5558,6 +5558,9 @@ The coordinates are in the mode line of @var{window}.
 @item header-line
 The coordinates are in the header line of @var{window}.
 
+@item tab-line
+The coordinates are in the tab line of @var{window}.
+
 @item right-divider
 The coordinates are in the divider separating @var{window} from a
 window on the right.
@@ -6115,6 +6118,15 @@ to suppress display of a header line for this window.  Display and
 contents of the header line on other windows showing this buffer are not
 affected.
 
+@item tab-line-format
+@vindex tab-line-format@r{, a window parameter}
+This parameter replaces the value of the buffer-local variable
+@code{tab-line-format} (@pxref{Mode Line Basics}) of this window's
+buffer whenever this window is displayed.  The symbol @code{none} means
+to suppress display of a tab line for this window.  Display and
+contents of the tab line on other windows showing this buffer are not
+affected.
+
 @item min-margins
 @vindex min-margins@r{, a window parameter}
 The value of this parameter is a cons cell whose @sc{car} and
diff --git a/etc/NEWS b/etc/NEWS
index 37382e843bd..f824eccaefc 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1896,12 +1896,12 @@ New tab-based keybindings (similar to frame-based):
 Also it's possible to switch named persistent window configurations
 without having graphical access to the tab-bar, even on a tty
 or when 'tab-bar-mode' is disabled, with these commands:
-'list-tabs' displays a list of named window configurations for switching;
-'make-tab' creates a new window configuration;
-'delete-tab' deletes the current window configuration;
-'switch-to-tab' switches to the window configuration by its name;
-'previous-tab' switches to the previous window configuration;
-'next-tab' switches to the next window configuration.
+'tab-new' creates a new window configuration;
+'tab-delete' deletes the current window configuration;
+'tab-select' switches to the window configuration by its name;
+'tab-previous' switches to the previous window configuration;
+'tab-next' switches to the next window configuration;
+'tab-list' displays a list of named window configurations for switching.
 
 ** 'global-tab-line-mode' enables the tab-line above each window to
 switch buffers in it to previous/next buffers.  Selecting a previous
diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index fb13ff4178b..3108c595e94 100644
--- a/lisp/tab-bar.el
+++ b/lisp/tab-bar.el
@@ -481,7 +481,7 @@ specified by `tab-bar-close-tab-select'."
 
 ;;; Non-graphical access to frame-local tabs (named window configurations)
 
-(defun tab-make ()
+(defun tab-new ()
   "Create a new named window configuration without having to click a tab."
   (interactive)
   (tab-bar-new-tab)
@@ -500,6 +500,7 @@ specified by `tab-bar-close-tab-select'."
 (defalias 'tab-select 'tab-bar-select-tab)
 (defalias 'tab-previous 'tab-bar-switch-to-prev-tab)
 (defalias 'tab-next 'tab-bar-switch-to-next-tab)
+(defalias 'tab-list 'tab-bar-list)
 
 (defun tab-bar-list ()
   "Display a list of named window configurations.