Documentation of tab-bar-show and friends

Documentation of tab-bar-show and friends

[Eli Zaretskii]

The current documentation of this seems to be incomplete and for some
reason hides some of the functionality.

First, the NEWS entry for tab-bar-show says:

  *** The tab bar is frame-local when 'tab-bar-show' is a number.
  Show/hide the tab bar independently for each frame, according to the
  value of 'tab-bar-show'.

What does it mean "frame-local" in this case?  Does it mean one should
use a frame parameter called tab-bar-show?  Or does it mean something
else?

Next, the above says "a number", but the doc string of tab-bar-show,
the defcustom forms, and the manual only describe one value: 1.
However, the code does:

   ((natnump tab-bar-show)
    (if (> (length (funcall tab-bar-tabs-function frame)) tab-bar-show) 1 0))))

So tab-bar-show can be meaningfully set to a number other than 1.
This is undocumented, for some reason.  Is that intentional?

Please help me rectify these problems.

Thanks.

Re: Documentation of tab-bar-show and friends

[Juri Linkov]

> The current documentation of this seems to be incomplete and for some
> reason hides some of the functionality.
>
> First, the NEWS entry for tab-bar-show says:
>
>   *** The tab bar is frame-local when 'tab-bar-show' is a number.
>   Show/hide the tab bar independently for each frame, according to the
>   value of 'tab-bar-show'.
>
> What does it mean "frame-local" in this case?  Does it mean one should
> use a frame parameter called tab-bar-show?  Or does it mean something
> else?

This means it affects each frame separately.

> Next, the above says "a number", but the doc string of tab-bar-show,
> the defcustom forms, and the manual only describe one value: 1.
> However, the code does:
>
>    ((natnump tab-bar-show)
>     (if (> (length (funcall tab-bar-tabs-function frame)) tab-bar-show) 1 0))))
>
> So tab-bar-show can be meaningfully set to a number other than 1.
> This is undocumented, for some reason.  Is that intentional?

Probably no one would want to use a number other than 1.

Re: Documentation of tab-bar-show and friends

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: emacs-devel@gnu.org
> Date: Mon, 06 Sep 2021 18:24:15 +0300
> 
> >   *** The tab bar is frame-local when 'tab-bar-show' is a number.
> >   Show/hide the tab bar independently for each frame, according to the
> >   value of 'tab-bar-show'.
> >
> > What does it mean "frame-local" in this case?  Does it mean one should
> > use a frame parameter called tab-bar-show?  Or does it mean something
> > else?
> 
> This means it affects each frame separately.

How does it do that?  It's a good-faith question: I don't understand
how you make that happen, except by using frame parameters.

> > Next, the above says "a number", but the doc string of tab-bar-show,
> > the defcustom forms, and the manual only describe one value: 1.
> > However, the code does:
> >
> >    ((natnump tab-bar-show)
> >     (if (> (length (funcall tab-bar-tabs-function frame)) tab-bar-show) 1 0))))
> >
> > So tab-bar-show can be meaningfully set to a number other than 1.
> > This is undocumented, for some reason.  Is that intentional?
> 
> Probably no one would want to use a number other than 1.

I don't think it's reasonable to second guess what the users would
like doing.

Re: Documentation of tab-bar-show and friends

[Juri Linkov]

>> >   *** The tab bar is frame-local when 'tab-bar-show' is a number.
>> >   Show/hide the tab bar independently for each frame, according to the
>> >   value of 'tab-bar-show'.
>> >
>> > What does it mean "frame-local" in this case?  Does it mean one should
>> > use a frame parameter called tab-bar-show?  Or does it mean something
>> > else?
>>
>> This means it affects each frame separately.
>
> How does it do that?  It's a good-faith question: I don't understand
> how you make that happen, except by using frame parameters.

Indeed, 'toggle-frame-tab-bar' modifies two frame parameters:
'tab-bar-lines' and 'tab-bar-lines-keep-state'.

>> > Next, the above says "a number", but the doc string of tab-bar-show,
>> > the defcustom forms, and the manual only describe one value: 1.
>> > However, the code does:
>> >
>> >    ((natnump tab-bar-show)
>> >     (if (> (length (funcall tab-bar-tabs-function frame)) tab-bar-show) 1 0))))
>> >
>> > So tab-bar-show can be meaningfully set to a number other than 1.
>> > This is undocumented, for some reason.  Is that intentional?
>>
>> Probably no one would want to use a number other than 1.
>
> I don't think it's reasonable to second guess what the users would
> like doing.

