From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [209.51.188.92]) by sourceware.org (Postfix) with ESMTPS id 700753858D3C for ; Mon, 17 Jan 2022 13:20:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 700753858D3C Received: from [2001:470:142:3::e] (port=37016 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n9RwQ-00083I-0o; Mon, 17 Jan 2022 08:20:58 -0500 Received: from [87.69.77.57] (port=4359 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n9RwL-0005Rv-9G; Mon, 17 Jan 2022 08:20:56 -0500 Date: Mon, 17 Jan 2022 15:20:44 +0200 Message-Id: <83k0eywlar.fsf@gnu.org> From: Eli Zaretskii To: Jan Vrany Cc: gdb-patches@sourceware.org In-Reply-To: <20220117124425.2658516-6-jan.vrany@labware.com> (message from Jan Vrany via Gdb-patches on Mon, 17 Jan 2022 12:44:25 +0000) Subject: Re: [PATCH 5/5] gdb/python: document GDB/MI commands in Python References: <20220117124425.2658516-1-jan.vrany@labware.com> <20220117124425.2658516-6-jan.vrany@labware.com> X-Spam-Status: No, score=1.2 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, RCVD_IN_BARRACUDACENTRAL, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=no autolearn_force=no version=3.4.4 X-Spam-Level: * X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 17 Jan 2022 13:20:59 -0000 [Please disregard the previous email, which was mistakenly sent too early.] > Date: Mon, 17 Jan 2022 12:44:25 +0000 > From: Jan Vrany via Gdb-patches > Cc: Jan Vrany > > --- a/gdb/NEWS > +++ b/gdb/NEWS > @@ -146,6 +146,8 @@ show debug lin-lwp > ** New function gdb.host_charset(), returns a string, which is the > name of the current host charset. > > + ** New GDB/MI commands can now be written in Python. The "new" part here took me by surprise. Why do we need it? Or how about this rewording: ** It is now possible to add GDB/MI commands implemented in Python. > +* GDB/MI Commands In Python:: Implementing new @sc{GDB/MI} commands in Python. ^^^^^^^^^^^ The argument of @sc should be in lower case. > +@cindex CLI commands in python > @cindex commands in python > @cindex python commands > You can implement new @value{GDBN} CLI commands in Python. A CLI > @@ -4092,6 +4095,71 @@ registration of the command with @value{GDBN}. Depending on how the > Python code is read into @value{GDBN}, you may need to import the > @code{gdb} module explicitly. > > +@node GDB/MI Commands In Python > +@subsubsection @sc{GDB/MI} Commands In Python > + > +@cindex MI commands in python > +@cindex commands in python > +@cindex python commands You've added a second copy of the last two index entries, without any qualifier. This will cause makeinfo to generate index entries "commands in python" and "commands is python<2>", without giving the reader any clue what is the difference between these two instances. It is much better to qualify each instance with some unique qualifier. Here, I'd use ", CLI" and ", GDB/MI" as the qualifiers. > +You can implement new @sc{GDB/MI} (@pxref{GDB/MI}) commands in Python. Same comment as for the NEWS entry. With a possibly similar solution. > +@var{name} is the name of the command. It must be a valid @sc{GDB/MI} > +command and must start with hyphen (-). What does "It must be a valid @sc{GDB/MI} command" mean here? Did you mean to say "It must be a valid @sc{GDB/MI} command name" instead? If so, I suggest It must be a valid name of a @sc{GDB/MI} command, and in particular must start with a hyphen (@samp{-}). > +@var{arguments} is a list of strings. Note, that @code{--thread} > +and @code{--frame} arguments are handled by @value{GDBN} itself therefore > +they do not show up in @code{arguments}. ^ Comma missing there. > +If this method throws an exception, it is turned into a @sc{GDB/MI} "it" here is ambiguous: does it mean the exception or does it mean the method? Suggest to be more explicit: If this method throws an exception, the exception is turned into a @sc{GDB/MI} @code{^error} response. > +@itemize > +@item If the value is Python sequence or iterator, it is converted to > +@sc{GDB/MI} @emph{list} with elements converted recursively. In an @itemize list, eacg @item should be alone on its line (unlike in a @table). > +@item If the value is Python dictionary, it is converted to > +@sc{GDB/MI} @emph{tuple}. I don't think using @emph here is a good idea. I think @code is better. @mph will look odd in Info. Thanks.