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

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

[Drew Adams]

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

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

[Basil L. Contovounesios]

[-- Attachment #1: Type: text/plain, Size: 699 bytes --]

severity 40667 minor
tags 40667 + patch
quit

Drew Adams <drew.adams@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:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Use-more-specific-xrefs-to-elisp-Frame-Parameters.patch --]
[-- Type: text/x-diff, Size: 2571 bytes --]

From 300b04c4e5a2d42ea210922899d3e5542fef5e8b Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@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


[-- Attachment #3: Type: text/plain, Size: 139 bytes --]


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

Thanks,

-- 
Basil

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

[Eli Zaretskii]

> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Date: Fri, 17 Apr 2020 17:07:28 +0100
> Cc: 40667@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.

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

[Basil L. Contovounesios]

tags 40667 wontfix
close 40667
quit

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Date: Fri, 17 Apr 2020 17:07:28 +0100
>> Cc: 40667@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