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

[Matt Rice <ratmice@gmail.com>]

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