Re: RFA: add .gdb_index documentation to gdb.texinfo

[Eli Zaretskii <eliz at gnu dot org>]

> From: Tom Tromey <tromey@redhat.com>
> CC: Mark Wielaard <mjw@redhat.com>
> Date: Wed, 20 Apr 2011 07:59:22 -0600
> 
> This patch moves the documentation from a comment in dwarf2read.c to the
> manual.

Thanks!

> +@node Index Section Format
> +@appendix .gdb_index section format

".gdb_index" should be in @code in the @appendix line.

> +@cindex .gdb_index section format

I would also add another @cindex entry, "index section format".

> +The section documents the index section that is created by @code{save
   ^^^^^^^^^^^
You probably meant "This section" here.

> +@code{offset_type}.  Big endian machines must byte-swap the values
> +before using them. Exceptions to this rule are noted.  The data is
                    ^^
Two spaces, please.

> +A string in the constant pool is @samp{\0}-terminated.

I think "zero-terminated" is better.

> +The hash value for a table entry is computed by an applying an
                                                   ^^
Remove that extra "an".

> +The step size used in the hash table is computed via
> +@code{((hash * 17) & (size - 1)) | 1}, where @samp{hash} is the hash
> +value, and @samp{size} is the size of the hash table.

It's unclear from the text when is this "step size" used.  Perhaps say
a word or two about that.

> +The names of C@t{++} symbols in the hash table are canonicalized.  We
> +don't currently have a simple description of the canonicalization
> +algorithm; if you intend to create new index sections, you must read
> +the code.
> +
> +A CU vector in the constant pool is a sequence of @code{offset_type}
> +values.  The first value is the number of CU indices in the vector.
> +Each subsequent value is the index of a CU in the CU list.  This
> +element in the hash table is used to indicate which CUs define the
> +symbol.

The text of this @item interleaves information about the hash table
proper with info about the constant pool, which is actually described
in the next @item.  Perhaps it would be good to have all the info
about the constant pool in the next item of the enumerated list?

Thanks.