[RFA,10/10] Update NEWS and documentation for help and apropos changes.

Message ID 20200510205530.21923-11-philippe.waroquiers@skynet.be
State Superseded
Headers show
Series
  • fix/improve cmd structure, class_alias, help, apropos
Related show

Commit Message

Aktemur, Tankut Baris via Gdb-patches May 10, 2020, 8:55 p.m.
gdb/ChangeLog

YYYY-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* NEWS: Mention changes to help and apropos.

gdb/doc/ChangeLog

YYYY-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* gdb.texinfo (Help): Document the help and apropos changes.
	(Aliases): Document new meaning of -a abbreviation flag.
---
 gdb/NEWS            | 10 ++++++++++
 gdb/doc/gdb.texinfo | 22 ++++++++++++----------
 2 files changed, 22 insertions(+), 10 deletions(-)

-- 
2.20.1

Comments

Eli Zaretskii May 11, 2020, 2:34 p.m. | #1
> Date: Sun, 10 May 2020 22:55:30 +0200

> From: Philippe Waroquiers via Gdb-patches <gdb-patches@sourceware.org>

> 

> gdb/ChangeLog

> 

> YYYY-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

> 

> 	* NEWS: Mention changes to help and apropos.

> 

> gdb/doc/ChangeLog

> 

> YYYY-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

> 

> 	* gdb.texinfo (Help): Document the help and apropos changes.

> 	(Aliases): Document new meaning of -a abbreviation flag.


Thanks, a couple of comments below.

> +* help and apropos commands will now show only once the help

> +  for a command and all its aliases, instead of showing several

> +  times the same help information.  When a command has one

> +  or more aliases, the help documentation shows the command name

> +  followed by all its aliases separated by commas, such as

> +  'backtrace, where, bt'.


Took me a few readings to understand what "show only once" in the 1st
sentence wants to say.  I suggest to rephrase:

  Help and apropos commands will now show the documentation of a
  command only once, even if that command has one or more aliases.
  These commands now show the command name, then all of its aliases,
  and finally the description of the command.

> +* 'help aliases' now only shows the user defined aliases.  GDB predefined


"only shows" => "shows only".  The former could be interpreted to mean
it shows the aliases and nothing else.

The documentation parts are OK with those changes.

Patch

diff --git a/gdb/NEWS b/gdb/NEWS
index 5b9eabe746..5b416006cc 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -3,6 +3,16 @@ 
 
 *** Changes since GDB 9
 
+* help and apropos commands will now show only once the help
+  for a command and all its aliases, instead of showing several
+  times the same help information.  When a command has one
+  or more aliases, the help documentation shows the command name
+  followed by all its aliases separated by commas, such as
+  'backtrace, where, bt'.
+
+* 'help aliases' now only shows the user defined aliases.  GDB predefined
+  aliases are shown together with their aliased command.
+
 * GDB now supports debuginfod, an HTTP server for distributing ELF/DWARF
   debugging information as well as source code.
 
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d5bf59349e..4458144789 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2041,8 +2041,10 @@  Command name abbreviations are allowed if unambiguous.
 
 @item help @var{class}
 Using one of the general help classes as an argument, you can get a
-list of the individual commands in that class.  For example, here is the
-help display for the class @code{status}:
+list of the individual commands in that class.  If a command has
+aliases, the aliases are given after the command name, separated by
+commas. For example, here is the help display for the class
+@code{status}:
 
 @smallexample
 (@value{GDBP}) help status
@@ -2052,9 +2054,11 @@  List of commands:
 
 @c Line break in "show" line falsifies real output, but needed
 @c to fit in smallbook page size.
-info -- Generic command for showing things
+info, inf, i -- Generic command for showing things
         about the program being debugged
-show -- Generic command for showing things
+info address -- Describe where symbol SYM is stored.
+...
+show, info set -- Generic command for showing things
         about the debugger
 
 Type "help" followed by command name for full
@@ -2065,7 +2069,9 @@  Command name abbreviations are allowed if unambiguous.
 
 @item help @var{command}
 With a command name as @code{help} argument, @value{GDBN} displays a
-short paragraph on how to use that command.
+short paragraph on how to use that command.  If that command has
+one or more aliases, @value{GDBN} will display a first line with
+the command name and all its aliases separated by commas.
 
 @kindex apropos
 @item apropos [-v] @var{regexp}
@@ -2087,9 +2093,6 @@  results in:
 @group
 alias -- Define a new command that is an alias of an existing command
 aliases -- Aliases of other commands
-d -- Delete some breakpoints or auto-display expressions
-del -- Delete some breakpoints or auto-display expressions
-delete -- Delete some breakpoints or auto-display expressions
 @end group
 @end smallexample
 
@@ -27512,8 +27515,7 @@  underscores.
 that is being aliased.
 
 The @samp{-a} option specifies that the new alias is an abbreviation
-of the command.  Abbreviations are not shown in command
-lists displayed by the @samp{help} command.
+of the command.  Abbreviations are not used in command completion.
 
 The @samp{--} option specifies the end of options,
 and is useful when @var{ALIAS} begins with a dash.