diff mbox

[wwwdocs] Nits in gcc-4.6/changes.html

Message ID ydd8vy06ha9.fsf@manam.CeBiTec.Uni-Bielefeld.DE
State New
Headers show

Commit Message

Rainer Orth Jan. 31, 2011, 6:48 p.m. UTC 
I've read all of the GCC 4.6 changes.html over the weekend and found a
couple of issues (mostly nits).  The ones I consider obvious are
included in the patch below (though I'm not a native speeker and may
simply be mistaken), but there are a couple of others:

* Fortran, Fortran 2008 support has been extended:, Minor changes:

  Perhaps use <ul></ul>?

* Go:

  List supported targets.  GNU/Linux, Solaris is in the works (mostly
  done), *BSD?

* Objective-C and Objective-C++:

  Most features are available in both languages.  Rather than stating
  this over and over again, which makes the text repetetive and boring,
  state it once up-front and only point out exceptions?

* picochip:

  Remove, or will this be filled?

* S/390, ...:

  ... make use of the following instruction facilities:

  Too many hyphens in the following list?

Feel free to adapt and check in.

Thanks.
	Rainer

Comments

Gerald Pfeifer Feb. 2, 2011, 10:19 p.m. UTC | #1 
On Mon, 31 Jan 2011, Rainer Orth wrote:
> I've read all of the GCC 4.6 changes.html over the weekend and found a 
> couple of issues (mostly nits).  The ones I consider obvious are 
> included in the patch below (though I'm not a native speeker and may 
> simply be mistaken), but there are a couple of others:
> 
> * Fortran, Fortran 2008 support has been extended:, Minor changes:
> 
>   Perhaps use <ul></ul>?

I'm not sure what you have in mind here?  Looking at the document
there already is an <ul>, perhaps you can suggest a patch?

> * Go:
> 
>   List supported targets.  GNU/Linux, Solaris is in the works (mostly
>   done), *BSD?

I believe that sounds useful.  Ian, what do you think?

> * Objective-C and Objective-C++:
> 
>   Most features are available in both languages.  Rather than stating
>   this over and over again, which makes the text repetetive and boring,
>   state it once up-front and only point out exceptions?

Nicola, what do you think?

> * picochip:
> 
>   Remove, or will this be filled?

Remove if it remains empty, though let's ping Hariharan -- any changes
you're planning to document?

> * S/390, ...:
> 
>   ... make use of the following instruction facilities:
> 
>   Too many hyphens in the following list?

Andreas?  This looks a bit strange, but I know that s390 terminology
always tends to be a bit different. :-)

Gerald
Hariharan Sandanagobalane Feb. 3, 2011, 9:02 a.m. UTC | #2 
On 02/02/11 22:19, Gerald Pfeifer wrote:
> On Mon, 31 Jan 2011, Rainer Orth wrote:
>> I've read all of the GCC 4.6 changes.html over the weekend and found a
>> couple of issues (mostly nits).  The ones I consider obvious are
>> included in the patch below (though I'm not a native speeker and may
>> simply be mistaken), but there are a couple of others:
>>
>> * Fortran, Fortran 2008 support has been extended:, Minor changes:
>>
>>    Perhaps use<ul></ul>?
>
> I'm not sure what you have in mind here?  Looking at the document
> there already is an<ul>, perhaps you can suggest a patch?
>
>> * Go:
>>
>>    List supported targets.  GNU/Linux, Solaris is in the works (mostly
>>    done), *BSD?
>
> I believe that sounds useful.  Ian, what do you think?
>
>> * Objective-C and Objective-C++:
>>
>>    Most features are available in both languages.  Rather than stating
>>    this over and over again, which makes the text repetetive and boring,
>>    state it once up-front and only point out exceptions?
>
> Nicola, what do you think?
>
>> * picochip:
>>
>>    Remove, or will this be filled?
>
> Remove if it remains empty, though let's ping Hariharan -- any changes
> you're planning to document?

There are no major changes to the port. Please remove picochip from the 
changes documentation.

Thanks
Hari

>
>> * S/390, ...:
>>
>>    ... make use of the following instruction facilities:
>>
>>    Too many hyphens in the following list?
>
> Andreas?  This looks a bit strange, but I know that s390 terminology
> always tends to be a bit different. :-)
>
> Gerald
>
Rainer Orth Feb. 3, 2011, 10:15 a.m. UTC | #3 
Gerald Pfeifer <gerald@pfeifer.com> writes:

