manual.yml: clarify explanation of map_values, including description of new behavior

#2466

1 files changed, 19 insertions, 6 deletions

diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml
index ed9a8c3a..d920cdc7 100644
--- a/docs/content/manual/manual.yml
+++ b/docs/content/manual/manual.yml
@@ -908,14 +908,18 @@ sections:
 
           For any filter `f`, `map(f)` will run that filter for each
           element of the input array, and return the outputs in a new
-          array. `map(.+1)` will increment each element of an array of numbers.
-
-          Similarly, `map_values(f)` will run that filter for each element,
-          but it will return an object when an object is passed.
+          array. For example, `map(.+1)` will increment each element
+          of an array of numbers, and `map(.,.)` will duplicate each
+          element of the input array.
 
-          `map(f)` is equivalent to `[.[] | f]`. In fact, this is how
-          it's defined. Similarly, `map_values(f)` is defined as `.[] |= f`.
+          `map(f)` is equivalent to `[.[] | f]`. In fact, this is how it's defined.
 
+          `map_values(f)` is similarly defined as `.[] |= f`.  This
+          essentially means that each value, $v, in the input array or
+          object is replaced by `first($v|f)`, it being understood
+          that if the input is an object, then keys for which this
+          expression is empty will be removed.
+          
         examples:
           - program: 'map(.+1)'
             input: '[1,2,3]'
@@ -925,6 +929,15 @@ sections:
             input: '{"a": 1, "b": 2, "c": 3}'
             output: ['{"a": 2, "b": 3, "c": 4}']
 
+          - program: 'map(., .)'
+            input: '[1,2]'
+            output: ['[1,1,2,2]']
+
+          - program: 'map_values(. // empty)'
+            input: '{"a": null, "b": true, "c": false}'
+            output: ['{"b":true}']
+
+
       - title: "`pick(pathexps)`"
         body: |