Document corner case parsing cell metadata fields in CLI

Because `--preserve-cell-metadata` can take zero or more arguments,
the argument parser assigns any positional arguments following this
flag as fields to preserve rather than notebook paths to process.
This means if you're not passing any custom fields to preserve, the
`--preserve-cell-metadata` flag needs to appear after the paths to
be processed, or the notebook path should be preceded with `--` to
tell the argument parser it's not an argument to
`--preserve-cell-metadata`.

README.md

@@ -57,18 +57,40 @@ nb-clean check < notebook.ipynb
 ```
 
 The check can be run with the following flags:
-* Check for empty cells: `-e` or `--remove-empty-cells`
-* Ignore checking cell metadata (optionally with a selection of metadata fields to ignore): `-m` or `--preserve-cell-metadata`
-* Ignore checking cell outputs: `-o` or `--preserve-cell-outputs`
-* Ignore checking cell execution counts: `-c` or `--preserve-execution-counts`
-* Ignore checking notebook metadata (such as language version): `-n` or `--preserve-notebook-metadata`
 
-For example, to check if the notebook is clean but ignoring notebook metadata:
+- To check for empty cells use `--remove-empty-cells` or the short form `-e`.
+- To ignore checking for cell metadata use `--preserve-cell-metadata` or the
+  short form `-m`. This will ignore all metadata fields. You can also pass a
+  list of fields to ignore with `--preserve-cell-metadata field1 field2` or
+  `-m field1 field2`. Note that when not passing a list of fields, either the
+  `-m` or `--preserve-cell-metadata` flag must be passed _after_ the notebook
+  paths to process, or the the notebook paths should be preceded with `--` so
+  they are not interpreted as metadata fields.
+- To ignore checking for cell outputs use `--preserve-cell-outputs` or the short
+  form `-o`.
+- To ignore checking for cell execution counts use `--preserve-execution-counts`
+  or the short form `-c`.
+- To ignore checking for notebook metadata (such as language version) use
+  `--preserve-notebook-metadata` or the short form `-n`.
+
+For example, to check if a notebook is clean but ignoring notebook metadata:
 
 ```bash
 nb-clean check --preserve-notebook-metadata notebook.ipynb
 ```
 
+To check if a notebook is clean, ignoring all cell metadata:
+
+```bash
+nb-clean check --preserve-cell-metadata -- notebook.ipynb
+```
+
+To check if a notebook is clean, ignoring only the `tags` cell metadata field:
+
+```bash
+nb-clean check --preserve-cell-metadata tags -- notebook.ipynb
+```
+
 `nb-clean` will exit with status code 0 if the notebook is clean, and status
 code 1 if it is not. `nb-clean` will also print details of cell execution
 counts, metadata, outputs, and empty cells it finds.
@@ -90,18 +112,39 @@ nb-clean clean < original.ipynb > cleaned.ipynb
 ```
 
 The cleaning can be run with the following flags:
-* Remove empty cells: `-e` or `--remove-empty-cells`
-* Preserve cell metadata (optionally with a selection of metadata fields to preserve): `-m` or `--preserve-cell-metadata`
-* Preserve cell outputs: `-o` or `--preserve-cell-outputs`
-* Preserve cell execution counts: `-c` or `--preserve-execution-counts`
-* Preserve notebook metadata (such as language version): `-n` or `--preserve-notebook-metadata`
 
-For example, to check if the notebook is clean but preserving notebook metadata:
+- To remove empty cells use `--remove-empty-cells` or the short form `-e`.
+- To preserve cell metadata use `--preserve-cell-metadata` or the short form
+  `-m`. This will preserve all metadata fields. You can also pass a list of
+  fields to preserve with `--preserve-cell-metadata field1 field2` or
+  `-m field1 field2`. Note that when not passing a list of fields, either the
+  `-m` or `--preserve-cell-metadata` flag must be passed _after_ the notebook
+  paths to process, or the the notebook paths should be preceded with `--` so
+  they are not interpreted as metadata fields.
+- To preserve cell outputs use `--preserve-cell-outputs` or the short form `-o`.
+- To preserve cell execution counts use `--preserve-execution-counts` or the
+  short form `-c`.
+- To preserve notebook metadata (such as language version) use
+  `--preserve-notebook-metadata` or the short form `-n`.
+
+For example, to clean a notebook whilst preserving notebook metadata:
 
 ```bash
 nb-clean clean --preserve-notebook-metadata notebook.ipynb
 ```
 
