Re: RFA: prologue value modules

[Eli Zaretskii <eliz@gnu.org>]

> Cc: gdb-patches@sources.redhat.com
> From: Jim Blandy <jimb@codesourcery.com>
> Date: Mon, 27 Mar 2006 15:59:33 -0800
> 
> >>
> >> Are we going to have this documented in gdbint.texinfo?
> >
> > Yes --- I promised that before.  Thanks for reminding me.
> 
> How's this doc patch?

It's fine, modulo some minor comments below.  Thanks.

> +Modern versions of GCC emit Dwarf call frame information (``CFI'')
> +that gives @value{GDBN} all the information it needs to do this.

AFAICS, this is the first time the manual mentions "CFI", so I think
at least an index entry is in order, if not a short explanation of
what it is (perhaps in a footnote for now, pending some real
documentation in the future), or a pointer to some doc on the net.

> +and fragile.  Keeping the prologue analyzers working as GCC (and the
> +ISA's themselves) evolved became a substantial task.

Ditto for "ISA".

> +@cindex @file{prologue-value.c}
> +@cindex abstract interpretation of function prologues
> +@cindex pseudo-evaluation of function prologues
> +To try to address this problem, the code in
> +@file{gdb/prologue-value.h} and @file{gdb/prologue-value.c} provide a

Should these file names include the leading "gdb/" directory?  I'm not
sure it's really required; OTOH, having too long strings in @file{}
might produce ugly printed version, because TeX does not know how to
hyphenate inside @file{}.

> +@example
> +   mov r2, r1      # set r2 to r1's value
> +@end example

This @example is indented differently than the rest.  Any reason?

> +@example
> +mov (fp+4), r2
> +@end example
> +@noindent
> +Then we'd know that the stack slot four bytes above the frame pointer
   ^^^^
This should be a lowercase "then", since it doesn't start a sentence.

> +register's original value.  If the ABI suggests a standard place

We have a section about the ABI, so I think a cross-reference there
will be a good idea.

>                                                      So I think it's
> +worthwhile to look for an approach that will be easier to understand
> +and maintain.  In the approach used here:

I think we need to reword ``I'' and ``here'', so that they look
natural in the context of the manual (as opposed to a mail message or
a source file).

> +The file @file{prologue-value.h} contains detailed comments explaining
> +the framework and how to use it.

Would it be a good idea to have the listing of the API in the manual,
with short explanations?  I'm not saying it is necessarily required,
but please give it a thought.