From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 84429 invoked by alias); 12 Jan 2018 08:34:03 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 84336 invoked by uid 89); 12 Jan 2018 08:34:02 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-24.9 required=5.0 tests=AWL,BAYES_00,GIT_PATCH_0,GIT_PATCH_1,GIT_PATCH_2,GIT_PATCH_3,SPF_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy= X-HELO: eggs.gnu.org Received: from eggs.gnu.org (HELO eggs.gnu.org) (208.118.235.92) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Fri, 12 Jan 2018 08:34:00 +0000 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eZumh-00089k-3h for gdb-patches@sourceware.org; Fri, 12 Jan 2018 03:33:59 -0500 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:36647) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eZumP-0007tn-Jv; Fri, 12 Jan 2018 03:33:37 -0500 Received: from [176.228.60.248] (port=3649 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eZumO-0007DF-VQ; Fri, 12 Jan 2018 03:33:37 -0500 Date: Fri, 12 Jan 2018 08:34:00 -0000 Message-Id: <83vag7329f.fsf@gnu.org> From: Eli Zaretskii To: Sergio Durigan Junior CC: gdb-patches@sourceware.org, tom@tromey.com In-reply-to: <20180111213530.23774-1-sergiodj@redhat.com> (message from Sergio Durigan Junior on Thu, 11 Jan 2018 16:35:30 -0500) Subject: Re: [PATCH] Install and generate docs for gdb-add-index Reply-to: Eli Zaretskii References: <20180111213530.23774-1-sergiodj@redhat.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-IsSubscribed: yes X-SW-Source: 2018-01/txt/msg00238.txt.bz2 > From: Sergio Durigan Junior > Cc: Tom Tromey , Eli Zaretskii , Sergio Durigan Junior > 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.