Re: [PATCH v2 4/4] Add doc and news for DWARF index cache

[Eli Zaretskii <eliz at gnu dot org>]

> From: Simon Marchi <simon.marchi@ericsson.com>
> CC: Simon Marchi <simon.marchi@ericsson.com>
> Date: Wed, 25 Jul 2018 18:47:04 -0400
> 
> This patch adds doc and news for the feature introduced by the previous
> patch.

Thanks.

> +* DWARF index cache: GDB can now automatically save indices DWARF symbols on

"indices of DWARF symbols", I presume?

> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index b36a39b..9533c72 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -20095,6 +20095,42 @@ 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.
>  
> +@subsection Automatic symbol index cache
> +
> +It is possible for GDB to automatically save a copy of this index in a cache
                      ^^^
@value{GDBN}

> +on disk and retrieve it from there when loading the same binary in the future.
> +This feature can be turned on with @command{set index-cache on}.  The following

@command is incorrect here, it's the markup for shell commands, like
'ls'.  What you want is @kbd.

> +@table @code
> +
> +@item set index-cache on
> +@itemx set index-cache off
> +
> +Enable or disable the use of the symbol index cache.

There should be no empty line between @item and the following
description.

> +
> +@item set index-cache directory @var{directory}
> +@itemx show index-cache directory
> +Set/show the directory where index files will be saved.  By default, the value
> +@code{$XDG_CACHE_HOME/gdb} is used if the @code{XDG_CACHE_HOME} environment
> +variable is defined.  The value @code{$HOME/.cache/gdb} is used otherwise.

Please don't use $FOO to mean an environment variable, that is a Unix
shell convention.  I suggest to rephrase:

  By default, the index is cached in the @file{gdb} subdirectory of
  the directory pointed to by the @env{XDG_CACHE_HOME} environment
  variable, if it is defined, else in the @file{.cache/gdb}
  subdirectory of your home directory.

> +@item set index-cache format @var{format}
> +@itemx show index-cache format
> +Set/show the format in which index files are saved.  @var{format} can be either
> +@code{gdb} (the default) or @code{dwarf-5}.  Note that @value{GDBN} is currently
> +only able to read back files in the @code{gdb} format from the cache, so
> +@code{dwarf-5} is not very useful.

If 'dwarf-5' cannot be used, why are we documenting it, and why are we
documenting/implementing this command in the first place?

> +@item show index-cache stats
> +Print the number of cache hits and misses for the index cache since the launch
> +of @value{GDBN}.

This begs the question: for which index cache will this show the
statistics?  For the one defined by the latest "set index-cache
directory" command?