--- AnyEvent/lib/AnyEvent.pm	2008/04/25 09:11:59	1.80
+++ AnyEvent/lib/AnyEvent.pm	2008/04/25 13:32:39	1.82
@@ -82,9 +82,9 @@
 During the first call of any watcher-creation method, the module tries
 to detect the currently loaded event loop by probing whether one of the
 following modules is already loaded: L<Coro::EV>, L<Coro::Event>, L<EV>,
-L<Event>, L<Glib>, L<Tk>, L<AnyEvent::Impl::Perl>, L<Event::Lib>, L<Qt>,
+L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>,
 L<POE>. The first one found is used. If none are found, the module tries
-to load these modules (excluding Event::Lib, Qt and POE as the pure perl
+to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl
 adaptor should always succeed) in the order given. The first one that can
 be successfully loaded will be used. If, after this, still none could be
 found, AnyEvent will fall back to a pure-perl event loop, which is not
@@ -149,9 +149,7 @@
 respectively. C<cb> is the callback to invoke each time the file handle
 becomes ready.
 
-As long as the I/O watcher exists it will keep the file descriptor or a
-copy of it alive/open.
-
+The I/O watcher might use the underlying file descriptor or a copy of it.
 It is not allowed to close a file handle as long as any watcher is active
 on the underlying file descriptor.
 
@@ -255,16 +253,38 @@
 signal handler for C<SIGCHLD>. The callback will be called with the pid
 and exit status (as returned by waitpid).
 
-Example: wait for pid 1333
+There is a slight catch to child watchers, however: you usually start them
+I<after> the child process was created, and this means the process could
+have exited already (and no SIGCHLD will be sent anymore).
+
+Not all event models handle this correctly (POE doesn't), but even for
+event models that I<do> handle this correctly, they usually need to be
+loaded before the process exits (i.e. before you fork in the first place).
+
+This means you cannot create a child watcher as the very first thing in an
+AnyEvent program, you I<have> to create at least one watcher before you
+C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
+
+Example: fork a process and wait for it
+
+  my $done = AnyEvent->condvar;
+
+  AnyEvent::detect; # force event module to be initialised
+
+  my $pid = fork or exit 5;
 
   my $w = AnyEvent->child (
-     pid => 1333,
+     pid => $pid,
      cb  => sub {
         my ($pid, $status) = @_;
         warn "pid $pid exited with status $status";
+        $done->broadcast;
      },
   );
 
+  # do something else, then wait for process exit
+  $done->wait;
+
 =head2 CONDITION VARIABLES
 
 Condition variables can be created by calling the C<< AnyEvent->condvar >>
@@ -361,8 +381,8 @@
    AnyEvent::Impl::EV        based on EV (an interface to libev, best choice).
    AnyEvent::Impl::Event     based on Event, second best choice.
    AnyEvent::Impl::Glib      based on Glib, third-best choice.
-   AnyEvent::Impl::Tk        based on Tk, very bad choice.
    AnyEvent::Impl::Perl      pure-perl implementation, inefficient but portable.
+   AnyEvent::Impl::Tk        based on Tk, very bad choice.
    AnyEvent::Impl::Qt        based on Qt, cannot be autoprobed (see its docs).
    AnyEvent::Impl::EventLib  based on Event::Lib, leaks memory and worse.
    AnyEvent::Impl::POE       based on POE, not generic enough for full support.