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

From: "Basil L. Contovounesios" <[email-masked]>
Date: Fri, 17 Apr 2020 17:07:28 +0100

severity 40667 minor
tags 40667 + patch
quit

Drew Adams <[email-masked]> 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:

>From 300b04c4e5a2d42ea210922899d3e5542fef5e8b Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <[email-masked]>
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

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

Thanks,

-- 
Basil