Document `path(path_expression)` builtin

diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml
index cc2d5a25b07c20bab76ba4c22a86d316b0061060..4704254214b21c0de4895b704f630e65209c9348 100644 (file)
--- a/docs/content/3.manual/manual.yml
+++ b/docs/content/3.manual/manual.yml
@@ -618,6 +618,33 @@ sections:
             input: '[[0,1], ["a","b","c"]]'
             output: ['[false, true]']
 
+      - title: "`path(path_expression)`"
+        body: |
+
+          Outputs array representations of the given path expression
+          in `.`.  The outputs are arrays of strings (keys in objects0
+          and/or numbers (array indices.
+
+          Path expressions are jq expressions like `.a`, but also `.[]`.
+          There are two types of path expressions: ones that can match
+          exactly, and ones that cannot.  For example, `.a.b.c` is an
+          exact match path expression, while `.a[].b` is not.
+
+          `path(exact_path_expression)` will produce the array
+          representation of the path expression even if it does not
+          exist in `.`, if `.` is `null` or an array or an object.
+
+          `path(pattern)` will produce array representations of the
+          paths matching `pattern` if the paths exist in `.`.
+
+        examples:
+          - program: 'path(.a[0].b)'
+            input: 'null'
+            output: ['["a",0,"b"]']
+          - program: '[path(..)]'
+            input: '{"a":[{"b":1}]}'
+            output: ['[[],["a"],["a",0],["a",0,"b"]]']
+
       - title: "`del(path_expression)`"
         body: |