From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 17 Oct 2021 08:57:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 51247@debbugs.gnu.org Cc: Juri Linkov X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.163446096718423 (code B ref -1); Sun, 17 Oct 2021 08:57:01 +0000 Received: (at submit) by debbugs.gnu.org; 17 Oct 2021 08:56:07 +0000 Received: from localhost ([127.0.0.1]:43563 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mc1xe-0004n5-Ew for submit@debbugs.gnu.org; Sun, 17 Oct 2021 04:56:06 -0400 Received: from lists.gnu.org ([209.51.188.17]:41272) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mc1xa-0004mv-3P for submit@debbugs.gnu.org; Sun, 17 Oct 2021 04:56:04 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:37286) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mc1xZ-0001wW-Np for bug-gnu-emacs@gnu.org; Sun, 17 Oct 2021 04:56:01 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:47592) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mc1xX-000139-P4; Sun, 17 Oct 2021 04:56:00 -0400 Received: from [87.69.77.57] (port=3670 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mc1xW-0003aU-Hs; Sun, 17 Oct 2021 04:55:59 -0400 Date: Sun, 17 Oct 2021 11:56:01 +0300 Message-Id: <831r4kghcu.fsf@gnu.org> From: Eli Zaretskii X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Some functions in tab-bar.el and the data they return are documented insufficiently, so much so that it makes the code there very hard to develop and maintain by anyone except the original author. Internal functions and data strictures don't need to have doc strings, but they do have to be explained enough for anyone to understand and modify the code without the need to step through it with a debugger. (Also, quite a few commands there lacked doc strings, which should be avoided at all costs. I fixed that today.) I show below the places where IMO the lack of proper documentation is particularly evident, or where the documentation is insufficient or inaccurate. Please fill at least those gaps; bonus points for documenting more than this bare minimum. (defun tab-bar--key-to-number (key) This function needs at least to document the meaning of each value it can return: nil, t, or a number. (defun tab-bar--event-to-item (posn) (if (posn-window posn) (let ((caption (car (posn-string posn)))) (when caption (get-text-property 0 'menu-item caption))) This function should document the possible return values and their meaning. It should also say something about the text property it retrieves from posn-string, and how that property is used. (defun tab-bar--format-tab (tab i) "Format TAB using its index I and return the result as a string." the doc string of this function is at least inaccurate, if not incorrect: it doesn't (always) return a string. Please document what it does return and the meaning of the various forms of the value. (defun tab-bar--format-tab-group (tab i &optional current-p) This function lacks any documentation of the value it returns; please add some minimal docs. (defun tab-bar-format-tabs-groups () "Show tabs with their groups." The doc string says "show", but this functions doesn't display anything, AFAICT, it produces a list. Please adjust the doc string and add a description of the returned value. (defun tab-bar--tab (&optional frame) Please add some minimal documentation of the return value. (defun tab-bar--current-tab (&optional tab frame) (defun tab-bar--current-tab-make (&optional tab) (defun tab-bar--current-tab-find (&optional tabs frame) (defun tab-bar--current-tab-index (&optional tabs frame) (defun tab-bar--tab-index (tab &optional tabs frame) (defun tab-bar--tab-index-by-name (name &optional tabs frame) (defun tab-bar--tab-index-recent (nth &optional tabs frame) (defun tab-bar--tabs-recent (&optional tabs frame) These functions need at least some comment saying what each one of them does. (defun tab-switcher-delete-from-list (tab) "Delete the window configuration from both lists." Which "both lists"? (defun switch-to-buffer-other-tab (buffer-or-name &optional norecord) "Switch to buffer BUFFER-OR-NAME in another tab. Like \\[switch-to-buffer-other-frame] (which see), but creates a new tab. Interactively, prompt for the buffer to switch to." This command should document the NORECORD argument. Thanks. In GNU Emacs 28.0.60 (build 72, i686-pc-mingw32) of 2021-10-17 built on HOME-C4E4A596F7 Repository revision: 35920791df78400a36bf4420584bd8349ce9bbee Repository branch: emacs-28 Windowing system distributor 'Microsoft Corp.', version 5.1.2600 System Description: Microsoft Windows XP Service Pack 3 (v5.1.0.2600) Configured using: 'configure -C --prefix=/d/usr --with-wide-int --with-modules --enable-checking=yes,glyphs 'CFLAGS=-O0 -gdwarf-4 -g3'' Configured features: ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND THREADS TIFF TOOLKIT_SCROLL_BARS XPM ZLIB Important settings: value of $LANG: ENU locale-coding-system: cp1255 Major mode: Lisp Interaction Minor modes in effect: tooltip-mode: t global-eldoc-mode: t eldoc-mode: t show-paren-mode: t electric-indent-mode: t mouse-wheel-mode: t tool-bar-mode: t menu-bar-mode: t file-name-shadow-mode: t global-font-lock-mode: t font-lock-mode: t blink-cursor-mode: t auto-composition-mode: t auto-encryption-mode: t auto-compression-mode: t line-number-mode: t indent-tabs-mode: t transient-mark-mode: t Load-path shadows: None found. Features: (shadow sort mail-extr emacsbug message rmc puny dired dired-loaddefs rfc822 mml mml-sec epa derived epg rfc6068 epg-config gnus-util rmail rmail-loaddefs auth-source cl-seq eieio eieio-core cl-macs eieio-loaddefs password-cache json map text-property-search time-date subr-x seq byte-opt gv bytecomp byte-compile cconv mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader cl-loaddefs cl-lib sendmail rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils iso-transl tooltip eldoc paren electric uniquify ediff-hook vc-hooks lisp-float-type elisp-mode mwheel dos-w32 ls-lisp disp-table term/w32-win w32-win w32-vars term/common-win tool-bar dnd fontset image regexp-opt fringe tabulated-list replace newcomment text-mode lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow isearch easymenu timer select scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors frame minibuffer cl-generic cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech european ethiopic indian cyrillic chinese composite emoji-zwj charscript charprop case-table epa-hook jka-cmpr-hook help simple abbrev obarray cl-preloaded nadvice button loaddefs faces cus-face macroexp files window text-properties overlay sha1 md5 base64 format env code-pages mule custom widget hashtable-print-readable backquote threads w32notify w32 lcms2 multi-tty make-network-process emacs) Memory information: ((conses 16 56715 8028) (symbols 48 7801 1) (strings 16 21649 1976) (string-bytes 1 632631) (vectors 16 13631) (vector-slots 8 180039 9875) (floats 8 23 59) (intervals 40 266 93) (buffers 888 10)) From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 17 Oct 2021 17:32:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163449186520105 (code B ref 51247); Sun, 17 Oct 2021 17:32:02 +0000 Received: (at 51247) by debbugs.gnu.org; 17 Oct 2021 17:31:05 +0000 Received: from localhost ([127.0.0.1]:45201 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcA00-0005EC-Qv for submit@debbugs.gnu.org; Sun, 17 Oct 2021 13:31:05 -0400 Received: from relay6-d.mail.gandi.net ([217.70.183.198]:39841) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mc9zz-0005DI-KU for 51247@debbugs.gnu.org; Sun, 17 Oct 2021 13:31:03 -0400 Received: (Authenticated sender: juri@linkov.net) by relay6-d.mail.gandi.net (Postfix) with ESMTPSA id 14431C0004; Sun, 17 Oct 2021 17:30:56 +0000 (UTC) From: Juri Linkov References: <831r4kghcu.fsf@gnu.org> Date: Sun, 17 Oct 2021 20:17:43 +0300 In-Reply-To: <831r4kghcu.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 17 Oct 2021 11:56:01 +0300") Message-ID: <87y26ry3vs.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) > Some functions in tab-bar.el and the data they return are documented > insufficiently, so much so that it makes the code there very hard to > develop and maintain by anyone except the original author. Internal > functions and data strictures don't need to have doc strings, but they > do have to be explained enough for anyone to understand and modify the > code without the need to step through it with a debugger. It was on my TODO list to add docstrings to new functions after their names and a list of arguments stabilizes. For example, there was a need to rename some functions now in bug#51246. > I show below the places where IMO the lack of proper documentation is > particularly evident, or where the documentation is insufficient or > inaccurate. Please fill at least those gaps; bonus points for > documenting more than this bare minimum. I fixed all places that you noticed (please check), except the following: > (defun tab-bar-format-tabs-groups () > "Show tabs with their groups." > > The doc string says "show", but this functions doesn't display > anything, AFAICT, it produces a list. Please adjust the doc string > and add a description of the returned value. This docstring is automatically displayed in the Customization buffer of `tab-bar-format' that looks like this: Hide Tab Bar Format: Hook: [ ] tab-bar-format-menu-global Show global menu on clicking the Menu button. [X] tab-bar-format-history Show back and forward buttons when ‘tab-bar-history-mode’ is enabled. More [ ] 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. > (defun switch-to-buffer-other-tab (buffer-or-name &optional norecord) > "Switch to buffer BUFFER-OR-NAME in another tab. > Like \\[switch-to-buffer-other-frame] (which see), but creates a new tab. > Interactively, prompt for the buffer to switch to." > > This command should document the NORECORD argument. Oops, this was copy/paste from switch-to-buffer, switch-to-buffer-other-window, switch-to-buffer-other-frame that all just pass NORECORD down to 'pop-to-buffer'. But switch-to-buffer-other-tab doesn't use 'pop-to-buffer'. It uses 'display-buffer' that has no NORECORD arg. So this arg should be obsoleted, or maybe deleted right away. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 17 Oct 2021 18:05:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.16344938647557 (code B ref 51247); Sun, 17 Oct 2021 18:05:02 +0000 Received: (at 51247) by debbugs.gnu.org; 17 Oct 2021 18:04:24 +0000 Received: from localhost ([127.0.0.1]:45228 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcAWF-0001xp-Jt for submit@debbugs.gnu.org; Sun, 17 Oct 2021 14:04:24 -0400 Received: from eggs.gnu.org ([209.51.188.92]:42414) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcAWA-0001xa-Tz for 51247@debbugs.gnu.org; Sun, 17 Oct 2021 14:04:22 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:58872) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcAW5-0007o2-HJ; Sun, 17 Oct 2021 14:04:13 -0400 Received: from [87.69.77.57] (port=3816 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcAW4-0006FS-FI; Sun, 17 Oct 2021 14:04:13 -0400 Date: Sun, 17 Oct 2021 21:04:16 +0300 Message-Id: <83mtn7frz3.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87y26ry3vs.fsf@mail.linkov.net> (message from Juri Linkov on Sun, 17 Oct 2021 20:17:43 +0300) References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Sun, 17 Oct 2021 20:17:43 +0300 > > > I show below the places where IMO the lack of proper documentation is > > particularly evident, or where the documentation is insufficient or > > inaccurate. Please fill at least those gaps; bonus points for > > documenting more than this bare minimum. > > I fixed all places that you noticed (please check) Thanks. A few questions/suggestions below: (defun tab-bar--key-to-number (key) + "This function is used to interpret the key that represents a tab. +It returns `t' for the `nil' value, `nil' for the current tab, +returns the number for the symbol that begins with `tab-' like `tab-1', +and `t' for other values." I'd rewrite as follows: (defun tab-bar--key-to-number (key) "Return the tab number represented by KEY. If KEY is a symbol 'tab-N', where N is a tab number, the value is N. If KEY is \\='current-tab, the value is nil. For any other value of KET, the value is t." Is this correct? (defun tab-bar--event-to-item (posn) + "This function extracts extra info from the mouse event POSN. +It returns a list that contains three elements: a key, +a key binding, and a boolean value whether the close button \"+\" +was clicked." I'd rewrite as follows: (defun tab-bar--event-to-item (posn) "This function extracts extra info from the mouse event at position POSN. It returns a list of the form (KEY KEY-BINDING CLOSE-P), where: KEY is a symbol representing a tab, such as \\='tab-1 or \\='current-tab; KEY-BINDING is the binding of KEY; CLOSE-P is non-nil if the mouse event was a click on the close button \"x\", nil otherwise." Is this correct? (defun tab-bar--format-tab-group (tab i &optional current-p) + "Format TAB as a tab that represents a group of tabs. +Use the argument I as its index Whose index is "its index" here? (defun tab-bar--current-tab-make (&optional tab) - ;; `tab' here is an argument meaning "use tab as template". This is - ;; necessary when switching tabs, otherwise the destination tab - ;; inherits the current tab's `explicit-name' parameter. + "Make the current tab data structure from TAB. +TAB here is an argument meaning \"use tab as template\". This is +necessary when switching tabs, otherwise the destination tab +inherits the current tab's `explicit-name' parameter." I don't think I understand what do you mean by "use tab as template", can you explain? > except the following: > > > (defun tab-bar-format-tabs-groups () > > "Show tabs with their groups." > > > > The doc string says "show", but this functions doesn't display > > anything, AFAICT, it produces a list. Please adjust the doc string > > and add a description of the returned value. > > This docstring is automatically displayed in the Customization buffer > of `tab-bar-format' that looks like this: > > Hide Tab Bar Format: > Hook: > [ ] tab-bar-format-menu-global > Show global menu on clicking the Menu button. > [X] tab-bar-format-history > Show back and forward buttons when ‘tab-bar-history-mode’ is enabled. More > [ ] 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. > > (defun switch-to-buffer-other-tab (buffer-or-name &optional norecord) > > "Switch to buffer BUFFER-OR-NAME in another tab. > > Like \\[switch-to-buffer-other-frame] (which see), but creates a new tab. > > Interactively, prompt for the buffer to switch to." > > > > This command should document the NORECORD argument. > > Oops, this was copy/paste from switch-to-buffer, switch-to-buffer-other-window, > switch-to-buffer-other-frame that all just pass NORECORD down to 'pop-to-buffer'. > But switch-to-buffer-other-tab doesn't use 'pop-to-buffer'. It uses 'display-buffer' > that has no NORECORD arg. So this arg should be obsoleted, or maybe deleted right away. Fine with me, please use advertised-calling-convention or somesuch to hide that argument. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 17 Oct 2021 18:32:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163449550510084 (code B ref 51247); Sun, 17 Oct 2021 18:32:01 +0000 Received: (at 51247) by debbugs.gnu.org; 17 Oct 2021 18:31:45 +0000 Received: from localhost ([127.0.0.1]:45241 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcAwj-0002cZ-BF for submit@debbugs.gnu.org; Sun, 17 Oct 2021 14:31:45 -0400 Received: from relay2-d.mail.gandi.net ([217.70.183.194]:59309) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcAwh-0002cN-3t for 51247@debbugs.gnu.org; Sun, 17 Oct 2021 14:31:44 -0400 Received: (Authenticated sender: juri@linkov.net) by relay2-d.mail.gandi.net (Postfix) with ESMTPSA id 81D9840003; Sun, 17 Oct 2021 18:31:36 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> Date: Sun, 17 Oct 2021 21:29:21 +0300 In-Reply-To: <83mtn7frz3.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 17 Oct 2021 21:04:16 +0300") Message-ID: <87tuhfv726.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) > (defun tab-bar--current-tab-make (&optional tab) > - ;; `tab' here is an argument meaning "use tab as template". This is > - ;; necessary when switching tabs, otherwise the destination tab > - ;; inherits the current tab's `explicit-name' parameter. > + "Make the current tab data structure from TAB. > +TAB here is an argument meaning \"use tab as template\". This is > +necessary when switching tabs, otherwise the destination tab > +inherits the current tab's `explicit-name' parameter." > > I don't think I understand what do you mean by "use tab as template", > can you explain? Actually, "use tab as template" was not my text, but I improved it anyway, together with all your suggestions. >> [ ] 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. >> > (defun switch-to-buffer-other-tab (buffer-or-name &optional norecord) >> > "Switch to buffer BUFFER-OR-NAME in another tab. >> > Like \\[switch-to-buffer-other-frame] (which see), but creates a new tab. >> > Interactively, prompt for the buffer to switch to." >> > >> > This command should document the NORECORD argument. >> >> Oops, this was copy/paste from switch-to-buffer, switch-to-buffer-other-window, >> switch-to-buffer-other-frame that all just pass NORECORD down to 'pop-to-buffer'. >> But switch-to-buffer-other-tab doesn't use 'pop-to-buffer'. It uses 'display-buffer' >> that has no NORECORD arg. So this arg should be obsoleted, or maybe deleted right away. > > Fine with me, please use advertised-calling-convention or somesuch to > hide that argument. Done. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 17 Oct 2021 19:14:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163449802113956 (code B ref 51247); Sun, 17 Oct 2021 19:14:01 +0000 Received: (at 51247) by debbugs.gnu.org; 17 Oct 2021 19:13:41 +0000 Received: from localhost ([127.0.0.1]:45275 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcBbG-0003cy-3Z for submit@debbugs.gnu.org; Sun, 17 Oct 2021 15:13:41 -0400 Received: from eggs.gnu.org ([209.51.188.92]:52430) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcBbA-0003ci-IP for 51247@debbugs.gnu.org; Sun, 17 Oct 2021 15:13:37 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:32920) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcBb4-0001kl-RL; Sun, 17 Oct 2021 15:13:26 -0400 Received: from [87.69.77.57] (port=4109 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcBb4-0000cN-DR; Sun, 17 Oct 2021 15:13:26 -0400 Date: Sun, 17 Oct 2021 22:13:30 +0300 Message-Id: <83lf2rforp.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87tuhfv726.fsf@mail.linkov.net> (message from Juri Linkov on Sun, 17 Oct 2021 21:29:21 +0300) References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > 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 From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 17 Oct 2021 19:31:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163449902415548 (code B ref 51247); Sun, 17 Oct 2021 19:31:02 +0000 Received: (at 51247) by debbugs.gnu.org; 17 Oct 2021 19:30:24 +0000 Received: from localhost ([127.0.0.1]:45285 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcBrU-00042i-3Y for submit@debbugs.gnu.org; Sun, 17 Oct 2021 15:30:24 -0400 Received: from relay12.mail.gandi.net ([217.70.178.232]:58211) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcBrR-00042V-EC for 51247@debbugs.gnu.org; Sun, 17 Oct 2021 15:30:22 -0400 Received: (Authenticated sender: juri@linkov.net) by relay12.mail.gandi.net (Postfix) with ESMTPSA id E2C56200008; Sun, 17 Oct 2021 19:30:14 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> Date: Sun, 17 Oct 2021 22:27:43 +0300 In-Reply-To: <83lf2rforp.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 17 Oct 2021 22:13:30 +0300") Message-ID: <87mtn7v4cw.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) >> 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? Everything is right, except this sentence: > @@ -705,11 +705,14 @@ tab-bar-format > +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. Since menu items are used to display tabs, something like this would be more correct: Adding a function to the list causes the tab bar to show that string, or display tabs represented by menu items on the tab bar. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 17 Oct 2021 19:40:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163449954716279 (code B ref 51247); Sun, 17 Oct 2021 19:40:02 +0000 Received: (at 51247) by debbugs.gnu.org; 17 Oct 2021 19:39:07 +0000 Received: from localhost ([127.0.0.1]:45289 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcBzu-0004EU-Ut for submit@debbugs.gnu.org; Sun, 17 Oct 2021 15:39:07 -0400 Received: from eggs.gnu.org ([209.51.188.92]:55630) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcBzk-0004Dr-2o for 51247@debbugs.gnu.org; Sun, 17 Oct 2021 15:39:06 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:33776) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcBze-0004iI-D7; Sun, 17 Oct 2021 15:38:50 -0400 Received: from [87.69.77.57] (port=1707 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcBze-00028i-1D; Sun, 17 Oct 2021 15:38:50 -0400 Date: Sun, 17 Oct 2021 22:38:55 +0300 Message-Id: <83h7dffnlc.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87mtn7v4cw.fsf@mail.linkov.net> (message from Juri Linkov on Sun, 17 Oct 2021 22:27:43 +0300) References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Sun, 17 Oct 2021 22:27:43 +0300 > > >> 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? > > Everything is right, except this sentence: > > > @@ -705,11 +705,14 @@ tab-bar-format > > +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. > > Since menu items are used to display tabs, something like this > would be more correct: > > Adding a function to the list causes the tab bar to show > that string, or display tabs represented by menu items > on the tab bar. But that's not what I see. What I see is a single tab called "Menu", which, when clicked, shows the global menu. Or what do you mean by "tabs represented by menu items"? How can a tab be represented by a menu item? From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 17 Oct 2021 19:50:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163450015017310 (code B ref 51247); Sun, 17 Oct 2021 19:50:01 +0000 Received: (at 51247) by debbugs.gnu.org; 17 Oct 2021 19:49:10 +0000 Received: from localhost ([127.0.0.1]:45301 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcC9e-0004V8-Gx for submit@debbugs.gnu.org; Sun, 17 Oct 2021 15:49:10 -0400 Received: from relay4-d.mail.gandi.net ([217.70.183.196]:36037) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcC9c-0004Ut-HI for 51247@debbugs.gnu.org; Sun, 17 Oct 2021 15:49:09 -0400 Received: (Authenticated sender: juri@linkov.net) by relay4-d.mail.gandi.net (Postfix) with ESMTPSA id E7D71E0003; Sun, 17 Oct 2021 19:49:01 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> Date: Sun, 17 Oct 2021 22:48:37 +0300 In-Reply-To: <83h7dffnlc.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 17 Oct 2021 22:38:55 +0300") Message-ID: <87a6j7v3e2.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) >> Everything is right, except this sentence: >> >> > @@ -705,11 +705,14 @@ tab-bar-format >> > +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. >> >> Since menu items are used to display tabs, something like this >> would be more correct: >> >> Adding a function to the list causes the tab bar to show >> that string, or display tabs represented by menu items >> on the tab bar. > > But that's not what I see. What I see is a single tab called "Menu", > which, when clicked, shows the global menu. The menu from the tab called "Menu" is displayed with 'popup-menu'. > Or what do you mean by "tabs represented by menu items"? How can a > tab be represented by a menu item? Menu items are transformed to tab strings in parse_tab_bar_item. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: martin rudalics Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 08:22:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii , 51247@debbugs.gnu.org Cc: Juri Linkov Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163454531327111 (code B ref 51247); Mon, 18 Oct 2021 08:22:02 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 08:21:53 +0000 Received: from localhost ([127.0.0.1]:45859 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcNu5-00073D-MC for submit@debbugs.gnu.org; Mon, 18 Oct 2021 04:21:53 -0400 Received: from mout.gmx.net ([212.227.17.21]:34125) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcNu0-00072w-OQ for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 04:21:51 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1634545301; bh=YknX01u5lrzhSo84aXhyJmD6J1iiKkZzWHmemkAN+fE=; h=X-UI-Sender-Class:Subject:To:Cc:References:From:Date:In-Reply-To; b=CjeOPrX3DVJvDBFunSfkSjCWUC0uLlLrCRTQS1wYuFVksvoTDrkcrM0fptk4gbm6/ xVrVagvgT+oVD2A7Rt8lp2+Ewdzsvv3g4LTUYEPiDTmI1QdQ2JzJjdXB6Z21zIdvPK A0c5BYKIiULW3MeZMBzQJXVAxim/RBryWTN9IyZo= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from [192.168.1.100] ([46.125.249.125]) by mail.gmx.net (mrgmx105 [212.227.17.168]) with ESMTPSA (Nemesis) id 1Mdvqg-1nBA9b2U0U-00az8V; Mon, 18 Oct 2021 10:21:41 +0200 References: <831r4kghcu.fsf@gnu.org> From: martin rudalics Message-ID: <4c43cacf-2529-b0b1-bda9-26c03d545c17@gmx.at> Date: Mon, 18 Oct 2021 10:21:40 +0200 MIME-Version: 1.0 In-Reply-To: <831r4kghcu.fsf@gnu.org> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K1:KQSqI/KdVU6wtccKW81uX47l9NAtFqfOgu+s7X49dtOeAxclC15 zlHBgOff+bOP26XtYZoc2XG4k2qSoCQcQBjt/5LqRBCIqKCe2qIEg/3XFrrFdeJxl/r4Y6c j2FH+df24SAf11mGTJfRKDpIa99OmBEV18RQ1U/C0A4xo5iIrt0dc+0EWLlAH0OSEZXWsvz MykP8UlhLUP/aQ6XM0wqA== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:p+O7/br49BI=:nNZTrN1KKGqeRWY5Tc2RzA gSmJst981yDWF4RCobxi3SfOo0NYzwWfojtCpkw54czEcAmKc35RX956rU2GW1vXbI0wclxaS /xkoydr0pqpk2rjezAwlNrv/tI9Bc318M/Wajdq02zzE8nt5Xa34aZ0G2ISqzeXvTphno5Bat EbgyCz9xLFgW85DeS2P9fYLrqXXYdlQHVd5GjZ1wwqUlv5cLv1a6te9CsQHr5k8VgUXOXYpPE eevWtS+JGTpbG9sIAKwJALcc/Ed15mEyaFh43dL2g8R2c2+9I7w02xMY3zbcyDnKiOxgTd9MR V9IcSkPU0m6S/IWjr+T3QQ15vNSH9m/8j/NHyhUzOLTS5a1hrSAVqPemKOMQoZmw1ZyqKTcNI 0m5K0JStetmqIUS7vVYmgmTCsQLslJ+nKQvcqarf5FVWhObJX5NdmLEaMVLooG2WpWmuUAryc vtd4dhw0cia+hzvpwj8049BNBVvkcmkmcoytKeWB7jxrdnqHlhea/t1WSCa8xXQcINwfoxF/A MTJlOxrAGiKUGwEygldKJeDj88eh7cF1Fe4Yt7byrZcKW838IkwaT46R0ZpV0xujK6hthdVwA Hg5d0Ey///x9H4eGffWN0Z4fxdTTfEcr6sH34WxOVrrnEMpsyLh3pGC+nz2eCLoffYevhsOCf IL1vjLUW65lI8AgIRJ6DtUQ2XNwk4woYfjvi/1/UVERPJSsIM9NhVGXAs6H1KyLF6yAsaWNvG VMelv6uhEt1HxzqFM7YQj/APSlfLYd6aiTXYuCP8YrjdfxFdpBG6RcdJ0ViBJdaGN2HK35+Z9 zT6pz4LaQ8OYEQyOnNrzrIlZGSx4DfvFih5wzwako61pisWoNn/QswCx/SnZ/4JdCsiVa3ynF zKBS6lAnmEjdyEcsxgDgQPTpArVkYa4uAEH46b15uypoguCxRdqVYevZv6kJXgIzWT4A3n0uy lUDN0PWVlCi1RqaoI0MXzZ9mwXHEVdZLFhxpxp4ggPXowO633CT3oPuTsvuj2NHcSWgtKDROW NzFRF8q/pyLDwZDXVJuOdPV9Y8o0N79U8OWObVA9lKzUVhXOsGgWsFKp9KLy15Oo516zWd4sv MhlPSwYt1CIInk= X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) > Some functions in tab-bar.el and the data they return are documented > insufficiently, so much so that it makes the code there very hard to > develop and maintain by anyone except the original author. I now added a few tab bar and tab line related elements to the Elisp manual. Please have a look and tell me if anything else should be added or done. Some reshuffling (especially that of the "Selecting Window" section) will be inconvenient to trace. Apologies for that but I think the general accessibility of some of the contained terms is hopefully better now. Thanks, martin From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 11:39:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163455711215712 (code B ref 51247); Mon, 18 Oct 2021 11:39:02 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 11:38:32 +0000 Received: from localhost ([127.0.0.1]:46095 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcQyN-00045L-MT for submit@debbugs.gnu.org; Mon, 18 Oct 2021 07:38:31 -0400 Received: from eggs.gnu.org ([209.51.188.92]:46794) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcQyI-000456-Mt for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 07:38:30 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:35240) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcQyB-0004eQ-I5; Mon, 18 Oct 2021 07:38:19 -0400 Received: from [87.69.77.57] (port=4848 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcQyB-0005Ka-3z; Mon, 18 Oct 2021 07:38:19 -0400 Date: Mon, 18 Oct 2021 14:38:25 +0300 Message-Id: <83bl3mftqm.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87a6j7v3e2.fsf@mail.linkov.net> (message from Juri Linkov on Sun, 17 Oct 2021 22:48:37 +0300) References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Sun, 17 Oct 2021 22:48:37 +0300 > > >> Everything is right, except this sentence: > >> > >> > @@ -705,11 +705,14 @@ tab-bar-format > >> > +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. > >> > >> Since menu items are used to display tabs, something like this > >> would be more correct: > >> > >> Adding a function to the list causes the tab bar to show > >> that string, or display tabs represented by menu items > >> on the tab bar. > > > > But that's not what I see. What I see is a single tab called "Menu", > > which, when clicked, shows the global menu. > > The menu from the tab called "Menu" is displayed with 'popup-menu'. > > > Or what do you mean by "tabs represented by menu items"? How can a > > tab be represented by a menu item? > > Menu items are transformed to tab strings in parse_tab_bar_item. Sorry, I'm still confused. Again, checking this option: > [ ] tab-bar-format-menu-global > Show global menu on clicking the Menu button. causes the tab bar to include a single tab called "Menu", and if I click on that tab, I see the items from the global menu-bar. In any case, I don't see the importance of the fine difference between "menu items" and "menu items that represent tabs" in this case. AFAIU, whatever menu is produced by that option is what's displayed on the tab bar; the items in the menu are entirely up to the function which produces the menu. Isn't that right? From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 14:15:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: martin rudalics Cc: 51247@debbugs.gnu.org, juri@linkov.net Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163456648116825 (code B ref 51247); Mon, 18 Oct 2021 14:15:01 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 14:14:41 +0000 Received: from localhost ([127.0.0.1]:48208 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcTPU-0004NI-LJ for submit@debbugs.gnu.org; Mon, 18 Oct 2021 10:14:40 -0400 Received: from eggs.gnu.org ([209.51.188.92]:59170) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcTPS-0004N6-R7 for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 10:14:39 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:41908) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcTPM-0007EH-Rl; Mon, 18 Oct 2021 10:14:32 -0400 Received: from [87.69.77.57] (port=2728 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcTPM-00049X-Ee; Mon, 18 Oct 2021 10:14:32 -0400 Date: Mon, 18 Oct 2021 17:14:39 +0300 Message-Id: <83ee8ie7xs.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <4c43cacf-2529-b0b1-bda9-26c03d545c17@gmx.at> (message from martin rudalics on Mon, 18 Oct 2021 10:21:40 +0200) References: <831r4kghcu.fsf@gnu.org> <4c43cacf-2529-b0b1-bda9-26c03d545c17@gmx.at> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Cc: Juri Linkov > From: martin rudalics > Date: Mon, 18 Oct 2021 10:21:40 +0200 > > > Some functions in tab-bar.el and the data they return are documented > > insufficiently, so much so that it makes the code there very hard to > > develop and maintain by anyone except the original author. > > I now added a few tab bar and tab line related elements to the Elisp > manual. Please have a look and tell me if anything else should be added > or done. Thanks. Some comments/questions: > +@item Tab Bar > +@cindex internal tab bar Why "internal"? copy/pasta? You use the term "minibuffer window", which I think is sub-optimal: that window is also used for displaying the echo-area. I prefer the term "mini-window" instead. > +Note that the window returned by @code{minibuffer-window} called with > +the argument @var{frame} is returned by @code{window-list} called with > +the same argument if and only if that window actually belongs to > +@var{frame}. This is a mouthful (is it really important to say this here?). Please rephrase, in particular with fewer instances of the passive tense. (The next sentence after that is also unnecessarily passive and hard to read.) I made a few minor editing changes in the text you installed. Thanks for taking care of the manual. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 16:22:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.16345740845187 (code B ref 51247); Mon, 18 Oct 2021 16:22:02 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 16:21:24 +0000 Received: from localhost ([127.0.0.1]:48351 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcVO5-0001LY-1h for submit@debbugs.gnu.org; Mon, 18 Oct 2021 12:21:24 -0400 Received: from relay5-d.mail.gandi.net ([217.70.183.197]:49427) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcVO2-0001LL-U7 for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 12:21:19 -0400 Received: (Authenticated sender: juri@linkov.net) by relay5-d.mail.gandi.net (Postfix) with ESMTPSA id 710A21C0005; Mon, 18 Oct 2021 16:21:11 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> Date: Mon, 18 Oct 2021 18:53:40 +0300 In-Reply-To: <83bl3mftqm.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 18 Oct 2021 14:38:25 +0300") Message-ID: <87czo2peob.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) >> The menu from the tab called "Menu" is displayed with 'popup-menu'. >> >> > Or what do you mean by "tabs represented by menu items"? How can a >> > tab be represented by a menu item? >> >> Menu items are transformed to tab strings in parse_tab_bar_item. > > Sorry, I'm still confused. Again, checking this option: > >> [ ] tab-bar-format-menu-global >> Show global menu on clicking the Menu button. > > causes the tab bar to include a single tab called "Menu", and if I > click on that tab, I see the items from the global menu-bar. > > In any case, I don't see the importance of the fine difference between > "menu items" and "menu items that represent tabs" in this case. > AFAIU, whatever menu is produced by that option is what's displayed on > the tab bar; the items in the menu are entirely up to the function > which produces the menu. Isn't that right? This text is still wrong: 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. The tab called "Menu" displays menu items from the global menu-bar, not from those menu items mentioned in the doc string. Those menu items are used only to display tabs. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 16:37:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163457500014940 (code B ref 51247); Mon, 18 Oct 2021 16:37:02 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 16:36:40 +0000 Received: from localhost ([127.0.0.1]:48378 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcVct-0003su-Ti for submit@debbugs.gnu.org; Mon, 18 Oct 2021 12:36:40 -0400 Received: from eggs.gnu.org ([209.51.188.92]:34488) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcVcs-0003sg-1j for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 12:36:38 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:46514) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcVcm-0001c7-KO; Mon, 18 Oct 2021 12:36:32 -0400 Received: from [87.69.77.57] (port=3644 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcVcm-0005bG-7h; Mon, 18 Oct 2021 12:36:32 -0400 Date: Mon, 18 Oct 2021 19:36:39 +0300 Message-Id: <83a6j6e1d4.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87czo2peob.fsf@mail.linkov.net> (message from Juri Linkov on Mon, 18 Oct 2021 18:53:40 +0300) References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Mon, 18 Oct 2021 18:53:40 +0300 > > > In any case, I don't see the importance of the fine difference between > > "menu items" and "menu items that represent tabs" in this case. > > AFAIU, whatever menu is produced by that option is what's displayed on > > the tab bar; the items in the menu are entirely up to the function > > which produces the menu. Isn't that right? > > This text is still wrong: > > 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. > > The tab called "Menu" displays menu items from the global menu-bar, > not from those menu items mentioned in the doc string. > Those menu items are used only to display tabs. Then please point me to a function out of those mentioned in tab-bar-format's :options that returns a list of menu items. The sentence in the doc string "Every item in the list is a function that returns a string, or a list of menu-item elements, or nil" wasn't mine, it was yours. What did you have in mind when you wrote that? From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 16:48:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163457562515946 (code B ref 51247); Mon, 18 Oct 2021 16:48:01 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 16:47:05 +0000 Received: from localhost ([127.0.0.1]:48399 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcVmz-000498-MN for submit@debbugs.gnu.org; Mon, 18 Oct 2021 12:47:05 -0400 Received: from relay11.mail.gandi.net ([217.70.178.231]:34839) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcVmy-00048c-Dz for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 12:47:05 -0400 Received: (Authenticated sender: juri@linkov.net) by relay11.mail.gandi.net (Postfix) with ESMTPSA id A1D95100003; Mon, 18 Oct 2021 16:46:57 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> Date: Mon, 18 Oct 2021 19:44:31 +0300 In-Reply-To: <83a6j6e1d4.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 18 Oct 2021 19:36:39 +0300") Message-ID: <87wnmal1u8.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) >> This text is still wrong: >> >> 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. >> >> The tab called "Menu" displays menu items from the global menu-bar, >> not from those menu items mentioned in the doc string. >> Those menu items are used only to display tabs. > > Then please point me to a function out of those mentioned in > tab-bar-format's :options that returns a list of menu items. The > sentence in the doc string "Every item in the list is a function that > returns a string, or a list of menu-item elements, or nil" wasn't > mine, it was yours. What did you have in mind when you wrote that? - tab-bar-format-menu-global returns a list of menu items that display the "Menu" tab. This tab is bound to a command that uses popup-menu to display the global menu on clicking. - tab-bar-format-history returns a list of menu items that produce back and forward buttons. - tab-bar-format-tabs and tab-bar-format-tabs-groups return a list of menu items that produce the tabs for the tab bar. ... - Only tab-bar-separator returns a string. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 16:54:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163457600516624 (code B ref 51247); Mon, 18 Oct 2021 16:54:03 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 16:53:25 +0000 Received: from localhost ([127.0.0.1]:48403 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcVt6-0004K3-CU for submit@debbugs.gnu.org; Mon, 18 Oct 2021 12:53:25 -0400 Received: from eggs.gnu.org ([209.51.188.92]:40132) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcVsr-0004Jc-Gr for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 12:53:23 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:47086) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcVsm-0005sw-0l; Mon, 18 Oct 2021 12:53:04 -0400 Received: from [87.69.77.57] (port=4720 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcVsl-0007go-IO; Mon, 18 Oct 2021 12:53:03 -0400 Date: Mon, 18 Oct 2021 19:53:10 +0300 Message-Id: <838ryqe0ll.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87wnmal1u8.fsf@mail.linkov.net> (message from Juri Linkov on Mon, 18 Oct 2021 19:44:31 +0300) References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Mon, 18 Oct 2021 19:44:31 +0300 > > >> This text is still wrong: > >> > >> 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. > >> > >> The tab called "Menu" displays menu items from the global menu-bar, > >> not from those menu items mentioned in the doc string. > >> Those menu items are used only to display tabs. > > > > Then please point me to a function out of those mentioned in > > tab-bar-format's :options that returns a list of menu items. The > > sentence in the doc string "Every item in the list is a function that > > returns a string, or a list of menu-item elements, or nil" wasn't > > mine, it was yours. What did you have in mind when you wrote that? > > - tab-bar-format-menu-global returns a list of menu items > that display the "Menu" tab. This tab is bound to a command > that uses popup-menu to display the global menu on clicking. > > - tab-bar-format-history returns a list of menu items > that produce back and forward buttons. > > - tab-bar-format-tabs and tab-bar-format-tabs-groups > return a list of menu items that produce the tabs for the tab bar. > ... > > - Only tab-bar-separator returns a string. Then the doc string after my changes is exactly right. I have no idea what you see that's wrong with it. You say some functions return menu items and some return a list of menu items, and that's what the doc string says. You say that these values are displayed on the tab bar, and that's what the doc string says. So what exactly is wrong?? From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 17:02:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: juri@linkov.net Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163457648117531 (code B ref 51247); Mon, 18 Oct 2021 17:02:02 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 17:01:21 +0000 Received: from localhost ([127.0.0.1]:48421 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcW0m-0004Yg-Rt for submit@debbugs.gnu.org; Mon, 18 Oct 2021 13:01:21 -0400 Received: from eggs.gnu.org ([209.51.188.92]:42174) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcW0k-0004YP-0l for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 13:01:18 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:47334) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcW0e-0006cY-JI; Mon, 18 Oct 2021 13:01:12 -0400 Received: from [87.69.77.57] (port=1247 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcW0e-0004QP-3h; Mon, 18 Oct 2021 13:01:12 -0400 Date: Mon, 18 Oct 2021 20:01:18 +0300 Message-Id: <837deae081.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <838ryqe0ll.fsf@gnu.org> (message from Eli Zaretskii on Mon, 18 Oct 2021 19:53:10 +0300) References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Date: Mon, 18 Oct 2021 19:53:10 +0300 > From: Eli Zaretskii > Cc: 51247@debbugs.gnu.org > > Then the doc string after my changes is exactly right. I have no idea > what you see that's wrong with it. You say some functions return menu > items and some return a list of menu items, and that's what the doc > string says. You say that these values are displayed on the tab bar, > and that's what the doc string says. So what exactly is wrong?? Or let me turn the table and ask you to explain to a potential Lisp programmer what to expect from adding a function to the list in tab-bar-format. Suppose J.R. Hacker wants to write a function suitable for inclusion in this list, and suppose the function returns a string or a list of menu items -- what should J.R. Hacker expect from putting that function in this list? how will the tab bar display the value returned by the function? From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 17:02:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163457648817550 (code B ref 51247); Mon, 18 Oct 2021 17:02:03 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 17:01:28 +0000 Received: from localhost ([127.0.0.1]:48424 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcW0u-0004Z0-3Q for submit@debbugs.gnu.org; Mon, 18 Oct 2021 13:01:28 -0400 Received: from relay1-d.mail.gandi.net ([217.70.183.193]:58657) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcW0s-0004Yf-GS for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 13:01:27 -0400 Received: (Authenticated sender: juri@linkov.net) by relay1-d.mail.gandi.net (Postfix) with ESMTPSA id 90364240008; Mon, 18 Oct 2021 17:01:19 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> Date: Mon, 18 Oct 2021 20:01:09 +0300 In-Reply-To: <838ryqe0ll.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 18 Oct 2021 19:53:10 +0300") Message-ID: <878ryql12i.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) > Then the doc string after my changes is exactly right. I have no idea > what you see that's wrong with it. You say some functions return menu > items and some return a list of menu items, and that's what the doc > string says. You say that these values are displayed on the tab bar, > and that's what the doc string says. So what exactly is wrong?? 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. It says that only when you click on the tab bar, those menu items are used to display some menu. But in fact those menu items are used to display tabs or buttons, without clicking. This is more correct: Adding a function to the list causes the tab bar to show that string, or display tabs or buttons created from those menu items. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 17:03:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163457656617678 (code B ref 51247); Mon, 18 Oct 2021 17:03:02 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 17:02:46 +0000 Received: from localhost ([127.0.0.1]:48429 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcW2A-0004b4-CV for submit@debbugs.gnu.org; Mon, 18 Oct 2021 13:02:46 -0400 Received: from relay1-d.mail.gandi.net ([217.70.183.193]:59925) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcW29-0004ap-C0 for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 13:02:45 -0400 Received: (Authenticated sender: juri@linkov.net) by relay1-d.mail.gandi.net (Postfix) with ESMTPSA id 01DA6240007; Mon, 18 Oct 2021 17:02:38 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> Date: Mon, 18 Oct 2021 20:02:21 +0300 In-Reply-To: <837deae081.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 18 Oct 2021 20:01:18 +0300") Message-ID: <8735oyl10i.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) > Or let me turn the table and ask you to explain to a potential Lisp > programmer what to expect from adding a function to the list in > tab-bar-format. Suppose J.R. Hacker wants to write a function > suitable for inclusion in this list, and suppose the function returns > a string or a list of menu items -- what should J.R. Hacker expect > from putting that function in this list? how will the tab bar display > the value returned by the function? It will display tabs or buttons from these menu items. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 17:16:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163457731418767 (code B ref 51247); Mon, 18 Oct 2021 17:16:02 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 17:15:14 +0000 Received: from localhost ([127.0.0.1]:48433 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcWEE-0004sd-FM for submit@debbugs.gnu.org; Mon, 18 Oct 2021 13:15:14 -0400 Received: from eggs.gnu.org ([209.51.188.92]:44994) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcWE9-0004sH-Mp for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 13:15:13 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:47676) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcWE4-0003Sv-6m; Mon, 18 Oct 2021 13:15:04 -0400 Received: from [87.69.77.57] (port=2098 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcWE3-0007f7-QF; Mon, 18 Oct 2021 13:15:04 -0400 Date: Mon, 18 Oct 2021 20:15:09 +0300 Message-Id: <835ytudzky.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <8735oyl10i.fsf@mail.linkov.net> (message from Juri Linkov on Mon, 18 Oct 2021 20:02:21 +0300) References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Mon, 18 Oct 2021 20:02:21 +0300 > > > Or let me turn the table and ask you to explain to a potential Lisp > > programmer what to expect from adding a function to the list in > > tab-bar-format. Suppose J.R. Hacker wants to write a function > > suitable for inclusion in this list, and suppose the function returns > > a string or a list of menu items -- what should J.R. Hacker expect > > from putting that function in this list? how will the tab bar display > > the value returned by the function? > > It will display tabs or buttons from these menu items. When will it be tabs and when will it be buttons? And to which of these does "menu" belong? From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 17:23:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163457775719485 (code B ref 51247); Mon, 18 Oct 2021 17:23:01 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 17:22:37 +0000 Received: from localhost ([127.0.0.1]:48451 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcWLN-00054D-8t for submit@debbugs.gnu.org; Mon, 18 Oct 2021 13:22:37 -0400 Received: from relay1-d.mail.gandi.net ([217.70.183.193]:34493) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcWL9-00053l-CR for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 13:22:35 -0400 Received: (Authenticated sender: juri@linkov.net) by relay1-d.mail.gandi.net (Postfix) with ESMTPSA id 9812F240010; Mon, 18 Oct 2021 17:22:15 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> Date: Mon, 18 Oct 2021 20:21:48 +0300 In-Reply-To: <835ytudzky.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 18 Oct 2021 20:15:09 +0300") Message-ID: <87ee8ijljn.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) >> It will display tabs or buttons from these menu items. > > When will it be tabs and when will it be buttons? Tabs are buttons that switch window configurations. > And to which of these does "menu" belong? "Menu" should not be mentioned at all, it's some unimportant detail from one non-default option. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 17:33:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163457837820614 (code B ref 51247); Mon, 18 Oct 2021 17:33:03 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 17:32:58 +0000 Received: from localhost ([127.0.0.1]:48512 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcWVN-0005MQ-OP for submit@debbugs.gnu.org; Mon, 18 Oct 2021 13:32:57 -0400 Received: from eggs.gnu.org ([209.51.188.92]:50172) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcWVM-0005ME-PQ for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 13:32:57 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:48260) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcWVG-0003SO-QD; Mon, 18 Oct 2021 13:32:50 -0400 Received: from [87.69.77.57] (port=3200 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcWVG-0004hT-DT; Mon, 18 Oct 2021 13:32:50 -0400 Date: Mon, 18 Oct 2021 20:32:57 +0300 Message-Id: <834k9edyra.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87ee8ijljn.fsf@mail.linkov.net> (message from Juri Linkov on Mon, 18 Oct 2021 20:21:48 +0300) References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Mon, 18 Oct 2021 20:21:48 +0300 > > >> It will display tabs or buttons from these menu items. > > > > When will it be tabs and when will it be buttons? > > Tabs are buttons that switch window configurations. But how do I explain in the doc string to the future programmers what they should do to get tabs and what they should do to get buttons that drop a menu? Presumably, each of these needs a list of menu items of different forms, but how should they be different? How does the tab bar know what to display given the menu items returned by these functions? From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: martin rudalics Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 17:44:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org, juri@linkov.net Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163457903721574 (code B ref 51247); Mon, 18 Oct 2021 17:44:02 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 17:43:57 +0000 Received: from localhost ([127.0.0.1]:48518 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcWg0-0005bt-R9 for submit@debbugs.gnu.org; Mon, 18 Oct 2021 13:43:57 -0400 Received: from mout.gmx.net ([212.227.15.18]:60051) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcWfy-0005be-2I for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 13:43:55 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1634579027; bh=UFr4pzYjK9IcHmKI5np2NsF5k4nbVa75SCjByvd27us=; h=X-UI-Sender-Class:Subject:To:Cc:References:From:Date:In-Reply-To; b=FsdXceoiZmrLKdNKmbz6smuQJYfisZ7nRBuSXBuD83L111CiZGklZ88s8ZQKOsg1y 9M4PxxGrPjRlCFdt3nLh/IM81tBuAd91PJw5DQFNCUWij7E7IDXLRYOHwq4q2DBWQ1 r/aNSWR4ss+8AKMIzMbGiZny9WwQbYyjC7+xigIM= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from [192.168.1.100] ([46.125.249.39]) by mail.gmx.net (mrgmx004 [212.227.17.190]) with ESMTPSA (Nemesis) id 1MORAa-1mMdgK45cs-00PsJP; Mon, 18 Oct 2021 19:43:47 +0200 References: <831r4kghcu.fsf@gnu.org> <4c43cacf-2529-b0b1-bda9-26c03d545c17@gmx.at> <83ee8ie7xs.fsf@gnu.org> From: martin rudalics Message-ID: <3d2c6767-b2f4-d27c-4153-67d5163c64f9@gmx.at> Date: Mon, 18 Oct 2021 19:43:45 +0200 MIME-Version: 1.0 In-Reply-To: <83ee8ie7xs.fsf@gnu.org> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K1:LAyXa8/EwYOne4cWR7vFP2U0O+D0Hu1bCPc4DeqAiFKXxp2klBP zNcZxOtdbaw3Ze1X81kcT5YQp4b4CUyP7JN+T39jK8tJI/z2+wWOiohzGmTTRiX93rUronC oYfxrFrvTZTgZ7d7ufkxXO1PcwepQG9B0ydCynvrr1NsKqV9U+WiMoJYpwz9hx/AhBn8M2/ vtcgdI9pRLAtzRHxeg2wQ== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:FCtt1iziM6E=:IoUetRh6kUR6WFHDW2Hk2J rRjUXvNHJ+ukdFC6EPEKDJfVPG8cuzvQXmDt4TzWXcrOcX4Trz3lQFAFQhROltRYsT0z3pBVe 1YqMVgAKvyUOSQHTm4ZIhuInkYoTlH6q+LRlt/0sCqWmMOj7/mMAYCt/ivfIUxOuwh72hB15y eMEP8dWJHi70rAMpW2oakpKUtzP8Y7iQEOds/iGZFZXVP3vjpniGurRkR3PAbrAAeALL5LCle WyW26DsLvqXhWjdconlIj5f/UxKYqi/r2AvOoW5Gnmr3IzT+WNpusy/1sF8czWrhcken5BSZK xSMafetbSVaQNGEt8A29X4qtglBoYhNi7Q8pB5aAuCRZBwo8ePAgbVNjvre3w0IQNX/fzBUGl e24AVtowhdyUE7UGmxKpRdPyjeIpVbu+v8kc0ApwH0qH3au5Xmpc8h87cKGoqf08rWfJ0kDB1 x6MuL5/CbF1XM+gp3hGC6W5ynWi95Qrqbx+iIIhzf/iESwEIPNcRh5F5xn+e6/XaYK1ylMMos vIVcw8nyWRDlQSECppQzBOSF412C8GhWdJ/VTUhWM95EvF9asI+OSo2zhzpwQ6j8MQlQm3qSx iSdCaFHFLQfaN861qF0QWmRB+rMuyZY8jP/hFTooDGgrNrlOMRkvVhd46aSdWCFbjmo/HGC9R ZwxIM4MQmlwnDEcGqp5y2CeRGQqDUNpl+i9F/6gTJMl9qviblKqaIfLi3wrRDmlX49D6WiRlL SOVf8fajUI5tMcdjXg6KRiKOwo/Jg1bm71+ocqsF8HORHXUOwp7tY/94quyPESXfAYCe159CV osbr271iFDo8zbeuQ0WOYsOvHNIDU+df0+E6cm5WvO4PgSOicWSFt2a/H4CLxl7JoBIsH/6fW rIZ7GF3/QKVN6hD7q4sP+VzaHMqmqa+zBCveSl9uvFiN3s5Kamgop/RDDRV/UK89bCDqI19hX gcY9zzq/MMBGPkNVegHr2qA0o5Rhw5UedmN1zApuDmJTfsvREHGIWJw3y2YvDuibM5tDyt99m rfw9tqI4Qnya/Ywfc8NRfc/jphBO6EUWlpTDFcgHH5eR54xzsH+V6iVKvmbCb/dypL4e3LbSX +gkb5IajNttha4= X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) > Thanks. Some comments/questions: > >> +@item Tab Bar >> +@cindex internal tab bar > > Why "internal"? copy/pasta? Intentional but silly. Fixed. > You use the term "minibuffer window", which I think is sub-optimal: > that window is also used for displaying the echo-area. I prefer the > term "mini-window" instead. That ship has sailed somehow. We have an entire section called "Minibuffer Windows". >> +Note that the window returned by @code{minibuffer-window} called with >> +the argument @var{frame} is returned by @code{window-list} called with >> +the same argument if and only if that window actually belongs to >> +@var{frame}. > > This is a mouthful (is it really important to say this here?). Please > rephrase, in particular with fewer instances of the passive tense. > (The next sentence after that is also unnecessarily passive and hard > to read.) I removed that paragraph. Honestly, it would have taken me too much time to understand it myself. > I made a few minor editing changes in the text you installed. Thanks. This one - A @dfn{window} describes a portion of the screen that Emacs uses to + A @dfn{window} describes the portion of the screen that Emacs uses to is not really correct because with multiple windows we have several such portions but maybe it's more intuitive for the reader. Thanks, martin From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Oct 2021 18:24:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: martin rudalics Cc: 51247@debbugs.gnu.org, juri@linkov.net Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163458143225398 (code B ref 51247); Mon, 18 Oct 2021 18:24:01 +0000 Received: (at 51247) by debbugs.gnu.org; 18 Oct 2021 18:23:52 +0000 Received: from localhost ([127.0.0.1]:48563 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcXIe-0006ba-GG for submit@debbugs.gnu.org; Mon, 18 Oct 2021 14:23:52 -0400 Received: from eggs.gnu.org ([209.51.188.92]:33056) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcXIa-0006bK-BS for 51247@debbugs.gnu.org; Mon, 18 Oct 2021 14:23:50 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:49802) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcXIU-0007HQ-E3; Mon, 18 Oct 2021 14:23:42 -0400 Received: from [87.69.77.57] (port=2330 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcXIS-0003Xq-7T; Mon, 18 Oct 2021 14:23:42 -0400 Date: Mon, 18 Oct 2021 21:23:47 +0300 Message-Id: <8335oydwek.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <3d2c6767-b2f4-d27c-4153-67d5163c64f9@gmx.at> (message from martin rudalics on Mon, 18 Oct 2021 19:43:45 +0200) References: <831r4kghcu.fsf@gnu.org> <4c43cacf-2529-b0b1-bda9-26c03d545c17@gmx.at> <83ee8ie7xs.fsf@gnu.org> <3d2c6767-b2f4-d27c-4153-67d5163c64f9@gmx.at> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Cc: 51247@debbugs.gnu.org, juri@linkov.net > From: martin rudalics > Date: Mon, 18 Oct 2021 19:43:45 +0200 > > - A @dfn{window} describes a portion of the screen that Emacs uses to > + A @dfn{window} describes the portion of the screen that Emacs uses to > > is not really correct because with multiple windows we have several such > portions but maybe it's more intuitive for the reader. My English is not really native, but AFAIK once you describe a thing, it should be "the thing", not "a thing". Let's hear from natives, though. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 19 Oct 2021 07:14:04 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.16346276211964 (code B ref 51247); Tue, 19 Oct 2021 07:14:04 +0000 Received: (at 51247) by debbugs.gnu.org; 19 Oct 2021 07:13:41 +0000 Received: from localhost ([127.0.0.1]:49241 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcjJa-0000VX-3l for submit@debbugs.gnu.org; Tue, 19 Oct 2021 03:13:41 -0400 Received: from relay9-d.mail.gandi.net ([217.70.183.199]:42187) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcjJU-0000Up-3E for 51247@debbugs.gnu.org; Tue, 19 Oct 2021 03:13:33 -0400 Received: (Authenticated sender: juri@linkov.net) by relay9-d.mail.gandi.net (Postfix) with ESMTPSA id 0C517FF811; Tue, 19 Oct 2021 07:13:24 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> Date: Tue, 19 Oct 2021 09:49:59 +0300 In-Reply-To: <834k9edyra.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 18 Oct 2021 20:32:57 +0300") Message-ID: <871r4hldq8.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) >> >> It will display tabs or buttons from these menu items. >> > >> > When will it be tabs and when will it be buttons? >> >> Tabs are buttons that switch window configurations. > > But how do I explain in the doc string to the future programmers what > they should do to get tabs and what they should do to get buttons that > drop a menu? You don't need to explain about buttons that drop a menu. This is irrelevant for the description of tab-bar-format. Just imagine there is no tab-bar-format-menu-global that uses own unrelated menu items. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 19 Oct 2021 12:09:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163464529519393 (code B ref 51247); Tue, 19 Oct 2021 12:09:01 +0000 Received: (at 51247) by debbugs.gnu.org; 19 Oct 2021 12:08:15 +0000 Received: from localhost ([127.0.0.1]:49744 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcnug-00052j-Pu for submit@debbugs.gnu.org; Tue, 19 Oct 2021 08:08:15 -0400 Received: from eggs.gnu.org ([209.51.188.92]:58944) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcnud-00052I-4r for 51247@debbugs.gnu.org; Tue, 19 Oct 2021 08:08:11 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:50464) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcnuX-0008KY-7A; Tue, 19 Oct 2021 08:08:05 -0400 Received: from [87.69.77.57] (port=4090 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcnuW-0001iy-R3; Tue, 19 Oct 2021 08:08:05 -0400 Date: Tue, 19 Oct 2021 15:08:14 +0300 Message-Id: <83lf2pcj4h.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <871r4hldq8.fsf@mail.linkov.net> (message from Juri Linkov on Tue, 19 Oct 2021 09:49:59 +0300) References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Tue, 19 Oct 2021 09:49:59 +0300 > > >> >> It will display tabs or buttons from these menu items. > >> > > >> > When will it be tabs and when will it be buttons? > >> > >> Tabs are buttons that switch window configurations. > > > > But how do I explain in the doc string to the future programmers what > > they should do to get tabs and what they should do to get buttons that > > drop a menu? > > You don't need to explain about buttons that drop a menu. > This is irrelevant for the description of tab-bar-format. > Just imagine there is no tab-bar-format-menu-global > that uses own unrelated menu items. Sorry, that won't fly. The doc string should explain enough for other Lisp programmers to be able to produce buttons that drop down menus. So please humor me with a detailed enough answer to my questions, I'm investing enough energy in this stuff to be entitled to a bit more than a couple of dismissive sentences. We must have a decent doc string for this defcustom. Please help me fix what we have now. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 19 Oct 2021 19:14:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163467079722445 (code B ref 51247); Tue, 19 Oct 2021 19:14:02 +0000 Received: (at 51247) by debbugs.gnu.org; 19 Oct 2021 19:13:17 +0000 Received: from localhost ([127.0.0.1]:52026 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcuY0-0005px-VE for submit@debbugs.gnu.org; Tue, 19 Oct 2021 15:13:17 -0400 Received: from relay4-d.mail.gandi.net ([217.70.183.196]:47591) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mcuXz-0005pj-A2 for 51247@debbugs.gnu.org; Tue, 19 Oct 2021 15:13:15 -0400 Received: (Authenticated sender: juri@linkov.net) by relay4-d.mail.gandi.net (Postfix) with ESMTPSA id 3139CE0005; Tue, 19 Oct 2021 19:13:07 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> <83lf2pcj4h.fsf@gnu.org> Date: Tue, 19 Oct 2021 22:09:27 +0300 In-Reply-To: <83lf2pcj4h.fsf@gnu.org> (Eli Zaretskii's message of "Tue, 19 Oct 2021 15:08:14 +0300") Message-ID: <8735ow7rx4.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) >> You don't need to explain about buttons that drop a menu. >> This is irrelevant for the description of tab-bar-format. >> Just imagine there is no tab-bar-format-menu-global >> that uses own unrelated menu items. > > Sorry, that won't fly. The doc string should explain enough for other > Lisp programmers to be able to produce buttons that drop down menus. This is the whole point. The doc string of this variable is not an appropriate place to teach Lisp programmers how to produce buttons that drop down menus. Or you might as well include the whole Emacs Lisp Reference Manual in this doc string. > So please humor me with a detailed enough answer to my questions, I'm > investing enough energy in this stuff to be entitled to a bit more > than a couple of dismissive sentences. > > We must have a decent doc string for this defcustom. Please help me > fix what we have now. You assumed in the doc string that those menu items as used to display a menu, whereas in fact those menu items as used to display tabs and other buttons on the tab bar. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 20 Oct 2021 11:36:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163472973324059 (code B ref 51247); Wed, 20 Oct 2021 11:36:01 +0000 Received: (at 51247) by debbugs.gnu.org; 20 Oct 2021 11:35:33 +0000 Received: from localhost ([127.0.0.1]:52870 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1md9sb-0006Fz-1o for submit@debbugs.gnu.org; Wed, 20 Oct 2021 07:35:33 -0400 Received: from eggs.gnu.org ([209.51.188.92]:33058) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1md9sZ-0006Fe-Db for 51247@debbugs.gnu.org; Wed, 20 Oct 2021 07:35:31 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:34678) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1md9sT-0004Im-SM; Wed, 20 Oct 2021 07:35:25 -0400 Received: from [87.69.77.57] (port=3159 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1md9sB-0000yv-17; Wed, 20 Oct 2021 07:35:24 -0400 Date: Wed, 20 Oct 2021 14:35:18 +0300 Message-Id: <83sfwwapzd.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <8735ow7rx4.fsf@mail.linkov.net> (message from Juri Linkov on Tue, 19 Oct 2021 22:09:27 +0300) References: <831r4kghcu.fsf@gnu.org> <87y26ry3vs.fsf@mail.linkov.net> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> <83lf2pcj4h.fsf@gnu.org> <8735ow7rx4.fsf@mail.linkov.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Tue, 19 Oct 2021 22:09:27 +0300 > > >> You don't need to explain about buttons that drop a menu. > >> This is irrelevant for the description of tab-bar-format. > >> Just imagine there is no tab-bar-format-menu-global > >> that uses own unrelated menu items. > > > > Sorry, that won't fly. The doc string should explain enough for other > > Lisp programmers to be able to produce buttons that drop down menus. > > This is the whole point. The doc string of this variable is not an > appropriate place to teach Lisp programmers how to produce buttons > that drop down menus. That's not what I meant. I meant to explain to people who already know to produce menus how to format those menus in these two different manners for two different effects. > Or you might as well include the whole Emacs Lisp Reference Manual > in this doc string. This is not constructive and not helpful, let alone uncalled-for. > > So please humor me with a detailed enough answer to my questions, I'm > > investing enough energy in this stuff to be entitled to a bit more > > than a couple of dismissive sentences. > > > > We must have a decent doc string for this defcustom. Please help me > > fix what we have now. > > You assumed in the doc string that those menu items as used > to display a menu, whereas in fact those menu items as used > to display tabs and other buttons on the tab bar. I'm trying to understand the difference between the two kinds of menus, the one which causes the tab bar to display tabs, vs the one that causes the display of a single tab that drops down a menu. Please help me understand that difference. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 20 Oct 2021 16:52:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163474871628397 (code B ref 51247); Wed, 20 Oct 2021 16:52:01 +0000 Received: (at 51247) by debbugs.gnu.org; 20 Oct 2021 16:51:56 +0000 Received: from localhost ([127.0.0.1]:55352 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdEom-0007Nx-Jb for submit@debbugs.gnu.org; Wed, 20 Oct 2021 12:51:56 -0400 Received: from relay5-d.mail.gandi.net ([217.70.183.197]:57611) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdEol-0007Nj-Ek for 51247@debbugs.gnu.org; Wed, 20 Oct 2021 12:51:55 -0400 Received: (Authenticated sender: juri@linkov.net) by relay5-d.mail.gandi.net (Postfix) with ESMTPSA id 58D4C1C000D; Wed, 20 Oct 2021 16:51:47 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> <83lf2pcj4h.fsf@gnu.org> <8735ow7rx4.fsf@mail.linkov.net> <83sfwwapzd.fsf@gnu.org> Date: Wed, 20 Oct 2021 19:50:53 +0300 In-Reply-To: <83sfwwapzd.fsf@gnu.org> (Eli Zaretskii's message of "Wed, 20 Oct 2021 14:35:18 +0300") Message-ID: <87ee8f1vyq.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) >> You assumed in the doc string that those menu items as used >> to display a menu, whereas in fact those menu items as used >> to display tabs and other buttons on the tab bar. > > I'm trying to understand the difference between the two kinds of > menus, the one which causes the tab bar to display tabs, vs the one > that causes the display of a single tab that drops down a menu. > Please help me understand that difference. The tab bar is created from the list where elements are either a string, or a menu-item with a title and a binding. The title is displayed as a button on the tab bar. Clicking on such button calls the binding. The binding usually is a command that switches tabs. But the binding can do everything. To make the distinction more clear, I created a new command `tab-bar-menu-bar' that is bound to the button created by `tab-bar-format-menu-bar'. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 21 Oct 2021 11:06:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.16348143471320 (code B ref 51247); Thu, 21 Oct 2021 11:06:02 +0000 Received: (at 51247) by debbugs.gnu.org; 21 Oct 2021 11:05:47 +0000 Received: from localhost ([127.0.0.1]:56321 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdVtL-0000LE-5N for submit@debbugs.gnu.org; Thu, 21 Oct 2021 07:05:47 -0400 Received: from eggs.gnu.org ([209.51.188.92]:40118) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdVtJ-0000Kx-3Z for 51247@debbugs.gnu.org; Thu, 21 Oct 2021 07:05:45 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:46422) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mdVtD-00087p-Fq; Thu, 21 Oct 2021 07:05:39 -0400 Received: from [87.69.77.57] (port=3405 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mdVsq-0000fi-IA; Thu, 21 Oct 2021 07:05:28 -0400 Date: Thu, 21 Oct 2021 14:05:25 +0300 Message-Id: <831r4eab9m.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87ee8f1vyq.fsf@mail.linkov.net> (message from Juri Linkov on Wed, 20 Oct 2021 19:50:53 +0300) References: <831r4kghcu.fsf@gnu.org> <83mtn7frz3.fsf@gnu.org> <87tuhfv726.fsf@mail.linkov.net> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> <83lf2pcj4h.fsf@gnu.org> <8735ow7rx4.fsf@mail.linkov.net> <83sfwwapzd.fsf@gnu.org> <87ee8f1vyq.fsf@mail.linkov.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Wed, 20 Oct 2021 19:50:53 +0300 > > The tab bar is created from the list where elements are either a string, > or a menu-item with a title and a binding. The title is displayed as > a button on the tab bar. Clicking on such button calls the binding. > The binding usually is a command that switches tabs. But the binding > can do everything. Thanks. What if the function in tab-bar-format returns nil -- how is that handled? From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 21 Oct 2021 16:53:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163483518024395 (code B ref 51247); Thu, 21 Oct 2021 16:53:01 +0000 Received: (at 51247) by debbugs.gnu.org; 21 Oct 2021 16:53:00 +0000 Received: from localhost ([127.0.0.1]:58425 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdbJM-0006LK-8q for submit@debbugs.gnu.org; Thu, 21 Oct 2021 12:53:00 -0400 Received: from relay3-d.mail.gandi.net ([217.70.183.195]:50623) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdbJG-0006Kr-CJ for 51247@debbugs.gnu.org; Thu, 21 Oct 2021 12:52:59 -0400 Received: (Authenticated sender: juri@linkov.net) by relay3-d.mail.gandi.net (Postfix) with ESMTPSA id C60C760014; Thu, 21 Oct 2021 16:52:47 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> <83lf2pcj4h.fsf@gnu.org> <8735ow7rx4.fsf@mail.linkov.net> <83sfwwapzd.fsf@gnu.org> <87ee8f1vyq.fsf@mail.linkov.net> <831r4eab9m.fsf@gnu.org> Date: Thu, 21 Oct 2021 19:43:34 +0300 In-Reply-To: <831r4eab9m.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 21 Oct 2021 14:05:25 +0300") Message-ID: <87ee8e1lap.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) >> The tab bar is created from the list where elements are either a string, >> or a menu-item with a title and a binding. The title is displayed as >> a button on the tab bar. Clicking on such button calls the binding. >> The binding usually is a command that switches tabs. But the binding >> can do everything. > > Thanks. What if the function in tab-bar-format returns nil -- how is > that handled? Interesting question, I tried this (add-hook 'tab-bar-format 'ignore 1) and everything still works fine. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 21 Oct 2021 17:13:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163483636326702 (code B ref 51247); Thu, 21 Oct 2021 17:13:01 +0000 Received: (at 51247) by debbugs.gnu.org; 21 Oct 2021 17:12:43 +0000 Received: from localhost ([127.0.0.1]:58455 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdbcR-0006wc-Jf for submit@debbugs.gnu.org; Thu, 21 Oct 2021 13:12:43 -0400 Received: from eggs.gnu.org ([209.51.188.92]:32890) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdbcP-0006wM-TL for 51247@debbugs.gnu.org; Thu, 21 Oct 2021 13:12:42 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:57568) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mdbcJ-0004fB-SP; Thu, 21 Oct 2021 13:12:36 -0400 Received: from [87.69.77.57] (port=2125 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mdbcJ-0006zT-EE; Thu, 21 Oct 2021 13:12:35 -0400 Date: Thu, 21 Oct 2021 20:12:33 +0300 Message-Id: <83mtn28fpa.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87ee8e1lap.fsf@mail.linkov.net> (message from Juri Linkov on Thu, 21 Oct 2021 19:43:34 +0300) References: <831r4kghcu.fsf@gnu.org> <83lf2rforp.fsf@gnu.org> <87mtn7v4cw.fsf@mail.linkov.net> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> <83lf2pcj4h.fsf@gnu.org> <8735ow7rx4.fsf@mail.linkov.net> <83sfwwapzd.fsf@gnu.org> <87ee8f1vyq.fsf@mail.linkov.net> <831r4eab9m.fsf@gnu.org> <87ee8e1lap.fsf@mail.linkov.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Thu, 21 Oct 2021 19:43:34 +0300 > > > Thanks. What if the function in tab-bar-format returns nil -- how is > > that handled? > > Interesting question, I tried this > > (add-hook 'tab-bar-format 'ignore 1) > > and everything still works fine. I'm afraid this doesn't help me. The doc strings says: Every item in the list is a function that returns a string, or a list of menu-item elements, or nil. I now have a good idea what to say about return values that are strings and those that are lists of menu items. What do I say about return values of nil? what is their effect on the tab bar's appearance? Are you saying that there's no effect whatsoever? From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 21 Oct 2021 17:29:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163483731428453 (code B ref 51247); Thu, 21 Oct 2021 17:29:02 +0000 Received: (at 51247) by debbugs.gnu.org; 21 Oct 2021 17:28:34 +0000 Received: from localhost ([127.0.0.1]:58466 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdbrm-0007Or-9V for submit@debbugs.gnu.org; Thu, 21 Oct 2021 13:28:34 -0400 Received: from relay7-d.mail.gandi.net ([217.70.183.200]:34299) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdbrl-0007Og-JK for 51247@debbugs.gnu.org; Thu, 21 Oct 2021 13:28:33 -0400 Received: (Authenticated sender: juri@linkov.net) by relay7-d.mail.gandi.net (Postfix) with ESMTPSA id 2BFC82000A; Thu, 21 Oct 2021 17:28:26 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> <83lf2pcj4h.fsf@gnu.org> <8735ow7rx4.fsf@mail.linkov.net> <83sfwwapzd.fsf@gnu.org> <87ee8f1vyq.fsf@mail.linkov.net> <831r4eab9m.fsf@gnu.org> <87ee8e1lap.fsf@mail.linkov.net> <83mtn28fpa.fsf@gnu.org> Date: Thu, 21 Oct 2021 20:27:03 +0300 In-Reply-To: <83mtn28fpa.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 21 Oct 2021 20:12:33 +0300") Message-ID: <8735ouz3ub.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) >> (add-hook 'tab-bar-format 'ignore 1) >> >> and everything still works fine. > > I'm afraid this doesn't help me. The doc strings says: > > Every item in the list is a function that returns > a string, or a list of menu-item elements, or nil. > > I now have a good idea what to say about return values that are > strings and those that are lists of menu items. What do I say about > return values of nil? what is their effect on the tab bar's > appearance? Are you saying that there's no effect whatsoever? The nil value is supported only for the case when a function is on the tab-bar-format list, but its return value depends on some variable, and on some conditions might return nil. An example is tab-bar-format-history: when tab-bar-history-mode is nil, then tab-bar-format-history returns nil, but it doesn't break the tab bar. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 21 Oct 2021 17:43:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163483812730031 (code B ref 51247); Thu, 21 Oct 2021 17:43:02 +0000 Received: (at 51247) by debbugs.gnu.org; 21 Oct 2021 17:42:07 +0000 Received: from localhost ([127.0.0.1]:58480 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdc4t-0007oJ-1P for submit@debbugs.gnu.org; Thu, 21 Oct 2021 13:42:07 -0400 Received: from eggs.gnu.org ([209.51.188.92]:39396) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdc4q-0007nn-Qz for 51247@debbugs.gnu.org; Thu, 21 Oct 2021 13:42:05 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:58134) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mdc4j-0006Ok-9g; Thu, 21 Oct 2021 13:41:58 -0400 Received: from [87.69.77.57] (port=3973 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mdc4i-0007nr-Ro; Thu, 21 Oct 2021 13:41:57 -0400 Date: Thu, 21 Oct 2021 20:41:54 +0300 Message-Id: <83k0i68ecd.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <8735ouz3ub.fsf@mail.linkov.net> (message from Juri Linkov on Thu, 21 Oct 2021 20:27:03 +0300) References: <831r4kghcu.fsf@gnu.org> <83h7dffnlc.fsf@gnu.org> <87a6j7v3e2.fsf@mail.linkov.net> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> <83lf2pcj4h.fsf@gnu.org> <8735ow7rx4.fsf@mail.linkov.net> <83sfwwapzd.fsf@gnu.org> <87ee8f1vyq.fsf@mail.linkov.net> <831r4eab9m.fsf@gnu.org> <87ee8e1lap.fsf@mail.linkov.net> <83mtn28fpa.fsf@gnu.org> <8735ouz3ub.fsf@mail.linkov.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Thu, 21 Oct 2021 20:27:03 +0300 > > >> (add-hook 'tab-bar-format 'ignore 1) > >> > >> and everything still works fine. > > > > I'm afraid this doesn't help me. The doc strings says: > > > > Every item in the list is a function that returns > > a string, or a list of menu-item elements, or nil. > > > > I now have a good idea what to say about return values that are > > strings and those that are lists of menu items. What do I say about > > return values of nil? what is their effect on the tab bar's > > appearance? Are you saying that there's no effect whatsoever? > > The nil value is supported only for the case when a function > is on the tab-bar-format list, but its return value depends > on some variable, and on some conditions might return nil. > > An example is tab-bar-format-history: when tab-bar-history-mode > is nil, then tab-bar-format-history returns nil, but it doesn't break > the tab bar. OK, but what I want to say is what effect do such functions have on the tab bar appearance when they return nil? It sounds like you say that the appearance is not affected in any way in that case? From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Juri Linkov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 21 Oct 2021 17:50:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.163483857430961 (code B ref 51247); Thu, 21 Oct 2021 17:50:02 +0000 Received: (at 51247) by debbugs.gnu.org; 21 Oct 2021 17:49:34 +0000 Received: from localhost ([127.0.0.1]:58484 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdcC5-00083J-Sd for submit@debbugs.gnu.org; Thu, 21 Oct 2021 13:49:34 -0400 Received: from relay6-d.mail.gandi.net ([217.70.183.198]:52257) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdcC4-000833-3P for 51247@debbugs.gnu.org; Thu, 21 Oct 2021 13:49:32 -0400 Received: (Authenticated sender: juri@linkov.net) by relay6-d.mail.gandi.net (Postfix) with ESMTPSA id 101CFC0004; Thu, 21 Oct 2021 17:49:24 +0000 (UTC) From: Juri Linkov Organization: LINKOV.NET References: <831r4kghcu.fsf@gnu.org> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> <83lf2pcj4h.fsf@gnu.org> <8735ow7rx4.fsf@mail.linkov.net> <83sfwwapzd.fsf@gnu.org> <87ee8f1vyq.fsf@mail.linkov.net> <831r4eab9m.fsf@gnu.org> <87ee8e1lap.fsf@mail.linkov.net> <83mtn28fpa.fsf@gnu.org> <8735ouz3ub.fsf@mail.linkov.net> <83k0i68ecd.fsf@gnu.org> Date: Thu, 21 Oct 2021 20:48:47 +0300 In-Reply-To: <83k0i68ecd.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 21 Oct 2021 20:41:54 +0300") Message-ID: <87wnm6xo8w.fsf@mail.linkov.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) >> The nil value is supported only for the case when a function >> is on the tab-bar-format list, but its return value depends >> on some variable, and on some conditions might return nil. >> >> An example is tab-bar-format-history: when tab-bar-history-mode >> is nil, then tab-bar-format-history returns nil, but it doesn't break >> the tab bar. > > OK, but what I want to say is what effect do such functions have on > the tab bar appearance when they return nil? It sounds like you say > that the appearance is not affected in any way in that case? Exactly, they have no effect. From unknown Tue Jun 17 22:27:45 2025 X-Loop: help-debbugs@gnu.org Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 21 Oct 2021 18:12:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51247 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juri Linkov Cc: 51247@debbugs.gnu.org Received: via spool by 51247-submit@debbugs.gnu.org id=B51247.1634839863945 (code B ref 51247); Thu, 21 Oct 2021 18:12:01 +0000 Received: (at 51247) by debbugs.gnu.org; 21 Oct 2021 18:11:03 +0000 Received: from localhost ([127.0.0.1]:58512 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdcWt-0000FB-3j for submit@debbugs.gnu.org; Thu, 21 Oct 2021 14:11:03 -0400 Received: from eggs.gnu.org ([209.51.188.92]:46446) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdcWp-0000Ec-4l for 51247@debbugs.gnu.org; Thu, 21 Oct 2021 14:11:02 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:58884) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mdcWg-0006dt-Pn; Thu, 21 Oct 2021 14:10:52 -0400 Received: from [87.69.77.57] (port=1757 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mdcWG-0000N5-P7; Thu, 21 Oct 2021 14:10:50 -0400 Date: Thu, 21 Oct 2021 21:10:20 +0300 Message-Id: <83ee8e8d0z.fsf@gnu.org> From: Eli Zaretskii In-Reply-To: <87wnm6xo8w.fsf@mail.linkov.net> (message from Juri Linkov on Thu, 21 Oct 2021 20:48:47 +0300) References: <831r4kghcu.fsf@gnu.org> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> <83lf2pcj4h.fsf@gnu.org> <8735ow7rx4.fsf@mail.linkov.net> <83sfwwapzd.fsf@gnu.org> <87ee8f1vyq.fsf@mail.linkov.net> <831r4eab9m.fsf@gnu.org> <87ee8e1lap.fsf@mail.linkov.net> <83mtn28fpa.fsf@gnu.org> <8735ouz3ub.fsf@mail.linkov.net> <83k0i68ecd.fsf@gnu.org> <87wnm6xo8w.fsf@mail.linkov.net> X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Juri Linkov > Cc: 51247@debbugs.gnu.org > Date: Thu, 21 Oct 2021 20:48:47 +0300 > > >> The nil value is supported only for the case when a function > >> is on the tab-bar-format list, but its return value depends > >> on some variable, and on some conditions might return nil. > >> > >> An example is tab-bar-format-history: when tab-bar-history-mode > >> is nil, then tab-bar-format-history returns nil, but it doesn't break > >> the tab bar. > > > > OK, but what I want to say is what effect do such functions have on > > the tab bar appearance when they return nil? It sounds like you say > > that the appearance is not affected in any way in that case? > > Exactly, they have no effect. Thanks. From debbugs-submit-bounces@debbugs.gnu.org Thu Oct 21 14:11:29 2021 Received: (at control) by debbugs.gnu.org; 21 Oct 2021 18:11:29 +0000 Received: from localhost ([127.0.0.1]:58515 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdcXJ-0000Fw-D7 for submit@debbugs.gnu.org; Thu, 21 Oct 2021 14:11:29 -0400 Received: from eggs.gnu.org ([209.51.188.92]:46530) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mdcXH-0000Fk-P4 for control@debbugs.gnu.org; Thu, 21 Oct 2021 14:11:28 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:58914) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mdcXC-0000DJ-5a for control@debbugs.gnu.org; Thu, 21 Oct 2021 14:11:22 -0400 Received: from [87.69.77.57] (port=1820 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mdcXB-0000TI-PU for control@debbugs.gnu.org; Thu, 21 Oct 2021 14:11:22 -0400 Date: Thu, 21 Oct 2021 21:11:18 +0300 Message-Id: <83czny8czd.fsf@gnu.org> From: Eli Zaretskii To: control@debbugs.gnu.org In-Reply-To: <87wnm6xo8w.fsf@mail.linkov.net> (message from Juri Linkov on Thu, 21 Oct 2021 20:48:47 +0300) Subject: Re: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions References: <831r4kghcu.fsf@gnu.org> <83bl3mftqm.fsf@gnu.org> <87czo2peob.fsf@mail.linkov.net> <83a6j6e1d4.fsf@gnu.org> <87wnmal1u8.fsf@mail.linkov.net> <838ryqe0ll.fsf@gnu.org> <837deae081.fsf@gnu.org> <8735oyl10i.fsf@mail.linkov.net> <835ytudzky.fsf@gnu.org> <87ee8ijljn.fsf@mail.linkov.net> <834k9edyra.fsf@gnu.org> <871r4hldq8.fsf@mail.linkov.net> <83lf2pcj4h.fsf@gnu.org> <8735ow7rx4.fsf@mail.linkov.net> <83sfwwapzd.fsf@gnu.org> <87ee8f1vyq.fsf@mail.linkov.net> <831r4eab9m.fsf@gnu.org> <87ee8e1lap.fsf@mail.linkov.net> <83mtn28fpa.fsf@gnu.org> <8735ouz3ub.fsf@mail.linkov.net> <83k0i68ecd.fsf@gnu.org> <87wnm6xo8w.fsf@mail.linkov.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) close 51247 thanks