From: Andrew Burgess Date: Tue, 12 Jan 2021 13:02:30 +0000 (+0000) Subject: gdb/doc: reorder and group sections relating to aliases X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=a72d0f3d69896b5fcdc916e0547fe774dcb58614;p=binutils-gdb.git 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/ChangeLog b/gdb/doc/ChangeLog index 64eb52bd521..200239c2068 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,16 @@ +2021-01-21 Andrew Burgess + + * 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'. + 2021-01-21 Hannes Domani PR python/19151 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 @@ show you the alternatives available, if there is more than one possibility). * 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 @@ uppercase. (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 @@ being debugged. @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 @@ auto-loaded. 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 @@ This extends to errors while performing such requests: If an error happens 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