Re: [PATCH] gdb/doc: reorder and group sections relating to aliases

[Eli Zaretskii <eliz@gnu.org>]

> From: Andrew Burgess <andrew.burgess@embecosm.com>
> 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.