From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 86077 invoked by alias); 12 Jan 2018 16:58:46 -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 86066 invoked by uid 89); 12 Jan 2018 16:58:45 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-26.9 required=5.0 tests=BAYES_00,GIT_PATCH_0,GIT_PATCH_1,GIT_PATCH_2,GIT_PATCH_3,SPF_HELO_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy=thorough X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Fri, 12 Jan 2018 16:58:44 +0000 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id A9CFDC0799B3; Fri, 12 Jan 2018 16:58:42 +0000 (UTC) Received: from localhost (unused-10-15-17-193.yyz.redhat.com [10.15.17.193]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 4C5CC171C4; Fri, 12 Jan 2018 16:58:40 +0000 (UTC) From: Sergio Durigan Junior To: Eli Zaretskii Cc: gdb-patches@sourceware.org, tom@tromey.com Subject: Re: [PATCH] Install and generate docs for gdb-add-index References: <20180111213530.23774-1-sergiodj@redhat.com> <83vag7329f.fsf@gnu.org> Date: Fri, 12 Jan 2018 16:58:00 -0000 In-Reply-To: <83vag7329f.fsf@gnu.org> (Eli Zaretskii's message of "Fri, 12 Jan 2018 10:33:16 +0200") Message-ID: <87lgh3au9s.fsf@redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-IsSubscribed: yes X-SW-Source: 2018-01/txt/msg00247.txt.bz2 Thanks for the thorough review, Eli! On Friday, January 12 2018, Eli Zaretskii wrote: >> 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. 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/