[40/40] Document breakpoints / linespec & co improvements (manual + NEWS)

  * NEWS: Mention breakpoints, linespecs and explicit locations
	improvements.

gdb/doc/ChangeLog:
yyyy-mm-dd  Pedro Alves  <palves@redhat.com>

	* gdb.texinfo (Linespec Locations): Document how "function" is
	interpreted in C++.
	(Explicit Locations): Document how "-function" is interpreted in
	C++.  Document -qualified.
---
 gdb/doc/gdb.texinfo | 26 ++++++++++++++++++++++++++
 gdb/NEWS            | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)
  

> From: Pedro Alves <palves@redhat.com>
> Date: Fri,  2 Jun 2017 13:22:38 +0100
> 
> +For example, assuming a program with symbols named @code{A::B::func}
> +and @code{B::func}, both commands @code{break -function func} and
> +@code{break -function B::func} set a breakpoint on both symbols.

The 2 commands are long and include whitespace, so I'd suggest
enclosing each one in @w{..}, to avoid a line break in the middle of a
command.

Also, I think @kbd is more appropriate here than @code, since you mean
commands the user will type, not just command names.

I'm surprised you didn't change anything where the manual discusses
quoting of names and symbols.  For example, the node "Completion"
explicitly describes a use case with overloaded functions in C++; the
node "Symbols" describes a case with "::" that requires quoting.
There's another example in "Machine Code", and also in "Ambiguous
Expression", and in "Variables".  Maybe you already reviewed all of
those and concluded no changes were necessary, but I just thought I'd
mention them.

> +  ** GDB now has a much improved linespec and explicit locations TAB
> +     completion support, that better understands what you're
> +     completing and offers better suggestions.

Is this a general improvement, or is it limited to C++ symbols?  If
the latter, suggest to mention that.

> +  ** GDB can now complete function parameters in linespecs and
> +     explicit locations, even without quoting.  When setting
> +     breakpoints, quoting around functions names to help with
> +     TAB-completion is generally no longer necessary.

Likewise.

> +  ** GDB can now set breakpoints functions marked with [abi:cxx11]
> +     tags.

"on functions", I think.

And btw, what are those tags?  I don't think I see them documented in
the manual; did I miss something?

Thanks.
  

On 06/02/2017 02:01 PM, Eli Zaretskii wrote:
>> From: Pedro Alves <palves@redhat.com>
>> Date: Fri,  2 Jun 2017 13:22:38 +0100
>>
>> +For example, assuming a program with symbols named @code{A::B::func}
>> +and @code{B::func}, both commands @code{break -function func} and
>> +@code{break -function B::func} set a breakpoint on both symbols.
> 
> The 2 commands are long and include whitespace, so I'd suggest
> enclosing each one in @w{..}, to avoid a line break in the middle of a
> command.
> 
> Also, I think @kbd is more appropriate here than @code, since you mean
> commands the user will type, not just command names.
> 
> I'm surprised you didn't change anything where the manual discusses
> quoting of names and symbols.  For example, the node "Completion"
> explicitly describes a use case with overloaded functions in C++; the
> node "Symbols" describes a case with "::" that requires quoting.
> There's another example in "Machine Code", and also in "Ambiguous
> Expression", and in "Variables".  Maybe you already reviewed all of
> those and concluded no changes were necessary, but I just thought I'd
> mention them.

Thanks, I just didn't think of looking for quoting bits in the
manual, for some reason.  I'll take a closer look.

> 
>> +  ** GDB now has a much improved linespec and explicit locations TAB
>> +     completion support, that better understands what you're
>> +     completing and offers better suggestions.
> 
> Is this a general improvement, or is it limited to C++ symbols?  If
> the latter, suggest to mention that.

You're right.  It's more general than C++.

> 
>> +  ** GDB can now complete function parameters in linespecs and
>> +     explicit locations, even without quoting.  When setting
>> +     breakpoints, quoting around functions names to help with
>> +     TAB-completion is generally no longer necessary.
> 
> Likewise.
> 
>> +  ** GDB can now set breakpoints functions marked with [abi:cxx11]
>> +     tags.
> 
> "on functions", I think.
> 
> And btw, what are those tags?  

This is the best document that I know describing them:

 https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/