>> * Fortran, Fortran 2008 support has been extended:, Minor changes:
>> 
>>   Perhaps use <ul></ul>?
>
> I'm not sure what you have in mind here?  Looking at the document
> there already is an <ul>, perhaps you can suggest a patch?

I meant to use <ul></ul> for the individual items under the Minor
changes heading, rather than using a long sentence.  I found the current
version hard to read, and since it's effectively a list, why not just
make it one?

	Rainer
Andreas Krebbel Feb. 3, 2011, 2:35 p.m. UTC | #4 
>> * S/390, ...:
>>
>>   ... make use of the following instruction facilities:
>>
>>   Too many hyphens in the following list?
> 
> Andreas?  This looks a bit strange, but I know that s390 terminology
> always tends to be a bit different. :-)

Indeed these are the facility names as they come from the S/390 documentation:
http://publibfi.boulder.ibm.com/epubs/pdf/dz9zs006.pdf

But they certainly can be removed if you prefer. I don't have a strong opinion about that.

-Andreas-
Iain Sandoe Feb. 3, 2011, 8:11 p.m. UTC | #5 
On 2 Feb 2011, at 22:19, Gerald Pfeifer wrote:

> On Mon, 31 Jan 2011, Rainer Orth wrote:
>
>> * Objective-C and Objective-C++:
>>
>>  Most features are available in both languages.  Rather than stating
>>  this over and over again, which makes the text repetetive and  
>> boring,
>>  state it once up-front and only point out exceptions?
>
> Nicola, what do you think?

my £0.02

maybe :

"except as noted, the following changes apply to both Objective-C and  
Objective-C++"

and then remove  "in Objective-C and Objective-C++" from each entry  
(leaving fast enumeration as is).

Nicola?

Iain
Nicola Pero Feb. 3, 2011, 8:20 p.m. UTC | #6 
>> * Objective-C and Objective-C++:
>> 
>>   Most features are available in both languages.  Rather than stating
>>   this over and over again, which makes the text repetetive and boring,
>>   state it once up-front and only point out exceptions?
>
> Nicola, what do you think?

Sure, sounds great.

Thanks
Iain Sandoe Feb. 3, 2011, 8:26 p.m. UTC | #7 
On 3 Feb 2011, at 20:20, Nicola Pero wrote:

>
>>> * Objective-C and Objective-C++:
>>>
>>>  Most features are available in both languages.  Rather than stating
>>>  this over and over again, which makes the text repetetive and  
>>> boring,
>>>  state it once up-front and only point out exceptions?
>>
>> Nicola, what do you think?
>
> Sure, sounds great.

for the last two entries one could use "Objective-C family" or  
Objective-C* (if the latter is allowable in GCC docs.)
comments?

Iain
Nicola Pero Feb. 3, 2011, 10:21 p.m. UTC | #8 
>>> * Objective-C and Objective-C++:
>>>
>>>  Most features are available in both languages.  Rather than stating
>>>  this over and over again, which makes the text repetetive and  
>>> boring,
>>>  state it once up-front and only point out exceptions?
>>
>> Nicola, what do you think?
>
> Sure, sounds great.

To clarify, I (personally) would simply replace all the statements

> The Objective-C 2.0 dot-syntax is now supported both in Objective-C
> and Objective-C++.

with the shorter, more readable and less boring --

> The Objective-C 2.0 dot-syntax is now supported.

It's obvious that it applies to both Objective-C and Objective-C++,
because the section is entitled "Objective-C and Objective-C++" ;-)

(the only exception is fast enumeration, which is not implemented
in Objective-C++, and where we could leave the text as it is)

I don't mind other solutions though.  Feel free to make it more readable.


> for the last two entries one could use "Objective-C family" or  
> Objective-C* (if the latter is allowable in GCC docs.)
> comments?

But I would argue against using "Objective-C*" because I find it
unusual and cryptic.  The confused reader won't find it explained
in Wikipedia either.  I'd actually suggest we avoid it in comments
and documentation as a matter of policy.  If not, we should have it
clearly explained somewhere easy to find. ;-)

