+Invocation and command-line option reference
+============================================
+
+Usages
+------
+
+```
+1$ nailing-cargo <nailing-opts> <cargo-opts> [--] <subcmd>...
+2$ nailing-cargo <nailing-opts> --- <cargo> <cargo-opts> [--] <subcmd>...
+3$ nailing-cargo <nailing-opts> --- [--] <build-command>...
+```
+Ususally the `--` is not needed. (It should generally be passed by
+programs which wrap nailing-cargo. See below.)
+
+In usage 1, nailing-cargo runs `cargo` (from `PATH`). In the usage 2
+nailing-cargo runs `<cargo>`. In both these cases it adds its own
+options to control cargo's behaviour. In both of these cases
+nailing-cargo looks at `<subcmd>` to determine the cargo subcommand
+being run: this controls various defaults, to try to do the right
+things.
+
+In the third syntax, nailing-cargo runs `<build-command>...` without
+additional arguments and does not attempt to identify the cargo
+subcommand(s) that it will run. Possibly it will be necessary to pass
+`--online` or `--cargo-lock-update`, or even `--cargo-*arg*`
+
+### Invocation argument disambiguation rules ###
+
+For authors of tools which call nailing-cargo (and pedants):
+NB: The usages overlap in syntax!
+nailing-cargo follows the following rules when
+ interpreting its command line:
+
+ * The first option not recognised as a nailing-cargo option is
+ treated as the start of the `<cargo-opts>`.
+
+ * `<cargo-opts>` are terminated by `--` (which is removed) or the
+ first argument which does not start with a `-`.
+
+ (It is not possible to get nailing-cargo to pass the value `--`
+ as a separate argument to a cargo global option, but cargo global
+ options can typically take the values cuddled with `=`, so doing
+ that is not necessary.)
+
+ * After `---`, nailing-cargo will search for a `--`, to the end of
+ the arguments if necessary. The position of the `--` determines
+ whether this is usage 2 or usage 3, and what `<subcmd>` is.
+
+ If the arguments after `nailing-cargo ... ---` might contain `--`
+ anywhere, an explicit `--` should be passed.
+
+ * If no `--` appears after `---`, the word after `---` is the
+ command to run; if its final pathname component contains the
+ string `cargo`, it is treated as `<cargo>` (implying usage 2 and
+ the search for `<subcmd>`). Otherwise it is treated as
+ `<build-command>` (usage 3).
+
+Options
+-------