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

[Andrew Burgess <andrew.burgess@embecosm.com>]

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