From: Tom Tromey <tromey@adacore.com>
Date: Tue, 23 Jul 2024 16:01:39 +0000 (-0600)
Subject: Refine the 'define' documentation
X-Git-Tag: gdb-16-branchpoint~1334
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fa8c46f5adeddedc492534302057deb7fcf1939a;p=thirdparty%2Fbinutils-gdb.git

Refine the 'define' documentation

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.

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

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)