[PATCH] gdb/doc: reorder and group sections relating to aliases

[PATCH] gdb/doc: reorder and group sections relating to aliases

[Andrew Burgess]

This started by observing that the section name:

  Automatically prepend default arguments to user-defined aliases

Is very long.  When this is rendered in the PDF manual (at least for
me), this name is so long that in the table of contents the page
number ends up being misaligned.

My first thought was we could drop the 'to user-defined aliases' bit
if this section became a sub-section of the section on aliases.

So then I looked for a section with 'aliases' in its name, and
couldn't find one.

It turns out that aliases are documented in a section called:

  Creating new spellings of existing commands

Which (to me) seems an odd aspect of aliases to emphasise.

So, in this patch I make the following changes:

  - Move the section on aliases earlier in the manual, this is now
    immediately after the section about creating user defined
    commands.  This made more sense to me.

  - Rename the section on aliases to 'Command Aliases'.

  - Update the wording of the first paragraph in the 'Command Aliases'
    section so that it reads better given the new name.

  - Add a cross-reference from the 'Command Aliases' section to the
    'Python' section now that the aliases section comes first.

  - Capitalised @var{default-args} to @var{DEFAULT-ARGS} in the
    'Command Aliases' section, this is consistent with the other uses
    of @var in this section.

  - Move the section on default args to become a sub-section of the
    'Command Aliases' section, and rename this sub-section to just
    'Default Arguments'.

  - Add a @cindex entry to the default arguments sub-section.

gdb/doc/ChangeLog:

	* gdb.texinfo (Commands): Update menu.
	(Extending GDB): Likewise.
	(Command aliases default args): Moved later into the document,
	added a cindex entry.
	(Aliases): Moved earlier in the document.  Minor rewording of the
	first paragraph, capitalised some @var{default-aliases} inline
	with the other uses or @var in this section, and added a cross
	reference to the Python node.
---
 gdb/doc/ChangeLog   |  11 ++
 gdb/doc/gdb.texinfo | 378 ++++++++++++++++++++++----------------------
 2 files changed, 200 insertions(+), 189 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 69fa6b709bf..ffee95d4f70 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1634,7 +1634,6 @@
 * Command Settings::            How to change default behavior of commands
 * Completion::                  Command completion
 * Command Options::             Command options
-* Command aliases default args::        Automatically prepend default arguments to user-defined aliases
 * Help::                        How to ask @value{GDBN} for help
 @end menu
 
@@ -2055,89 +2054,6 @@
 (For more on using the @code{print} command, see @ref{Data, ,Examining
 Data}.)
 
