Re: [DOC PATCH] sourcebuild.texi, describe binary compatibilitytesting

[Gerald Pfeifer <pfeifer at dbai dot tuwien dot ac dot at>]

On Wed, 9 Apr 2003, Janis Johnson wrote:
>> wrote this support, so I doubt that anyone else will review it for
>> technical content.  I would greatly appreciate a review from a
>> documentation maintainer.

Sorry for the delay, here are some random comments of mine (some of
which I hope to be useful):

  2003-04-09  Janis Johnson  <janis187 at us dot ibm dot com>

	* doc/sourcebuild.texi (Test Suites): Document support for testing
	binary compatibility.

  2003-04-09  Janis Johnson  <janis187 at us dot ibm dot com>

	* README.compat: Delete.

Could we "link" these two ChangeLogs, so that (for someone investigating
in the future) it becomes more clear that README.compat wasn't just
removed but migrated?

Index: doc/sourcebuild.texi
===================================================================
+The file @file{compat.exp} provides language-independent support for
+binary compatibility testing.  It supports testing interoperability
+of two compilers that follow the same ABI, or of multiple sets of
+compiler options that are not intended to affect binary compatibility.
+It is intended to be used for test suites that complement ABI test
+suites.

"are not intended" -> "should not"?  (I found this a bit clearer, and
it also avoid the repetitive use of "intended".)

+A test supported by this framework is split into three parts, each in
+a separate source file: a main program and two pieces that split up
+the functionality being tested.

The second instance of "split (up" I found a bit unclear, but I don't
have a good suggestion, either. :-(

+ @item @var{testname}_main dot  at var{suffix}
+contains the main program, which calls a function in file

Should there be a full stop at the end? (Also in the other cases, but I'm
not sure what's proper use in English here.)

+Within each test, the main program and
+one funtional piece are compiled by the GCC under test.
       ^^^
Typo.

+The other
+piece can be compiled by an alternate compiler.  If no alternate
+compiler is specified, then they are all compiled by the GCC under
+test.

"They" is a bit undetermined here; at least I stumbled over it while
reading the patch. ;-)

+ the environment variable @code{COMPAT_OPTIONS} as:

I believe this should be @env{COMPAT_OPTIONS}.

+COMPAT_OPTIONS="[list [list @{ at var{tst1} at } @{ at var{alt1} at }]
+  ...[list @{ at var{tstn} at } @{ at var{altn} at }]]"

A verbose explanation of this example might help avoid any possible
misinterpretations.

+To run only the C++ compatibility suite using the compiler under test
+and another version of GCC, using non-default pairs of compiler options
+lists, do the following from @file{$ at {objdir@}/gcc}:

"using...lists" is a bit hard to parse, though I had no problems actually
understanding it.  Should objdir be @var{objdir}?

+A test that fails when the pieces are compiled with different

"its pieces" or "its parts"?

+A test that fails for the alternate compiler but
+passes for the compiler under test probably tests for a fix that
+is not present in the alternate compiler.

"...tests for a bug that was fixed in the compiler under test but may
be present in the alternate compiler"?


(As usual, feel free to consider these comments as you see fit, and just
ignore those that make no sense. <g>)

Gerald
-- 
Gerald "Jerry"   pfeifer at dbai dot tuwien dot ac dot at   http://www.pfeifer.com/gerald/