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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 12 Jan 2021 17:01:15 +0000
> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Cc: gdb-patches@sourceware.org
> 
> > >   - 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'd prefer to have a node.

> It feels weird to me to have sub-sections added into the @menu
> blocks, but maybe that's just an issue on my side.

It's fine to have such a menu.

> Is there any advice or guidance you could give on how to choose
> between node and anchor?

I use @anchor only when I need to produce a cross-reference to a very
long node, most of which is not related to the subject of the
cross-reference.  Nodes are better because they help navigating
through the document, and you can arrive to nodes by means other than
cross-references.

> I'd also be interested in better understanding the differences
> between these two, I read the manual but didn't feel enlightened.

Basically, a node is also a section/subsection, whereas anchor isn't.