-@node Command aliases default args
-@section Automatically prepend default arguments to user-defined aliases
-
-You can tell @value{GDBN} to always prepend some default arguments to
-the list of arguments provided explicitly by the user when using a
-user-defined alias.
-
-If you repeatedly use the same arguments or options for a command, you
-can define an alias for this command and tell @value{GDBN} to
-automatically prepend these arguments or options to the list of
-arguments you type explicitly when using the alias@footnote{@value{GDBN}
-could easily accept default arguments for pre-defined commands and aliases,
-but it was deemed this would be confusing, and so is not allowed.}.
-
-For example, if you often use the command @code{thread apply all}
-specifying to work on the threads in ascending order and to continue in case it
-encounters an error, you can tell @value{GDBN} to automatically preprend
-the @code{-ascending} and @code{-c} options by using:
-
-@smallexample
-(@value{GDBP}) alias thread apply asc-all = thread apply all -ascending -c
-@end smallexample
-
-Once you have defined this alias with its default args, any time you type
-the @code{thread apply asc-all} followed by @code{some arguments},
-@value{GDBN} will execute  @code{thread apply all -ascending -c some arguments}.
-
-To have even less to type, you can also define a one word alias:
-@smallexample
-(@value{GDBP}) alias t_a_c = thread apply all -ascending -c
-@end smallexample
-
-As usual, unambiguous abbreviations can be used for @var{alias}
-and @var{default-args}.
-
-The different aliases of a command do not share their default args.
-For example, you define a new alias @code{bt_ALL} showing all possible
-information and another alias @code{bt_SMALL} showing very limited information
-using:
-@smallexample
-(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \
-   -past-main -past-entry -full
-(@value{GDBP}) alias bt_SMALL = backtrace -entry-values no -frame-arg none \
-   -past-main off -past-entry off
-@end smallexample
-
-(For more on using the @code{alias} command, see @ref{Aliases}.)
-
-Default args are not limited to the arguments and options of @var{command},
-but can specify nested commands if @var{command} accepts such a nested command
-as argument.
-For example, the below defines @code{faalocalsoftype} that lists the
-frames having locals of a certain type, together with the matching
-local vars:
-@smallexample
-(@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t
-(@value{GDBP}) faalocalsoftype int
-#1  0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86
-i = 0
-ret = 21845
-@end smallexample
-
-This is also very useful to define an alias for a set of nested @code{with}
-commands to have a particular combination of temporary settings.  For example,
-the below defines the alias @code{pp10} that pretty prints an expression
-argument, with a maximum of 10 elements if the expression is a string or
-an array:
-@smallexample
-(@value{GDBP}) alias pp10 = with print pretty -- with print elements 10 -- print
-@end smallexample
-This defines the alias  @code{pp10} as being a sequence of 3 commands.
-The first part @code{with print pretty --} temporarily activates the setting
-@code{set print pretty}, then launches the command that follows the separator
-@code{--}.
-The command following the first part is also a @code{with} command that
-temporarily changes the setting @code{set print elements} to 10, then
-launches the command that follows the second separator @code{--}.
-The third part @code{print} is the command the @code{pp10} alias will launch,
-using the temporary values of the settings and the arguments explicitly given
-by the user.
-For more information about the @code{with} command usage,
-see @ref{Command Settings}.
-
 @node Help
 @section Getting Help
 @cindex online documentation
@@ -26898,11 +26814,11 @@
 
 @menu
 * Sequences::                Canned Sequences of @value{GDBN} Commands
+* Aliases::                  Command Aliases
 * Python::                   Extending @value{GDBN} using Python
 * Guile::                    Extending @value{GDBN} using Guile
 * Auto-loading extensions::  Automatically loading extensions
 * Multiple Extension Languages:: Working with multiple extension languages
-* Aliases::                  Creating new spellings of existing commands
 @end menu
 
 To facilitate the use of extension languages, @value{GDBN} is capable
@@ -27535,6 +27451,194 @@
 If @var{regexp} is supplied only canned sequences of commands scripts with
 matching names are printed.
 
+@node Aliases
+@section Command Aliases
+@cindex aliases for commands
+
+Aliases allow you to define alternate spellings for existing commands.
+For example, if a new @value{GDBN} command defined in Python
+(@pxref{Python}) has a long name, it is handy to have an abbreviated
+version of it that involves less typing.
+
+@value{GDBN} itself uses aliases.  For example @samp{s} is an alias
+of the @samp{step} command even though it is otherwise an ambiguous
+abbreviation of other commands like @samp{set} and @samp{show}.
+
+Aliases are also used to provide shortened or more common versions
+of multi-word commands.  For example, @value{GDBN} provides the
+@samp{tty} alias of the @samp{set inferior-tty} command.
+
+You can define a new alias with the @samp{alias} command.
+
+@table @code
+
+@kindex alias
+@item alias [-a] [--] @var{ALIAS} = @var{COMMAND} [DEFAULT-ARGS...]
+
+@end table
+
+@var{ALIAS} specifies the name of the new alias.
+Each word of @var{ALIAS} must consist of letters, numbers, dashes and
+underscores.
+
+@var{COMMAND} specifies the name of an existing command
+that is being aliased.
+
+@var{COMMAND} can also be the name of an existing alias.  In this case,
+@var{COMMAND} cannot be an alias that has default arguments.
+
+The @samp{-a} option specifies that the new alias is an abbreviation
+of the command.  Abbreviations are not used in command completion.
+
+The @samp{--} option specifies the end of options,
+and is useful when @var{ALIAS} begins with a dash.
+
+You can specify @var{DEFAULT-ARGS} for your alias.
+These @var{DEFAULT-ARGS} will be automatically added before the alias
+arguments typed explicitly on the command line.
+
+For example, the below defines an alias @code{btfullall} that shows all local
+variables and all frame arguments:
+@smallexample
+(@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all
+@end smallexample
+
+For more information about @var{DEFAULT-ARGS}, see @ref{Command
+aliases default args, ,Default Arguments}.
+
+Here is a simple example showing how to make an abbreviation
+of a command so that there is less to type.
+Suppose you were tired of typing @samp{disas}, the current
+shortest unambiguous abbreviation of the @samp{disassemble} command
+and you wanted an even shorter version named @samp{di}.
+The following will accomplish this.
+
+@smallexample
+(gdb) alias -a di = disas
+@end smallexample
+
+Note that aliases are different from user-defined commands.
+With a user-defined command, you also need to write documentation
+for it with the @samp{document} command.
+An alias automatically picks up the documentation of the existing command.
+
+Here is an example where we make @samp{elms} an abbreviation of
+@samp{elements} in the @samp{set print elements} command.
+This is to show that you can make an abbreviation of any part
+of a command.
+
+@smallexample
+(gdb) alias -a set print elms = set print elements
+(gdb) alias -a show print elms = show print elements
+(gdb) set p elms 20
+(gdb) show p elms
+Limit on string chars or array elements to print is 200.
+@end smallexample
+
+Note that if you are defining an alias of a @samp{set} command,
+and you want to have an alias for the corresponding @samp{show}
+command, then you need to define the latter separately.
+
+Unambiguously abbreviated commands are allowed in @var{COMMAND} and
+@var{ALIAS}, just as they are normally.
+
+@smallexample
+(gdb) alias -a set pr elms = set p ele
+@end smallexample
+
+Finally, here is an example showing the creation of a one word
+alias for a more complex command.
+This creates alias @samp{spe} of the command @samp{set print elements}.
+
+@smallexample
+(gdb) alias spe = set print elements
+(gdb) spe 20
+@end smallexample
+
+@node Command aliases default args
+@subsection Default Arguments
+@cindex aliases for commands, default arguments
+
+You can tell @value{GDBN} to always prepend some default arguments to
+the list of arguments provided explicitly by the user when using a
+user-defined alias.
+
+If you repeatedly use the same arguments or options for a command, you
+can define an alias for this command and tell @value{GDBN} to
+automatically prepend these arguments or options to the list of
+arguments you type explicitly when using the alias@footnote{@value{GDBN}
+could easily accept default arguments for pre-defined commands and aliases,
+but it was deemed this would be confusing, and so is not allowed.}.
+
+For example, if you often use the command @code{thread apply all}
+specifying to work on the threads in ascending order and to continue in case it
+encounters an error, you can tell @value{GDBN} to automatically preprend
+the @code{-ascending} and @code{-c} options by using:
+
+@smallexample
+(@value{GDBP}) alias thread apply asc-all = thread apply all -ascending -c
+@end smallexample
+
+Once you have defined this alias with its default args, any time you type
+the @code{thread apply asc-all} followed by @code{some arguments},
+@value{GDBN} will execute  @code{thread apply all -ascending -c some arguments}.
+
+To have even less to type, you can also define a one word alias:
+@smallexample
+(@value{GDBP}) alias t_a_c = thread apply all -ascending -c
+@end smallexample
+
+As usual, unambiguous abbreviations can be used for @var{alias}
+and @var{default-args}.
+
+The different aliases of a command do not share their default args.
+For example, you define a new alias @code{bt_ALL} showing all possible
+information and another alias @code{bt_SMALL} showing very limited information
+using:
+@smallexample
+(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \
+   -past-main -past-entry -full
+(@value{GDBP}) alias bt_SMALL = backtrace -entry-values no -frame-arg none \
+   -past-main off -past-entry off
+@end smallexample
+
+(For more on using the @code{alias} command, see @ref{Aliases}.)
+
+Default args are not limited to the arguments and options of @var{command},
+but can specify nested commands if @var{command} accepts such a nested command
+as argument.
+For example, the below defines @code{faalocalsoftype} that lists the
+frames having locals of a certain type, together with the matching
+local vars:
+@smallexample
+(@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t
+(@value{GDBP}) faalocalsoftype int
+#1  0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86
+i = 0
+ret = 21845
+@end smallexample
+
+This is also very useful to define an alias for a set of nested @code{with}
+commands to have a particular combination of temporary settings.  For example,
+the below defines the alias @code{pp10} that pretty prints an expression
+argument, with a maximum of 10 elements if the expression is a string or
+an array:
+@smallexample
+(@value{GDBP}) alias pp10 = with print pretty -- with print elements 10 -- print
+@end smallexample
+This defines the alias  @code{pp10} as being a sequence of 3 commands.
+The first part @code{with print pretty --} temporarily activates the setting
+@code{set print pretty}, then launches the command that follows the separator
+@code{--}.
+The command following the first part is also a @code{with} command that
+temporarily changes the setting @code{set print elements} to 10, then
+launches the command that follows the second separator @code{--}.
+The third part @code{print} is the command the @code{pp10} alias will launch,
+using the temporary values of the settings and the arguments explicitly given
+by the user.
+For more information about the @code{with} command usage,
+see @ref{Command Settings}.
+
 @c Python docs live in a separate file.
 @include python.texi
 
@@ -27834,110 +27938,6 @@
 while, for example, trying to pretty-print an object then the error is
 reported and any following extension languages are not tried.
 
-@node Aliases
-@section Creating new spellings of existing commands
-@cindex aliases for commands
-
-It is often useful to define alternate spellings of existing commands.
-For example, if a new @value{GDBN} command defined in Python has
-a long name to type, it is handy to have an abbreviated version of it
-that involves less typing.
-
-@value{GDBN} itself uses aliases.  For example @samp{s} is an alias
-of the @samp{step} command even though it is otherwise an ambiguous
-abbreviation of other commands like @samp{set} and @samp{show}.
-
-Aliases are also used to provide shortened or more common versions
-of multi-word commands.  For example, @value{GDBN} provides the
-@samp{tty} alias of the @samp{set inferior-tty} command.
-
-You can define a new alias with the @samp{alias} command.
-
-@table @code
-
-@kindex alias
-@item alias [-a] [--] @var{ALIAS} = @var{COMMAND} [DEFAULT-ARGS...]
-
-@end table
-
-@var{ALIAS} specifies the name of the new alias.
-Each word of @var{ALIAS} must consist of letters, numbers, dashes and
-underscores.
-
-@var{COMMAND} specifies the name of an existing command
-that is being aliased.
-
-@var{COMMAND} can also be the name of an existing alias.  In this case,
-@var{COMMAND} cannot be an alias that has default arguments.
-
-The @samp{-a} option specifies that the new alias is an abbreviation
-of the command.  Abbreviations are not used in command completion.
-
-The @samp{--} option specifies the end of options,
-and is useful when @var{ALIAS} begins with a dash.
-
-You can specify @var{default-args} for your alias.
-These @var{default-args} will be automatically added before the alias
-arguments typed explicitly on the command line.
-
-For example, the below defines an alias @code{btfullall} that shows all local
-variables and all frame arguments:
-@smallexample
-(@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all
-@end smallexample
-
-For more information about @var{default-args}, see @ref{Command aliases default args,
-,Automatically prepend default arguments to user-defined aliases}.
-
-Here is a simple example showing how to make an abbreviation
-of a command so that there is less to type.
-Suppose you were tired of typing @samp{disas}, the current
-shortest unambiguous abbreviation of the @samp{disassemble} command
-and you wanted an even shorter version named @samp{di}.
-The following will accomplish this.
-
-@smallexample
-(gdb) alias -a di = disas
-@end smallexample
-
-Note that aliases are different from user-defined commands.
-With a user-defined command, you also need to write documentation
-for it with the @samp{document} command.
-An alias automatically picks up the documentation of the existing command.
-
-Here is an example where we make @samp{elms} an abbreviation of
-@samp{elements} in the @samp{set print elements} command.
-This is to show that you can make an abbreviation of any part
-of a command.
-
-@smallexample
-(gdb) alias -a set print elms = set print elements
-(gdb) alias -a show print elms = show print elements
-(gdb) set p elms 20
-(gdb) show p elms
-Limit on string chars or array elements to print is 200.
-@end smallexample
-
-Note that if you are defining an alias of a @samp{set} command,
-and you want to have an alias for the corresponding @samp{show}
-command, then you need to define the latter separately.
-
-Unambiguously abbreviated commands are allowed in @var{COMMAND} and
-@var{ALIAS}, just as they are normally.
-
-@smallexample
-(gdb) alias -a set pr elms = set p ele
-@end smallexample
-
-Finally, here is an example showing the creation of a one word
-alias for a more complex command.
-This creates alias @samp{spe} of the command @samp{set print elements}.
-
-@smallexample
-(gdb) alias spe = set print elements
-(gdb) spe 20
-@end smallexample
-
 @node Interpreters
 @chapter Command Interpreters
 @cindex command interpreters
-- 
2.25.4

Re: [PATCH] gdb/doc: reorder and group sections relating to aliases

[Eli Zaretskii]

> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Date: Tue, 12 Jan 2021 13:18:29 +0000
> 
>   - Move the section on aliases earlier in the manual, this is now
>     immediately after the section about creating user defined
>     commands.  This made more sense to me.
> 
>   - Rename the section on aliases to 'Command Aliases'.
> 
>   - Update the wording of the first paragraph in the 'Command Aliases'
>     section so that it reads better given the new name.
> 
>   - Add a cross-reference from the 'Command Aliases' section to the
>     'Python' section now that the aliases section comes first.

These changes are OK.

>   - Capitalised @var{default-args} to @var{DEFAULT-ARGS} in the
>     'Command Aliases' section, this is consistent with the other uses
>     of @var in this section.

Use of @var{UPPER-CASE} is discouraged, as it looks sub-optimally in
the printed version of the manual.  The argument of @var gets up-cased
in the Info output anyway, but in the printed manual and in the HTML
format it is rendered in slanted typeface, which looks nicer.  When
you up-case the argument in Texinfo, we get upper-case slanted text in
print and HTML, which is less nice.

So I'd appreciate if we could down-case all arguments of @var in this
section, even though the original was using upper case.

>   - Move the section on default args to become a sub-section of the
>     'Command Aliases' section, and rename this sub-section to just
>     'Default Arguments'.

This is fine, but you must also add a @menu in the parent section
"Command Aliases", because otherwise at least some versions of
makeinfo will barf or display a warning: the @menu is necessary for
makeinfo to understand the structure of the nodes (which is UP of
which) and generate the necessary links.

>   - Add a @cindex entry to the default arguments sub-section.
> 
> gdb/doc/ChangeLog:
> 
> 	* gdb.texinfo (Commands): Update menu.
> 	(Extending GDB): Likewise.
> 	(Command aliases default args): Moved later into the document,
> 	added a cindex entry.
> 	(Aliases): Moved earlier in the document.  Minor rewording of the
> 	first paragraph, capitalised some @var{default-aliases} inline
> 	with the other uses or @var in this section, and added a cross
> 	reference to the Python node.

Please mention in the ChangeLog the old names of these sections, so
that if someone looks for their history in the log, they will find
this changeset.

Thanks again for doing this.

Re: [PATCH] gdb/doc: reorder and group sections relating to aliases

[Andrew Burgess]

* Eli Zaretskii <eliz@gnu.org> [2021-01-12 18:02:00 +0200]:

> > From: Andrew Burgess <andrew.burgess@embecosm.com>
> > Date: Tue, 12 Jan 2021 13:18:29 +0000
> > 
> >   - Move the section on aliases earlier in the manual, this is now
> >     immediately after the section about creating user defined
> >     commands.  This made more sense to me.
> > 
> >   - Rename the section on aliases to 'Command Aliases'.
> > 
> >   - Update the wording of the first paragraph in the 'Command Aliases'
> >     section so that it reads better given the new name.
> > 
> >   - Add a cross-reference from the 'Command Aliases' section to the
> >     'Python' section now that the aliases section comes first.
> 
> These changes are OK.
> 
> >   - Capitalised @var{default-args} to @var{DEFAULT-ARGS} in the
> >     'Command Aliases' section, this is consistent with the other uses
> >     of @var in this section.
> 
> Use of @var{UPPER-CASE} is discouraged, as it looks sub-optimally in
> the printed version of the manual.  The argument of @var gets up-cased
> in the Info output anyway, but in the printed manual and in the HTML
> format it is rendered in slanted typeface, which looks nicer.  When
> you up-case the argument in Texinfo, we get upper-case slanted text in
> print and HTML, which is less nice.
> 
> So I'd appreciate if we could down-case all arguments of @var in this
> section, even though the original was using upper case.
> 
> >   - Move the section on default args to become a sub-section of the
> >     'Command Aliases' section, and rename this sub-section to just
> >     'Default Arguments'.
> 
> This is fine, but you must also add a @menu in the parent section
> "Command Aliases", because otherwise at least some versions of
> makeinfo will barf or display a warning: the @menu is necessary for
> makeinfo to understand the structure of the nodes (which is UP of
> which) and generate the necessary links.

How do you feel about using anchor instead of node?

I would naturally have used anchor here, but in an unrelated patch you
suggested using node instead, so I tried it here and didn't see any
problems (makeinfo 6.7).

It feels weird to me to have sub-sections added into the @menu
blocks, but maybe that's just an issue on my side.

Is there any advice or guidance you could give on how to choose
between node and anchor?  I'd also be interested in better
understanding the differences between these two, I read the manual but
didn't feel enlightened.

Thanks,
Andrew



> 
> >   - Add a @cindex entry to the default arguments sub-section.
> > 
> > gdb/doc/ChangeLog:
> > 
> > 	* gdb.texinfo (Commands): Update menu.
> > 	(Extending GDB): Likewise.
> > 	(Command aliases default args): Moved later into the document,
> > 	added a cindex entry.
> > 	(Aliases): Moved earlier in the document.  Minor rewording of the
> > 	first paragraph, capitalised some @var{default-aliases} inline
> > 	with the other uses or @var in this section, and added a cross
> > 	reference to the Python node.
> 
> Please mention in the ChangeLog the old names of these sections, so
> that if someone looks for their history in the log, they will find
> this changeset.
> 
> Thanks again for doing this.

Re: [PATCH] gdb/doc: reorder and group sections relating to aliases

[Eli Zaretskii]

> Date: Tue, 12 Jan 2021 17:01:15 +0000
> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Cc: gdb-patches@sourceware.org
> 
> > >   - Move the section on default args to become a sub-section of the
> > >     'Command Aliases' section, and rename this sub-section to just
> > >     'Default Arguments'.
> > 
> > This is fine, but you must also add a @menu in the parent section
> > "Command Aliases", because otherwise at least some versions of
> > makeinfo will barf or display a warning: the @menu is necessary for
> > makeinfo to understand the structure of the nodes (which is UP of
> > which) and generate the necessary links.
> 
> How do you feel about using anchor instead of node?

I'd prefer to have a node.

> It feels weird to me to have sub-sections added into the @menu
> blocks, but maybe that's just an issue on my side.

It's fine to have such a menu.

> Is there any advice or guidance you could give on how to choose
> between node and anchor?

I use @anchor only when I need to produce a cross-reference to a very
long node, most of which is not related to the subject of the
cross-reference.  Nodes are better because they help navigating
through the document, and you can arrive to nodes by means other than
cross-references.

> I'd also be interested in better understanding the differences
> between these two, I read the manual but didn't feel enlightened.

Basically, a node is also a section/subsection, whereas anchor isn't.

Re: [PATCH] gdb/doc: reorder and group sections relating to aliases

[Andrew Burgess]

* Eli Zaretskii <eliz@gnu.org> [2021-01-13 17:04:49 +0200]:

> > Date: Tue, 12 Jan 2021 17:01:15 +0000
> > From: Andrew Burgess <andrew.burgess@embecosm.com>
> > Cc: gdb-patches@sourceware.org
> > 
> > > >   - Move the section on default args to become a sub-section of the
> > > >     'Command Aliases' section, and rename this sub-section to just
> > > >     'Default Arguments'.
> > > 
> > > This is fine, but you must also add a @menu in the parent section
> > > "Command Aliases", because otherwise at least some versions of
> > > makeinfo will barf or display a warning: the @menu is necessary for
> > > makeinfo to understand the structure of the nodes (which is UP of
> > > which) and generate the necessary links.
> > 
> > How do you feel about using anchor instead of node?
> 
> I'd prefer to have a node.
> 
> > It feels weird to me to have sub-sections added into the @menu
> > blocks, but maybe that's just an issue on my side.
> 
> It's fine to have such a menu.
> 
> > Is there any advice or guidance you could give on how to choose
> > between node and anchor?
> 
> I use @anchor only when I need to produce a cross-reference to a very
> long node, most of which is not related to the subject of the
> cross-reference.  Nodes are better because they help navigating
> through the document, and you can arrive to nodes by means other than
> cross-references.
> 
> > I'd also be interested in better understanding the differences
> > between these two, I read the manual but didn't feel enlightened.
> 
> Basically, a node is also a section/subsection, whereas anchor isn't.

Thanks for the feedback.

The patch I pushed is below, I believe this addresses all of your
feedback.

Thanks,
Andrew

----

commit a72d0f3d69896b5fcdc916e0547fe774dcb58614
Author: Andrew Burgess <andrew.burgess@embecosm.com>
Date:   Tue Jan 12 13:02:30 2021 +0000

    gdb/doc: reorder and group sections relating to aliases
    
    This started by observing that the section name:
    
      Automatically prepend default arguments to user-defined aliases
    
    Is very long.  When this is rendered in the PDF manual (at least for
    me), this name is so long that in the table of contents the page
    number ends up being misaligned.
    
    My first thought was we could drop the 'to user-defined aliases' bit
    if this section became a sub-section of the section on aliases.
    
    So then I looked for a section with 'aliases' in its name, and
    couldn't find one.
    
    It turns out that aliases are documented in a section called:
    
      Creating new spellings of existing commands
    
    Which (to me) seems an odd aspect of aliases to emphasise.
    
    So, in this patch I make the following changes:
    
      - Move the section on aliases earlier in the manual, this is now
        immediately after the section about creating user defined
        commands.  This made more sense to me.
    
      - Rename the section on aliases from 'Creating new spellings of
        existing commands' to 'Command Aliases'.
    
      - Update the wording of the first paragraph in the 'Command Aliases'
        section so that it reads better given the new name.
    
      - Add a cross-reference from the 'Command Aliases' section to the
        'Python' section now that the aliases section comes first.
    
      - Down case all the text inside @var within this section as this is
        the correct style for the GDB manual.
    
      - Move the section on default args to become a sub-section of the
        'Command Aliases' section, and rename this sub-section from
        'Automatically prepend default arguments to user-defined aliases'
        to 'Default Arguments'.
    
      - Add @menu into the 'Command Aliases' section to link to the
        'Default Arguments' subsection.
    
      - Add a @cindex entry to the default arguments sub-section.
    
    gdb/doc/ChangeLog:
    
            * gdb.texinfo (Commands): Update menu.
            (Extending GDB): Likewise.
            (Command aliases default args): Moved later into the document,
            added a cindex entry.  Renamed the section 'Automatically prepend
            default arguments to user-defined aliases' to 'Default Arguments'.
            (Aliases): Moved earlier in the document.  Minor rewording of the
            first paragraph, down-cased the text inside all uses of @var, and
            added a cross reference to the Python code.  Renamed the section
            'Creating new spellings of existing commands' to 'Command
            Aliases'.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 69fa6b709bf..c9b432c0eb6 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1634,7 +1634,6 @@
 * Command Settings::            How to change default behavior of commands
 * Completion::                  Command completion
 * Command Options::             Command options
-* Command aliases default args::        Automatically prepend default arguments to user-defined aliases
 * Help::                        How to ask @value{GDBN} for help
 @end menu
 
@@ -2055,89 +2054,6 @@
 (For more on using the @code{print} command, see @ref{Data, ,Examining
 Data}.)
 
-@node Command aliases default args
-@section Automatically prepend default arguments to user-defined aliases
-
-You can tell @value{GDBN} to always prepend some default arguments to
-the list of arguments provided explicitly by the user when using a
-user-defined alias.
-
-If you repeatedly use the same arguments or options for a command, you
-can define an alias for this command and tell @value{GDBN} to
-automatically prepend these arguments or options to the list of
-arguments you type explicitly when using the alias@footnote{@value{GDBN}
-could easily accept default arguments for pre-defined commands and aliases,
-but it was deemed this would be confusing, and so is not allowed.}.
-
-For example, if you often use the command @code{thread apply all}
-specifying to work on the threads in ascending order and to continue in case it
-encounters an error, you can tell @value{GDBN} to automatically preprend
-the @code{-ascending} and @code{-c} options by using:
-
-@smallexample
-(@value{GDBP}) alias thread apply asc-all = thread apply all -ascending -c
-@end smallexample
-
-Once you have defined this alias with its default args, any time you type
-the @code{thread apply asc-all} followed by @code{some arguments},
-@value{GDBN} will execute  @code{thread apply all -ascending -c some arguments}.
-
-To have even less to type, you can also define a one word alias:
-@smallexample
-(@value{GDBP}) alias t_a_c = thread apply all -ascending -c
-@end smallexample
-
-As usual, unambiguous abbreviations can be used for @var{alias}
-and @var{default-args}.
-
-The different aliases of a command do not share their default args.
-For example, you define a new alias @code{bt_ALL} showing all possible
-information and another alias @code{bt_SMALL} showing very limited information
-using:
-@smallexample
-(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \
-   -past-main -past-entry -full
-(@value{GDBP}) alias bt_SMALL = backtrace -entry-values no -frame-arg none \
-   -past-main off -past-entry off
-@end smallexample
-
-(For more on using the @code{alias} command, see @ref{Aliases}.)
-
-Default args are not limited to the arguments and options of @var{command},
-but can specify nested commands if @var{command} accepts such a nested command
-as argument.
-For example, the below defines @code{faalocalsoftype} that lists the
-frames having locals of a certain type, together with the matching
-local vars:
-@smallexample
-(@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t
-(@value{GDBP}) faalocalsoftype int
-#1  0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86
-i = 0
-ret = 21845
-@end smallexample
-
-This is also very useful to define an alias for a set of nested @code{with}
-commands to have a particular combination of temporary settings.  For example,
-the below defines the alias @code{pp10} that pretty prints an expression
-argument, with a maximum of 10 elements if the expression is a string or
-an array:
-@smallexample
-(@value{GDBP}) alias pp10 = with print pretty -- with print elements 10 -- print
-@end smallexample
-This defines the alias  @code{pp10} as being a sequence of 3 commands.
-The first part @code{with print pretty --} temporarily activates the setting
-@code{set print pretty}, then launches the command that follows the separator
-@code{--}.
-The command following the first part is also a @code{with} command that
-temporarily changes the setting @code{set print elements} to 10, then
-launches the command that follows the second separator @code{--}.
-The third part @code{print} is the command the @code{pp10} alias will launch,
-using the temporary values of the settings and the arguments explicitly given
-by the user.
-For more information about the @code{with} command usage,
-see @ref{Command Settings}.
-
 @node Help
 @section Getting Help
 @cindex online documentation
@@ -26898,11 +26814,11 @@
 
 @menu
 * Sequences::                Canned Sequences of @value{GDBN} Commands
+* Aliases::                  Command Aliases
 * Python::                   Extending @value{GDBN} using Python
 * Guile::                    Extending @value{GDBN} using Guile
 * Auto-loading extensions::  Automatically loading extensions
 * Multiple Extension Languages:: Working with multiple extension languages
-* Aliases::                  Creating new spellings of existing commands
 @end menu
 
 To facilitate the use of extension languages, @value{GDBN} is capable
@@ -27535,6 +27451,196 @@
 If @var{regexp} is supplied only canned sequences of commands scripts with
 matching names are printed.
 
+@node Aliases
+@section Command Aliases
+@cindex aliases for commands
+
+@menu
+* Command aliases default args::	Default arguments for aliases
+@end menu
+
+Aliases allow you to define alternate spellings for existing commands.
+For example, if a new @value{GDBN} command defined in Python
+(@pxref{Python}) has a long name, it is handy to have an abbreviated
+version of it that involves less typing.
+
+@value{GDBN} itself uses aliases.  For example @samp{s} is an alias
+of the @samp{step} command even though it is otherwise an ambiguous
+abbreviation of other commands like @samp{set} and @samp{show}.
+
+Aliases are also used to provide shortened or more common versions
+of multi-word commands.  For example, @value{GDBN} provides the
+@samp{tty} alias of the @samp{set inferior-tty} command.
+
+You can define a new alias with the @samp{alias} command.
+
+@table @code
+
+@kindex alias
+@item alias [-a] [--] @var{alias} = @var{command} [@var{default-args}]
+
+@end table
+
+@var{alias} specifies the name of the new alias.  Each word of
+@var{alias} must consist of letters, numbers, dashes and underscores.
+
+@var{command} specifies the name of an existing command
+that is being aliased.
+
+@var{command} can also be the name of an existing alias.  In this
+case, @var{command} cannot be an alias that has default arguments.
+
+The @samp{-a} option specifies that the new alias is an abbreviation
+of the command.  Abbreviations are not used in command completion.
+
+The @samp{--} option specifies the end of options,
+and is useful when @var{alias} begins with a dash.
+
+You can specify @var{default-args} for your alias.  These
+@var{default-args} will be automatically added before the alias
+arguments typed explicitly on the command line.
+
+For example, the below defines an alias @code{btfullall} that shows all local
+variables and all frame arguments:
+@smallexample
+(@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all
+@end smallexample
+
+For more information about @var{default-args}, see @ref{Command
+aliases default args, ,Default Arguments}.
+
+Here is a simple example showing how to make an abbreviation of a
+command so that there is less to type.  Suppose you were tired of
+typing @samp{disas}, the current shortest unambiguous abbreviation of
+the @samp{disassemble} command and you wanted an even shorter version
+named @samp{di}.  The following will accomplish this.
+
+@smallexample
+(gdb) alias -a di = disas
+@end smallexample
+
+Note that aliases are different from user-defined commands.  With a
+user-defined command, you also need to write documentation for it with
+the @samp{document} command.  An alias automatically picks up the
+documentation of the existing command.
+
+Here is an example where we make @samp{elms} an abbreviation of
+@samp{elements} in the @samp{set print elements} command.
+This is to show that you can make an abbreviation of any part
+of a command.
+
+@smallexample
+(gdb) alias -a set print elms = set print elements
+(gdb) alias -a show print elms = show print elements
+(gdb) set p elms 20
+(gdb) show p elms
+Limit on string chars or array elements to print is 200.
+@end smallexample
+
+Note that if you are defining an alias of a @samp{set} command,
+and you want to have an alias for the corresponding @samp{show}
+command, then you need to define the latter separately.
+
+Unambiguously abbreviated commands are allowed in @var{command} and
+@var{alias}, just as they are normally.
+
+@smallexample
+(gdb) alias -a set pr elms = set p ele
+@end smallexample
+
+Finally, here is an example showing the creation of a one word
+alias for a more complex command.
+This creates alias @samp{spe} of the command @samp{set print elements}.
+
+@smallexample
+(gdb) alias spe = set print elements
+(gdb) spe 20
+@end smallexample
+
+@node Command aliases default args
+@subsection Default Arguments
+@cindex aliases for commands, default arguments
+
+You can tell @value{GDBN} to always prepend some default arguments to
+the list of arguments provided explicitly by the user when using a
+user-defined alias.
+
+If you repeatedly use the same arguments or options for a command, you
+can define an alias for this command and tell @value{GDBN} to
+automatically prepend these arguments or options to the list of
+arguments you type explicitly when using the alias@footnote{@value{GDBN}
+could easily accept default arguments for pre-defined commands and aliases,
+but it was deemed this would be confusing, and so is not allowed.}.
+
+For example, if you often use the command @code{thread apply all}
+specifying to work on the threads in ascending order and to continue in case it
+encounters an error, you can tell @value{GDBN} to automatically preprend
+the @code{-ascending} and @code{-c} options by using:
+
+@smallexample
+(@value{GDBP}) alias thread apply asc-all = thread apply all -ascending -c
+@end smallexample
+
+Once you have defined this alias with its default args, any time you type
+the @code{thread apply asc-all} followed by @code{some arguments},
+@value{GDBN} will execute  @code{thread apply all -ascending -c some arguments}.
+
+To have even less to type, you can also define a one word alias:
+@smallexample
+(@value{GDBP}) alias t_a_c = thread apply all -ascending -c
+@end smallexample
+
+As usual, unambiguous abbreviations can be used for @var{alias}
+and @var{default-args}.
+
+The different aliases of a command do not share their default args.
+For example, you define a new alias @code{bt_ALL} showing all possible
+information and another alias @code{bt_SMALL} showing very limited information
+using:
+@smallexample
+(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \
+   -past-main -past-entry -full
+(@value{GDBP}) alias bt_SMALL = backtrace -entry-values no -frame-arg none \
+   -past-main off -past-entry off
+@end smallexample
+
+(For more on using the @code{alias} command, see @ref{Aliases}.)
+
+Default args are not limited to the arguments and options of @var{command},
+but can specify nested commands if @var{command} accepts such a nested command
+as argument.
+For example, the below defines @code{faalocalsoftype} that lists the
+frames having locals of a certain type, together with the matching
+local vars:
+@smallexample
+(@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t
+(@value{GDBP}) faalocalsoftype int
+#1  0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86
+i = 0
+ret = 21845
+@end smallexample
+
+This is also very useful to define an alias for a set of nested @code{with}
+commands to have a particular combination of temporary settings.  For example,
+the below defines the alias @code{pp10} that pretty prints an expression
+argument, with a maximum of 10 elements if the expression is a string or
+an array:
+@smallexample
+(@value{GDBP}) alias pp10 = with print pretty -- with print elements 10 -- print
+@end smallexample
+This defines the alias  @code{pp10} as being a sequence of 3 commands.
+The first part @code{with print pretty --} temporarily activates the setting
+@code{set print pretty}, then launches the command that follows the separator
+@code{--}.
+The command following the first part is also a @code{with} command that
+temporarily changes the setting @code{set print elements} to 10, then
+launches the command that follows the second separator @code{--}.
+The third part @code{print} is the command the @code{pp10} alias will launch,
+using the temporary values of the settings and the arguments explicitly given
+by the user.
+For more information about the @code{with} command usage,
+see @ref{Command Settings}.
+
 @c Python docs live in a separate file.
 @include python.texi
 
@@ -27834,110 +27940,6 @@
 while, for example, trying to pretty-print an object then the error is
 reported and any following extension languages are not tried.
 
-@node Aliases
-@section Creating new spellings of existing commands
-@cindex aliases for commands
-
-It is often useful to define alternate spellings of existing commands.
-For example, if a new @value{GDBN} command defined in Python has
-a long name to type, it is handy to have an abbreviated version of it
-that involves less typing.
-
-@value{GDBN} itself uses aliases.  For example @samp{s} is an alias
-of the @samp{step} command even though it is otherwise an ambiguous
-abbreviation of other commands like @samp{set} and @samp{show}.
-
-Aliases are also used to provide shortened or more common versions
-of multi-word commands.  For example, @value{GDBN} provides the
-@samp{tty} alias of the @samp{set inferior-tty} command.
-
-You can define a new alias with the @samp{alias} command.
-
-@table @code
-
-@kindex alias
-@item alias [-a] [--] @var{ALIAS} = @var{COMMAND} [DEFAULT-ARGS...]
-
-@end table
-
-@var{ALIAS} specifies the name of the new alias.
-Each word of @var{ALIAS} must consist of letters, numbers, dashes and
-underscores.
-
-@var{COMMAND} specifies the name of an existing command
-that is being aliased.
-
-@var{COMMAND} can also be the name of an existing alias.  In this case,
-@var{COMMAND} cannot be an alias that has default arguments.
-
-The @samp{-a} option specifies that the new alias is an abbreviation
-of the command.  Abbreviations are not used in command completion.
-
-The @samp{--} option specifies the end of options,
-and is useful when @var{ALIAS} begins with a dash.
-
-You can specify @var{default-args} for your alias.
-These @var{default-args} will be automatically added before the alias
-arguments typed explicitly on the command line.
-
-For example, the below defines an alias @code{btfullall} that shows all local
-variables and all frame arguments:
-@smallexample
-(@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all
-@end smallexample
-
-For more information about @var{default-args}, see @ref{Command aliases default args,
-,Automatically prepend default arguments to user-defined aliases}.
-
-Here is a simple example showing how to make an abbreviation
-of a command so that there is less to type.
-Suppose you were tired of typing @samp{disas}, the current
-shortest unambiguous abbreviation of the @samp{disassemble} command
-and you wanted an even shorter version named @samp{di}.
-The following will accomplish this.
-
-@smallexample
-(gdb) alias -a di = disas
-@end smallexample
-
-Note that aliases are different from user-defined commands.
-With a user-defined command, you also need to write documentation
-for it with the @samp{document} command.
-An alias automatically picks up the documentation of the existing command.
-
-Here is an example where we make @samp{elms} an abbreviation of
-@samp{elements} in the @samp{set print elements} command.
-This is to show that you can make an abbreviation of any part
-of a command.
-
-@smallexample
-(gdb) alias -a set print elms = set print elements
-(gdb) alias -a show print elms = show print elements
-(gdb) set p elms 20
-(gdb) show p elms
-Limit on string chars or array elements to print is 200.
-@end smallexample
-
-Note that if you are defining an alias of a @samp{set} command,
-and you want to have an alias for the corresponding @samp{show}
-command, then you need to define the latter separately.
-
-Unambiguously abbreviated commands are allowed in @var{COMMAND} and
-@var{ALIAS}, just as they are normally.
-
-@smallexample
-(gdb) alias -a set pr elms = set p ele
-@end smallexample
-
-Finally, here is an example showing the creation of a one word
-alias for a more complex command.
-This creates alias @samp{spe} of the command @samp{set print elements}.
-
-@smallexample
-(gdb) alias spe = set print elements
-(gdb) spe 20
-@end smallexample
-
 @node Interpreters
 @chapter Command Interpreters
 @cindex command interpreters

Re: [PATCH] gdb/doc: reorder and group sections relating to aliases

[Eli Zaretskii]

> Date: Thu, 21 Jan 2021 18:18:36 +0000
> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Cc: Eli Zaretskii <eliz@gnu.org>
> 
> Thanks for the feedback.
> 
> The patch I pushed is below, I believe this addresses all of your
> feedback.

Yes.  One nit is that @menu is better placed at the end of a node, not
at its beginning.

Re: [PATCH] gdb/doc: reorder and group sections relating to aliases

[Andrew Burgess]

* Eli Zaretskii <eliz@gnu.org> [2021-01-21 21:46:16 +0200]:

> > Date: Thu, 21 Jan 2021 18:18:36 +0000
> > From: Andrew Burgess <andrew.burgess@embecosm.com>
> > Cc: Eli Zaretskii <eliz@gnu.org>
> > 
> > Thanks for the feedback.
> > 
> > The patch I pushed is below, I believe this addresses all of your
> > feedback.
> 
> Yes.  One nit is that @menu is better placed at the end of a node, not
> at its beginning.

Sorry about that.  I pushed the patch below to fix this.

Thanks,
Andrew

---

commit fe461d2f70ed618c39b887579d07f49f603c1de5
Author: Andrew Burgess <andrew.burgess@embecosm.com>
Date:   Fri Jan 22 09:28:07 2021 +0000

    gdb/doc: move @menu to the end of the node
    
    Commit:
    
      commit a72d0f3d69896b5fcdc916e0547fe774dcb58614
      Date:   Tue Jan 12 13:02:30 2021 +0000
    
          gdb/doc: reorder and group sections relating to aliases
    
    Added a @menu block into the wrong place within a @node.  This commit
    moves it to the end of the @node, where it should be been placed.
    
    gdb/doc/ChangeLog:
    
            * gdb.texinfo (Aliases): Move @menu to the end of the node.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b4133413061..1335c9093c8 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -27455,10 +27455,6 @@
 @section Command Aliases
 @cindex aliases for commands
 
-@menu
-* Command aliases default args::	Default arguments for aliases
-@end menu
-
 Aliases allow you to define alternate spellings for existing commands.
 For example, if a new @value{GDBN} command defined in Python
 (@pxref{Python}) has a long name, it is handy to have an abbreviated
@@ -27557,6 +27553,10 @@
 (gdb) spe 20
 @end smallexample
 
+@menu
+* Command aliases default args::	Default arguments for aliases
+@end menu
+
 @node Command aliases default args
 @subsection Default Arguments
 @cindex aliases for commands, default arguments