From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [IPv6:2001:470:142:3::10]) by sourceware.org (Postfix) with ESMTPS id 50E7B389366E for ; Tue, 12 Jan 2021 16:01:50 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 50E7B389366E Received: from fencepost.gnu.org ([2001:470:142:3::e]:34087) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kzM7B-0002cB-Td; Tue, 12 Jan 2021 11:01:49 -0500 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:1500 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kzM7A-0001jp-7E; Tue, 12 Jan 2021 11:01:49 -0500 Date: Tue, 12 Jan 2021 18:02:00 +0200 Message-Id: <83a6tedtzb.fsf@gnu.org> From: Eli Zaretskii To: Andrew Burgess Cc: gdb-patches@sourceware.org In-Reply-To: <20210112131829.3108184-1-andrew.burgess@embecosm.com> (message from Andrew Burgess on Tue, 12 Jan 2021 13:18:29 +0000) Subject: Re: [PATCH] gdb/doc: reorder and group sections relating to aliases References: <20210112131829.3108184-1-andrew.burgess@embecosm.com> X-Spam-Status: No, score=1.5 required=5.0 tests=BAYES_00, KAM_DMARC_STATUS, RCVD_IN_BARRACUDACENTRAL, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=no autolearn_force=no version=3.4.2 X-Spam-Level: * X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) 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, 12 Jan 2021 16:01:51 -0000 > From: Andrew Burgess > Date: Tue, 12 Jan 2021 13:18:29 +0000 > > - Move the section on aliases earlier in the manual, this is now > immediately after the section about creating user defined > commands. This made more sense to me. > > - Rename the section on aliases to 'Command Aliases'. > > - Update the wording of the first paragraph in the 'Command Aliases' > section so that it reads better given the new name. > > - Add a cross-reference from the 'Command Aliases' section to the > 'Python' section now that the aliases section comes first. These changes are OK. > - Capitalised @var{default-args} to @var{DEFAULT-ARGS} in the > 'Command Aliases' section, this is consistent with the other uses > of @var in this section. Use of @var{UPPER-CASE} is discouraged, as it looks sub-optimally in the printed version of the manual. The argument of @var gets up-cased in the Info output anyway, but in the printed manual and in the HTML format it is rendered in slanted typeface, which looks nicer. When you up-case the argument in Texinfo, we get upper-case slanted text in print and HTML, which is less nice. So I'd appreciate if we could down-case all arguments of @var in this section, even though the original was using upper case. > - Move the section on default args to become a sub-section of the > 'Command Aliases' section, and rename this sub-section to just > 'Default Arguments'. This is fine, but you must also add a @menu in the parent section "Command Aliases", because otherwise at least some versions of makeinfo will barf or display a warning: the @menu is necessary for makeinfo to understand the structure of the nodes (which is UP of which) and generate the necessary links. > - Add a @cindex entry to the default arguments sub-section. > > gdb/doc/ChangeLog: > > * gdb.texinfo (Commands): Update menu. > (Extending GDB): Likewise. > (Command aliases default args): Moved later into the document, > added a cindex entry. > (Aliases): Moved earlier in the document. Minor rewording of the > first paragraph, capitalised some @var{default-aliases} inline > with the other uses or @var in this section, and added a cross > reference to the Python node. Please mention in the ChangeLog the old names of these sections, so that if someone looks for their history in the log, they will find this changeset. Thanks again for doing this.