Re: [PATCH v2] Add support for the --readnever command-line option

[Eli Zaretskii <eliz at gnu dot org>]

> From: Sergio Durigan Junior <sergiodj@redhat.com>
> Cc: Joel Brobecker <brobecker@adacore.com>,
> 	Yao Qi <qiyaoltc@gmail.com>,
> 	Pedro Alves <palves@redhat.com>,
> 	Eli Zaretskii <eliz@gnu.org>,
> 	Sergio Durigan Junior <sergiodj@redhat.com>
> Date: Fri, 24 Nov 2017 18:01:22 -0500
> 
> diff --git a/gdb/NEWS b/gdb/NEWS
> index 754ce103bd..32229d3cea 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -3,6 +3,10 @@
>  
>  *** Changes since GDB 8.0
>  
> +* New "--readnever" command line option instructs GDB to not read each
> +  symbol file's symbolic debug information.  This makes startup faster
> +  but at the expense of not being able to perform symbolic debugging.
> +

This part is okay, but I would add here as well a hint about the use
cases this supports.  Like this, for example:

  This option is intended for use cases where symbolic debugging will
  not be used, e.g., when you only need to dump the debuggee's core.

> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 00451d243d..f3eef8dfeb 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -1037,6 +1037,15 @@ Read each symbol file's entire symbol table immediately, rather than
>  the default, which is to read it incrementally as it is needed.
>  This makes startup slower, but makes future operations faster.
>  
> +@item --readnever
> +@cindex @code{--readnever}
> +Do not read each symbol file's symbolic debug information.  This makes
> +startup faster but at the expense of not being able to perform
> +symbolic debugging.  DWARF unwind information is also not read,
> +meaning backtraces may become incomplete or inaccurate.  One use of
> +this is when a user simply wants to do the following sequence: attach,
> +dump core, detach.  Loading the debugging information in this case is
> +an unnecessary cause of delay.
>  @end table
>  
>  @node Mode Options
> @@ -18486,6 +18495,14 @@ tables by using the @samp{-readnow} option with any of the commands that
>  load symbol table information, if you want to be sure @value{GDBN} has the
>  entire symbol table available.
>  
> +@kindex readnever
> +@cindex never read symbols
> +@cindex symbols, never read
> +@item symbol-file @r{[} -readnever @r{]} @var{filename}
> +@itemx file @r{[} -readnever @r{]} @var{filename}
> +You can instruct @value{GDBN} to never read the symbolic information
> +contained in @var{filename} by using the @samp{-readnever} option.
> +

This will cause index entries about "readnever" point to 2 different
places, with no way for the reader to tell up front which place is
about where they want to go.  So I suggest to change the index entries
as follows:

  @cindex @code{--readnever}, command-line option
  ...
  @cindex @code{-readnever}, option for symbol-file command

(Note that I switched from @kindex to @cindex, since @kindex is used
for command names, and -readnever isn't.)

Otherwise, the patch for the manual is OK.

> @@ -1183,6 +1213,9 @@ Selection of debuggee and its files:\n\n\
>    --se=FILE          Use FILE as symbol file and executable file.\n\
>    --symbols=SYMFILE  Read symbols from SYMFILE.\n\
>    --readnow          Fully read symbol files on first access.\n\
> +  --readnever        Do not read symbol files.\n\
> +                     There is currently a known limitation that this only\n\
> +                     has an effect on symbol files provided in DWARF format.\n\

The part about its being limited to DWARF should now go away, right?

Thanks.