CLI Changes Sub-PR: Documentation

CHANGELOG.md

@@ -53,6 +53,148 @@ This name should be decided amongst the team before the release.
 * [#535](https://github.com/tweag/topiary/pull/535) Improved error message when idempotency fails due to invalid output in the first pass.
 * [#533](https://github.com/tweag/topiary/pull/533) Update tree-sitter-ocaml to 0.20.3
 * [#576](https://github.com/tweag/topiary/pull/576) Allows prepending/appending `@begin_scope` and `@end_scope`
+* [#583](https://github.com/tweag/topiary/pull/583) Modernisation of the command line interface (see [below](#cli-migration-guide), for details)
+
+#### CLI Migration Guide
+
+Full documentation for the CLI can be found in the project's
+[`README`](/README.md). Herein we summarise how the v0.2.3 functionality
+maps to the new interface, to aid migration.
+
+##### Formatting
+
+###### From Files, In Place
+
+Before:
+```
+topiary [--skip-idempotence] \
+        [--tolerate-parsing-errors] \
+        --in-place \
+        --input-files INPUT_FILES...
+```
+
+After:
+```
+topiary fmt [--skip-idempotence] \
+            [--tolerate-parsing-errors] \
+            INPUT_FILES...
+```
+
+###### From File, To New File
+
+Before:
+```
+topiary [--skip-idempotence] \
+        [--tolerate-parsing-errors] \
+        (--langauge LANGUAGE | --query QUERY) \
+        --input-files INPUT_FILE \
+        --output-file OUTPUT_FILE
+```
+
+After (use IO redirection):
+```
+topiary [--skip-idempotence] \
+        [--tolerate-parsing-errors] \
+        (--langauge LANGUAGE | --query QUERY) \
+        < INPUT_FILE \
+        > OUTPUT_FILE
+```
+
+###### Involving Standard Input and Output
+
+Before:
+```
+topariy [--skip-idempotence] \
+        [--tolerate-parsing-errors] \
+        (--langauge LANGUAGE | --query QUERY) \
+        (--input-files - | < INPUT_FILE) \
+        [--output-file -]
+```
+
+After (use IO redirection):
+```
+topiary [--skip-idempotence] \
+        [--tolerate-parsing-errors] \
+        (--langauge LANGUAGE | --query QUERY) \
+        < INPUT_FILE
+```
+
+##### Visualisation
+
+###### From File
+
+Before:
+```
+topiary --visualise[=FORMAT] \
+        --input-files INPUT_FILE \
+        [--output-file OUTPUT_FILE | > OUTPUT_FILE]
+```
+
+After:
+```
+topiary vis [--tolerate-parsing-errors] \
+            [--format FORMAT] \
+            INPUT_FILE \
+            [> OUTPUT_FILE]
+```
+
+###### Involving Standard Input and Output
+
+Before:
+```
+topiary --visualise[=FORMAT] \
+        (--langauge LANGUAGE | --query QUERY) \
+        < INPUT_FILE \
+        [--output-file OUTPUT_FILE | > OUTPUT_FILE]
+```
+
+After (use IO redirection):
+```
+topiary vis [--tolerate-parsing-errors] \
+            [--format FORMAT] \
+            (--langauge LANGUAGE | --query QUERY) \
+            < INPUT_FILE \
+            [> OUTPUT_FILE]
+```
+
+##### Configuration
+
+###### Custom Configuration
+
+To replicate the behaviour of v0.2.3, set the configuration collation
+mode to `revise`. This can be done with the `TOPIARY_CONFIG_COLLATION`
+environment variable, or the `--configuration-collation` argument.
+
+The new default collation method is `merge`, which is subtly different
+when it comes to collating collections.
+
+###### Overriding Configuration
+
+Before (or using the `TOPIARY_CONFIGURATION_OVERRIDE` environment
+variable):
+```
+topiary --configuration-override CONFIG_FILE ...
+```
+
+After (or using a combination of `TOPIARY_CONFIG_FILE` and
+`TOPIARY_CONFIG_COLLATION` environment variables):
+```
+topiary --configuration CONFIG_FILE \
+        --configuration-collation override \
+        ...
+```
+
+###### Examining Computed Configuration
+
+Before (to standard error, then proceeding with other functions):
+```
+topiary --output-configuration ...
+```
+
+After (to standard output, as a dedicated function):
+```
+topiary cfg
+```
 
 ## v0.2.3 - Cyclic Cypress - 2023-06-20