From: Andrew Burgess <andrew.burgess@embecosm.com>
Date: Fri, 22 Jan 2021 10:06:17 +0000 (+0000)
Subject: gdb/doc: don't rely on @menu item within the docs
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=d8c4766d31456946a2a42239bccc789af3eaa1b9;p=binutils-gdb.git

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

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  <andrew.burgess@embecosm.com>
+
+	* gdb.texinfo (Auto-loading extensions): Add additional cross
+	references and move @menu to the end of the node.
+
 2021-01-22  Andrew Burgess  <andrew.burgess@embecosm.com>
 
 	* 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}