From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id c1zCCk9t5WEmAgAAWB0awg (envelope-from ) for ; Mon, 17 Jan 2022 08:21:19 -0500 Received: by simark.ca (Postfix, from userid 112) id 1AC921F34E; Mon, 17 Jan 2022 08:21:19 -0500 (EST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on simark.ca X-Spam-Level: X-Spam-Status: No, score=-2.0 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RDNS_DYNAMIC,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.2 Received: from sourceware.org (ip-8-43-85-97.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 372D01EAA4 for ; Mon, 17 Jan 2022 08:21:18 -0500 (EST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 52E00385801E for ; Mon, 17 Jan 2022 13:21:17 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 52E00385801E DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1642425677; bh=T70WNaLwBQ8x6JF8AKu/KFqeSPGZ1QtZMtX7a+w2FgI=; h=Date:To:In-Reply-To:Subject:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=OpBW2pG7GmXKRmIDxyJkly61HqzkxcuBbe1ifUL9RFq51A2EisFXc/DEOXa4zDoZl 8R4ySmPMyVZQRAB3sMmItk7YezPUEC/aZv2GnpOe+u1i3A6fPyrC6k1+t0OTAqTMdv qp5mLcEzawsN5MnjK21+k2FU+O/BlLDUbHxcQvHk= 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> To: Jan Vrany 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-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: , From: Eli Zaretskii via Gdb-patches Reply-To: Eli Zaretskii Cc: gdb-patches@sourceware.org Errors-To: gdb-patches-bounces+public-inbox=simark.ca@sourceware.org Sender: "Gdb-patches" [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.