Document the meaning of colored version numbers in the manpage of opa…

…m show

Co-authored-by: R. Boujbel <[email protected]>

master_changes.md

@@ -190,6 +190,7 @@ users)
   * Manual: add information when flags (`avoid-version`, `deprecated`) were introduced [#6320 @hannesm]
   * Add winget command for installing opam [#6338 @tobil4sk]
   * Fix broken link to non-existing archlinux community repo [#6361 @juergenhoetzel]
+  * Document the meaning of colored version numbers in the manpage of `opam show` [#6358 @kit-ty-kate]
 
 ## Security fixes
 

src/client/opamCommands.ml

@@ -921,7 +921,18 @@ let show cli =
         available packages as well as a short description for each.";
     `P "Paths to package definition files or to directories containing package \
         definitions can also be specified, in which case the corresponding \
-        metadata will be shown."
+        metadata will be shown.";
+    `P "Note: on terminal supporting it, version numbers can be colored the \
+        following ways:";
+    `Noblank;
+    `I ("-", "Magenta and bold: versions installed the current switch");
+    `Noblank;
+    `I ("-", "Bold: versions installed in other switches");
+    `Noblank;
+    `I ("-", "Red and crossed: versions not available on the current platform");
+    `Noblank;
+    `I ("-", "Gray: versions tagged with the $(i,avoid-version) or \
+              $(i,deprecated) flag");
   ] in
   let fields =
     mk_opt ~cli cli_original ["f";"field"] "FIELDS"

src/client/opamListCommand.ml

@@ -506,6 +506,7 @@ let field_of_string ~raw =
     | Some f -> Field f
     | None -> OpamConsole.error_and_exit `Bad_arguments "No printer for %S" s
 
+(* NOTE: upon changes, please update the man page section in opamCommands.ml *)
 let version_color st nv =
   let installed = (* (in any switch) *)
     OpamGlobalState.installed_versions st.switch_global nv.name