unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Documentation of tab-bar-show and friends
@ 2021-09-06  8:12 Eli Zaretskii
  2021-09-06 15:24 ` Juri Linkov
  0 siblings, 1 reply; 13+ messages in thread
From: Eli Zaretskii @ 2021-09-06  8:12 UTC (permalink / raw)
  To: Juri Linkov; +Cc: emacs-devel

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.



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-06  8:12 Documentation of tab-bar-show and friends Eli Zaretskii
@ 2021-09-06 15:24 ` Juri Linkov
  2021-09-06 16:00   ` Eli Zaretskii
  0 siblings, 1 reply; 13+ messages in thread
From: Juri Linkov @ 2021-09-06 15:24 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-06 15:24 ` Juri Linkov
@ 2021-09-06 16:00   ` Eli Zaretskii
  2021-09-09  7:54     ` Juri Linkov
  0 siblings, 1 reply; 13+ messages in thread
From: Eli Zaretskii @ 2021-09-06 16:00 UTC (permalink / raw)
  To: Juri Linkov; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-06 16:00   ` Eli Zaretskii
@ 2021-09-09  7:54     ` Juri Linkov
  2021-09-09 17:47       ` Eli Zaretskii
  0 siblings, 1 reply; 13+ messages in thread
From: Juri Linkov @ 2021-09-09  7:54 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

>> >   *** 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.



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-09  7:54     ` Juri Linkov
@ 2021-09-09 17:47       ` Eli Zaretskii
  2021-09-09 18:47         ` Juri Linkov
  0 siblings, 1 reply; 13+ messages in thread
From: Eli Zaretskii @ 2021-09-09 17:47 UTC (permalink / raw)
  To: Juri Linkov; +Cc: emacs-devel

> 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?



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-09 17:47       ` Eli Zaretskii
@ 2021-09-09 18:47         ` Juri Linkov
  2021-09-09 19:04           ` Eli Zaretskii
  0 siblings, 1 reply; 13+ messages in thread
From: Juri Linkov @ 2021-09-09 18:47 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-09 18:47         ` Juri Linkov
@ 2021-09-09 19:04           ` Eli Zaretskii
  2021-09-09 19:22             ` Juri Linkov
  0 siblings, 1 reply; 13+ messages in thread
From: Eli Zaretskii @ 2021-09-09 19:04 UTC (permalink / raw)
  To: Juri Linkov; +Cc: emacs-devel

> 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?



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-09 19:04           ` Eli Zaretskii
@ 2021-09-09 19:22             ` Juri Linkov
  2021-09-11 12:02               ` Eli Zaretskii
  0 siblings, 1 reply; 13+ messages in thread
From: Juri Linkov @ 2021-09-09 19:22 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

>> 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.



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-09 19:22             ` Juri Linkov
@ 2021-09-11 12:02               ` Eli Zaretskii
  2021-09-11 19:10                 ` Juri Linkov
  0 siblings, 1 reply; 13+ messages in thread
From: Eli Zaretskii @ 2021-09-11 12:02 UTC (permalink / raw)
  To: Juri Linkov; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-11 12:02               ` Eli Zaretskii
@ 2021-09-11 19:10                 ` Juri Linkov
  2021-09-12  7:03                   ` Eli Zaretskii
  0 siblings, 1 reply; 13+ messages in thread
From: Juri Linkov @ 2021-09-11 19:10 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-11 19:10                 ` Juri Linkov
@ 2021-09-12  7:03                   ` Eli Zaretskii
  2021-09-12 16:03                     ` Juri Linkov
  0 siblings, 1 reply; 13+ messages in thread
From: Eli Zaretskii @ 2021-09-12  7:03 UTC (permalink / raw)
  To: Juri Linkov; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-12  7:03                   ` Eli Zaretskii
@ 2021-09-12 16:03                     ` Juri Linkov
  2021-09-12 16:23                       ` Eli Zaretskii
  0 siblings, 1 reply; 13+ messages in thread
From: Juri Linkov @ 2021-09-12 16:03 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

> 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'.



^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Documentation of tab-bar-show and friends
  2021-09-12 16:03                     ` Juri Linkov
@ 2021-09-12 16:23                       ` Eli Zaretskii
  0 siblings, 0 replies; 13+ messages in thread
From: Eli Zaretskii @ 2021-09-12 16:23 UTC (permalink / raw)
  To: Juri Linkov; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2021-09-12 16:23 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-09-06  8:12 Documentation of tab-bar-show and friends Eli Zaretskii
2021-09-06 15:24 ` Juri Linkov
2021-09-06 16:00   ` Eli Zaretskii
2021-09-09  7:54     ` Juri Linkov
2021-09-09 17:47       ` Eli Zaretskii
2021-09-09 18:47         ` Juri Linkov
2021-09-09 19:04           ` Eli Zaretskii
2021-09-09 19:22             ` Juri Linkov
2021-09-11 12:02               ` Eli Zaretskii
2021-09-11 19:10                 ` Juri Linkov
2021-09-12  7:03                   ` Eli Zaretskii
2021-09-12 16:03                     ` Juri Linkov
2021-09-12 16:23                       ` Eli Zaretskii

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).