Re: [PATCH] Install and generate docs for gdb-add-index

[Sergio Durigan Junior <sergiodj@redhat.com>]

Thanks for the thorough review, Eli!

On Friday, January 12 2018, Eli Zaretskii wrote:

>> From: Sergio Durigan Junior <sergiodj@redhat.com>
>> Cc: Tom Tromey <tom@tromey.com>,	Eli Zaretskii <eliz@gnu.org>,	Sergio Durigan Junior <sergiodj@redhat.com>
>> Date: Thu, 11 Jan 2018 16:35:30 -0500
>> 
>> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
>> index dba2fa766a..62fcdd524e 100644
>> --- a/gdb/doc/gdb.texinfo
>> +++ b/gdb/doc/gdb.texinfo
>> @@ -19775,6 +19775,14 @@ There are currently some limitation on indices.  They only work when
>>  for DWARF debugging information, not stabs.  And, they do not
>>  currently work for programs using Ada.
>>  
>> +@value{GDBN} comes with a program, @command{gdb-add-index}, which can
>> +be used to add the index to a symbol file.  It takes the symbol file
>> +as its only argument:
>> +
>> +@smallexample
>> +$ gdb-add-index symfile
>> +@end smallexample
>
> I think we should have a cross-reference here to the detailed
> description of this script.

OK, included:

  For convenience, @value{GDBN} comes with a program,
  @command{gdb-add-index}, which can be used to add the index to a
  symbol file.  It takes the symbol file as its only argument:

  @smallexample
  $ gdb-add-index symfile
  @end smallexample

  @xref{gdb-add-index}.

>> +@node gdb-add-index man
>> +@heading gdb-add-index
>
> Please add an index entry here:
>
>  @pindex gdb-add-index

Done.

>> +@c man begin DESCRIPTION gdb-add-index
>> +When GDB finds a symbol file, it scans the symbols in the file in order
>> +to construct an internal symbol table.  This lets most GDB operations
>> +work quickly--at the cost of a delay early on.  For large programs,
>> +this delay can be quite lengthy, so GDB provides a way to build an
>> +index, which speeds up startup.
>
> Please use @value{GDBN} instead of a literal "GDB".

Fixed.

>> +To determine whether a file contains such an index, use the command
>> +@command{readelf -S filename}: the index is stored in a section named
>    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Commands typed by the user should have the @kbd markup, not @command.
> The latter is for names of shell commands, i.e. in general file names
> of executable programs and scripts.

Fixed.

>> +@code{.gdb_index}.  Note that the index is never generated for files that do
>    ^^^^^^^^^^^^^^^^^
> File names should have the @file markup.

This refers to a section name, not a file name.  Should it still be
marked as @file?

>> +not contain DWARF debug information (sections named @code{.debug_*}).
>
> I think this sentence is too obscure.  I think we should say
> explicitly that the index can only be produced on systems which use
> ELF binaries and DWARF debug info.  E.g., users of GDB on MS-Windows
> should understand from this that they cannot use this feature.

Here's how I've rewritten this part:

  To determine whether a file contains such an index, use the command
  @kbd{readelf -S filename}: the index is stored in a section named
  @code{.gdb_index}.  The index file can only be produced on systems
  which use ELF binaries and DWARF debug information (i.e., sections
  named @code{.debug_*}).

>> +@command{gdb-add-index} uses @value{GDBN} and @command{objdump} found
>> +in the @code{PATH} environment variable.  If you want to use different
>           ^^^^^^^^^^^
> Environment variables should have the @env markup.

Fixed.

>> +versions of these programs, you can specify them through the
>> +@code{GDB} and @code{OBJDUMP} environment variables.
>
> Likewise.

Fixed.

>> +
>> +See more in
>> +@ifset man
>> +the @value{GDBN} manual in node @code{Index Files}
>> +-- shell command @code{info -f gdb -n 'Index Files'}.
>                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> @kbd, not @code.
>
> Also, please use quotation "like this", because 'like this' only works
> on Posix platforms.

Fixed.

> The documentation part is OK with those fixed.

Thanks!  I'll wait for your reply re. the @file question, and then push
it.

-- 
Sergio
GPG key ID: 237A 54B1 0287 28BF 00EF  31F4 D0EB 7628 65FC 5E36
Please send encrypted e-mail if possible
http://sergiodj.net/