This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH] Install and generate docs for gdb-add-index
- From: Eli Zaretskii <eliz at gnu dot org>
- To: Sergio Durigan Junior <sergiodj at redhat dot com>
- Cc: gdb-patches at sourceware dot org, tom at tromey dot com
- Date: Fri, 12 Jan 2018 10:33:16 +0200
- Subject: Re: [PATCH] Install and generate docs for gdb-add-index
- Authentication-results: sourceware.org; auth=none
- References: <20180111213530.23774-1-sergiodj@redhat.com>
- Reply-to: Eli Zaretskii <eliz at gnu dot org>
> 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.
> +@node gdb-add-index man
> +@heading gdb-add-index
Please add an index entry here:
@pindex gdb-add-index
> +@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".
> +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.
> +@code{.gdb_index}. Note that the index is never generated for files that do
^^^^^^^^^^^^^^^^^
File names should have the @file markup.
> +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.
> +@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.
> +versions of these programs, you can specify them through the
> +@code{GDB} and @code{OBJDUMP} environment variables.
Likewise.
> +
> +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.
The documentation part is OK with those fixed.
Thanks.