--- cvsroot/Coro/README	2013/03/06 06:00:08	1.32
+++ cvsroot/Coro/README	2015/02/11 19:30:34	1.35
@@ -551,14 +551,14 @@
                  $SIG{VTALRM} = sub { cede };
                  # and then start the interval timer
                  Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
-              }; 
+              };
               Coro::on_leave {
                  # on leaving the thread, we stop the interval timer again
                  Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
-              }; 
+              };
 
               &{+shift};
-           }  
+           }
 
            # use like this:
            timeslice {
@@ -663,13 +663,16 @@
         on running complicated cleanup handlers that rely on its thread
         context, things will not work.
 
-        Any cleanup code being run (e.g. from "guard" blocks) will be run
-        without a thread context, and is not allowed to switch to other
-        threads. On the plus side, "->cancel" will always clean up the
-        thread, no matter what. If your cleanup code is complex or you want
-        to avoid cancelling a C-thread that doesn't know how to clean up
-        itself, it can be better to "->throw" an exception, or use
-        "->safe_cancel".
+        Any cleanup code being run (e.g. from "guard" blocks, destructors
+        and so on) will be run without a thread context, and is not allowed
+        to switch to other threads. A common mistake is to call "->cancel"
+        from a destructor called by die'ing inside the thread to be
+        cancelled for example.
+
+        On the plus side, "->cancel" will always clean up the thread, no
+        matter what. If your cleanup code is complex or you want to avoid
+        cancelling a C-thread that doesn't know how to clean up itself, it
+        can be better to "->throw" an exception, or use "->safe_cancel".
 
         The arguments to "->cancel" are not copied, but instead will be
         referenced directly (e.g. if you pass $var and after the call change
@@ -684,15 +687,16 @@
     $coro->safe_cancel ($arg...)
         Works mostly like "->cancel", but is inherently "safer", and
         consequently, can fail with an exception in cases the thread is not
-        in a cancellable state.
+        in a cancellable state. Essentially, "->safe_cancel" is a "->cancel"
+        with extra checks before canceling.
 
-        This method works a bit like throwing an exception that cannot be
-        caught - specifically, it will clean up the thread from within
-        itself, so all cleanup handlers (e.g. "guard" blocks) are run with
-        full thread context and can block if they wish. The downside is that
-        there is no guarantee that the thread can be cancelled when you call
-        this method, and therefore, it might fail. It is also considerably
-        slower than "cancel" or "terminate".
+        It works a bit like throwing an exception that cannot be caught -
+        specifically, it will clean up the thread from within itself, so all
+        cleanup handlers (e.g. "guard" blocks) are run with full thread
+        context and can block if they wish. The downside is that there is no
+        guarantee that the thread can be cancelled when you call this
+        method, and therefore, it might fail. It is also considerably slower
+        than "cancel" or "terminate".
 
         A thread is in a safe-cancellable state if it either hasn't been run
         yet, or it has no C context attached and is inside an SLF function.
@@ -780,7 +784,7 @@
         arguments, if any, and *must not* die, under any circumstances.
 
         There can be any number of "on_destroy" callbacks per coro, and
-        there is no way currently to remove a callback once added.
+        there is currently no way to remove a callback once added.
 
     $oldprio = $coro->prio ($newprio)
         Sets (or gets, if the argument is missing) the priority of the coro
@@ -856,7 +860,7 @@
         blocked).
 
         Coro will try to catch you when you block in the event loop
-        ("FATAL:$Coro::IDLE blocked itself"), but this is just best effort
+        ("FATAL:$Coro::idle blocked itself"), but this is just best effort
         and only works when you do not run your own event loop.
 
         This function allows your callbacks to block by executing them in