From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id qKG0EHn1ZmFbBwAAWB0awg (envelope-from ) for ; Wed, 13 Oct 2021 11:04:25 -0400 Received: by simark.ca (Postfix, from userid 112) id 344A31F0BB; Wed, 13 Oct 2021 11:04:25 -0400 (EDT) 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=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI,NICE_REPLY_A,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.2 Received: from sourceware.org (server2.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 6BFA11E813 for ; Wed, 13 Oct 2021 11:04:24 -0400 (EDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id B0C053858439 for ; Wed, 13 Oct 2021 15:04:23 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org B0C053858439 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1634137463; bh=+5xK6Z46GuopQsvODBd0bwdctq/yGn4PskLDUtp2kR0=; h=Subject:To:References:Date:In-Reply-To:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=fidAXUOX1mFCs03/gbpfrjC8RBLiPVuXtIY0KZpC57X/GGCoCgeqNVXW9mzk5gFJP 9xMkkgU6uAe6bmWtEdgaL94Eveb93eW9itld5wUbXpjjySGPQLmQrS/J6GmJVoRwLr 8qGmUkN2oJwnOWs6LBChixOFmIqp0WOXU5lfBYcU= Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by sourceware.org (Postfix) with ESMTP id C4D45385843D for ; Wed, 13 Oct 2021 15:04:01 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org C4D45385843D Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-445-zfvJCuCxPkKy8s_46BdalQ-1; Wed, 13 Oct 2021 11:03:58 -0400 X-MC-Unique: zfvJCuCxPkKy8s_46BdalQ-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 243B31006AAA; Wed, 13 Oct 2021 15:03:57 +0000 (UTC) Received: from blarsen.remote.csb (ovpn-116-53.gru2.redhat.com [10.97.116.53]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 9B7F55C1A3; Wed, 13 Oct 2021 15:03:55 +0000 (UTC) Subject: Re: [PATCH] [gdb/doc]: Updated manpages to be consistent with help To: Eli Zaretskii References: <20211013130409.10711-1-blarsen@redhat.com> <83bl3tniel.fsf@gnu.org> Message-ID: Date: Wed, 13 Oct 2021 12:03:51 -0300 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.14.0 MIME-Version: 1.0 In-Reply-To: <83bl3tniel.fsf@gnu.org> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit 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: Bruno Larsen via Gdb-patches Reply-To: Bruno Larsen Cc: gdb-patches@sourceware.org Errors-To: gdb-patches-bounces+public-inbox=simark.ca@sourceware.org Sender: "Gdb-patches" On 10/13/21 10:50 AM, Eli Zaretskii wrote: >> Date: Wed, 13 Oct 2021 10:04:09 -0300 >> From: Bruno Larsen via Gdb-patches >> >> Updated manpages to be consistent with help information provided by the >> binary. The main changes are Making all long-form options have '--', >> instead of a single '-' and added most of the missing options to the >> manpage. > > Thanks. The replacement of '-' by '--' are mechanical and don't need > any approval. > > Many other changes replace something like this: > > Use @file{file} as SOMETHING. > > with something like this: > > Use file @file{somefile} as SOMETHING. > > I must confess that I prefer the former form, because it makes the > text more concise and easier to read, by avoiding one more "file". > Thanks for the review. This change in specific, I understand why you may not be a fan, but the idea was to sync between manpages and --help, and since help calls those "somefile" instead of just "file" I thought it was worth doing. I can roll them back, but I think the --help text should be changed to be the same generic file. Same goes for DIR and directory, which you mention below. Up to your preferences which of those I do. I'll implement to all the other style changes you mentioned. It could be worth adding them to the Documentation writing standard (https://sourceware.org/gdb/wiki/Internals%20GDB-Doc-Standards) since that page is almost empty. >> -@item -nh >> +@item --directory=@var{DIR} >> +@itemx -d @var{DIR} >> +Add @var{DIR} to the path to search for source files. > > The string inside @var{..} should never be upper-case. (Yes, I know > this was in the original text.) > > Also, here I'd prefer > > Add @var{directory} to the path to search for source files. > > because "DIR" doesn't necessarily speak for its being a directory. > -- Cheers! Bruno Larsen