diff mbox series

Refine the 'define' documentation

Message ID 20240723160754.418236-1-tromey@adacore.com
State New
Headers
Series Refine the 'define' documentation |

Checks

Context Check Description
linaro-tcwg-bot/tcwg_gdb_build--master-aarch64 warning Patch is already merged
linaro-tcwg-bot/tcwg_gdb_build--master-arm warning Patch is already merged

Commit Message

Tom Tromey July 23, 2024, 4:07 p.m. UTC 
  A while ago, an AdaCore user reported some difficulties with the
'define' command.  While some of these difficulties are intrinsic, or
at least difficult to change, it seemed sensible to document a couple
of the typical problems -- and to make the text describing argument
substitution a bit more prominent.
---
 gdb/doc/gdb.texinfo | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

Comments

Eli Zaretskii July 23, 2024, 4:16 p.m. UTC | #1 
> From: Tom Tromey <tromey@adacore.com>
> Cc: Tom Tromey <tromey@adacore.com>
> Date: Tue, 23 Jul 2024 10:07:54 -0600
> 
> A while ago, an AdaCore user reported some difficulties with the
> 'define' command.  While some of these difficulties are intrinsic, or
> at least difficult to change, it seemed sensible to document a couple
> of the typical problems -- and to make the text describing argument
> substitution a bit more prominent.
> ---
>  gdb/doc/gdb.texinfo | 22 ++++++++++++++++------
>  1 file changed, 16 insertions(+), 6 deletions(-)

Thanks, this is OK.

Approved-By: Eli Zaretskii <eliz@gnu.org>
diff mbox series

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index c55913c7c79..147b8d4c24e 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -29228,9 +29228,21 @@  files.
 @cindex arguments, to user-defined commands
 A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
 which you assign a new name as a command.  This is done with the
-@code{define} command.  User commands may accept an unlimited number of arguments
-separated by whitespace.  Arguments are accessed within the user command
-via @code{$arg0@dots{}$argN}.  A trivial example:
+@code{define} command.
+
+User commands may accept an unlimited number of arguments separated by
+whitespace.  Arguments are accessed within the user command via
+@code{$arg0@dots{}$argN}.  The arguments are text substitutions, so
+they may reference variables, use complex expressions, or even perform
+inferior functions calls.  Note, however, that this textual
+substitution means that working with certain arguments is difficult.
+For example, there is no way for the user to pass an argument
+containing a space; and while stringifying an argument can be done
+using an expression like @code{"$arg1"}, this will fail if the
+argument contains a quote.  For more complicated and robust commands,
+we recommend writing them in Python; see @ref{CLI Commands In Python}.
+
+A trivial example:
 
 @smallexample
 define adder
@@ -29247,9 +29259,7 @@  adder 1 2 3
 
 @noindent
 This defines the command @code{adder}, which prints the sum of
-its three arguments.  Note the arguments are text substitutions, so they may
-reference variables, use complex expressions, or even perform inferior
-functions calls.
+its three arguments.
 
 @cindex argument count in user-defined commands
 @cindex how many arguments (user-defined commands)