Flag for fixed list merge key traverse override behavior,

and fix traversing map with merge key that would override local key (completes #2110 fix)

pkg/yqlib/doc/operators/anchor-and-alias-operators.md

@@ -96,6 +96,38 @@ y: 2
 x: 1
 ```
 
+## Override with local key
+like https://yaml.org/type/merge.html, but with x: 1 before the merge key. This is legacy behavior, see --yaml-fix-merge-anchor-to-spec
+
+Given a sample.yml file of:
+```yaml
+- &CENTER
+  x: 1
+  y: 2
+- &LEFT
+  x: 0
+  y: 2
+- &BIG
+  r: 10
+- &SMALL
+  r: 1
+- x: 1
+  !!merge <<:
+    - *BIG
+    - *LEFT
+    - *SMALL
+```
+then
+```bash
+yq '.[4] | explode(.)' sample.yml
+```
+will output
+```yaml
+x: 0
+r: 10
+y: 2
+```
+
 ## Get anchor
 Given a sample.yml file of:
 ```yaml

pkg/yqlib/doc/operators/traverse-read.md

@@ -304,6 +304,8 @@ foo_a
 ```
 
 ## Traversing merge anchors with override
+This is legacy behavior, see --yaml-fix-merge-anchor-to-spec
+
 Given a sample.yml file of:
 ```yaml
 foo: &foo
@@ -399,7 +401,7 @@ foobar_thing
 ```
 
 ## Traversing merge anchor lists
-Note that the keys earlier in the merge anchors sequence override later ones
+Note that the later merge anchors override previous, but this is legacy behavior, see --yaml-fix-merge-anchor-to-spec
 
 Given a sample.yml file of:
 ```yaml
@@ -428,10 +430,12 @@ yq '.foobarList.thing' sample.yml
 ```
 will output
 ```yaml
-foo_thing
+bar_thing
 ```
 
 ## Splatting merge anchor lists
+With legacy override behavior, see --yaml-fix-merge-anchor-to-spec
+
 Given a sample.yml file of:
 ```yaml
 foo: &foo
@@ -460,9 +464,9 @@ yq '.foobarList[]' sample.yml
 will output
 ```yaml
 bar_b
-foo_thing
-foobarList_c
 foo_a
+bar_thing
+foobarList_c
 ```
 
 ## Select multiple indices