Re: [www-patch] bugs.html rewrite, part 6a: clarify ABI section

[Volker Reichelt <reichelt at igpm dot rwth-aachen dot de>]

On 14 Jan, Richard Earnshaw wrote:
>> Breaking out the version stuff into an own paragraph is a good idea.
>> I'd like to add "Note:" in front of the explanation.
> 
> I think "Note" should be reserved for things that it is vital that the 
> reader take note of (this is more of an aside, or footnote) than a real 
> note.  As I said, if there were a more appropriate place for the 
> information I'd move it there and just create a hyperlink reference from 
> the main code.

Agreed. How about "Remark:" then - or rather nothing?

>> However, I don't like the idea of breaking out the sentence about the
>> Java stuff. It refers directly to "... recompile all libraries that
>> contain C++ code ..." and the following sentence which tells you about
>> the trouble you can get in. I therefore prefer to put the sentence right
>> there.
> 
> I felt it spoilt the flow of the main paragraph, and was clear enough 
> about what it was referring to on its own.

Yes, it does spoil the flow. But IMHO placing it after the versioning
stuff is worse, since it can too easily be skipped by accident resulting
in malfunctioning programs.

> However, I've probably read the text too many times now to be completely
> sure which is best...

Me too... That's why I didn't see that your explanation of versioning
mentioned GCC 3.2.0 and 3.3.0 - which is inaccurate. I fixed that and
added a sentence about our change in the naming scheme for 3.4.

Ok?

Regards,
Volker


Index: bugs.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/bugs.html,v
retrieving revision 1.82
diff -c -p -r1.82 bugs.html
*** bugs.html	13 Jan 2004 17:36:40 -0000	1.82
--- bugs.html	15 Jan 2004 00:42:35 -0000
*************** and the scope operator.</p></dd>
*** 691,704 ****
  
  <h4>ABI changes</h4>
  
! <p>The application binary interface (ABI) defines how the elements of
! classes are laid out, how functions are called, how function names are
! mangled etc.  It usually changes with each major release (i.e. when the
! first or second part of the version number changes).  You <em>must</em>
! recompile all C++ libraries, or you risk linker errors or malfunctioning
! programs.  However, the ABI is not changed with bug-fix releases (i.e.
! when the third part of the version number changes).  The code should be
! binary compatible among these versions.</p>
  
  <h4>Standard conformance</h4>
  
--- 691,718 ----
  
  <h4>ABI changes</h4>
  
! <p>The C++ application binary interface (ABI) consists of two
! components: the first defines how the elements of classes are laid
! out, how functions are called, how function names are mangled, etc;
! the second part deals with the internals of the objects in libstdc++.
! Although we strive for a non-changing ABI, so far we have had to
! modify it with each major release.  If you change your compiler to a
! different major release <em>you must recompile all libraries that
! contain C++ code</em>.  If you fail to do so you risk getting linker
! errors or malfunctioning programs.  Some of our Java support libraries
! also contain C++ code, so you might want to recompile all libraries to
! be safe.  It should not be necessary to recompile if you have changed
! to a bug-fix release of the same version of the compiler; bug-fix
! releases are careful to avoid ABI changes. See also the
! <a href="onlinedocs/gcc/Compatibility.html">compatibility section</a>
! of the GCC manual.</p>
! 
! <p>Remark: A major release is designated by a change to the first or second
! component of the two- or three-part version number.  A minor (bug-fix)
! release is designated by a change to the third component only.  Thus GCC
! 3.2 and 3.3 are major releases, while 3.3.1 and 3.3.2 are bug-fix releases
! for GCC 3.3.  With the 3.4 series we are introducing a new naming scheme;
! the first release of this series will be 3.4.0 instead of just 3.4.</p>
  
  <h4>Standard conformance</h4>
  
===================================================================