Exactly, so this is the reason why there is no restriction
on possible future extensions that can support numbers greater than 1.

Re: Documentation of tab-bar-show and friends

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: emacs-devel@gnu.org
> Date: Thu, 09 Sep 2021 10:54:37 +0300
> 
> >> >   *** The tab bar is frame-local when 'tab-bar-show' is a number.
> >> >   Show/hide the tab bar independently for each frame, according to the
> >> >   value of 'tab-bar-show'.
> >> >
> >> > What does it mean "frame-local" in this case?  Does it mean one should
> >> > use a frame parameter called tab-bar-show?  Or does it mean something
> >> > else?
> >>
> >> This means it affects each frame separately.
> >
> > How does it do that?  It's a good-faith question: I don't understand
> > how you make that happen, except by using frame parameters.
> 
> Indeed, 'toggle-frame-tab-bar' modifies two frame parameters:
> 'tab-bar-lines' and 'tab-bar-lines-keep-state'.

I'm still missing something: how does one go about setting tab bar
independently for several frames?  NEWS says "according to the value
of tab-bar-show", but that variable is global, so setting it affects
all the frames, no?

Re: Documentation of tab-bar-show and friends

[Juri Linkov]

> I'm still missing something: how does one go about setting tab bar
> independently for several frames?  NEWS says "according to the value
> of tab-bar-show", but that variable is global, so setting it affects
> all the frames, no?

toggle-frame-tab-bar overrides the value of tab-bar-show.
I remember mentioning this in some discussion, but can't
find this in the documentation, sorry.

Generally, there are two levels of customization:

1. The global tab-bar-show that defines when to show/hide the tab bar
depending on the number of tabs.  This variable affects all frames.

2. It's possible to override the aforementioned behavior
by explicitly calling toggle-frame-tab-bar on a frame.
Then the value of tab-bar-show has no effect on that frame.

Re: Documentation of tab-bar-show and friends

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: emacs-devel@gnu.org
> Date: Thu, 09 Sep 2021 21:47:02 +0300
> 
> Generally, there are two levels of customization:
> 
> 1. The global tab-bar-show that defines when to show/hide the tab bar
> depending on the number of tabs.  This variable affects all frames.
> 
> 2. It's possible to override the aforementioned behavior
> by explicitly calling toggle-frame-tab-bar on a frame.
> Then the value of tab-bar-show has no effect on that frame.

Then I don't understand why NEWS says

  *** The tab bar is frame-local when 'tab-bar-show' is a number.
  You can show/hide the tab bar independently for each frame, according
  to the value of 'tab-bar-show'.

If you say that frame-local tab bar _overrides_ tab-bar-show, then how
come the value of tab-bar-show is described here as _causing_ the tab
bar to be frame-local?

Re: Documentation of tab-bar-show and friends

[Juri Linkov]

>> Generally, there are two levels of customization:
>>
>> 1. The global tab-bar-show that defines when to show/hide the tab bar
>> depending on the number of tabs.  This variable affects all frames.
>>
>> 2. It's possible to override the aforementioned behavior
>> by explicitly calling toggle-frame-tab-bar on a frame.
>> Then the value of tab-bar-show has no effect on that frame.
>
> Then I don't understand why NEWS says
>
>   *** The tab bar is frame-local when 'tab-bar-show' is a number.
>   You can show/hide the tab bar independently for each frame, according
>   to the value of 'tab-bar-show'.
>
> If you say that frame-local tab bar _overrides_ tab-bar-show, then how
> come the value of tab-bar-show is described here as _causing_ the tab
> bar to be frame-local?

The tab bar is frame-local in the sense that it is enabled/disabled
depending on the number of its tabs.  So e.g. on a frame with one tab
there is no tab bar, on another frame with two tabs there is a tab bar,
when tab-bar-show is 1, and toggle-frame-tab-bar was not used.

Re: Documentation of tab-bar-show and friends

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: emacs-devel@gnu.org
> Date: Thu, 09 Sep 2021 22:22:44 +0300
> 
> >> Generally, there are two levels of customization:
> >>
> >> 1. The global tab-bar-show that defines when to show/hide the tab bar
> >> depending on the number of tabs.  This variable affects all frames.
> >>
> >> 2. It's possible to override the aforementioned behavior
> >> by explicitly calling toggle-frame-tab-bar on a frame.
> >> Then the value of tab-bar-show has no effect on that frame.
> >
> > Then I don't understand why NEWS says
> >
> >   *** The tab bar is frame-local when 'tab-bar-show' is a number.
> >   You can show/hide the tab bar independently for each frame, according
> >   to the value of 'tab-bar-show'.
> >
> > If you say that frame-local tab bar _overrides_ tab-bar-show, then how
> > come the value of tab-bar-show is described here as _causing_ the tab
> > bar to be frame-local?
> 
> The tab bar is frame-local in the sense that it is enabled/disabled
> depending on the number of its tabs.  So e.g. on a frame with one tab
> there is no tab bar, on another frame with two tabs there is a tab bar,
> when tab-bar-show is 1, and toggle-frame-tab-bar was not used.

