From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <eliz@gnu.org>
Received: from eggs.gnu.org (eggs.gnu.org [IPv6:2001:470:142:3::10])
 by sourceware.org (Postfix) with ESMTPS id 28B753856DFB
 for <gdb-patches@sourceware.org>; Tue, 31 May 2022 12:36:41 +0000 (GMT)
DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 28B753856DFB
Received: from fencepost.gnu.org ([2001:470:142:3::e]:36148)
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <eliz@gnu.org>)
 id 1nw171-0007j3-Ug; Tue, 31 May 2022 08:36:39 -0400
Received: from [87.69.77.57] (port=2263 helo=home-c4e4a596f7)
 by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <eliz@gnu.org>)
 id 1nw16l-0007Mn-QO; Tue, 31 May 2022 08:36:37 -0400
Date: Tue, 31 May 2022 15:36:28 +0300
Message-Id: <83k0a1j2ur.fsf@gnu.org>
From: Eli Zaretskii <eliz@gnu.org>
To: Pedro Alves <pedro@palves.net>
Cc: gdb-patches@sourceware.org
In-Reply-To: <b3df27f3-0fe1-34c7-4a1d-3bb3cf1afd10@palves.net> (message from
 Pedro Alves on Tue, 31 May 2022 12:05:53 +0100)
Subject: Re: [PATCH] Improve clear command's documentation
References: <20220526194250.2310460-1-pedro@palves.net>
 <838rqmm7gb.fsf@gnu.org> <6914f754-4e33-5aa1-4ea6-dca9504e8bfe@palves.net>
 <837d63j8tx.fsf@gnu.org> <b3df27f3-0fe1-34c7-4a1d-3bb3cf1afd10@palves.net>
X-Spam-Status: No, score=1.6 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,
 T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no version=3.4.6
X-Spam-Level: *
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
 server2.sourceware.org
X-BeenThere: gdb-patches@sourceware.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Gdb-patches mailing list <gdb-patches.sourceware.org>
List-Unsubscribe: <https://sourceware.org/mailman/options/gdb-patches>,
 <mailto:gdb-patches-request@sourceware.org?subject=unsubscribe>
List-Archive: <https://sourceware.org/pipermail/gdb-patches/>
List-Post: <mailto:gdb-patches@sourceware.org>
List-Help: <mailto:gdb-patches-request@sourceware.org?subject=help>
List-Subscribe: <https://sourceware.org/mailman/listinfo/gdb-patches>,
 <mailto:gdb-patches-request@sourceware.org?subject=subscribe>
X-List-Received-Date: Tue, 31 May 2022 12:36:42 -0000

> Date: Tue, 31 May 2022 12:05:53 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> How about this, basically a complete rewrite of the clear command's
> documentation:

Thanks, the idea to rewrite it is indeed a good one.  But the actual
text IMO came out highly repetitive, and has several markup issues.
Rather than commenting on each issue, I suggest the following reworded
text:

 @item clear @var{locspec}
 Delete any breakpoint whose code location corresponds to
 @var{locspec}.  @xref{Location Specifications}, for the various forms
 of  @var{locspec}.  Which code locations correspond to @var{locspec}
 depends on the form used in the location specifications @var{locspec}:

 @table @code
 @item @var{linenum}
 @itemx @var{filename}:@var{linenum}
 @itemx -line @var{linenum}
 @itemx -source @var{filename} -line @var{linenum}
 If @var{locspec} specifies a line number, with or without a file
 name, the command deletes any breakpoint whose code location is
 at or within the specified line @var{linenum} in files that match the
 specified @var{filename}.  If @var{filename} is omitted, it defaults
 to the current source file.

 @item *@var{address}
 If @var{locspec} specifies an address, the command deletes any
 breakpoint whose code location is at the given @var{address}.

 @item @var{function}
 @itemx -function @var{function}
 If @var{locspec} specifies a function, the command deletes any
 breakpoint whose code location is at the entry to any function whose
 name matches @var{function}.
 @end table

 Ambiguity in names of files and functions can be resolved as
 described in @ref{Location Specifications}.

WDYT?