From: Juri Linkov Date: Mon, 20 Apr 2020 23:23:35 +0000 (+0300) Subject: Improve the documentation of tab-bar and tab-line X-Git-Tag: emacs-27.1-rc1~199 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=692ad40539805e435a16b90067fa5917e4fea9f8;p=emacs.git 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". --- diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 4273357995f..d98441b5ab8 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 60f2be9a513..6b82aeb8234 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 94218424d37..d9373b8bc78 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 416431b8cd4..4d622ec0e3f 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 a15aa17a66f..dceb8d3ca5b 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 92d60d2d7c2..f5fb6b1e797 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 910ef8fd88d..cb5e9bce4d1 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 091c831e9d6..fe8a8d8775b 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.