This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [doc RFA] Misc. fixes to Python docs
- From: Doug Evans <xdje42 at gmail dot com>
- To: Eli Zaretskii <eliz at gnu dot org>
- Cc: "gdb-patches at sourceware dot org" <gdb-patches at sourceware dot org>
- Date: Mon, 23 Dec 2013 07:34:59 -0800
- Subject: Re: [doc RFA] Misc. fixes to Python docs
- Authentication-results: sourceware.org; auth=none
- References: <m3haa0tjkd dot fsf at sspiff dot org> <83a9fs8brb dot fsf at gnu dot org>
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.