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 A954B3858D28 for ; Tue, 18 Jan 2022 15:10:01 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org A954B3858D28 Received: from [2001:470:142:3::e] (port=37816 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 1n9q7U-0006rV-UE; Tue, 18 Jan 2022 10:10:00 -0500 Received: from [87.69.77.57] (port=3700 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 1n9q7U-0003rY-QB; Tue, 18 Jan 2022 10:10:01 -0500 Date: Tue, 18 Jan 2022 17:09:53 +0200 Message-Id: <83ee55ulku.fsf@gnu.org> From: Eli Zaretskii To: Jan Vrany Cc: gdb-patches@sourceware.org In-Reply-To: <41f128101c14a2794decf8a25b5a3940234d68e6.camel@labware.com> (message from Jan Vrany on Tue, 18 Jan 2022 12:34:00 +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> <83k0eywlar.fsf@gnu.org> <41f128101c14a2794decf8a25b5a3940234d68e6.camel@labware.com> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=1.3 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: Tue, 18 Jan 2022 15:10:02 -0000 > From: Jan Vrany > Cc: Eli Zaretskii > Date: Tue, 18 Jan 2022 12:34:00 +0000 > > > 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. > > I see. However I'm not sure what do you mean by "qualifiers".  > In new version (which I'll submit once I get review on > other patches in this series) I changed index entries to > > @node CLI Commands In Python > @subsubsection CLI Commands In Python > > @cindex commands in python @subentry CLI > @cindex python commands @subentry CLI @subentry is a very new feature, so I'd prefer not to use it yet, as that would force everyone who builds GDB to upgrade. Something much simpler, like this, will do: @cindex commands in python, in CLI @cindex commands in python, in GDB/MI > > > +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. > > This phrasing with "new" (both here and in NEWS) was taken from entries > for CLI commands. For NEWS, I have changed it as you suggested, it's better. > > But for manual it makes less sense to me. Wording "It is now possible to add GDB/MI  > commands implemented in Python." sounds to me as to suggest this is some > new feature. Yes, of course: you need to drop the "now" part in the manual. It is only appropriate in NEWS. But the rest reads well here. What problems do you have with It is possible to add GDB/MI commands implemented in Python.