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

[Andrew Burgess <andrew.burgess@embecosm.com>]

* Eli Zaretskii <eliz@gnu.org> [2021-01-12 18:02:00 +0200]:

> > 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.

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.