Thanks
Iain Sandoe Feb. 3, 2011, 11:46 p.m. UTC | #9 
<trimmed cc list>

On 3 Feb 2011, at 22:21, Nicola Pero wrote:

>
> It's obvious that it applies to both Objective-C and Objective-C++,
> because the section is entitled "Objective-C and Objective-C++" ;-)

agreed .. one could just write GCC or 'the compiler' as appropriate,

>> for the last two entries one could use "Objective-C family" or
>> Objective-C* (if the latter is allowable in GCC docs.)
>> comments?
>
> But I would argue against using "Objective-C*" because I find it
> unusual and cryptic.  The confused reader won't find it explained
> in Wikipedia either.

I admit it took a couple of passes through before it became obvious  
what it meant.

> I'd actually suggest we avoid it in comments
> and documentation as a matter of policy.

Where we have it in comments is (mainly, if not solely) import from  
apple-local stuff.
It does have the advantage of being compact  - and perhaps I have also  
used it for the sake of consistency.

However,  I'm OK either way (changing comments or leaving them as is)  
- since the imports from FSF apple local will be almost completely  
exhausted by the m64 stuff.

>  If not, we should have it
> clearly explained somewhere easy to find. ;-)

we could always document it -- it would only take one sentence ;-)

cheers
Iain
Gerald Pfeifer Feb. 5, 2011, 12:52 a.m. UTC | #10 
On Thu, 3 Feb 2011, Andreas Krebbel wrote:
>> Andreas?  This looks a bit strange, but I know that s390 terminology
>> always tends to be a bit different. :-)
> Indeed these are the facility names as they come from the S/390 
> documentation: http://publibfi.boulder.ibm.com/epubs/pdf/dz9zs006.pdf
> 
> But they certainly can be removed if you prefer. I don't have a strong 
> opinion about that.

If these are the official names, let's definitely keep them.

Gerald
Gerald Pfeifer Feb. 27, 2011, 11:58 p.m. UTC | #11 
Hi Rainer,

On Mon, 31 Jan 2011, Rainer Orth wrote:
> I've read all of the GCC 4.6 changes.html over the weekend and found a
> couple of issues (mostly nits).  The ones I consider obvious are
> included in the patch below (though I'm not a native speeker and may
> simply be mistaken), but there are a couple of others:

I realized that based on your input a number of changes were made,
but we never took care of your own patch.  Ooops.  I had a look at
this one, too, and it looks good.  Please go ahead and apply it.

> -    <li>Optimization for Intel Core 2 processor is now available through
> +    <li>Optimization for the Intel Core 2 processor is now available through

This change is correct, I am just wondering whether saying "Intel
Core 2 processors" might be better, since there is not just one such
beast, but it's a family.

Gerald
Rainer Orth March 11, 2011, 3:33 p.m. UTC | #12 
Hi Gerald,

> On Mon, 31 Jan 2011, Rainer Orth wrote:
>> I've read all of the GCC 4.6 changes.html over the weekend and found a
>> couple of issues (mostly nits).  The ones I consider obvious are
>> included in the patch below (though I'm not a native speeker and may
>> simply be mistaken), but there are a couple of others:
>
> I realized that based on your input a number of changes were made,
> but we never took care of your own patch.  Ooops.  I had a look at
> this one, too, and it looks good.  Please go ahead and apply it.

I missed that myself, thanks for noticing.

>> -    <li>Optimization for Intel Core 2 processor is now available through
>> +    <li>Optimization for the Intel Core 2 processor is now available through
>
> This change is correct, I am just wondering whether saying "Intel
> Core 2 processors" might be better, since there is not just one such
> beast, but it's a family.

I wen't for `the Intel Core 2 processors', and finally checked in the
patch.

Thanks.
	Rainer
diff mbox

Patch

Index: htdocs/gcc-4.6/changes.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/gcc-4.6/changes.html,v
retrieving revision 1.101
diff -u -p -r1.101 changes.html
--- htdocs/gcc-4.6/changes.html	29 Jan 2011 10:43:23 -0000	1.101
+++ htdocs/gcc-4.6/changes.html	31 Jan 2011 18:36:49 -0000
@@ -39,9 +39,9 @@ 
     in <a href="../gcc-4.5/changes.html">GCC 4.5.0</a>.</li>
 
     <li id="libquadmath">GCC now ships with the LGPL-licensed
