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

[Doug Evans <xdje42@gmail.com>]

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.