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

#2466

docs/content/manual/manual.yml

@@ -908,13 +908,17 @@ 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.
+          array. For example, `map(.+1)` will increment each element
+          of an array of numbers, and `map(.,.)` will duplicate each
+          element of the input array.
 
-          Similarly, `map_values(f)` will run that filter for each element,
+          `map(f)` is equivalent to `[.[] | f]`. In fact, this is how it's defined.
-          but it will return an object when an object is passed.
 
-          `map(f)` is equivalent to `[.[] | f]`. In fact, this is how
+          `map_values(f)` is similarly defined as `.[] |= f`.  This
-          it's defined. Similarly, `map_values(f)` is defined as `.[] |= f`.
+          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)'
@@ -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: |