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

[Matt Rice <ratmice at gmail dot 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