[doc] Fixes to testsuite chapter in sourcebuild.texi

[Rainer Orth]

Hi Janis,

> On Mon, 2010-03-15 at 19:28 +0100, Rainer Orth wrote:
>> After Janis' hint, I've just completed reading the testsuite chapter in
>> the internals manual.  Overall, it's been very helpful, with one notable
>> exception (which is mentioned in some FIXME): there's no guide for
>> testsuite writers, something like an `Anatomy of a DejaGnu/GCC
>> Testsuite'.  I don't think the DejaGnu docs provide anything like this,
>> but would like to be proven wrong.
>
> No, I've never found anything about the directives from DejaGnu's .exp
> files in the DejaGnu documentation.

that's what I feared.  I'll try to see what I can come up with when
developing the minimal boehm-gc testsuite.

>> As a first experiment, I'd like to turn the single boehm-gc test into a
>> dg testsuite, since I've often noticed that failures there are the root
>> cause for libjava failures, but the failure goes completely unnoticed in
>> make check output.  Afterwards, I'll try to convert ACATS into a dg
>> testsuite as well, which will be more challening, but nicely resolves the
>> current lack of multilib testing.
>
> That sounds great!  I'll let the Ada people approve the ACATS changes.

Sure: ACATS (and Ada) testing is intricate enough as is ;-)

>> Anyway, below's the first round of fixes to problems I've found, mostly
>> markup fixes and changing filenames for .exp files into pathnames
>> relative to gcc/testsuite.  Besides, I've completed (or even created)
>> keyword lists for dg-require-effective-target, dg-add-options,
>> dg-require-<support>, and dg-final.  Mostly, the lists are just
>> placeholders since I don't currently have the time to fill them in, but it
>> serves as a reminder what's missing.
>
> Thanks for doing this, the fixes are great.  I don't like the new lists,
> which really clutter up the test directives section.  They are useful to
> document, so I would recommend moving them to new subsections.  In fact
> I would (and unless you want to do it, I will) move most of that current
> section into several subsections:
>
>   Directives
>   Selector expressions
>   Effective-target keywords
>   Add options needed for a feature
>   Require support for a feature
>   Final test actions
>
> Better names are welcome.  Most of what's in the current section would
> go into the new "Directives" subsection, which would have links to the
> other subsections in the appropriate places.  That will make them easy
> to find from the top section and also within the Directives subsection,
> while keeping those long lists from cluttering up the directives list.

Sounds like an excellent idea.  Since I've got enough on my plate
already, please do.

>> The changes pass make doc/gccint.info and make doc/gccint.dvi, so at
>> least syntactically they're ok.  There's a strange problem with
>> formatting of the dvi output, though: in the table of effective-target
>> keywords, sometimes (at irregular intervals and seemingly unrelated to
>> the input) there's extra spacing between lines.
>> 
>> Ok for mainline?
>
> Let me try rearranging things a bit more as described above.  First,
> though, I can check in your obvious fixes (with you as the author in
> the ChangeLog), unless you'd like to do that yourself.

Please go ahead.  Btw., I've forgotten about a couple of issues I found
when reading the printout, which may be useful to investigate:

* First of all, I forgot to check if the list of dg-* directives is
  complete.

* In `Directives used within DejaGnu tests', there should be some
  introductory line(s) before the listing of directives proper.

* It's not completely obvious how the directives are sorted.
  Alphabetically may not be the best option, though.  That problem will
  either be diminished or go away with your proposed reorganization,
  though.

I think that's it for the moment.

	Rainer

-- 
-----------------------------------------------------------------------------
Rainer Orth, Center for Biotechnology, Bielefeld University