From c5bdb287e8109beef06f477fa1212226945c265e Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 12 Sep 2021 11:02:58 +0300 Subject: [PATCH] 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 a32181e73be..e238966428b 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 -- 2.39.5