Re: [PATCH 1/7] gdb: Add new -n flag to some info commands

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Tue, 30 Jul 2019 22:02:45 +0100
> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Cc: gdb-patches@sourceware.org, Richard.Bunt@arm.com
> 
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -215,6 +215,11 @@ maint show test-options-completion-result
>       printing of some header information in a similar fashion to "info
>       variables" and "info functions".
>  
> +  ** The "info variables", "info functions", and "whereis" commands
> +     now take a '-n' flag that excludes non-debug symbols (symbols
> +     from the ELF's symbol table, rather than from the DWARf) from the
> +     results.

This is good, except that I wouldn't mention "ELF", because this
feature also works for non-ELF binaries, right?  So I'd just say
"symbols from the symbol table, not from the debug info such as
DWARF".

> +The function information comes from two sources, the debug information
> +associated with the executable (for example DWARF), but also non-debug
> +symbols are included in the results, these are symbols taken from the
> +symbol table of the executable.  A non-debug symbol is only included
> +if it is for a symbol in an executable section.  The @samp{-n} flag
> +excludes non-debugging symbols from the results.

My suggestion is to reverse the order: first say what -n does, then
explain the terminology:

  The @samp{-n} flag excludes @dfn{non-debugging symbols} from the
  results.  A non-debugging symbol is a symbol that comes from the
  executable's symbol table, not from the debug information (for
  example, DWARF) associated with the executable.

> @@ -18574,7 +18581,7 @@
>  
>  
>  @kindex info variables
> -@item info variables [-q]
> +@item info variables [-q] [-n]
>  Print the names and data types of all variables that are defined
>  outside of functions (i.e.@: excluding local variables).
>  The printed variables are grouped by source files and annotated with
> @@ -18587,11 +18594,18 @@
>  language of the variable, other values mean to use
>  the manually specified language (see @ref{Manually, ,Set Language Manually}).
>  
> +The variable information comes from two sources, the debug information
> +associated with the executable (for example DWARF), but also non-debug
> +symbols are included in the results, these are symbols taken from the
> +symbol table of the executable.  A non-debug symbol is only included
> +if it is for a symbol in a data section.  The @samp{-n} flag excludes
> +non-debugging symbols from the results.

Instead of repeating the same text just a few dozen lines after the
first instance, I'd just use "non-debugging symbols" here, because
they were already defined above.  IOW, keep the last sentence only.

Thanks.