Re: [RFA, doc RFA] Add gdb.add_command_alias

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Wed, 21 Sep 2011 14:12:11 -0700
> From: Doug Evans <dje@google.com>
> 
> @item alias [-a] -f @var{from} -t @var{to}
> 
> instead of what I've written:
> 
> @item alias [-a] -f FROM -t TO
> 
> But I don't know how to properly refer to -f from in subsequent text
> except as @samp{-f FROM} which is why I wrote what I wrote.
> Suggestions welcome.

Sorry, I don't understand the problem.  Or maybe I do, see below.

> -* New commands "info macros", and "info definitions" have been added.
> +* New commands "info macros", and "info definitions",
> +  and "alias" have been added.^^^

Redundant "and".

> +Python scripting language, and the third is defining new aliases of
> +existing commands.                                               ^^

"for", I think.

> +@node Aliases
> +@section Creating new spellings of existing commands

Please add here an index entry:

  @cindex aliases for commands

> +Define a new alias with the @samp{alias} command.

  You can define a new alias with the @samp{alias} command.

> +@item alias [-a] -f FROM -t TO
> +
> +@end table
> +
> +@samp{-f FROM} and @samp{-t TO} may be specified in either order.

If by "refer" above you mean refer to "-f FROM" etc., then what's
wrong with

  @samp{-f @var{from}}

?

> +The @samp{-f FROM} option specifies the name of an existing command
> +that is being aliased.
> +
> +The @samp{-t TO} option specifies the name of the new alias.

Btw, I'm not sure FROM and TO are a good idea; it's not like you are
copying something.  How about COMMAND and ALIAS instead?

> +The @samp{-a} option specifies that the new alias is an abbreviation
> +of the @samp{FROM} command, and will not appear in help command lists.

Suggest a rewording:

  The @samp{-a} option specifies that the new alias is an abbreviation
  of the @samp{FROM} command.  Abbreviations are not shown in command
  lists displayed by the @samp{help} command.

> +Note that aliases are different than user-defined commands.
                                   ^^^^
"from"

> +Here is an example where we make @samp{elms} an abbreviation of
> +@samp{elements} in the @samp{set print elements} command.
> +This is to show that you can make an abbreviation of any part
> +of a command.
> +
> +@smallexample
> +(gdb) alias -f "set print elements" -t "set print elms"
> +(gdb) alias -f "show print elements" -t "show print elms"

For didactic purposes, shouldn't these examples use -a?

> +Note that if you are defining an alias of a @samp{set} command,
> +you also need to define the alias of the corresponding @samp{show}
> +command, if desired.


"Need" and "if desired" are in contradiction.  Which is it?

Thanks.