Re: [Bug-gnupress] Typos in Using GCC, pages 31-34

[Simon Law]

On Wed, Apr 23, 2003 at 04:49:45PM -0400, Lisa M. Opus Goldstein wrote:
> I spent a fair amount of time on just the first 4 pages of section 3
> and produced the following report.  Before I spend much more time on
> it, I want to make sure that I am doing it in a useful format.  Unless
> I use ellipses, I am copying the full line as it appears in the
> manuscript.
> 
> please feel free to send format suggestions before I do the next batch.

        This is fine, since a human will have to convert this to
Texinfo.  I have snipped all the portions with simple changes and
provide responses to all the others.  A patch is attached at the end of
this document.

Simon

> Section 3, pages 31-34.
> 
> pg. 31,  third bulleted item:
> I am not a C programmer, so I am not completely sure if this item is
> incorrect or not:
> 
> orig: template template parameters can be mangled incorrectly.
> 
> suggested fix: template parameters which can be used incorrectly.
> (Please check to make sure this makes sense in the programming context)

        There's missing typography here.  I have reworded.

> pg 31, last line of third bulleted item:
> 
> orig: Instantiations of these templates may be mangled incorrectly.
> 
> suggested fix:  ? (I have no idea what the first word is trying to mean.)

        This sentence appears correct, although the wording is awkward.

> pg. 31, Second to last sentence on page.
> 
> orig: Here the computer will warn ... of the members.
> 
> suggested fix: Uses the future-tense "will" twice, unlike other
> entries which are grounded in the present tense.
> 
> Also, confused by usage of second "will".  Who is doing the
> re-ordering?  The computer?  Will the compiler fix the problem for the
> programmer?  Or will he need to physically change the code himself?
> Very unclear who the actor is.  If programmer, maybe use "must be
> rearranged" to show the person needs to take action.

        The compiler handles this automatically.

> pg. 33, definition for -Wno-pmf-conversions
> 
> Symmetry problem... lists three nouns, only puts "a" before two of
> them.  So, "to member function" should become "to a member function"

        This is jargon, "point to member function" is a valid term, so I
have reworded the sentence.

> pg 33, Section 3.6, 7th English line. (start of third  English section)
> 
> Formatting/Spacing problem.  This is the start of a new
> paragraph/section?  Should be more space between the 6th line
> beginning "grams; you can use..." and the indented 7th line beginning
> with "Here is a list of options..."

        I am unhappy about this, but think it is acceptable.

> pg 34, -Wno-protocol definition, 4th line down
> 
> orig: plicitly implemented in the class , even if a method implementation
> 
> The article "a" in "a method implementation" seems strange.  Is this
> correct?  Should it be "an implementation method"?

        In this phrase, "implementation" is in the nominative case, not
the genitive.


2003-04-23  Lisa M. Opus Goldstein  <address@hidden>

        * doc/invoke.texi: Fixes to style, grammar and diction.

--- invoke.texi.orig    2003-04-23 22:07:13.000000000 -0400
+++ invoke.texi 2003-04-23 23:02:11.000000000 -0400
@@ -1558,8 +1558,8 @@
 @code{A} data member of @code{B} is already at offset zero.
 
 @item
-Names of template functions whose types involve @code{typename} or
-template template parameters can be mangled incorrectly.
+Template functions whose template parameters involve @code{typename} or
address@hidden may have their names mangled incorrectly.
 
 @smallexample
 template <typename Q>
@@ -1576,14 +1576,14 @@
 
 @item -Wctor-dtor-privacy @r{(C++ only)}
 @opindex Wctor-dtor-privacy
-Warn when a class seems unusable, because all the constructors or
-destructors in a class are private and the class has no friends or
+Warn when a class seems unusable because all the constructors or
+destructors in that class are private, and it has neither friends nor
 public static member functions.  This warning is enabled by default.
 
 @item -Wnon-virtual-dtor @r{(C++ only)}
 @opindex Wnon-virtual-dtor
-Warn when a class declares a non-virtual destructor that should probably
-be virtual, because it looks like the class will be used polymorphically.
+Warn when a class appears to be polymorphic, thereby requiring a virtual
+destructor, yet it declares a non-virtual one.
 This warning is enabled by @option{-Wall}.
 
 @item -Wreorder @r{(C++ only)}
@@ -1601,9 +1601,9 @@
 @};
 @end smallexample
 
-Here the compiler will warn that the member initializers for @samp{i}
-and @samp{j} will be rearranged to match the declaration order of the
-members.  This warning is enabled by @option{-Wall}.
+The compiler will rearrange the member initializers for @samp{i}
+and @samp{j} to match the declaration order of the members, emitting
+a warning to that effect.  This warning is enabled by @option{-Wall}.
 @end table
 
 The following @address@hidden options are not affected by @option{-Wall}.
@@ -1633,8 +1633,8 @@
 
 @end itemize
 
-and about violations of the following style guidelines from Scott Meyers'
address@hidden Effective C++} book:
+Also warn about violations of the following style guidelines from 
+Scott Meyers' @cite{More Effective C++} book:
 
 @itemize @bullet
 @item
@@ -1646,8 +1646,8 @@
 
 @end itemize
 
-If you use this option, you should be aware that the standard library
-headers do not obey all of these guidelines; you can use @samp{grep -v}
+When selecting this option, be aware that the standard library
+headers do not obey all of these guidelines; use @samp{grep -v}
 to filter out those warnings.
 
 @item -Wno-deprecated @r{(C++ only)}
@@ -1657,7 +1657,7 @@
 @item -Wno-non-template-friend @r{(C++ only)}
 @opindex Wno-non-template-friend
 Disable warnings when non-templatized friend functions are declared
-within a template.  With the advent of explicit template specification
+within a template.  Since the advent of explicit template specification
 support in G++, if the name of the friend is an unqualified-id (i.e.,
 @samp{friend foo(int)}), the C++ language specification demands that the
 friend declare or define an ordinary, nontemplate function.  (Section
@@ -1665,7 +1665,7 @@
 could be interpreted as a particular specialization of a templatized
 function.  Because this non-conforming behavior is no longer the default
 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
-check existing code for potential trouble spots, and is on by default.
+check existing code for potential trouble spots and is on by default.
 This new compiler behavior can be turned off with
 @option{-Wno-non-template-friend} which keeps the conformant compiler code
 but disables the helpful warning.
@@ -1675,7 +1675,7 @@
 Warn if an old-style (C-style) cast to a non-void type is used within
 a C++ program.  The new-style casts (@samp{static_cast},
 @samp{reinterpret_cast}, and @samp{const_cast}) are less vulnerable to
-unintended effects, and much easier to grep for.
+unintended effects and much easier to search for.
 
 @item -Woverloaded-virtual @r{(C++ only)}
 @opindex Woverloaded-virtual
@@ -1695,7 +1695,7 @@
 @end smallexample
 
 the @code{A} class version of @code{f} is hidden in @code{B}, and code
-like this:
+like:
 
 @smallexample
 B* b;
@@ -1706,13 +1706,13 @@
 
 @item -Wno-pmf-conversions @r{(C++ only)}
 @opindex Wno-pmf-conversions
-Disable the diagnostic for converting a bound pointer to member function
-to a plain pointer.
+Disable the diagnostic for a bound pointer to member function
+that is converted into a plain pointer.
 
 @item -Wsign-promo @r{(C++ only)}
 @opindex Wsign-promo
 Warn when overload resolution chooses a promotion from unsigned or
-enumeral type to a signed type over a conversion to an unsigned type of
+enumeral type to a signed type, over a conversion to an unsigned type of
 the same size.  Previous versions of G++ would try to preserve
 unsignedness, but the standard mandates the current behavior.
 
@@ -1747,7 +1747,7 @@
 @cindex Objective-C options, command line
 @cindex options, Objective-C
 This section describes the command-line options that are only meaningful
-for Objective-C programs; but you can also use most of the GNU compiler
+for Objective-C programs, but you can also use most of the GNU compiler
 options regardless of what language your program is in.  For example,
 you might compile a file @code{some_class.m} like this:
 
@@ -1756,7 +1756,7 @@
 @end example
 
 @noindent
-In this example, only @option{-fgnu-runtime} is an option meant only for
+In this example, @option{-fgnu-runtime} is an option meant only for
 Objective-C programs; you can use the other options with any language
 supported by address@hidden
 
@@ -1802,25 +1802,25 @@
 Warn if multiple methods of different types for the same selector are
 found during compilation.  The check is performed on the list of methods
 in the final stage of compilation.  Additionally, a check is performed
-that for each selector appearing in a @code{@@selector(@dots{})}
-expression, a corresponding method with that selector has been found
+for each selector appearing in a @code{@@selector(@dots{})}
+expression, and a corresponding method for that selector has been found
 during compilation.  Because these checks scan the method table only at
 the end of compilation, these warnings are not produced if the final
-stage of compilation is not reached, for example because an error is
-found during compilation, or because the @code{-fsyntax-only} option is
+stage of compilation is not reached (i.e., an error is
+found during compilation) or because the @code{-fsyntax-only} option is
 being used.
 
 @item -Wundeclared-selector
 @opindex Wundeclared-selector
 Warn if a @code{@@selector(@dots{})} expression referring to an
 undeclared selector is found.  A selector is considered undeclared if no
-method with that name has been declared (explicitly, in an
address@hidden@@interface} or @code{@@protocol} declaration, or implicitly, in
-an @code{@@implementation} section) before the
address@hidden@@selector(@dots{})} expression.  This option always performs its
-checks as soon as a @code{@@selector(@dots{})} expression is found
-(while @code{-Wselector} only performs its checks in the final stage of
-compilation), and so additionally enforces the coding style convention
+method with that name has been declared before the 
address@hidden@@selector(@dots{})} expression, either explicitly in an
address@hidden@@interface} or @code{@@protocol} declaration, or implicitly in
+an @code{@@implementation} section.  This option always performs its
+checks as soon as a @code{@@selector(@dots{})} expression is found,
+while @code{-Wselector} only performs its checks in the final stage of
+compilation.  This also enforces the coding style convention
 that methods and selectors must be declared before being used.
 
 @c not documented because only avail via -Wp
@@ -1839,8 +1839,8 @@
 below can be used to control the diagnostic messages formatting
 algorithm, e.g.@: how many characters per line, how often source location
 information should be reported.  Right now, only the C++ front end can
-honor these options.  However it is expected, in the near future, that
-the remaining front ends would be able to digest them correctly.
+honor these options.  However, it is expected in the near future that
+the remaining front ends will be able to digest them correctly.
 
 @table @gcctabopt
 @item address@hidden