Re: add vector container type

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Thu, 13 Jul 2006 19:29:14 +0100
> From: Nathan Sidwell <nathan@codesourcery.com>
> CC: Mark Kettenis <mark.kettenis@xs4all.nl>,  gdb-patches@sourceware.org, 
>  dan@codesourcery.com
> 
> Eli Zaretskii wrote:
> >> Date: Mon, 10 Jul 2006 13:54:04 +0200 (CEST)
> >> From: "Mark Kettenis" <mark.kettenis@xs4all.nl>
> >> Cc: gdb-patches@sourceware.org, "Daniel Jacobowitz" <dan@codesourcery.com>
> >>
> >> Oh, and Eli will want you to write a paragraph on how to use this in
> >> gdbint.tex.
> > 
> > (You meant gdbint.texinfo.)  Yep, it would be nice.
> 
> Is this version ok?

Thanks.

Yes, it's okay, but please fix the following gotchas:

> + pointers to objects around -- in the former case the pointers are

Please use "---" -- 3 dashes in a row -- to produce an em-dash.  "--"
gets typeset as a shorter dash, almost as a hyphen (and makeinfo
simply removes one dash, so we will get "-" in the Info output, which
is not what you wanted).

There are other instances of "--", please fix them all.

> + dereferenced and the objects copied into the vector.  The scalar
> + object variant is suitable for int-like objects, and the vector

"int" is a C symbol, so please use a @code markup for it:

   ... is suitable for @code{int}-like objects ...

> + There are both 'index' and 'iterate' accessors.  The iterator returns

If the '...' quotes here were meant to emphasize the terminology,
@dfn{iterate} etc. will do it better.  If the quotes were just quotes,
please use the ``...'' style, it looks better in print.

Please also fix the other uses of '...'

> + use the embedded_size & embedded_init calls to create such objects,
            ^^^^^^^^^^^^^   ^^^^^^^^^^^^^
These are symbols, so please use @code

> + pointer to an array of data), because, if we allow NULL to also

NULL is also a symbol.

> + Vector types are defined using a DEF_VEC_@{O,P,I@}(TYPEDEF) macro.

Please give all the macros the @code markup.

> + Variables of vector type are declared using a VEC(TYPEDEF) macro.

I suspect that TYPEDEF is a placebo: it stands for something else,
like int or pointer.  If so, please use @code{VEC(@var{typedef})}
instead.  @var will do what is necessary to typeset meta-syntactic
variables such as this one.  Use @var{typedef} in every reference to
that argument in the following text as well.

Finally, perhaps you could precede this description with a short
explanation when would a GDB hacker use this facility, and also add at
least a simple list of the functions/macros provided by vec.c.