GNU bug report logs - #40667
26.3; (1) Emacs manual `i tool bar' (2) `tool-bar-position'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 40667 in the body.
You can then email your comments to 40667 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.3; (1) Emacs manual `i tool bar' (2) `tool-bar-position'
Date: Thu, 16 Apr 2020 09:31:26 -0700 (PDT)

1. Suggestion: have `i tool bar RET' send you to node `Tool Bars', not to
node `Table of Resources'.  Someone looking for info about the Emacs
tool bar is not necessarily looking for info about X Resources.

2. In node (emacs) `Tool Bars' there is a link to (elisp) `Frame
Parameters', for info about parameter `tool-bar-position'.  But that
node doesn't present that parameter.  Suggestion: change that link, to
point to node `Layout Parameters'.  That's where that parameter is
covered.

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

Message #8 received at 40667 <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 40667 <at> debbugs.gnu.org
Subject: Re: bug#40667: 26.3; (1) Emacs manual `i tool bar' (2)
 `tool-bar-position'
Date: Fri, 17 Apr 2020 17:07:28 +0100

[Message part 1 (text/plain, inline)]

severity 40667 minor
tags 40667 + patch
quit

Drew Adams <drew.adams <at> oracle.com> writes:

> 1. Suggestion: have `i tool bar RET' send you to node `Tool Bars', not to
> node `Table of Resources'.

This is already fixed in Emacs 27/28.

> 2. In node (emacs) `Tool Bars' there is a link to (elisp) `Frame
> Parameters', for info about parameter `tool-bar-position'.  But that
> node doesn't present that parameter.  Suggestion: change that link, to
> point to node `Layout Parameters'.  That's where that parameter is
> covered.

It's not just tool-bar-position; the Emacs manual contains at least
three other references to the supernode '(elisp) Frame Parameters'
rather than more specific subnodes:

[0001-Use-more-specific-xrefs-to-elisp-Frame-Parameters.patch (text/x-diff, inline)]

From 300b04c4e5a2d42ea210922899d3e5542fef5e8b Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Date: Fri, 17 Apr 2020 16:56:19 +0100
Subject: [PATCH] Use more specific xrefs to (elisp)Frame Parameters

* doc/emacs/frames.texi (Scroll Bars, Tool Bars): Cross-reference
more specific subnodes of "(elisp) Frame Parameters".  (Bug#40667)
---
 doc/emacs/frames.texi | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 7a583b96bb..e3655edcc4 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -1027,7 +1027,7 @@ Scroll Bars
   You can also use the X resource @samp{verticalScrollBars} to enable
 or disable the scroll bars (@pxref{Resources}).  To control the scroll
 bar width, change the @code{scroll-bar-width} frame parameter
-(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}).
+(@pxref{Layout Parameters,,, elisp, The Emacs Lisp Reference Manual}).
 
 @vindex scroll-bar-adjust-thumb-portion
 @cindex overscrolling
@@ -1092,7 +1092,7 @@ Scroll Bars
   You can also use the X resource @samp{horizontalScrollBars} to enable
 or disable horizontal scroll bars (@pxref{Resources}).  To control the
 scroll bar height, change the @code{scroll-bar-height} frame parameter
-(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}).
+(@pxref{Layout Parameters,,, elisp, The Emacs Lisp Reference Manual}).
 
 @node Window Dividers
 @section Window Dividers
@@ -1229,14 +1229,15 @@ Tool Bars
 
 @cindex Tool Bar position
   You can also control the placement of the tool bar for the GTK+ tool
-bar with the frame parameter @code{tool-bar-position}.  @xref{Frame
-Parameters,,, elisp, The Emacs Lisp Reference Manual}.
+bar with the frame parameter @code{tool-bar-position} (@pxref{Layout
+Parameters,,, elisp, The Emacs Lisp Reference Manual}).
 
   NS builds consider the tool bar to be a window decoration, and
-therefore do not display it when a window is undecorated.  @xref{Frame
-Parameters,,, elisp, The Emacs Lisp Reference Manual}.  On macOS the
-tool bar is hidden when the frame is put into fullscreen, but can be
-displayed by moving the mouse pointer to the top of the screen.
+therefore do not display it when a window is undecorated
+(@pxref{Management Parameters,,, elisp, The Emacs Lisp Reference
+Manual}).  On macOS the tool bar is hidden when the frame is put into
+fullscreen, but can be displayed by moving the mouse pointer to the
+top of the screen.
 
 @node Tab Bars
 @section Tab Bars
-- 
2.25.1

[Message part 3 (text/plain, inline)]

Eli, is this welcome on emacs-27?  Or is it better to xref the supernode
'(elisp) Frame Parameters' for more context?

Thanks,

-- 
Basil

Message #15 received at 40667 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 40667 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#40667: 26.3;
 (1) Emacs manual `i tool bar' (2) `tool-bar-position'
Date: Sat, 25 Apr 2020 13:42:37 +0300

> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Date: Fri, 17 Apr 2020 17:07:28 +0100
> Cc: 40667 <at> debbugs.gnu.org
> 
> > 2. In node (emacs) `Tool Bars' there is a link to (elisp) `Frame
> > Parameters', for info about parameter `tool-bar-position'.  But that
> > node doesn't present that parameter.  Suggestion: change that link, to
> > point to node `Layout Parameters'.  That's where that parameter is
> > covered.
> 
> It's not just tool-bar-position; the Emacs manual contains at least
> three other references to the supernode '(elisp) Frame Parameters'
> rather than more specific subnodes:

I'm not sure I agree with Drew's suggestion, and therefore with your
suggested changes.  From the context, it seems to me that the intent
is to let the readers understand what the frame parameters are in
general, not to let them read on the specific frame parameter being
discussed (the text there doesn't say anything new for the reader).

> Eli, is this welcome on emacs-27?  Or is it better to xref the supernode
> '(elisp) Frame Parameters' for more context?

I think it's better as it is now, yes.

Message #22 received at 40667-done <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 40667-done <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#40667: 26.3; (1) Emacs manual `i tool bar' (2)
 `tool-bar-position'
Date: Sat, 25 Apr 2020 12:05:12 +0100

tags 40667 wontfix
close 40667
quit

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
>> Date: Fri, 17 Apr 2020 17:07:28 +0100
>> Cc: 40667 <at> debbugs.gnu.org
>> 
>> > 2. In node (emacs) `Tool Bars' there is a link to (elisp) `Frame
>> > Parameters', for info about parameter `tool-bar-position'.  But that
>> > node doesn't present that parameter.  Suggestion: change that link, to
>> > point to node `Layout Parameters'.  That's where that parameter is
>> > covered.
>> 
>> It's not just tool-bar-position; the Emacs manual contains at least
>> three other references to the supernode '(elisp) Frame Parameters'
>> rather than more specific subnodes:
>
> I'm not sure I agree with Drew's suggestion, and therefore with your
> suggested changes.  From the context, it seems to me that the intent
> is to let the readers understand what the frame parameters are in
> general, not to let them read on the specific frame parameter being
> discussed (the text there doesn't say anything new for the reader).
>
>> Eli, is this welcome on emacs-27?  Or is it better to xref the supernode
>> '(elisp) Frame Parameters' for more context?
>
> I think it's better as it is now, yes.

Fine with me, so I'm closing this report.

-- 
Basil

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.