+To clean a notebook, preserving all cell metadata:
+
+```bash
+nb-clean clean --preserve-cell-metadata -- notebook.ipynb
+```
+
+To clean a notebook, preserving only the `tags` cell metadata field:
+
+```bash
+nb-clean clean --preserve-cell-metadata tags -- notebook.ipynb
+```
+
 ### Cleaning (Git filter)
 
 To add a filter to an existing Git repository to automatically clean notebooks
@@ -219,16 +262,16 @@ that of `nb-clean` >=2.0.0.
 The examples in the table uses long flags, but short flags can also be used
 instead.
 
-| Description                             | `nb-clean` 1.6.0                                                 | `nb-clean` >=2.0.0                                       |
-| --------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
-| Clean notebook                          | `nb-clean clean --input notebook.ipynb \| sponge notebook.ipynb` | `nb-clean clean notebook.ipynb`                          |
-| Clean notebook (remove empty cells)     | `nb-clean clean --input --remove-empty notebook.ipynb`           | `nb-clean clean --remove-empty-cells notebook.ipynb`     |
-| Clean notebook (preserve cell metadata) | `nb-clean clean --input --preserve-metadata notebook.ipynb`       | `nb-clean clean --preserve-cell-metadata notebook.ipynb` |
-| Check notebook                          | `nb-clean check --input notebook.ipynb`                          | `nb-clean check notebook.ipynb`                          |
-| Check notebook (ignore non-empty cells) | `nb-clean check --input --remove-empty notebook.ipynb`           | `nb-clean check --remove-empty-cells notebook.ipynb`     |
-| Check notebook (ignore cell metadata)   | `nb-clean check --input --preserve-metadata notebook.ipynb`      | `nb-clean check --preserve-cell-metadata notebook.ipynb` |
-| Add Git filter to clean notebooks       | `nb-clean configure-git`                                         | `nb-clean add-filter`                                    |
-| Remove Git filter                       | `nb-clean unconfigure-git`                                       | `nb-clean remove-filter`                                 |
+| Description                                 | `nb-clean` 1.6.0                                                 | `nb-clean` >=2.0.0                                          |
+| ------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------- |
+| Clean notebook                              | `nb-clean clean --input notebook.ipynb \| sponge notebook.ipynb` | `nb-clean clean notebook.ipynb`                             |
+| Clean notebook (remove empty cells)         | `nb-clean clean --input --remove-empty notebook.ipynb`           | `nb-clean clean --remove-empty-cells notebook.ipynb`        |
+| Clean notebook (preserve all cell metadata) | `nb-clean clean --input --preserve-metadata notebook.ipynb`      | `nb-clean clean --preserve-cell-metadata -- notebook.ipynb` |
+| Check notebook                              | `nb-clean check --input notebook.ipynb`                          | `nb-clean check notebook.ipynb`                             |
+| Check notebook (ignore non-empty cells)     | `nb-clean check --input --remove-empty notebook.ipynb`           | `nb-clean check --remove-empty-cells notebook.ipynb`        |
+| Check notebook (ignore all cell metadata)   | `nb-clean check --input --preserve-metadata notebook.ipynb`      | `nb-clean check --preserve-cell-metadata -- notebook.ipynb` |
+| Add Git filter to clean notebooks           | `nb-clean configure-git`                                         | `nb-clean add-filter`                                       |
+| Remove Git filter                           | `nb-clean unconfigure-git`                                       | `nb-clean remove-filter`                                    |
 
 ## Copyright