Re: ping: unreviewed doc patch

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

On Thu, 20 Mar 2003, Janis Johnson wrote:
> Another ping for this unreviewed patch first submitted on 2003-02-17:
>
>   http://gcc.gnu.org/ml/gcc-patches/2003-02/msg01382.html

Doc-patches like this really have a hard time getting reviewed, probably
because the doc-maintainers wait for the experts, and the experts suppose
doc-maintainers will handle the patch.

> OK for mainline and 3.3-branch?  It's also relevant for the 3.2-branch.
>
> 2003-02-17  Janis Johnson  <janis187 at us dot ibm dot com>
>
>	* doc/sourcebuild.texi (Test Suites): Document testing support for
>	gcov and profile-directed optimizations; describe gcc.misc-tests.

Assuming that you are sufficiently confident in the technical details,
this is fine for mainline and 3.3, modulo some remarks below. I don't
think we need to bother putting it on 3.2.

Thanks!
Gerald

Index: doc/sourcebuild.texi
===================================================================
+ at item @code{bprob*.c}
+test @option{-fbranch-probabilities} using @file{bprob.exp}, which

Here and in the following, should this be "Test" instead of "test"?

+A line count command appears on the source line that is expected
+to get the specified count, and has the form @code{count(@var{cnt})}
+within a comment.  A test should only check line counts for lines
+that will get the same count for any architecture.

How about "A line count command appears within a comment on the..."?

+They need not be on the line where the percentage is reported;
+instead, a beginning command appears on a line before a range of

I believe I'd find "A beginning command appears on a line..." (that
is, without the first line) easier to understand here.

"on a line" -> "on the line"?

+A beginning command can include a list of percentages, all of which are
+expected to be found within the range.  A range is terminated by the
+next command of the same kind.

I'm afraid the first sentence confused me somewhat -- an example might
make this clearer?

+Not all branches and calls need be checked.  Don't check for

"need to be"?  "One should not check for..."

+A single test can check for combinations of line counts, branch
+percentages, and call return percentages.  The command to check
+a line count must appear on the line that will report that count,
+but commands to check branch percentages and call return percentages
+can bracket the lines that report them.

"...while commands...have to bracket"?

+The file @file{profopt.exp} provides language-independent support for
+checking correct execution of a test built with a profile-directed
+optimization.

"with a" -> "with"?

+To test that the optimization actually generated better code, a
+test can be built and run a third time with normal optimizations to

I recommend to avoid the repetitive use of "test" here.

+ at item prof_ext
+suffix of a profile data file

"the profile data file(s)"?

+list of options with which to run each test, similar to lists for
+torture tests

"...to those for torture tests" or "...to the lists for torture tests"?


(Oops, sorry for being so picky.  Please feel free to ignore comments
that appear ignorant. ;-) )