--- libev/ev.pod	2008/03/08 07:04:56	1.134
+++ libev/ev.pod	2008/03/08 10:38:40	1.135
@@ -8,49 +8,63 @@
 
 =head2 EXAMPLE PROGRAM
 
+  // a single header file is required
   #include <ev.h>
 
+  // every watcher type has its own typedef'd struct
+  // with the name ev_<type>
   ev_io stdin_watcher;
   ev_timer timeout_watcher;
 
-  /* called when data readable on stdin */
+  // all watcher callbacks have a similar signature
+  // this callback is called when data is readable on stdin
   static void
   stdin_cb (EV_P_ struct ev_io *w, int revents)
   {
-    /* puts ("stdin ready"); */
-    ev_io_stop (EV_A_ w); /* just a syntax example */
-    ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */
+    puts ("stdin ready");
+    // for one-shot events, one must manually stop the watcher
+    // with its corresponding stop function.
+    ev_io_stop (EV_A_ w);
+
+    // this causes all nested ev_loop's to stop iterating
+    ev_unloop (EV_A_ EVUNLOOP_ALL);
   }
 
+  // another callback, this time for a time-out
   static void
   timeout_cb (EV_P_ struct ev_timer *w, int revents)
   {
-    /* puts ("timeout"); */
-    ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */
+    puts ("timeout");
+    // this causes the innermost ev_loop to stop iterating
+    ev_unloop (EV_A_ EVUNLOOP_ONE);
   }
 
   int
   main (void)
   {
+    // use the default event loop unless you have special needs
     struct ev_loop *loop = ev_default_loop (0);
 
-    /* initialise an io watcher, then start it */
+    // initialise an io watcher, then start it
+    // this one will watch for stdin to become readable
     ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
     ev_io_start (loop, &stdin_watcher);
 
-    /* simple non-repeating 5.5 second timeout */
+    // initialise a timer watcher, then start it
+    // simple non-repeating 5.5 second timeout
     ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
     ev_timer_start (loop, &timeout_watcher);
 
-    /* loop till timeout or data ready */
+    // now wait for events to arrive
     ev_loop (loop, 0);
 
+    // unloop was called, so exit
     return 0;
   }
 
 =head1 DESCRIPTION
 
-The newest version of this document is also available as a html-formatted
+The newest version of this document is also available as an html-formatted
 web page you might find easier to navigate when reading it for the first
 time: L<http://cvs.schmorp.de/libev/ev.html>.
 
@@ -86,12 +100,13 @@
 
 =head2 CONVENTIONS
 
-Libev is very configurable. In this manual the default configuration will
-be described, which supports multiple event loops. For more info about
-various configuration options please have a look at B<EMBED> section in
-this manual. If libev was configured without support for multiple event
-loops, then all functions taking an initial argument of name C<loop>
-(which is always of type C<struct ev_loop *>) will not have this argument.
+Libev is very configurable. In this manual the default (and most common)
+configuration will be described, which supports multiple event loops. For
+more info about various configuration options please have a look at
+B<EMBED> section in this manual. If libev was configured without support
+for multiple event loops, then all functions taking an initial argument of
+name C<loop> (which is always of type C<struct ev_loop *>) will not have
+this argument.
 
 =head2 TIME REPRESENTATION
 
@@ -299,8 +314,8 @@
 This works by calling C<getpid ()> on every iteration of the loop,
 and thus this might slow down your event loop if you do a lot of loop
 iterations and little real work, but is usually not noticeable (on my
-Linux system for example, C<getpid> is actually a simple 5-insn sequence
-without a syscall and thus I<very> fast, but my Linux system also has
+GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
+without a syscall and thus I<very> fast, but my GNU/Linux system also has
 C<pthread_atfork> which is even faster).
 
 The big advantage of this flag is that you can forget about fork (and
@@ -1421,6 +1436,12 @@
 watcher for a signal is stopped libev will reset the signal handler to
 SIG_DFL (regardless of what it was set to before).
 
+If possible and supported, libev will install its handlers with
+C<SA_RESTART> behaviour enabled, so syscalls should not be unduly
+interrupted. If you have a problem with syscalls getting interrupted by
+signals you can block all signals in an C<ev_check> watcher and unblock
+them in an C<ev_prepare> watcher.
+
 =head3 Watcher-Specific Functions and Data Members
 
 =over 4