Re: [rfc/rfa] Revsions to gdbint.texinfo

["Eli Zaretskii" <eliz at is dot elta dot co dot il>]

> Date: Fri, 15 Jun 2001 03:14:38 -0400
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> More work is always needed.

I'd say this is the understatement of the year! ;-)

I like these additions and welcome them; thanks!  What follows is
mostly boring minor nitpicking.

> ! The target architecture object is implemented as the C structure
> ! @code{struct gdbarch *}.  The structure, and its methods, are generated
> ! using the Bourn shell script @code{gdbarch.sh}.

gdbarch.sh is a file, so it should have the @file markup.

> + significant change.  Many of the macro's

That's "macros", without the quote.

> + section below are likely to be made obsolete.  See the file @code{TODO}

@file{TODO}.

> + @item gdb/@var{arch}-tdep.c, gdb/@var{arch}-tdep.h

If you need two items in a row, please use @itemx for all but the
first:

  @item gdb/@var{arch}-tdep.c
  @itemx gdb/@var{arch}-tdep.h

> + @subsection Memory Management

This section consistently uses @code{foo()}, with the parentheses, to
designate functions.  The parentheses should be removed, because the
name of the function is just `foo'; `foo()' is a call to that function
with no arguments.

> + et.al. these functions do not return when the memory pool is empty.

You should say "et.al.@:", otherwise TeX will typeset the period as if
it were at the end of a sentence.

> + @value{GDBN} can use the non-portable function for the allocation of
> + small tempoary values (such as strings).

Didn't you meant to mention that function's name, alloca?  Or is it so
bad that even its name shouldn't be pronounced in vain? ;-)

> + @code{sprintf()} are very proned to buffer overflow errors.}

I think "proned" is not correct English.  "prone" is the right usage.

> ! @samp{-Wunused-parameter} is precluded from the list.  The macro
> ! @samp{ATTRIBUTE_UNUSED} is not used as it leads to false negatives ---

ATTRIBUTE_UNUSED should be in @code, not in @samp, since it is not
something you type at some program's prompt.

> ! While in a definition, the function's name must be in column zero; in a
> ! function declaration, the name must be on the same line as the return
> ! type.
>   
> + @example
> + void foo (void);
> + @end example

This should say explicitly that the example shows declaration, not
definition.  Or mayube we should have two examples, one each for each
one of the two cases.

>   @cindex C data types
> + 
>   Code must not depend on the sizes of C data types, the format of the

This is wrong: there should be no blank line between an index entry
and the chunk of text it references.

> + Prototypes must be used when both @emph{declareing} and @emph{defineing}

That's "declaring" and "defining" ;-)

> + @value{GDBN} must not call @samp{abort()}.  Use @samp{internal_error()}.

@code{abort} and @code{internal_error}.

> + @samp{gdb_string.h}) the file name based on the POSIX header prefixed
> + with @samp{gdb_}.

These are file names, so use @file.

> + All debugging code must be controllable using the @samp{set debug
> + <module>} command.  Do not use @samp{printf}s to print trace messages.

Instead of <module> say @var{module}.