Explain `foreach`'s powers a bit more

diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml
index 4704254214b21c0de4895b704f630e65209c9348..12fcffb73b8d977241ea11fb44ede2beb8bdd819 100644 (file)
--- a/docs/content/3.manual/manual.yml
+++ b/docs/content/3.manual/manual.yml
@@ -1842,7 +1842,10 @@ sections:
           for each new state to extract an output of `foreach`.
 
           This is mostly useful only for constructing `reduce`- and
-          `limit`-like functions.
+          `limit`-like functions.  But it is much more general, as it
+          allows for partial reductions (see the example below), as well
+          as breaking out of the "loop" with `empty`, or even `error(x)`
+          if there's a try/catch around the foreach.
 
         examples:
           - program: '[foreach .[] as $item