[DOCPATCH] Sections 16 and 17 (was Re: [Bug-gnupress] Sec 16 and 17 proofreading)

[Simon Law]

On Fri, Apr 25, 2003 at 02:24:24PM -0400, Dan Colascione wrote:
> Pretty good. Patch follows.

        Excellent.  Jim, two revisions on this patch.

Simon

> diff -ur doc/bugreport.texi doc-modified/bugreport.texi
> --- doc/bugreport.texi        2003-04-06 18:55:04.000000000 -0400
> +++ doc-modified/bugreport.texi       2003-04-25 13:24:41.000000000 -0400
> @@ -25,7 +25,7 @@
>  send you a patch and ask you to tell us whether it works.
>  
>  In order for a bug report to serve its purpose, you must include the
> -information that makes for fixing the bug.
> +information necessary to find and fix the bug.
>  
>  @menu
>  * Criteria:  Bug Criteria.   Have you really found a bug?
> @@ -64,8 +64,8 @@
>  If the compiler produces valid assembly code that does not correctly
>  execute the input source code, that is a compiler bug.
>  
> -However, you must double-check to make sure, because you may have a
> -program whose behavior is undefined, which happened by chance to give
> +However, you must double-check to make sure that this is the case. You may 
> have a
> +program whose behavior is undefined that by chance gives
>  the desired results with another C or C++ compiler.

-However, you must double-check to make sure, because you may have a
-program whose behavior is undefined, which happened by chance to give
+However, you must double-check to make sure that this is the case.  You
+may have a program whose behaviour is undefined that gives, by chance,

>  For example, in many nonoptimizing compilers, you can write @samp{x;}
> diff -ur doc/compat.texi doc-modified/compat.texi
> --- doc/compat.texi   2002-10-11 19:58:31.000000000 -0400
> +++ doc-modified/compat.texi  2003-04-25 12:26:58.000000000 -0400
> @@ -152,5 +152,5 @@
>  it is necessary to tell @command{g++} the location and name of that
>  library.  It might also be necessary to specify different startup files
>  and other runtime support libraries, and to suppress the use of GCC's
> -support libraries with one or more of the options @option{-nostdlib},
> +support libraries with one or more of the options: @option{-nostdlib},
>  @option{-nostartfiles}, and @option{-nodefaultlibs}.
> Only in doc-modified/: gcc.log
> diff -ur doc/gcov.texi doc-modified/gcov.texi
> --- doc/gcov.texi     2003-04-12 18:05:13.000000000 -0400
> +++ doc-modified/gcov.texi    2003-04-25 14:23:11.000000000 -0400
> @@ -77,7 +77,7 @@
>  @command{gcov} helps you determine where to work on optimization.
>  
>  Software developers also use coverage testing in concert with
> -testsuites, to make sure software is actually good enough for a release.
> +testsuites to make sure software is actually good enough for a release.
>  Testsuites can verify that a program works as expected; a coverage
>  program tests to see how much of the program is exercised by the
>  testsuite.  Developers can then determine what kinds of test cases need
> @@ -153,7 +153,7 @@
>  
>  @item -c
>  @itemx --branch-counts
> -Write branch frequencies as the number of branches taken, rather than
> +Write branch frequencies as the number of branches taken rather than
>  the percentage of branches taken.
>  
>  @item -n
> @@ -220,9 +220,9 @@
>  nearest non-boundary value.
>  
>  When using @command{gcov}, you must first compile your program with two
> -special GCC options: @samp{-fprofile-arcs -ftest-coverage}.
> -This tells the compiler to generate additional information needed by
> -gcov (basically a flow graph of the program) and also includes
> +special GCC options: @option{-fprofile-arcs} and @option{-ftest-coverage}.
> +These tell the compiler to generate additional information needed by
> +gcov (basically, a flow graph of the program) and also include

-gcov (basically a flow graph of the program) and also includes
address@hidden (basically, a flow graph of the program) and also include

