Doc patch: clean up & clarify testsuite section (v2)

[Joseph S. Myers]

On Sat, 5 Oct 2002, Nathanael Nerode wrote:

> +@item gcc.c-torture
> +This contains particlar code fragments which have historically broken easily.
> +These tests are run with multiple optimization options, so tests for features
> +which only break at some optimization levels belong here.

That is not precisely accurate now: there are also tests that particular
optimizations occur (e.g. tests of built-in functions).

> +The "torture" tests are meant to be generic tests that can run on any

Don't use neutral ASCII double-quotes in Texinfo source.

> +DO NOT PUT NON-PORTABLE TESTCASES IN gcc.c-torture.
> +
> +ANY TARGET SPECIFIC TESTCASE MUST HAVE APPROPRIATE CODE TO PREVENT IT FROM
> +CAUSING A `FAILURE' ON UNSUPPORTED PLATFORMS.

Emphasis in Texinfo manuals should be done with @emph or @strong, not with
capitals in general.  When adapting plain text to Texinfo more needs to be
done than copying it.

> +Always use abort() for runtime failures, and exit(0) for success.
> +The testing harness is set up to watch for these and do something appropriate
> +(when necessary) for target boards.

This is generic documentation of testsuite idioms, which is already
present in the section "Idioms Used in Test Suite Code" and does not
belong in the documentation of individual directories.  Note need to add
@code{} appropriately when converting plain text to Texinfo.  Portability
comments above also belong in the general comments on idioms, since tests
everywhere need to avoid causing failures on unsupported systems; the docs
for each directory should describe what the appropriate mechanisms in that
directory are (.x files in c-torture, the target specifications in
gcc.dg).  Remove text from the READMEs in the patch if it is obsoleted in
the manual.

> +
>  @end table

Avoid adding stray blank lines in patches unnecessarily.

-- 
Joseph S. Myers
jsm28@cam.ac.uk