README: Expand 'canonicalize' section

Describe in more detail what effect 'canonicalize' will have (and
why).

Also mention the British spelling.

Signed-off-by: George Dunlap <george.dunlap@citrix.com>

diff --git a/README.md b/README.md
index ffdbc1ae705cd73b9bbdb8ce024e5113fbedd41b..7dc2872231c8c8d2c255abd63fa8d66069fefca0 100644 (file)
--- a/README.md
+++ b/README.md
@@ -381,7 +381,15 @@ the order of fields may be signicantly different.  You can run
 
 `xsatool NNN canonicalize`
 
-to reformat a file according to Golang's default format.
+to reformat a file according to Golang's default format.  This will:
+  - Sort maps according to lexographical order (golang canon)
+  - Sort elements that correspond do structures according to structure order
+       (golang canon)
+  - Sort versions in SupportedVersions in decending order (xsatool canon).
+  - Remove unknown or obsolete elements.  NB this includes the "XenVersion"
+    element in older recipes.
+       
+For convenience, the British spelling ("canonicalise") is also accepted.
 
 # Potential future functionality