-    <code>libquadmath</code> library, which provides for targets with
-    a <code>__float128</code> datatype quad-precision mathematical
-    functions. <code>__float128</code> is available for targets on
+    <code>libquadmath</code> library, which provides quad-precision
+    mathematical functions for targets with a <code>__float128</code>
+    datatype. <code>__float128</code> is available for targets on
     32-bit x86, x86-64 and Itanium architectures. The
     <code>libquadmath</code> library is automatically built on
     such targets when building the Fortran compiler.</li>
@@ -51,10 +51,10 @@ 
 <h2>General Optimizer Improvements</h2>
 
   <ul>
-    <li>A new general optimization level, <code>-Ofast</code> has been
+    <li>A new general optimization level, <code>-Ofast</code>, has been
       introduced.  It combines the existing optimization level <code>-O3</code>
       with options that can affect standards compliance but result in
-      better optimized code.  For example <code>-Ofast</code> enables
+      better optimized code.  For example, <code>-Ofast</code> enables
       <code>-ffast-math</code>.</li>
       <li>Link-time optimization improvements:
       <ul>
@@ -73,21 +73,22 @@ 
 	   <code>-flto-partition=none</code>. This may result in small code
 	   quality improvements.</li>
         <li>A large number of bugs were fixed.  GCC itself, Mozilla
-           Firefox and other other large applications can be built with
+           Firefox and other large applications can be built with
            LTO enabled.</li>
 	<li>The linker plugin support improvements
 	<ul>
 	   <li>Linker plugin is now enabled by default when the linker is
 	   detected to have plugin support.  This is the case for GNU
 	   ld 2.21.51 or newer (on ELF and Cygwin targets) and the Gold
-	   linker on ELF targets.  Plugin support of the Apple linker at
+	   linker on ELF targets.  Plugin support of the Apple linker on
 	   Darwin is not compatible with GCC.
 	   The linker plugin can also be controlled by the
 	   <code>-fuse-linker-plugin</code> command line option.</li>
 	   <li>Resolution information from the linker plugin is used to drive
            whole program assumptions. Use of the linker plugin results in
            more aggressive optimization on binaries and on shared libraries
-           that use the hidden visibility attribute. Consequently the use
+	   that use the <code>hidden</code> visibility
+	   attribute. Consequently the use
 	   of <code>-fwhole-program</code> is not neccesary in addition to
            LTO.</li>
 	</ul>
@@ -99,7 +100,7 @@ 
            aggressively, leading to better inter-procedural optimization
            and faster dynamic linking.</li>
         <li>Memory usage and intermediate language streaming performance
-           has been improved.</li>
+           have been improved.</li>
         <li>Static constructors and destructors from individual units are
            inlined into a single function.
            This can significantly improve startup times of large C++
@@ -111,7 +112,7 @@ 
       <li>Interprocedural optimization improvements
       <ul>
 	  <li>The interprocedural framework was re-tuned for link time
-	      optimization. Several scalability issues were solved.</li>
+	      optimization. Several scalability issues were resolved.</li>
 	  <li>Improved auto-detection of <code>const</code> and <code>pure</code>
 	      functions.  Newly, <code>noreturn</code> functions are auto-detected.
 	      <p>The <a href="http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#Warning-Options"><code>-Wsuggest-attribute=[const|pure|noreturn]</code></a>
@@ -133,8 +134,9 @@ 
 		 <li>Scalability for large compilation units was improved
 		     significantly.</li>
 		 <li>Inlining of callbacks is now more aggressive.</li>
-		 <li>Virtual methods considered for inlining when caller is
-		     inlined and devirtualization is possible then.</li>
+		 <li>Virtual methods are considered for inlining when the
+		     caller is
+		     inlined and devirtualization is then possible.</li>
                  <li>Inlining when optimizing for size (either in cold
                     regions of a program or when compiling with
                     <code>-Os</code>) was improved to better handle C++
