docs: fix arithmetic update-assignment equivalence (#3682)

The manual said `a op= b` is equivalent to `a |= . op b`. It is actually
equivalent to `(b as $b | a |= . op $b)`: the right-hand side gets `.`
as input, not the value being updated, and each value it outputs gives a
separate result.

This updates the description and adds two examples, `.a += .b` and `.a
+= (1,2)`. `tests/man.test` and `jq.1.prebuilt` are regenerated.

Fixes #2119, fixes #2407

docs/content/manual/dev/manual.yml

@@ -3561,6 +3561,13 @@ sections:
 
           The left-hand side can be any general path expression; see `path()`.
 
+          The right-hand side of `|=` is run with the value at the path
+          as its input, not with `.`. This is what sets it apart from
+          plain assignment (`=`) and the arithmetic update-assignment
+          operators such as `+=`, whose right-hand side is run with `.`.
+          For example, `.a |= .b` sets `.a` to the `b` field of `.a`,
+          while `.a = .b` and `.a += .b` use the `b` field of `.`.
+
           Note that the left-hand side of `|=` refers to a value in `.`.
           Thus `$var.foo |= . + 1` won't work as expected (`$var.foo` is
           not a valid or useful path expression in `.`); use `$var |
@@ -3588,13 +3595,27 @@ sections:
         body: |
 
           jq has a few operators of the form `a op= b`, which are all
-          equivalent to `a |= . op b`. So, `+= 1` can be used to
-          increment values, being the same as `|= . + 1`.
+          equivalent to `(b as $b | a |= . op $b)`. So, `+= 1` can be
+          used to increment values, being the same as `|= . + 1`.
+
+          Note that the right-hand side `b` is evaluated with the same
+          input as the left-hand side, not with the value at the path
+          being updated. So `.a += .b` adds the value of `.b` to `.a`,
+          whereas `.a |= . + .b` would look up `.b` inside the value of
+          `.a`.
+          If `b` outputs multiple values, then `a op= b` outputs one
+          result for each of them.
 
         examples:
           - program: .foo += 1
             input: '{"foo": 42}'
             output: ['{"foo": 43}']
+          - program: '.a += .b'
+            input: '{"a": 1, "b": 2}'
+            output: ['{"a": 3, "b": 2}']
+          - program: '.a += (1,2)'
+            input: '{"a": 0}'
+            output: ['{"a": 1}', '{"a": 2}']
 
       - title: "Plain assignment: `=`"
         body: |