doc: Add more info on migrating to sub 2.x

README.md

@@ -75,7 +75,7 @@ directory structure:
 
 The entry point in `bin/awesomecli` can then be:
 
-```
+```bash
 #!/usr/bin/env bash
 
 sub --name awesomecli --executable "${BASH_SOURCE[0]}" --relative ".." -- "$@"
@@ -158,6 +158,10 @@ to an XDG compliant cache directory that can be used for storing temporary files
 
 ## Migrating to Sub 2.x
 
+### --bin was renamed to --executable
+
+The `--bin` argument was renamed to `--executable` to better reflect its purpose.
+
 ### Usage comments
 
 Sub 2.x introduces automatic validation and parsing of command line arguments