From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wm1-x32c.google.com (mail-wm1-x32c.google.com [IPv6:2a00:1450:4864:20::32c]) by sourceware.org (Postfix) with ESMTPS id 4B8B33893661 for ; Tue, 12 Jan 2021 17:01:18 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 4B8B33893661 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=embecosm.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=andrew.burgess@embecosm.com Received: by mail-wm1-x32c.google.com with SMTP id a6so2539307wmc.2 for ; Tue, 12 Jan 2021 09:01:18 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=embecosm.com; s=google; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to; bh=0JbubZYNkLjlPZRKjpVR3xcB5KeMmqAY+lsF/M2aMLE=; b=Q4YBb/jkr7LxQLzEqcQIOJGrLgOQGtXbSwZ+Ks/FxEqol10SbWv5J7tXoxPOUii1R3 DN3p71fPEJZYFcC6czs8tJYOQ7MRi3arl/I9FGl7Asb96Vg4+q2IBoiwL/Vz3W+0u1P+ vS84BsQWTZVAQMwfppL9DSpjp48RW/iyyDcQ0egXvj7r1J42nkBym0PIktcfZ3MVIY+a 0WeQYhmEijORvWTiPwdjbN69dn1sOeUURDu197omo7tReNHDwcJFQLnE4aI+Eg6T6D1l YUH1+aXp6ggJ6yv0Ryp+cm2JTCOVQGKfxWKH2KsDktZ2wRBbvFhoChWW26Odyr2/iiA4 21hA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to; bh=0JbubZYNkLjlPZRKjpVR3xcB5KeMmqAY+lsF/M2aMLE=; b=tXhTW79d1bqGwMJomTncLFVC1ExAf2qWju93LdwEgo4eRleb8q73KBZhxGNjckDovN yxi3tXwrlMr2j0hSsINp43sSHSA0RR+zwE0Tcl3RswCwbw2gzFnJ+Dn94uCwjds0/54f /0Eh9+wuchHIBpuWdHfgsaF/0bkcW0frwl0pWC3qceZY1cx25KUR7+sPCB0HEE8yDRON W3u3d0YR73+/qNup8TQFHZ4mC8BosqaX9tspMlhbNlMXVKkwRkKKNim4ZMfbIZcMJEpD 96C0XGMDgqWwp6CNPsO720/4bBac7RAZIuN/wdTnjaaT389E2+p0c3fBeKJBqjrAwZb7 58HQ== X-Gm-Message-State: AOAM530PuNuspAMv5raREJmnzHejp7fvwsFbFvHLpVaiIBLzakYzPixh WY26a7OjJJXn8RLiF3S7QiNl2+yYLvw8hQ== X-Google-Smtp-Source: ABdhPJxduvr2KBsRmBG8gm1i2ss0aqW1dZjD2fiJXgAicowsTdt49cZInm7w1Rl+B3mQAe4mF6+9Ow== X-Received: by 2002:a1c:e3c4:: with SMTP id a187mr235118wmh.58.1610470877359; Tue, 12 Jan 2021 09:01:17 -0800 (PST) Received: from localhost (host86-166-129-230.range86-166.btcentralplus.com. [86.166.129.230]) by smtp.gmail.com with ESMTPSA id 67sm4883861wmb.47.2021.01.12.09.01.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 12 Jan 2021 09:01:16 -0800 (PST) Date: Tue, 12 Jan 2021 17:01:15 +0000 From: Andrew Burgess To: Eli Zaretskii Cc: gdb-patches@sourceware.org Subject: Re: [PATCH] gdb/doc: reorder and group sections relating to aliases Message-ID: <20210112170115.GB265215@embecosm.com> References: <20210112131829.3108184-1-andrew.burgess@embecosm.com> <83a6tedtzb.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <83a6tedtzb.fsf@gnu.org> X-Operating-System: Linux/5.8.13-100.fc31.x86_64 (x86_64) X-Uptime: 16:57:12 up 34 days, 21:41, X-Editor: GNU Emacs [ http://www.gnu.org/software/emacs ] X-Spam-Status: No, score=-5.7 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 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 17:01:19 -0000 * Eli Zaretskii [2021-01-12 18:02:00 +0200]: > > 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. How do you feel about using anchor instead of node? I would naturally have used anchor here, but in an unrelated patch you suggested using node instead, so I tried it here and didn't see any problems (makeinfo 6.7). It feels weird to me to have sub-sections added into the @menu blocks, but maybe that's just an issue on my side. Is there any advice or guidance you could give on how to choose between node and anchor? I'd also be interested in better understanding the differences between these two, I read the manual but didn't feel enlightened. Thanks, Andrew > > > - 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.