[doc RFA] Misc. fixes to Python docs

[doc RFA] Misc. fixes to Python docs

[Doug Evans]

Hi.

I found this collection of fixes.

The @tindex is for consistency with all other such entries.

The @code{"charset"} instead of @samp{charset} is for consistency with
earlier use.

The others should be straightforward.

2013-12-22  Doug Evans  <xdje42@gmail.com>

	* gdb.texinfo (Basic Python): Add docs for gdb.VERSION,
	gdb.HOST_CONFIG, gdb.TARGET_CONFIG.
	(Values From Inferior): Use @tindex instead of @cindex.
	Use @code instead of @samp for charset encodings.  Fix typo.
	(Types In Python): Use @code{gdb.Type} instead of @code{Type}.
	(Objfiles In Python): Remove unnecessary self-@xref.
	(Frames In Python): Use @xref instead of @pxref.
	(GDB/MI Variable Objects): Mention -var-set-visualizer.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b7551c2..8c77a95 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23655,6 +23655,23 @@ use in all scripts evaluated by the @code{python} command.
 A string containing the python directory (@pxref{Python}).
 @end defvar
 
+@findex gdb.VERSION
+@defvar gdb.VERSION
+A string containing the @value{GDBN} version.
+@end defvar
+
+@findex gdb.HOST_CONFIG
+@defvar gdb.HOST_CONFIG
+A string containing the host configuration.
+This is the string passed to @code{--host} when @value{GDBN} was configured.
+@end defvar
+
+@findex gdb.TARGET_CONFIG
+@defvar gdb.TARGET_CONFIG
+A string containing the target configuration.
+This is the string passed to @code{--target} when @value{GDBN} was configured.
+@end defvar
+
 @findex gdb.execute
 @defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]})
 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
@@ -23958,7 +23975,7 @@ hello-world takes no arguments
 @cindex values from inferior, with Python
 @cindex python, working with values from inferior
 
-@cindex @code{gdb.Value}
+@tindex gdb.Value
 @value{GDBN} provides values it obtains from the inferior program in
 an object of type @code{gdb.Value}.  @value{GDBN} uses this object
 for its internal bookkeeping of the inferior's values, and for
@@ -24250,8 +24267,8 @@ In Python}).  Otherwise, this method will throw an exception.
 
 If the optional @var{encoding} argument is given, it must be a string
 naming the encoding of the @code{gdb.LazyString}.  Some examples are:
-@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}.  If the
-@var{encoding} argument is an encoding that @value{GDBN} does
+@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}.  If the
+@var{encoding} argument is an encoding that @value{GDBN} does not
 recognize, @value{GDBN} will raise an error.
 
 When a lazy string is printed, the @value{GDBN} encoding machinery is
@@ -24317,7 +24334,7 @@ bar = some_type['foo']
 description of the @code{Type.fields} method for a description of the
 @code{gdb.Field} class.
 
-An instance of @code{Type} has the following attributes:
+An instance of @code{gdb.Type} has the following attributes:
 
 @defvar Type.code
 The type code for this type.  The type code will be one of the
@@ -24375,7 +24392,7 @@ non-zero value, which is the size of the field in bits.  Otherwise,
 this will be zero; in this case the field's size is given by its type.
 
 @item type
-The type of the field.  This is usually an instance of @code{Type},
+The type of the field.  This is usually an instance of @code{gdb.Type},
 but it can be @code{None} in some situations.
 
 @item parent_type
@@ -26482,7 +26499,6 @@ this function returns @code{None}.
 @findex gdb.objfiles
 @defun gdb.objfiles ()
 Return a sequence of all the objfiles current known to @value{GDBN}.
-@xref{Objfiles In Python}.
 @end defun
 
 Each objfile is represented by an instance of the @code{gdb.Objfile}
@@ -26544,7 +26560,7 @@ The following frame-related functions are available in the @code{gdb} module:
 
 @findex gdb.selected_frame
 @defun gdb.selected_frame ()
-Return the selected frame object.  (@pxref{Selection,,Selecting a Frame}).
+Return the selected frame object.  @xref{Selection,,Selecting a Frame}.
 @end defun
 
 @findex gdb.newest_frame
@@ -32322,6 +32338,8 @@ access this functionality:
 @tab set frozeness attribute
 @item @code{-var-set-update-range}
 @tab set range of children to display on update
+@item @code{-var-set-visualizer}
+@tab set the pretty-printer for this variable
 @end multitable
 
 In the next subsection we describe each operation in detail and suggest

Re: [doc RFA] Misc. fixes to Python docs

[Eli Zaretskii]

> From: Doug Evans <xdje42@gmail.com>
> Date: Sun, 22 Dec 2013 17:58:10 -0800
> 
> I found this collection of fixes.
> 
> The @tindex is for consistency with all other such entries.
> 
> The @code{"charset"} instead of @samp{charset} is for consistency with
> earlier use.

I question the second issue.  IMO @samp looks much better in print
than @code{".."}.

> +@findex gdb.VERSION
> +@defvar gdb.VERSION

@defvar inserts its argument into the index automatically, so no need
for @findex (which is wrong anyway, since this is a variable, not a
function).

> @@ -26482,7 +26499,6 @@ this function returns @code{None}.
>  @findex gdb.objfiles
>  @defun gdb.objfiles ()
>  Return a sequence of all the objfiles current known to @value{GDBN}.
> -@xref{Objfiles In Python}.
>  @end defun

Why did you remove the cross-reference?

OK with those changes.

Thanks.

Re: [doc RFA] Misc. fixes to Python docs

[Doug Evans]

On Sun, Dec 22, 2013 at 7:52 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Doug Evans <xdje42@gmail.com>
>> Date: Sun, 22 Dec 2013 17:58:10 -0800
>>
>> I found this collection of fixes.
>>
>> The @tindex is for consistency with all other such entries.
>>
>> The @code{"charset"} instead of @samp{charset} is for consistency with
>> earlier use.
>
> I question the second issue.  IMO @samp looks much better in print
> than @code{".."}.

I don't have a strong opinion, other than Consistency Is Good.

>> +@findex gdb.VERSION
>> +@defvar gdb.VERSION
>
> @defvar inserts its argument into the index automatically, so no need
> for @findex (which is wrong anyway, since this is a variable, not a
> function).

Heh, righto.
And in fact I have another patch to remove a lot of dupes for some defuns.

>> @@ -26482,7 +26499,6 @@ this function returns @code{None}.
>>  @findex gdb.objfiles
>>  @defun gdb.objfiles ()
>>  Return a sequence of all the objfiles current known to @value{GDBN}.
>> -@xref{Objfiles In Python}.
>>  @end defun
>
> Why did you remove the cross-reference?

We're in the chapter on "Objfiles In Python" and it's telling the
reader "See the chapter on Objfiles In Python."
[Yes, I know xref doesn't expand to include "the chapter on".  I'm
expanding the wording for illustration's sake.]
Self-xrefs feel really out of place.