>  additional code in the object files for generating the extra profiling
>  information needed by gcov.  These additional files are placed in the
>  directory where the object file is located.
> @@ -353,12 +353,12 @@
>  
>  If you plan to use @command{gcov} to help optimize your code, you must
>  first compile your program with two special GCC options:
> address@hidden -ftest-coverage}.  Aside from that, you can use any
> -other GCC options; but if you want to prove that every single line
> -in your program was executed, you should not compile with optimization
> -at the same time.  On some machines the optimizer can eliminate some
> -simple code lines by combining them with other lines.  For example, code
> -like this:
> address@hidden and @option{-ftest-coverage}. Aside from these,
> +you can use any other GCC options, but if you want to prove that every
> +single line in your program was executed, you should not compile with
> +optimization at the same time. On some machines, the optimizer can
> +eliminate some simple code lines by combining them with other lines. For
> +example, code like this:
>  
>  @smallexample
>  if (a != b)
> diff -ur doc/trouble.texi doc-modified/trouble.texi
> --- doc/trouble.texi  2003-01-24 10:52:58.000000000 -0500
> +++ doc-modified/trouble.texi 2003-04-25 13:16:52.000000000 -0400
> @@ -64,7 +64,7 @@
>  @section Cross-Compiler Problems
>  
>  You may run into problems with cross compilation on certain machines,
> -for several reasons.
> +for several reasons:
>  
>  @itemize @bullet
>  @item
> @@ -110,15 +110,15 @@
>  files generated by another C++ compiler.
>  
>  An area where the difference is most apparent is name mangling.  The use
> -of different name mangling is intentional, to protect you from more subtle
> +of different name mangling is intentional and is intended to protect you 
> from more subtle
>  problems.
>  Compilers differ as to many internal details of C++ implementation,
> -including: how class instances are laid out, how multiple inheritance is
> +including how class instances are laid out, how multiple inheritance is
>  implemented, and how virtual function calls are handled.  If the name
>  encoding were made the same, your programs would link against libraries
>  provided from other compilers---but the programs would then crash when
> -run.  Incompatible libraries are then detected at link time, rather than
> -at run time.
> +run.  With different name mangling, incompatible libraries are then
> +detected at link time, rather than at run time.
>  
>  @item
>  Older GDB versions sometimes fail to read the output of GCC version
> @@ -147,10 +147,10 @@
>  of the child process to clobber those of the parent.  Because of this,
>  programs that call @code{vfork} are likely to lose when compiled
>  optimized with GCC when the child code alters registers which contain
> -C variables in the parent.  This affects variables which are live in the
> +C variables in the parent.  This bug affects variables which are live in the
>  parent across the call to @code{vfork}.
>  
> -If you encounter this, you can work around the problem by declaring
> +If you encounter this bug, you can work around the problem by declaring
>  variables @code{volatile} in the function that calls @code{vfork}, until
>  the problem goes away, or by not declaring them @code{register} and not
>  using @option{-O} for those source files.
> @@ -258,7 +258,7 @@
>  the HP assembler.  GAS for the PA does not have this problem.
>  
>  @item
> -In extremely rare cases involving some very large functions you may
> +In extremely rare cases involving some very large functions, you may
>  receive errors from the HP linker complaining about an out of bounds
>  unconditional branch offset.  This used to occur more often in previous
>  versions of GCC, but is now exceptionally rare.  If you should run
> @@ -750,7 +750,7 @@
>  variable when it writes debugging information.
>  
>  You have to expect a certain amount of disagreement between the
> -executable and your source code, when you use optimization.
> +executable and your source code when you use optimization.
>  
>  @cindex conflicting types
>  @cindex scope of declaration
> @@ -1297,7 +1297,7 @@
>  Strictly speaking, there is no prohibition in the ISO C standard
>  against allowing structures with volatile fields in registers, but
>  it does not seem to make any sense and is probably not what you wanted
> -to do.  So the compiler will give an error message in this case.
> +to do.  The compiler will give an error message in this case.
>  
>  @item
>  Making certain warnings into errors by default.
> @@ -1341,9 +1341,9 @@
>  Warnings may indicate danger points where you should check to make sure
>  that your program really does what you intend; or the use of obsolete
>  features; or the use of nonstandard features of GNU C or C++.  Many
> -warnings are issued only if you ask for them, with one of the @option{-W}
> -options (for instance, @option{-Wall} requests a variety of useful
> -warnings).
> +warnings are issued only if you ask for them with one of the @option{-W}
> +options. (For instance, @option{-Wall} requests a variety of useful
> +warnings.)
>  
>  @opindex pedantic
>  @opindex pedantic-errors
> 
>