--- cvsroot/libecb/ecb.pod	2011/05/26 23:55:58	1.17
+++ cvsroot/libecb/ecb.pod	2011/05/27 00:12:00	1.20
@@ -18,7 +18,7 @@
 detection, byte swapping or bit rotations.
 
 Or in other words, things that should be built-in into any standard C
-system, but isn't.
+system, but aren't.
 
 More might come.
 
@@ -57,7 +57,21 @@
 
 =head2 GCC ATTRIBUTES
 
-blabla where to put, what others
+A major part of libecb deals with GCC attributes. These are additional
+attributes that you cna assign to functions, variables and sometimes even
+types - much like C<const> or C<volatile> in C.
+
+While GCC allows declarations to show up in many surprising places,
+but not in many expeted places, the safest way is to put attribute
+declarations before the whole declaration:
+
+   ecb_const int mysqrt (int a);
+   ecb_unused int i;
+
+For variables, it is often nicer to put the attribute after the name, and
+avoid multiple declarations using commas:
+
+   int i ecb_unused;
 
 =over 4
 
@@ -107,12 +121,12 @@
      abort ();
    }
 
-In this case, the compiler would probbaly be smart enough to decude it on
-it's own, so this is mainly useful for declarations.
+In this case, the compiler would probably be smart enough to deduce it on
+its own, so this is mainly useful for declarations.
 
 =item ecb_const
 
-Declares that the function only depends on the values of it's arguments,
+Declares that the function only depends on the values of its arguments,
 much like a mathematical function. It specifically does not read or write
 any memory any arguments might point to, global variables, or call any
 non-const functions. It also must not have any side effects.
@@ -123,7 +137,7 @@
 expect any side effects.
 
 It is best suited for functions in the sense of mathematical functions,
-such as a function return the square root of its input argument.
+such as a function returning the square root of its input argument.
 
 Not suited would be a function that calculates the hash of some memory
 area you pass in, prints some messages or looks at a global variable to
@@ -156,7 +170,7 @@
 The compiler reacts by trying to place hot functions near to each other in
 memory.
 
-Whether a function is hot or not often depend son the whole program,
+Whether a function is hot or not often depends on the whole program,
 and less on the function itself. C<ecb_cold> is likely more useful in
 practise.
 
@@ -171,7 +185,7 @@
 functions), this knowledge can be used in other ways, for example, the
 function will be optimised for size, as opposed to speed, and codepaths
 leading to calls to those functions can automatically be marked as if
-C<ecb_unlikel> had been used to reach them.
+C<ecb_unlikely> had been used to reach them.
 
 Good examples for such functions would be error reporting functions, or
 functions only called in exceptional or rare cases.
@@ -406,6 +420,9 @@
 These two functions return the value of C<x> after shifting all the bits
 by C<count> positions to the right or left respectively.
 
+Current GCC versions understand these functions and usually compile them
+to "optimal" code (e.g. a single C<roll> on x86).
+
 =back
 
 =head2 ARITHMETIC
@@ -416,7 +433,8 @@
 
 Returns the positive remainder of the modulo operation between C<m> and
 C<n>. Unlike the C modulo operator C<%>, this function ensures that the
-return value is always positive).
+return value is always positive - ISO C guarantees very little when
+negative numbers are used with C<%>.
 
 C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be
 negatable, that is, both C<m> and C<-m> must be representable in its