--- AnyEvent/lib/AnyEvent.pm	2008/04/07 19:41:28	1.43
+++ AnyEvent/lib/AnyEvent.pm	2008/04/14 19:11:15	1.49
@@ -60,9 +60,9 @@
 offering the functionality that is useful, in as thin as a wrapper as
 technically possible.
 
-Of course, if you want lots of policy (this is arguably somewhat useful in
-many cases) and you want your users to the one and only event model your
-module forces on them, you should I<not> use this module.
+Of course, if you want lots of policy (this can arguably be somewhat
+useful) and you want to force your users to use the one and only event
+model, you should I<not> use this module.
 
 
 =head1 DESCRIPTION
@@ -181,16 +181,24 @@
 Wait (blocking if necessary) until the C<< ->broadcast >> method has been
 called on c<$cv>, while servicing other watchers normally.
 
-Not all event models support a blocking wait - some die in that case, so
-if you are using this from a module, never require a blocking wait, but
-let the caller decide wether the call will block or not (for example,
-by coupling condition variables with some kind of request results and
-supporting callbacks so the caller knows that getting the result will not
-block, while still suppporting blockign waits if the caller so desires).
-
 You can only wait once on a condition - additional calls will return
 immediately.
 
+Not all event models support a blocking wait - some die in that case
+(programs might want to do that so they stay interactive), so I<if you
+are using this from a module, never require a blocking wait>, but let the
+caller decide wether the call will block or not (for example, by coupling
+condition variables with some kind of request results and supporting
+callbacks so the caller knows that getting the result will not block,
+while still suppporting blocking waits if the caller so desires).
+
+Another reason I<never> to C<< ->wait >> in a module is that you cannot
+sensibly have two C<< ->wait >>'s in parallel, as that would require
+multiple interpreters or coroutines/threads, none of which C<AnyEvent>
+can supply (the coroutine-aware backends C<Coro::EV> and C<Coro::Event>
+explicitly support concurrent C<< ->wait >>'s from different coroutines,
+however).
+
 =item $cv->broadcast
 
 Flag the condition as ready - a running C<< ->wait >> and all further
@@ -254,9 +262,9 @@
    AnyEvent::Impl::EV        based on EV (an interface to libev, also best choice).
    AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
    AnyEvent::Impl::Event     based on Event, also second best choice :)
-   AnyEvent::Impl::Glib      based on Glib, 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.
+   AnyEvent::Impl::Perl      pure-perl implementation, inefficient but portable.
 
 =item AnyEvent::detect
 
@@ -636,7 +644,7 @@
 
    my $data = $fcp->client_get ($url);
 
-2. Blocking, but parallelizing:
+2. Blocking, but running in parallel:
 
    my @datas = map $_->result,
                   map $fcp->txn_client_get ($_),
@@ -645,9 +653,9 @@
 Both blocking examples work without the module user having to know
 anything about events.
 
-3a. Event-based in a main program, using any support Event module:
+3a. Event-based in a main program, using any supported event module:
 
-   use Event;
+   use EV;
 
    $fcp->txn_client_get ($url)->cb (sub {
       my $txn = shift;
@@ -655,7 +663,7 @@
       ...
    });
 
-   Event::loop;
+   EV::loop;
 
 3b. The module user could use AnyEvent, too:
 
@@ -672,11 +680,14 @@
 
 =head1 SEE ALSO
 
-Event modules: L<Coro::Event>, L<Coro>, L<Event>, L<Glib::Event>, L<Glib>.
+Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>,
+L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>.
 
-Implementations: L<AnyEvent::Impl::Coro>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>.
+Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
+L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>,
+L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>.
 
-Nontrivial usage example: L<Net::FCP>.
+Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
 
 =head1