@@ -187,7 +189,7 @@ 
       <li>Datastructures used by the dataflow framework in GCC were reorganized
 	  for better memory usage and more cache locality.  Compile
 	  time is improved especially on units with large functions (possibly
-	  resulting from a lot of inlining) not fitting in processor cache.
+	  resulting from a lot of inlining) not fitting into the processor cache.
 	  The compile time of the GCC C compiler binary with link-time
 	  optimization went down by over 10% (benchmarked on x86-64 target).</li>
   </ul>
@@ -215,7 +217,7 @@ 
       calls to functions that return to the current unit only via returning
       or exception handling.  This is the case for most library functions
       that have no callbacks.</li>
-    <li>Support for new data type <code>__int128</code> for targets having
+    <li>Support for a new data type <code>__int128</code> for targets having
     wide enough machine-mode support.</li>
     <li>The new function attribute <code>callee_pop_aggregate</code> allows
     to specify if the caller or callee is responsible for popping the
@@ -360,12 +362,12 @@ 
     warnings where a conversion leads to information loss.  This drastically
     reduces the number of warnings; <code>-Wconversion</code> is thus now
     enabled with <code>-Wall</code>. The flag <code>-Wconversion-extra</code>
-    has been added and warns also about other conversions;
+    has been added and also warns about other conversions;
     <code>-Wconversion-extra</code> typically issues a huge number of
     warnings, most of which can be ignored.</li>
     <li>A new command-line option <code>-Wunused-dummy-argument</code> warns
 	about unused dummy arguments and is included in <code>-Wall</code>.
-	Before <code>-Wunused-variable</code> also warned about unused dummy
+	Before, <code>-Wunused-variable</code> also warned about unused dummy
 	arguments.</li>
     <li>Fortran 2003 support has been extended:
       <ul>
@@ -406,7 +408,7 @@ 
 	<li>Support of the <code>NORM2</code> and <code>PARITY</code>
 	intrinsic functions.</li>
 	<li>The following bit intrinsics were added: <code>POPCNT</code>
-	and <code>POPPAR</code> for counting the number of one bits and
+	and <code>POPPAR</code> for counting the number of 1 bits and
 	returning the parity; <code>BGE</code>, <code>BGT</code>,
 	<code>BLE</code>, and <code>BLT</code> for bitwise comparisons;
 	<code>DSHIFTL</code> and <code>DSHIFTR</code> for combined left
@@ -431,7 +433,7 @@ 
 	<li>Pointers including procedure pointers and those in a derived
 	type (pointer components) can now be initialized by a target
 	instead of only by <code>NULL</code>.</li>
-	<li>The <code>EXIT</code> statement (with construct-name) can be
+	<li>The <code>EXIT</code> statement (with construct-name) can
 	now be used to leave not only the <code>DO</code> but also the
 	<code>ASSOCIATE</code>, <code>BLOCK</code>, <code>IF</code>,
 	<code>SELECT CASE</code> and <code>SELECT TYPE</code> constructs.</li>
@@ -445,7 +447,7 @@ 
 	module <code>ISO_C_BINDINGS</code> and <code>COMPILER_VERSION</code>
 	and <code>COMPILER_OPTIONS</code> of <code>ISO_FORTRAN_ENV</code>
 	have been implemented.</li>
-	<li>Minor changes: obsolesce diagnostics for <code>ENTRY</code>
+	<li>Minor changes: obsolescence diagnostics for <code>ENTRY</code>
 	was added for <code>-std=f2008</code>;
 	a line may start with a semicolon;
 	for internal and module procedures <code>END</code> can be used
@@ -566,10 +568,10 @@  Support for the <a href="http://golang.o
     <li>As a result of these enhancements, GCC can now be used to
     build Objective-C and Objective-C++ software that uses Foundation
     and other important system frameworks with the NeXT runtime on
-    Darwin 9 and Darwin 10 (OSX 10.5 and 10.6).  Currently this is for
+    Darwin 9 and Darwin 10 (Mac OS X 10.5 and 10.6).  Currently this is for
     m32 code only.</li>
 
-    <li>Many bugs in the Objective-C and Objective-C++ compiler have
+    <li>Many bugs in the Objective-C and Objective-C++ compilers have
     been fixed in this release; in particular, LTO can now be used
     when compiling Objective-C and Objective-C++ and the Objective-C
     and Objective-C++ parsers are much more robust in dealing with
