Making examples of the merge fix flag clearer

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

@@ -2,6 +2,15 @@
 
 This is the simplest (and perhaps most used) operator. It is used to navigate deeply into yaml structures.
 
+
+## NOTE --yaml-fix-merge-anchor-to-spec flag
+`yq` doesn't merge anchors `<<:` to spec, in some circumstances it incorrectly overrides existing keys when the spec documents not to do that.
+
+To minimise disruption while still fixing the issue, a flag has been added to toggle this behaviour. This will first default to false; and log warnings to users. Then it will default to true (and still allow users to specify false if needed)
+
+See examples of the flag differences below.
+
+
 ## Simple map navigation
 Given a sample.yml file of:
 ```yaml
@@ -352,7 +361,7 @@ a
 c
 ```
 
-## Traversing merge anchors with override
+## LEGACY: Traversing merge anchors with override
 This is legacy behaviour, see --yaml-fix-merge-anchor-to-spec
 
 Given a sample.yml file of:
@@ -385,7 +394,7 @@ will output
 foo_c
 ```
 
-## Traversing merge anchor lists
+## LEGACY: Traversing merge anchor lists
 Note that the later merge anchors override previous, but this is legacy behaviour, see --yaml-fix-merge-anchor-to-spec
 
 Given a sample.yml file of:
@@ -418,7 +427,7 @@ will output
 bar_thing
 ```
 
-## Splatting merge anchors
+## LEGACY: Splatting merge anchors
 With legacy override behaviour, see --yaml-fix-merge-anchor-to-spec
 
 Given a sample.yml file of:
@@ -453,7 +462,7 @@ foo_a
 foobar_thing
 ```
 
-## Splatting merge anchor lists
+## LEGACY: Splatting merge anchor lists
 With legacy override behaviour, see --yaml-fix-merge-anchor-to-spec
 
 Given a sample.yml file of: