Better document `path()`'s power; also `|=`

diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml
index e8e80115443b3ffb3b0f20109a5020253fab5cd3..2970ea83fd96cdf59130a6ee31596907e7391e1e 100644 (file)
--- a/docs/content/3.manual/manual.yml
+++ b/docs/content/3.manual/manual.yml
@@ -637,6 +637,11 @@ sections:
           `path(pattern)` will produce array representations of the
           paths matching `pattern` if the paths exist in `.`.
 
+          Note that the path expressions are not different from normal
+          expressions.  The expression
+          `path(..|select(type=="boolean"))` outputs all the paths to
+          boolean values in `.`, and only those paths.
+
         examples:
           - program: 'path(.a[0].b)'
             input: 'null'
@@ -1974,10 +1979,18 @@ sections:
           input, and produce the output {"a": 20}. The latter will set the "a"
           field of the input to the "a" field's "b" field, producing {"a": 10}.
 
+          The left-hand side can be any general path expression; see `path()`.
+
           Note that the left-hand side of '|=' refers to a value in `.`.
           Thus `$var.foo |= . + 1` won't work as expected; use `$var |
           .foo |= . + 1` instead.
 
+        examples:
+
+          - program: '(..|select(type=="boolean")) |= if . then 1 else 0 end'
+            input: '[true,false,[5,true,[true,[false]],false]]'
+            output: ['[1,0,[5,1,[1,[0]],0]]']
+
       - title: "`+=`, `-=`, `*=`, `/=`, `%=`, `//=`"
         body: |