The documentation sounded like options where handled in a fairly
standard way, meaning options and `--` could be anywhere in the
command line.
In reality, options have to be first, followed by `--`, then the key.
Document that behavior more explicitly, and add a test to detect if
this changes.