So the heading in NEWS, viz.:

  *** The tab bar is frame-local when 'tab-bar-show' is a number.

is incorrect, and should instead say that the tab bar can be made
frame-local by using toggle-frame-tab-bar, is that correct?  Because
the above heading tells me "if tab-show is set to a number, the tab
bar becomes frame-local", which is not correct, right?

Suppose now I did use toggle-frame-tab-bar, it still only allows me
only to enable and disable the tab bar for specific frames, but the
value of tab-bar-show is still the same for all the frames that do
display the tab bar.  Correct?

Thanks.

Re: Documentation of tab-bar-show and friends

[Juri Linkov]

> So the heading in NEWS, viz.:
>
>   *** The tab bar is frame-local when 'tab-bar-show' is a number.
>
> is incorrect, and should instead say that the tab bar can be made
> frame-local by using toggle-frame-tab-bar, is that correct?  Because
> the above heading tells me "if tab-show is set to a number, the tab
> bar becomes frame-local", which is not correct, right?
>
> Suppose now I did use toggle-frame-tab-bar, it still only allows me
> only to enable and disable the tab bar for specific frames, but the
> value of tab-bar-show is still the same for all the frames that do
> display the tab bar.  Correct?

The term "frame-local" is not well-defined and can mean different
things: for numeric 'tab-bar-show' it can mean that the presence of the
tab-bar on each frame depends on the number of tabs on that frame.
For toggle-frame-tab-bar it can mean that the user can enable/disable
the tab-bar for each frame manually.

Re: Documentation of tab-bar-show and friends

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: emacs-devel@gnu.org
> Date: Sat, 11 Sep 2021 22:10:13 +0300
> 
> > So the heading in NEWS, viz.:
> >
> >   *** The tab bar is frame-local when 'tab-bar-show' is a number.
> >
> > is incorrect, and should instead say that the tab bar can be made
> > frame-local by using toggle-frame-tab-bar, is that correct?  Because
> > the above heading tells me "if tab-show is set to a number, the tab
> > bar becomes frame-local", which is not correct, right?
> >
> > Suppose now I did use toggle-frame-tab-bar, it still only allows me
> > only to enable and disable the tab bar for specific frames, but the
> > value of tab-bar-show is still the same for all the frames that do
> > display the tab bar.  Correct?
> 
> The term "frame-local" is not well-defined and can mean different
> things: for numeric 'tab-bar-show' it can mean that the presence of the
> tab-bar on each frame depends on the number of tabs on that frame.
> For toggle-frame-tab-bar it can mean that the user can enable/disable
> the tab-bar for each frame manually.

Got it, thanks.

Re: Documentation of tab-bar-show and friends

[Juri Linkov]

> Got it, thanks.

BTW, this change in c5bdb287e8 is not quite right:

    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 (@pxref{Menu Bars}) and above the tool bar (@pxref{Tool Bars}).

The tab bar can't be above the tool bar when the tool bar is external.
On non-external builds, its position depends on this variable:

  tab-bar-position is a variable defined in ‘src/dispnew.c’.
  Specify on which side from the tool bar the tab bar shall be.
  Possible values are ‘t’ (below the tool bar), ‘nil’ (above the tool bar).
  This option affects only builds where the tool bar is not external.

Also

  @item C-x t @key{RET} @var{tabname} @key{RET}
  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})

Maybe then: "Future history of used tab names", because 'M-n' navigates
through the "future history".

Regarding this change:

  @kindex C-9, tab bar
  @kindex M-9, tab bar

I'm not sure if there is a need to say that <Mod>-9 is bound to 'tab-last'.

Re: Documentation of tab-bar-show and friends

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: emacs-devel@gnu.org
> Date: Sun, 12 Sep 2021 19:03:41 +0300
> 
> > Got it, thanks.
> 
> BTW, this change in c5bdb287e8 is not quite right:

Feel free to fix whatever needs fixing, and thanks.