Functions that ended up requiring an abi tag are demangled like this:

  string_printf[abi:cxx11](char const*, ...)
               ^^^^^^^^^^^

That's an actual function in GDB.  It ended requiring an ABI tag
because it returns std::string.  See intro of patch 39 for more.

> I don't think I see them documented in the manual; did I miss something?

Hmm, I guess we could add something, indeed.

Thanks,
Pedro Alves
  

Hi Eli,

On 06/02/2017 02:01 PM, Eli Zaretskii wrote:
>> From: Pedro Alves <palves@redhat.com>
>> > Date: Fri,  2 Jun 2017 13:22:38 +0100
>> > 
>> > +For example, assuming a program with symbols named @code{A::B::func}
>> > +and @code{B::func}, both commands @code{break -function func} and
>> > +@code{break -function B::func} set a breakpoint on both symbols.
> The 2 commands are long and include whitespace, so I'd suggest
> enclosing each one in @w{..}, to avoid a line break in the middle of a
> command.
> 
> Also, I think @kbd is more appropriate here than @code, since you mean
> commands the user will type, not just command names.

I was addressing this comment, and found myself a bit confused
on the distinction between kbd vs code, and what you mean by
"commands the user will type, not just command names".  Here I'm
referring to how the commands with those names behave, not explicitly
discussing typing.  E.g., the commands behave the same way
when found in a script too.  Doesn't that suggest @code instead?
If not, what would be an example of "just command names", ones that
the user will NOT type?  I.e., when should we use @code instead?

From here: 
 https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040kbd.html
I got the impression that a use of @kbd would be when describing
the completion machinery.  Or then the text clearly says something around
"type @kbd{....}".  What specifically confused me was this example
in that page that uses @code for a command name not unlike one of GDB's:

~~~
To give the @code{logout} command,
type the characters @kbd{l o g o u t @key{RET}}.
~~~

We seemingly use @code throughout in GDB's manual to refer to
command names, which adds to my confusion.  They may all be
incorrect, and I'm not trying to justify adding more wrong usages
at all.  I'd just like to understand better the distinction you have
in mind, so I can follow it consistently too.

Thanks,
Pedro Alves
  

> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <palves@redhat.com>
> Date: Wed, 21 Jun 2017 14:32:54 +0100
> 
> > Also, I think @kbd is more appropriate here than @code, since you mean
> > commands the user will type, not just command names.
> 
> I was addressing this comment, and found myself a bit confused
> on the distinction between kbd vs code, and what you mean by
> "commands the user will type, not just command names".  Here I'm
> referring to how the commands with those names behave, not explicitly
> discussing typing.  E.g., the commands behave the same way
> when found in a script too.  Doesn't that suggest @code instead?

Not IMO.

We use @code for names of individual commands, like @code{help} or
@code{run}.  When we need to show a full command line, it is better to
use @kbd because it is the markup suitable for commands that users
type.  I don't think it matters much whether they type it at GDB's
prompt or into a script.

In a nutshell, when I see a string with embedded whitespace marked up
in @code, I raise a brow ;-)

(And yes, I know that we use @code{set FOO} a lot.  That is IMO an
exception, since the "set" command alone makes very little sense in
GDB.)

> >From here: 
>  https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040kbd.html
> I got the impression that a use of @kbd would be when describing
> the completion machinery.  Or then the text clearly says something around
> "type @kbd{....}".

My rule is "when talking about something that users might/will type,
explicitly or implicitly".  It's admittedly a fine line sometimes,
which is why I use the "whitespace" heuristics (which is also
imperfect).

> What specifically confused me was this example
> in that page that uses @code for a command name not unlike one of GDB's:
> 
> ~~~
> To give the @code{logout} command,
> type the characters @kbd{l o g o u t @key{RET}}.
> ~~~

Why is that confusing?  This text specifically makes a point of
differentiating between a command's name and the way it is typed at
the keyboard.  It's a rare case, but it does happen.

> We seemingly use @code throughout in GDB's manual to refer to
> command names, which adds to my confusion.  They may all be
> incorrect, and I'm not trying to justify adding more wrong usages
> at all.  I'd just like to understand better the distinction you have
> in mind, so I can follow it consistently too.

I hope I explained at least some of that.

Thanks.