From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from NAM02-SN1-obe.outbound.protection.outlook.com (mail-sn1anam02on2048.outbound.protection.outlook.com [40.107.96.48]) by sourceware.org (Postfix) with ESMTPS id 2A3623858031 for ; Tue, 18 Jan 2022 12:34:07 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 2A3623858031 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=ONMcWUNeegU2fTLqmgsbEq/gO6KzeT2+NSOkMMZ6TVi/cvkuLrZydpn0AyFEJTFZeJuCxmD/eNWq8Ll+Dw8LcAEehtD+dA9EL7Qe7wxWSHcy5RDJTF7FgfDor+ZvufPkFLpnaAP6xPvK80FGQkrqtArkgXz0tHjWkW3Basw+hwVm5QU/Wjx44gU6wPpR5V1rbV2QHlWDx7j8VJ9hoFgelOGbRQsS+bRwAIycewgeZWZGkK2FcFp6uXAgMvlHHc7e+upRIoBw0owwRgS4YzF1+aKY6KSrSsSK5aJ+4qkDIG8uKCwOcKj3z/hGIFgEBTFeH3G9q2oiXnI0gLgd+/Br2Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=Bvz8B4xaQRqKhFH4+7kDR/1ZOgUuKUUNm70aT2KwtVs=; b=B0rxO1b2rmpO9f7mTgXLcvTBV/25lp1DNFEneZ9iBLcQMLozkwHjUrvPtHHw+MxmjxLc9GQnqvQ+xYgxVqqo0NKimEvU1a8YgTIwKwl5fPKiWZLPCJ3IAhv+KCFFQwBFag64v/nY6Jo25jsr+ckvQGKZCHiv+/7DFRgyQR613ICAqOtNSALxNdBL1br8eoWMIdKhef0PF9AeV3V93Yiw+9htc34Nw3JiOyv5wk5NEXO3AIGOC4omrb9Vs/wsQGT0G/5lnVTlgsuDlSeoX5ftlPxuNLoEvQ1SMXqNuDOoSPAkXHq80iRtp//rzPvdPkhXA+x3tLKq5U/fQ21AjEHKEA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=labware.com; dmarc=pass action=none header.from=labware.com; dkim=pass header.d=labware.com; arc=none Received: from DM6PR17MB3113.namprd17.prod.outlook.com (2603:10b6:5:6::10) by MN2PR17MB3904.namprd17.prod.outlook.com (2603:10b6:208:209::23) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4888.10; Tue, 18 Jan 2022 12:34:05 +0000 Received: from DM6PR17MB3113.namprd17.prod.outlook.com ([fe80::7839:31f:2416:6ba5]) by DM6PR17MB3113.namprd17.prod.outlook.com ([fe80::7839:31f:2416:6ba5%7]) with mapi id 15.20.4888.014; Tue, 18 Jan 2022 12:34:05 +0000 Message-ID: <41f128101c14a2794decf8a25b5a3940234d68e6.camel@labware.com> Subject: Re: [PATCH 5/5] gdb/python: document GDB/MI commands in Python From: Jan Vrany To: "gdb-patches@sourceware.org" Date: Tue, 18 Jan 2022 12:34:00 +0000 In-Reply-To: <83k0eywlar.fsf@gnu.org> References: <20220117124425.2658516-1-jan.vrany@labware.com> <20220117124425.2658516-6-jan.vrany@labware.com> <83k0eywlar.fsf@gnu.org> Content-Type: text/plain; charset="UTF-8" User-Agent: Evolution 3.38.3-1 Content-Transfer-Encoding: 8bit X-ClientProxiedBy: LO2P265CA0058.GBRP265.PROD.OUTLOOK.COM (2603:10a6:600:60::22) To DM6PR17MB3113.namprd17.prod.outlook.com (2603:10b6:5:6::10) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: a0925856-7305-4f7b-09d8-08d9da7ed09b X-MS-TrafficTypeDiagnostic: MN2PR17MB3904:EE_ X-Microsoft-Antispam-PRVS: X-MS-Oob-TLC-OOBClassifiers: OLM:10000; X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: CoytkKsQofJyM60khatWUZz2WCo3KTtx1AozoEFTqQKUD91YOx+T+16t8sfyQ+BvhfUBhUhxiPhqjz9DP0Claxo+vutB9IpsNV8HoBa30u4H8ZtRz4i2vXGZ+KvjxVfVo7E6L7apgI6IUXjS0dl8eqDx4PqdfeLG+tLYfobwRmsook0S6su/mIWdr//ueKLj9rRITGTNFQNmHCJJQTdKzIiIGqyOx5xfkjKjpFXVaSIidveqRlNo8SNFpkfmnGc3YchlbKv6bhmIAuIfzlFkXORQ3b8TDfTX48x/PwBliRLYZPOZsz6ByBjdqAM7Rkbkv6xsswFS09oa0CoO9FqCAr3yje0X2P0vrP9iuZPbxTbigxyNwyCtUSBTniafCGNvMDIRXzeRtgDMdvWtYbl/yPkEArp6B+l/5ogJbnaANhQM0PC+LhXQUaSbfV0gNVcCTstnNiUEVsr9hFOjq9kcZK4mOkXvmpQIBeWrL7Qk0Bl0FL9NDJtK/GP8yrESsWyxVO/3VFj//P584e41GCNajWUlIesjloBp6gybLvCEKHk0P5ndi4ApM3024WRJAzpiSyfOusQoYKXg0a7b/pTubSFrfvlZh2RR+SlXwvisOl5kaqzFubTVbJFEpIF8Yv4VCgIDSfdLnHSlaSPCtof/cZmBsyqmbkcmZ5asOPn3llDzUL3fdiRFHa1CMdhh32pAABuXMz1GL1eYlEkse5vFKQ== X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:DM6PR17MB3113.namprd17.prod.outlook.com; PTR:; CAT:NONE; SFS:(4636009)(366004)(8676002)(44832011)(316002)(66556008)(38100700002)(2906002)(38350700002)(5660300002)(66946007)(66476007)(6916009)(8936002)(6666004)(6506007)(52116002)(36756003)(86362001)(508600001)(4326008)(186003)(6486002)(2616005)(26005)(6512007); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?MHc4RkplSUZKUWdjczh0Ni9kWkZrcGJJMlJWODBsbzhUU3RPSDdPcGxZN29q?= =?utf-8?B?SGxLbUt2aEVnY095eURQYm5EMk9hSUhjbjlVTkc1ZG5NZFJQVnFwNHBHL2Nt?= =?utf-8?B?ZHUvT0FNdElVbnZZQzZEY0kxY3pIdHNHK1FsQkxVM29vbUFxMmZlT1I1bm12?= =?utf-8?B?c2xMa0hlaWNmRXdreXdDcU13dGdDTlJjNFRQNWRLMWZtUjlQK2xsc0xsOWVj?= =?utf-8?B?ZUVaRFNuT1RoUE5IdEYxVWgyOTBVTk1md2NmWjBtSGRWWE8wanZNanYvRGcx?= =?utf-8?B?VGxrVHFELzdYMEtnRzVqVFovQVBKY0EyazBUalhGRnFkQVYrTjFMQzByYldM?= =?utf-8?B?cUhqOUV6UTR3bzRPVGNkQVFYOUIwR1N4cUVBSVZ6S1BxNG42aFd6WDBYYWlj?= =?utf-8?B?cDBkNm9RelJEZURSb1ZESUg3enptbUtpUmo2MGpKNWptcHRCc2NKTklXeVlk?= =?utf-8?B?c004aGJialRRSFljYUxWOWVqQmJFc1RiT1JXMnNybGpyNjJWd0FhaU1YT25M?= =?utf-8?B?MGZ3cU5hZUFjTEk5NUYybWRqVTZFdVF3b2ZHbjJpV3JMTXloaDYwdVYwZUlK?= =?utf-8?B?Mi9ESnpVRnlKbk13bWpvR0pIWHFNd3RJdUhSUkZrdWRjT2I0KzVrSWpUb3RY?= =?utf-8?B?b00wdFlueXRBMEdSYW4yOUd5a3dkSllmQktSNG0zTzR5bU1nZVR1L2ZaT3J1?= =?utf-8?B?NFRZZFdTT3h5cm5zNGVaTzRvR1lCbWJ6b0VYekV1bklMb3pLMXlPdnJWQzR3?= =?utf-8?B?K0JDaFJpa3pqbG5TS25wNzVrMVcwUklnNEVDZVlJQW1DMzlkMml6YS8vYWQz?= =?utf-8?B?MjAyWW9sUkVjQmthb3JyQUFEMnNiVkkzY3hvTlROa09JL1EyTWx3WXhEZ0Zo?= =?utf-8?B?cjE0M3QrdkdkbjJGTW5rT1I1K05Wbkx2NDJUNlhUTXR0UHFEekd0eDJKQ3Fo?= =?utf-8?B?NTAxaWlJRlpyVDIxd2VmcWtzRXp1d205M1NRL3pzczdnNDJPN1FZU2tUQ1hH?= =?utf-8?B?c3JSWHFpVU84Zlc3MnRJMzI5TEY2cjdMZmFLVGpFU1RadktQUHd6ek81YUxn?= =?utf-8?B?djZ1cmpydGdtaTg4Q0ZaSXY2K3o4ZE5FM2dsanFSdlo4V2hUcnhSZjFvMUZU?= =?utf-8?B?TzhkN3IwWXJpRzZnTHBQeFdxeU5nRzJ5WDJQTGxrRW1RaXJIdk5WbWpuam9X?= =?utf-8?B?QThrbmpiZjBGTjZwc0FEbXdsdUNNcEdvSFBiQzVtWjR1azU4ajFjQ213UU96?= =?utf-8?B?YlR2R2U2MHQyaGNwVms0MmFLQmxQZ1FlYWhNY3A5S1pVbmZ0b2RRMkdKQmpU?= =?utf-8?B?dkJUbStPbkkzSGN2WFJ2WHpyb2pabnN2b05DYnJBUEZ4VGlmQ0haRVZKZ1ls?= =?utf-8?B?aUg5YW0rZHdseTl1clhUT0hDQStsU256K2syamR6ZzN2QU5pY3htMnY2cHlV?= =?utf-8?B?YWI1eC9SZFJOZ21TRVlCNmdzaTZrNkZGZEVKSTBUMURRNEdIc2pXRzhCam5R?= =?utf-8?B?TDhoRmJEVkw0ems0VTBzeHVzc3pWNktwM2w2ZkpYNFZmSFJJT1pLTUJvck1q?= =?utf-8?B?UWxHUitOcFEvN0c5UWhXbFh5bG84SEFqYVVQa3dxckVOWnZ5V2JGUGVXNXZ4?= =?utf-8?B?Qmszdjl1OWJwcnBSOUMya1g3OXBWMGNzbEVyWTFpdUNrN01wd1ByZ25XVzZz?= =?utf-8?B?NHNENVE1WHpWTkFpM1psV2VUblFWNHVEVndwek51S2lRUWh0dEEvRVA1c3RW?= =?utf-8?B?dGcxRHdkT3NEMlpPdE9QdFF0VFVBSjVBWXNyTkpEZkgwZnF3alUyekVBeVF0?= =?utf-8?B?R1BHaEo3NUZ6dXFLdFdWS0xFVnI2Q2Ivdi9MN2lOUkZPL0MvVDIwdkxLM25E?= =?utf-8?B?VUpDSy9zRThocFZPMXRaKzNZUWRMMTlrb1NvS3Q2SkJQZDRCRmhiOUVTMnFZ?= =?utf-8?B?SXRTY3doRFpwTHh6WWJ1WGcxaE1scmFiQ1ZxNWowTGM2eTc1eHFsbXJhV24r?= =?utf-8?B?VWZWZlpBR3F4SXNOYWZKQ2lIVUtsSFJYMGlOaENlRDFkM3BYVHYvTUltZnFF?= =?utf-8?B?RExES2k0TVBpbTdWQ3JSQXNoMmdVeWlQQTJpdzdHQnQ5NU8vVWFyVlFFU2th?= =?utf-8?B?bXNsNEU4L1h5MThhc2hCN1VNVDVnZjRWVFFlWCtHWjlId2dwWWlmL2NreW1U?= =?utf-8?Q?sQrSLfNl3r/lEyjDcFNiOMA=3D?= X-OriginatorOrg: labware.com X-MS-Exchange-CrossTenant-Network-Message-Id: a0925856-7305-4f7b-09d8-08d9da7ed09b X-MS-Exchange-CrossTenant-AuthSource: DM6PR17MB3113.namprd17.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 18 Jan 2022 12:34:05.4097 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: b5db0322-1aa0-4c0a-859c-ad0f96966f4c X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: emAr6i4XHOS++D+ZtGenRG5Pg+FJ1jVategE0rQo7jK26D84I24G/pDUQV5ltyXV7ITJnp5a8u9ADbsktqiCfw== X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR17MB3904 X-Spam-Status: No, score=-4.7 required=5.0 tests=BAYES_00, BODY_8BITS, DKIM_SIGNED, DKIM_VALID, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.4 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 12:34:09 -0000 Hi,  > > > 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. 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 and then @node GDB/MI Commands In Python @subsubsection @sc{gdb/mi} Commands In Python @cindex commands in python @subentry @sc{gdb/mi} @cindex python commands @subentry @sc{gdb/mi} It looks good to me in HTML version. Is that what you meant? It seems that this is the first use of @subentry in @cindex in GDB manual so perhaps you meant something different? > > > +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. It makes sense for NEWS but perhaps might look bit weird after 5 years (given that this series gets in) when this is no new feature.  Maybe I'm misunderstanding something... > > > +@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. > > I changed all the rest as suggested. Thanks! Jan