From: Eli Zaretskii <eliz@gnu.org>
To: Juri Linkov <juri@linkov.net>
Cc: 51247@debbugs.gnu.org
Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions
Date: Sun, 17 Oct 2021 22:13:30 +0300 [thread overview]
Message-ID: <83lf2rforp.fsf@gnu.org> (raw)
In-Reply-To: <87tuhfv726.fsf@mail.linkov.net> (message from Juri Linkov on Sun, 17 Oct 2021 21:29:21 +0300)
> From: Juri Linkov <juri@linkov.net>
> Cc: 51247@debbugs.gnu.org
> Date: Sun, 17 Oct 2021 21:29:21 +0300
>
> >> [ ] tab-bar-format-tabs
> >> Show all tabs.
> >> [X] tab-bar-format-tabs-groups
> >> Show tabs with their groups.
> >> [ ] tab-bar-separator
> >> Separator between tabs.
> >> [ ] tab-bar-format-add-tab
> >> Button to add a new tab.
> >> [X] tab-bar-format-align-right
> >> Align the rest of tab bar items to the right.
> >> [X] tab-bar-format-global
> >> Format ‘global-mode-string’ to display it in the tab bar. More
> >> [INS]
> >>
> >> So here its docstring explains what this option is useful for.
> >
> > Can't you provide a separate text for the Custom display? The doc
> > string in its current form is simply misleading.
>
> It's a feature of :options in defcustom that it takes the text
> from the docstrings. Maybe it's possible to override this text,
> but I currently don't know how.
OK, how about the patch below?
diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index 82ec617..3dc95c9 100644
--- a/lisp/tab-bar.el
+++ b/lisp/tab-bar.el
@@ -705,11 +705,14 @@ tab-bar-format
"Template for displaying tab bar items.
Every item in the list is a function that returns
a string, or a list of menu-item elements, or nil.
-When you add more items `tab-bar-format-align-right' and
-`tab-bar-format-global' to the end, then after enabling
-`display-time-mode' (or any other mode that uses `global-mode-string')
-it will display time aligned to the right on the tab bar instead of
-the mode line. Replacing `tab-bar-format-tabs' with
+Adding a function to the list causes the tab bar to show
+that string, or display a menu with those menu items when
+you click on the tab bar.
+If the list ends with `tab-bar-format-align-right' and
+`tab-bar-format-global', then after enabling `display-time-mode'
+(or any other mode that uses `global-mode-string'),
+it will display time aligned to the right on the tab bar instead
+of the mode line. Replacing `tab-bar-format-tabs' with
`tab-bar-format-tabs-groups' will group tabs on the tab bar."
:type 'hook
:options '(tab-bar-format-menu-global
@@ -728,7 +731,7 @@ tab-bar-format
:version "28.1")
(defun tab-bar-format-menu-global ()
- "Show global menu on clicking the Menu button."
+ "Produce the Menu button for the tab bar that shows a global menu."
`((add-tab menu-item (propertize "Menu" 'face 'tab-bar-tab-inactive)
(lambda (event) (interactive "e")
(let ((menu (make-sparse-keymap
@@ -745,7 +748,8 @@ tab-bar-format-menu-global
:help "Global Menu")))
(defun tab-bar-format-history ()
- "Show back and forward buttons when `tab-bar-history-mode' is enabled.
+ "Produce back and forward buttons for the tab bar.
+These buttons will be shown when `tab-bar-history-mode' is enabled.
You can hide these buttons by customizing `tab-bar-format' and removing
`tab-bar-format-history' from it."
(when tab-bar-history-mode
@@ -781,7 +785,7 @@ tab-bar--format-tab
,(alist-get 'close-binding tab))))))
(defun tab-bar-format-tabs ()
- "Show all tabs."
+ "Produce all the tabs for the tab bar."
(let ((i 0))
(mapcan
(lambda (tab)
@@ -855,7 +859,7 @@ tab-bar--format-tab-group
:help "Click to visit group"))))
(defun tab-bar-format-tabs-groups ()
- "Show tabs with their groups."
+ "Produce tabs for the tab bar grouped according to their groups."
(let* ((tabs (funcall tab-bar-tabs-function))
(current-group (funcall tab-bar-tab-group-function
(tab-bar--current-tab-find tabs)))
@@ -899,7 +903,7 @@ tab-bar-format-align-right
`((align-right menu-item ,str ignore))))
(defun tab-bar-format-global ()
- "Format `global-mode-string' to display it in the tab bar.
+ "Produce display of `global-mode-string' in the tab bar.
When `tab-bar-format-global' is added to `tab-bar-format'
(possibly appended after `tab-bar-format-align-right'),
then modes that display information on the mode line
next prev parent reply other threads:[~2021-10-17 19:13 UTC|newest]
Thread overview: 35+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-10-17 8:56 bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Eli Zaretskii
2021-10-17 17:17 ` Juri Linkov
2021-10-17 18:04 ` Eli Zaretskii
2021-10-17 18:29 ` Juri Linkov
2021-10-17 19:13 ` Eli Zaretskii [this message]
2021-10-17 19:27 ` Juri Linkov
2021-10-17 19:38 ` Eli Zaretskii
2021-10-17 19:48 ` Juri Linkov
2021-10-18 11:38 ` Eli Zaretskii
2021-10-18 15:53 ` Juri Linkov
2021-10-18 16:36 ` Eli Zaretskii
2021-10-18 16:44 ` Juri Linkov
2021-10-18 16:53 ` Eli Zaretskii
2021-10-18 17:01 ` Juri Linkov
2021-10-18 17:01 ` Eli Zaretskii
2021-10-18 17:02 ` Juri Linkov
2021-10-18 17:15 ` Eli Zaretskii
2021-10-18 17:21 ` Juri Linkov
2021-10-18 17:32 ` Eli Zaretskii
2021-10-19 6:49 ` Juri Linkov
2021-10-19 12:08 ` Eli Zaretskii
2021-10-19 19:09 ` Juri Linkov
2021-10-20 11:35 ` Eli Zaretskii
2021-10-20 16:50 ` Juri Linkov
2021-10-21 11:05 ` Eli Zaretskii
2021-10-21 16:43 ` Juri Linkov
2021-10-21 17:12 ` Eli Zaretskii
2021-10-21 17:27 ` Juri Linkov
2021-10-21 17:41 ` Eli Zaretskii
2021-10-21 17:48 ` Juri Linkov
2021-10-21 18:10 ` Eli Zaretskii
2021-10-18 8:21 ` martin rudalics
2021-10-18 14:14 ` Eli Zaretskii
2021-10-18 17:43 ` martin rudalics
2021-10-18 18:23 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83lf2rforp.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=51247@debbugs.gnu.org \
--cc=juri@linkov.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.