Add a bit more text about generators

docs/content/manual/manual.yml

@@ -524,6 +524,8 @@ sections:
           You can also use this on an object, and it will return all
           the values of the object.
 
+          Note that the iterator operator is a generator of values.
+
         examples:
           - program: '.[]'
             input: '[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]'
@@ -561,6 +563,8 @@ sections:
           .bar`, produces both the "foo" fields and "bar" fields as
           separate outputs.
 
+          The `,` operator is one way to contruct generators.
+
         examples:
           - program: '.foo, .bar'
             input: '{"foo": 42, "bar": "something else", "baz": true}'
@@ -579,13 +583,13 @@ sections:
 
           The | operator combines two filters by feeding the output(s) of
           the one on the left into the input of the one on the right. It's
-          pretty much the same as the Unix shell's pipe, if you're used to
-          that.
+          similar to the Unix shell's pipe, if you're used to that.
 
           If the one on the left produces multiple results, the one on
           the right will be run for each of those results. So, the
           expression `.[] | .foo` retrieves the "foo" field of each
-          element of the input array.
+          element of the input array.  This is a cartesian product,
+          which can be surprising.
 
           Note that `.a.b.c` is the same as `.a | .b | .c`.
 
@@ -3118,19 +3122,19 @@ sections:
             array or an object), `range(0; 10)` generates the integers
             between 0 and 10, and so on.
 
-            Even the comma operator is a generator, generating first the
-            values generated by the expression to the left of the comma,
-            then for each of those, the values generate by the
-            expression on the right of the comma.
+            Even the comma operator is a generator, generating first
+            the values generated by the expression to the left of the
+            comma, then the values generated by the expression on the
+            right of the comma.
 
             The `empty` builtin is the generator that produces zero
             outputs.  The `empty` builtin backtracks to the preceding
             generator expression.
 
             All jq functions can be generators just by using builtin
-            generators.  It is also possible to define new generators
-            using only recursion and the comma operator.  If the
-            recursive call(s) is(are) "in tail position" then the
+            generators.  It is also possible to construct new generators
+            using only recursion and the comma operator.  If
+            recursive calls are "in tail position" then the
             generator will be efficient.  In the example below the
             recursive call by `_range` to itself is in tail position.
             The example shows off three advanced topics: tail recursion,

jq.1.prebuilt

@@ -1,5 +1,5 @@
 .
-.TH "JQ" "1" "July 2023" "" ""
+.TH "JQ" "1" "August 2023" "" ""
 .
 .SH "NAME"
 \fBjq\fR \- Command\-line JSON processor
@@ -450,6 +450,9 @@ If you use the \fB\.[index]\fR syntax, but omit the index entirely, it will retu
 .P
 You can also use this on an object, and it will return all the values of the object\.
 .
+.P
+Note that the iterator operator is a generator of values\.
+.
 .IP "" 4
 .
 .nf
@@ -480,6 +483,9 @@ Like \fB\.[]\fR, but no errors will be output if \. is not an array or object\.
 .SS "Comma: ,"
 If two filters are separated by a comma, then the same input will be fed into both and the two filters\' output value streams will be concatenated in order: first, all of the outputs produced by the left expression, and then all of the outputs produced by the right\. For instance, filter \fB\.foo, \.bar\fR, produces both the "foo" fields and "bar" fields as separate outputs\.
 .
+.P
+The \fB,\fR operator is one way to contruct generators\.
+.
 .IP "" 4
 .
 .nf
@@ -501,10 +507,10 @@ jq \'\.[4,2]\'
 .IP "" 0
 .
 .SS "Pipe: |"
-The | operator combines two filters by feeding the output(s) of the one on the left into the input of the one on the right\. It\'s pretty much the same as the Unix shell\'s pipe, if you\'re used to that\.
+The | operator combines two filters by feeding the output(s) of the one on the left into the input of the one on the right\. It\'s similar to the Unix shell\'s pipe, if you\'re used to that\.
 .
 .P
-If the one on the left produces multiple results, the one on the right will be run for each of those results\. So, the expression \fB\.[] | \.foo\fR retrieves the "foo" field of each element of the input array\.
+If the one on the left produces multiple results, the one on the right will be run for each of those results\. So, the expression \fB\.[] | \.foo\fR retrieves the "foo" field of each element of the input array\. This is a cartesian product, which can be surprising\.
 .
 .P
 Note that \fB\.a\.b\.c\fR is the same as \fB\.a | \.b | \.c\fR\.
@@ -3547,13 +3553,13 @@ def repeat(exp):
 Some jq operators and functions are actually generators in that they can produce zero, one, or more values for each input, just as one might expect in other programming languages that have generators\. For example, \fB\.[]\fR generates all the values in its input (which must be an array or an object), \fBrange(0; 10)\fR generates the integers between 0 and 10, and so on\.
 .
 .P
-Even the comma operator is a generator, generating first the values generated by the expression to the left of the comma, then for each of those, the values generate by the expression on the right of the comma\.
+Even the comma operator is a generator, generating first the values generated by the expression to the left of the comma, then the values generated by the expression on the right of the comma\.
 .
 .P
 The \fBempty\fR builtin is the generator that produces zero outputs\. The \fBempty\fR builtin backtracks to the preceding generator expression\.
 .
 .P
-All jq functions can be generators just by using builtin generators\. It is also possible to define new generators using only recursion and the comma operator\. If the recursive call(s) is(are) "in tail position" then the generator will be efficient\. In the example below the recursive call by \fB_range\fR to itself is in tail position\. The example shows off three advanced topics: tail recursion, generator construction, and sub\-functions\.
+All jq functions can be generators just by using builtin generators\. It is also possible to construct new generators using only recursion and the comma operator\. If recursive calls are "in tail position" then the generator will be efficient\. In the example below the recursive call by \fB_range\fR to itself is in tail position\. The example shows off three advanced topics: tail recursion, generator construction, and sub\-functions\.
 .
 .IP "" 4
 .