[patch][python][doc] PR 12918 reference decode_line in py SAL docs.

[patch][python][doc] PR 12918 reference decode_line in py SAL docs.

[Matt Rice]

[-- Attachment #1: Type: text/plain, Size: 254 bytes --]

here is an attempt at 12918, along with the original reporter,
I also had overlooked the decode_line method.

2011-07-02  Matt Rice  <ratmice@gmail.com>

        * gdb.texinfo (Symbol Tables In Python): Add reference to the
        decode_line function.

[-- Attachment #2: foo.diff --]
[-- Type: application/octet-stream, Size: 752 bytes --]

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index dbaf30e..cbfaddd 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23258,7 +23258,9 @@ Access to symbol table data maintained by @value{GDBN} on the inferior
 is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
 @code{gdb.Symtab}.  Symbol table and line data for a frame is returned
 from the @code{find_sal} method in @code{gdb.Frame} object.
-@xref{Frames In Python}.
+@xref{Frames In Python}.  Symbol table and line data for an arbitrary
+linespec is returned from the @code{decode_line} function.
+@xref{Basic Python}.
 
 For more information on @value{GDBN}'s symbol table management, see
 @ref{Symbols, ,Examining the Symbol Table}, for more information.

Re: [patch][python][doc] PR 12918 reference decode_line in py SAL docs.

[Eli Zaretskii]

> Date: Sat, 2 Jul 2011 07:20:08 -0700
> From: Matt Rice <ratmice@gmail.com>
> 
> here is an attempt at 12918, along with the original reporter,
> I also had overlooked the decode_line method.
> 
> 2011-07-02  Matt Rice  <ratmice@gmail.com>
> 
>         * gdb.texinfo (Symbol Tables In Python): Add reference to the
>         decode_line function.
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index dbaf30e..cbfaddd 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -23258,7 +23258,9 @@ Access to symbol table data maintained by @value{GDBN} on the inferior
>  is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
>  @code{gdb.Symtab}.  Symbol table and line data for a frame is returned
>  from the @code{find_sal} method in @code{gdb.Frame} object.
> -@xref{Frames In Python}.
> +@xref{Frames In Python}.  Symbol table and line data for an arbitrary
> +linespec is returned from the @code{decode_line} function.
> +@xref{Basic Python}.
>  
>  For more information on @value{GDBN}'s symbol table management, see
>  @ref{Symbols, ,Examining the Symbol Table}, for more information.

Thanks, but how does this address the PR?  This is the full text of 
PR 12918:

  There is no (obvious) documented way to get a symtab_and_line object given an
  arbitrary address.  
  A function gdb.sal_for_pc() similar to gdb.block_for_pc() would be nice.

If you want to tell that decode_line is the answer for the PR's
request, then why not update the documentation of decode_line, which
is almost 2000 lines earlier in the manual and in a different node?

IOW, why are you adding this text in this particular place?

Sorry if I'm missing something obvious.

Re: [patch][python][doc] PR 12918 reference decode_line in py SAL docs.

[Matt Rice]

On Sat, Jul 2, 2011 at 10:00 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Sat, 2 Jul 2011 07:20:08 -0700
>> From: Matt Rice <ratmice@gmail.com>
>>
>> here is an attempt at 12918, along with the original reporter,
>> I also had overlooked the decode_line method.
>>
>> 2011-07-02  Matt Rice  <ratmice@gmail.com>
>>
>>         * gdb.texinfo (Symbol Tables In Python): Add reference to the
>>         decode_line function.
>>
>> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
>> index dbaf30e..cbfaddd 100644
>> --- a/gdb/doc/gdb.texinfo
>> +++ b/gdb/doc/gdb.texinfo
>> @@ -23258,7 +23258,9 @@ Access to symbol table data maintained by @value{GDBN} on the inferior
>>  is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
>>  @code{gdb.Symtab}.  Symbol table and line data for a frame is returned
>>  from the @code{find_sal} method in @code{gdb.Frame} object.
>> -@xref{Frames In Python}.
>> +@xref{Frames In Python}.  Symbol table and line data for an arbitrary
>> +linespec is returned from the @code{decode_line} function.
>> +@xref{Basic Python}.
>>
>>  For more information on @value{GDBN}'s symbol table management, see
>>  @ref{Symbols, ,Examining the Symbol Table}, for more information.
>
> Thanks, but how does this address the PR?  This is the full text of
> PR 12918:
>
>  There is no (obvious) documented way to get a symtab_and_line object given an
>  arbitrary address.
>  A function gdb.sal_for_pc() similar to gdb.block_for_pc() would be nice.
>
> If you want to tell that decode_line is the answer for the PR's
> request, then why not update the documentation of decode_line, which
> is almost 2000 lines earlier in the manual and in a different node?
>
> IOW, why are you adding this text in this particular place?
>
> Sorry if I'm missing something obvious.
>

The answer to the PR's request is already documented in the `Specify
Location' link[1] from decode_line answering it there directly I
thought would be good, but a duplication of existing docs.

So I thought that what was missing was the association from the
perspective of `Symtab and line'
Considering that `Symtab and line' already links to gdb.Frame as a way
to get a Symtab_and_line object, its omission creates the impression
of a missing feature.
when i was looking for decode_line, I looked everywhere _except_
`Basic Python',

Thus my hope was that a complete chain of links from the goal, would
provoke a more keen investigation into existing docs.

If someone has a better idea for further clarifying it i'm all for it.

[1] http://sourceware.org/gdb/current/onlinedocs/gdb/Specify-Location.html#Specify-Location

Re: [patch][python][doc] PR 12918 reference decode_line in py SAL docs.

[Eli Zaretskii]

> Date: Sat, 2 Jul 2011 14:53:42 -0700
> From: Matt Rice <ratmice@gmail.com>
> Cc: gdb-patches@sourceware.org
> 
> Thus my hope was that a complete chain of links from the goal, would
> provoke a more keen investigation into existing docs.
> 
> If someone has a better idea for further clarifying it i'm all for it.

Maybe we should simply ask the OP what, if anything, is missing, given
the existing documentation of decode_line.