@@ -582,7 +584,7 @@  Support for the <a href="http://golang.o
     <li>The GNU Objective-C runtime library now defines the macro
     <code>__GNU_LIBOBJC__</code> (with a value that is increased at
     every release where there is any change to the API) in
-    <code>objc/objc.h</code> making it easy to determine if the GNU
+    <code>objc/objc.h</code>, making it easy to determine if the GNU
     Objective-C runtime library is being used, and if so, which
     version.  Previous versions of the GNU Objective-C runtime library
     (and other Objective-C runtime libraries such as the Apple one) do
@@ -606,14 +608,13 @@  Support for the <a href="http://golang.o
     older versions of the GNU Objective-C runtime library, which do
     not support the new API, do not define such a macro.</li>
 
-    <li>Runtime support for <code>@synchronized</code> has been added
-    to the runtime.</li>
+    <li>Runtime support for <code>@synchronized</code> has been added.</li>
 
     <li>Runtime support for Objective-C 2.0 synthesized property
-    accessors has been added to the runtime.</li>
+    accessors has been added.</li>
 
     <li>Runtime support for Objective-C 2.0 fast enumeration has been
-    added to the runtime.</li>
+    added.</li>
   </ul>
 
 <h2 id="targets">New Targets and Target Specific Improvements</h2>
@@ -670,7 +671,7 @@  Support for the <a href="http://golang.o
 	<li>Support for emitting profiler counter calls before function
 	prologues.  This is enabled via a new command-line option
 	<code>-mfentry</code>.</li>
-    <li>Optimization for Intel Core 2 processor is now available through
+    <li>Optimization for the Intel Core 2 processor is now available through
 	the <code>-march=core2</code> and <code>-mtune=core2</code>
 	options.</li>
     <li>Support for Intel Core i3/i5/i7 processors is now available through
@@ -687,12 +688,12 @@  Support for the <a href="http://golang.o
       <code>-fomit-frame-pointer</code>.  The default can be reverted
       to <code>-fno-omit-frame-pointer</code> by configuring GCC with
       the <code>--enable-frame-pointer</code> configure option.</li>
-    <li>Darwin, FreeBSD, MinGW and Cygwin now all support
+    <li>Darwin, FreeBSD, Solaris 2, MinGW and Cygwin now all support
       <code>__float128</code> on 32-bit x86 targets.</li>
     <li>AVX floating-point arithmetic can now be enabled by default at
       configure time with the new <code>--with-fpmath=avx</code> option.</li>
     <li>The SSA loop prefetching pass is enabled when
-      using <code>-O3</code> when optimizing for CPUs with where prefetching
+      using <code>-O3</code> when optimizing for CPUs where prefetching
       is beneficial (AMD CPUs newer than K6).</li>
     <li>Support for TBM (Trailing Bit Manipulation) built-in functions
       and code generation is available via <code>-mtbm</code>.</li>
@@ -702,9 +703,12 @@  Support for the <a href="http://golang.o
 
 <h3 id="microblaze">MicroBlaze</h3>
 
-<p>Support has been added for the Xilinx MicroBlaze softcore Processor
-(microblaze-elf) embedded target.  This configurable processor is
-supported on several Xilinx Spartan and Virtex FPGAs. </p>
+  <ul>
+    <li>Support has been added for the Xilinx MicroBlaze softcore processor
+     (microblaze-elf) embedded target.  This configurable processor is
+     supported on several Xilinx Spartan and Virtex FPGAs.
+    </li>
+  </ul>
 
 <h3>MIPS</h3>
   <ul>
@@ -784,9 +788,9 @@  supported on several Xilinx Spartan and 
       instruction scheduling appropriate for the new out-of-order
       pipeline architecture.</li>
     <li>When using the <code>-m31 -mzarch</code> options the generated
-      code still conforms to the 32 bit ABI but uses the general
-      purpose registers as 64 bit registers internally.  This
-      requires a Linux kernel saving the whole 64 bit registers when
+      code still conforms to the 32-bit ABI but uses the general
+      purpose registers as 64-bit registers internally.  This
+      requires a Linux kernel saving the whole 64-bit registers when
       doing a context switch.  Kernels providing that feature
       indicate that by the 'highgprs' string
       in <code>/proc/cpuinfo</code>.</li>