From d8c4766d31456946a2a42239bccc789af3eaa1b9 Mon Sep 17 00:00:00 2001 From: Andrew Burgess Date: Fri, 22 Jan 2021 10:06:17 +0000 Subject: [PATCH] gdb/doc: don't rely on @menu item within the docs The node 'Auto-loading extensions' currently relies on a @menu item to provide a set of cross-references to different parts of the manual. Additionally the menu is placed part way through the node and the text prior to the menu seems (to me) to assume that the menu will be formatted into the document. This is a bad idea as the menus are not always part of the final document (e.g. pdf output does not include the menu), when compared to the info page the pdf version of this node is less helpful as it lacks proper cross references. Menus should always be placed at the end of a node. In this commit I rewrite a paragraph to add extra cross references inline within the text. I then move the menu to the end of the node. gdb/doc/ChangeLog: * gdb.texinfo (Auto-loading extensions): Add additional cross references and move @menu to the end of the node. --- gdb/doc/ChangeLog | 5 +++++ gdb/doc/gdb.texinfo | 26 +++++++++++++++----------- 2 files changed, 20 insertions(+), 11 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index a6be040cbc1..be37ac444ec 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,8 @@ +2021-01-22 Andrew Burgess + + * gdb.texinfo (Auto-loading extensions): Add additional cross + references and move @menu to the end of the node. + 2021-01-22 Andrew Burgess * gdb.texinfo (Aliases): Move @menu to the end of the node. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 1335c9093c8..f18b1c15224 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -27651,17 +27651,15 @@ see @ref{Command Settings}. @section Auto-loading extensions @cindex auto-loading extensions -@value{GDBN} provides two mechanisms for automatically loading extensions -when a new object file is read (for example, due to the @code{file} -command, or because the inferior has loaded a shared library): -@file{@var{objfile}-gdb.@var{ext}} and the @code{.debug_gdb_scripts} -section of modern file formats like ELF. - -@menu -* objfile-gdb.ext file: objfile-gdbdotext file. The @file{@var{objfile}-gdb.@var{ext}} file -* .debug_gdb_scripts section: dotdebug_gdb_scripts section. The @code{.debug_gdb_scripts} section -* Which flavor to choose?:: -@end menu +@value{GDBN} provides two mechanisms for automatically loading +extensions when a new object file is read (for example, due to the +@code{file} command, or because the inferior has loaded a shared +library): @file{@var{objfile}-gdb.@var{ext}} (@pxref{objfile-gdbdotext +file,,The @file{@var{objfile}-gdb.@var{ext}} file}) and the +@code{.debug_gdb_scripts} section of modern file formats like ELF +(@pxref {dotdebug_gdb_scripts section,,The @code{.debug_gdb_scripts} +section}). For a discussion of the differences between these two +approaches see @ref{Which flavor to choose?}. The auto-loading feature is useful for supplying application-specific debugging commands and features. @@ -27676,6 +27674,12 @@ For Python files see @ref{Python Auto-loading}. Note that loading of this script file also requires accordingly configured @code{auto-load safe-path} (@pxref{Auto-loading safe path}). +@menu +* objfile-gdbdotext file:: The @file{@var{objfile}-gdb.@var{ext}} file +* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section +* Which flavor to choose?:: Choosing between these approaches +@end menu + @node objfile-gdbdotext file @subsection The @file{@var{objfile}-gdb.@var{ext}} file @cindex @file{@var{objfile}-gdb.gdb} -- 2.30.2