Re: Internals manual fixups

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Sat, 28 Jun 2008 11:26:04 -0700
> From: Stan Shebs <stanshebs@earthlink.net>
> 
> As threatened, here is my first round of bashing on the internals 
> manual. Eli, how does it look to you?

As threatened, I returned from my traveling and are slowly catching up
on the backlog.

> -host and target are not the same, doing a fork to start the target
> +host and target are not the same, doing a fork() to start the target

GNU coding standards frown on using "fork()" with the purpose of
saying that `fork' is a function.  The rationale is that "fork()"
looks like a call to `fork' with no arguments, which is not what you
want.  Please use @code{fork} instead.

> -@code{gdbarch_get_longjmp_target}, which will examine the @code{jmp_buf}
> -structure and extract the longjmp target address.  Since @code{jmp_buf}
> -is target specific, you will need to define it in the appropriate
> -@file{tm-@var{target}.h} file.  Look in @file{tm-sun4os4.h} and
> -@file{sparc-tdep.c} for examples of how to do this.
> +@code{gdbarch_get_longjmp_target}, which will examine the
> +@code{jmp_buf} structure and extract the longjmp target address.
> +Since @code{jmp_buf} is target specific and typically defined in a
> +target header not available to @value{GDBN}, you will need to
> +determine the offset of the PC manually and return that; many targets

Please in the future don't re-fill paragraphs together with real
changes.  It makes it harder for me to review changes, because I need
to find the _real_ changes among whitespace changes.  If you want to
change whitespace, feel free to commit without an RFA.

Also, `longjmp' is a function, so it should be in @code, like the rest
of the symbols here.

> +define a @code{jb_pc_offset} field in the tdep structure to save the
> +value once calculated. See @file{i386-tdep.c} for an example.

First, please make sure you have 2 spaces after a period that ends a
sentence.  Second, please remember that @file{foo} will become just
`foo' in the makeinfo/TeX output, so the word "file" that this text
begs should be added explicitly, to explain more clearly where to
look.

> -watchpoints before stepping the inferior.
> +watchpoints before stepping the inferior. Currently this is only
> +defined for Solaris x86.

I generally find text that mentions specific hosts a maintenance
nightmare: we will have to remember from now on to modify it whenever
some other platform defines this.  I prefer saying something vague,
like "on some platforms".

> +all. Studies have shown that nearly all the time spent is
      ^^
Two spaces, please, here and elsewhere.

> +Returns a @code{(register, offset)} pair representing the virtual

I think it would be better here to give "register" and "offset" the
@var markup.


> +frame pointer in use at the code address @var{pc}.

Btw, saying that this pair "represents the virtual frame pointer"
seems to be not enough, as the reader is left to wonder what is the
role of each one of the 2 members of this pair.  Please consider
adding some more details.

> +(@pxref{Support Libraries, ,Opcodes}).  @var{info} is a structure (of
> +type @code{disassemble_info}) defined in @file{include/dis-asm.h} used

Again, please use an explicit "file" word in the text, @file alone is
not enough.

> +(Target header files such as
> +@file{gdb/config/@var{arch}/tm-@var{ttt}.h},
> +@file{gdb/config/@var{arch}/tm-@var{arch}.h}, and
> +@file{config/tm-@var{os}.h} are no longer used.)

Then why mention them at all?

>  that runs in the target system.  @value{GDBN} provides several sample
>  @dfn{stubs} that can be integrated into target programs or operating
> -systems for this purpose; they are named @file{*-stub.c}.
> +systems for this purpose; they are named @file{*-stub.c}. Many

I think @var{cpu}-stub.c is better than *-stub.c here.

Otherwise, this is okay.

Note that I didn't verify that everything you removed is indeed not
used.

Thanks.