Improve merge docs

operators/multiply-merge.md

@@ -3,7 +3,9 @@
 Like the multiple operator in jq, depending on the operands, this multiply operator will do different things. Currently numbers, arrays and objects are supported.
 
 ## Objects and arrays - merging
-Objects are merged deeply matching on matching keys. By default, array values override and are not deeply merged.
+Objects are merged _deeply_ matching on matching keys. By default, array values override and are not deeply merged.
+
+You can use the add operator `+`, to shallow merge objects, see more info [here](https://mikefarah.gitbook.io/yq/operators/add).
 
 Note that when merging objects, this operator returns the merged object (not the parent). This will be clearer in the examples below.
 
@@ -16,6 +18,7 @@ You can control how objects are merged by using one or more of the following fla
 - `n` only merge _new_ fields
 - `c` clobber custom tags
 
+To perform a shallow merge only, use the add operator `+`, see more info [here](https://mikefarah.gitbook.io/yq/operators/add).
 
 ### Merge two files together
 This uses the load operator to merge file2 into file1.

usage/formatting-expressions.md

@@ -0,0 +1,61 @@
+# Formatting Expressions
+
+`From version v4.41+`
+
+You can put expressions into `.yq` files, use whitespace and comments to break up complex expressions and explain what's going on.
+
+## Using expression files and comments
+Given a sample.yaml file of:
+```yaml
+a:
+  b: old
+```
+And an 'update.yq' expression file of:
+```bash
+# This is a yq expression that updates the map
+# for several great reasons outlined here.
+
+.a.b = "new" # line comment here
+| .a.c = "frog"
+
+# Now good things will happen.
+```
+then
+```bash
+yq --from-file update.yq sample.yml
+```
+will output
+```yaml
+a:
+  b: new
+  c: frog
+```
+
+## Commenting out yq expressions
+Note that `c` is no longer set to 'frog'.
+
+Given a sample.yaml file of:
+```yaml
+a:
+  b: old
+```
+And an 'update.yq' expression file of:
+```bash
+# This is a yq expression that updates the map
+# for several great reasons outlined here.
+
+.a.b = "new" # line comment here
+# | .a.c = "frog"
+
+# Now good things will happen.
+```
+then
+```bash
+yq --from-file update.yq sample.yml
+```
+will output
+```yaml
+a:
+  b: new
+```
+

usage/xml.md

@@ -370,7 +370,7 @@ cat: purrs
 ```
 then
 ```bash
-yq -o=xml '.' sample.yml
+yq -o=xml sample.yml
 ```
 will output
 ```xml
@@ -387,7 +387,7 @@ pets:
 ```
 then
 ```bash
-yq -o=xml '.' sample.yml
+yq -o=xml sample.yml
 ```
 will output
 ```xml
@@ -409,7 +409,7 @@ cat:
 ```
 then
 ```bash
-yq -o=xml '.' sample.yml
+yq -o=xml sample.yml
 ```
 will output
 ```xml
@@ -430,7 +430,7 @@ cat:
 ```
 then
 ```bash
-yq -o=xml '.' sample.yml
+yq -o=xml sample.yml
 ```
 will output
 ```xml
@@ -457,7 +457,7 @@ cat: # inline_cat
 ```
 then
 ```bash
-yq -o=xml '.' sample.yml
+yq -o=xml sample.yml
 ```
 will output
 ```xml
@@ -487,7 +487,7 @@ apple:
 ```
 then
 ```bash
-yq -o=xml '.' sample.yml
+yq -o=xml sample.yml
 ```
 will output
 ```xml