Re: [RFA/doco/testsuite] Document new gdb_test_timeout global variable.

[Eli Zaretskii <eliz at gnu dot org>]

> From: Joel Brobecker <brobecker@adacore.com>
> Date: Mon,  8 Feb 2010 16:17:32 +0400
> 
> This patch documents a new testsuite variable introduced to allow
> the user to configure the timeout duration used while running
> the testsuite.
> 
>     http://www.sourceware.org/ml/gdb-patches/2010-02/msg00101.html
> 
> gdb/doc/ChangeLog:
> 
>         * gdbint.texinfo (Testsuite): New section "Testsuite Configuration",
>         documenting the gdb_test_timeout variable.

Thanks.

> +@section Testsuite Configuration

It's usually a good idea to put a @cindex entry with the same text as
the name of the section (with all words lower-cased) right after the
section header.  That is because most section names introduce a topic,
and users looking for that info will likely think about that topic as
well.

> +It is possible to adjust the behavior of the testsuite by defining
> +the global variables listed below, either in a @file{site.exp} file,
> +or in a @code{board} file.

Why "board" is in @code, not in @file?  Isn't it a file?

> +If not specifically defined, this variable gets automatically defined
> +to the same value as @code{timeout} during the testsuite initialization
> +(the actual value depends on the exact running parameters).

It would be worth saying more about how to find out the default
value.  If I'm a reader of this section, I might ask myself whether I
need to set the variable to a non-default value, but it is impossible
to answer that question without knowing what would be the value if I
don't do anything.

> +This global variable is usually used when the debugger is slower than

"usually used" sounds awkward.  How about "comes in handy"?

> +test failures.  For instance, when testing on a remote machine, or against
> +a system where communications are slow.

The last sentence is not a complete one.  How about

  Examples include testing on a remote ...

?