Document using extra dictionaries with pre-commit

This closes streetsidesoftware#206 and stems from
streetsidesoftware/cspell#3426
where I had to dig around rather a lot to pull the pieces together.
Hopefully the docs make life easier for the next person who wants
to do this kind of thing.

Signed-off-by: Daniel F. Dickinson <[email protected]>

README.md

@@ -22,6 +22,16 @@ default is to only apply from within VSCode for files of type `shellscript`).
 
 [Using CSpell overrides](docs/README-OVERRIDES.md)
 
+### Using dictionaries from `cspell-dicts`
+
+For example, using the fr_FR and fr_FR_90 dictionaries when local is `fr`
+
+[Using extra CSpell dictionaries with
+`pre-commit`](docs/README-PRE-COMMIT-EXTRA-DICTS.md)
+
+You can of course combine using override with using dictionaries from
+`cspell-dicts`.
+
 ### Setup Custom Dictionary
 
 To use a custom dictionary with the `pre-commit` hook, create either a `cspell.config.yaml` or `cspell.json` file in your project's root directory.

docs/README-PRE-COMMIT-EXTRA-DICTS.md

@@ -0,0 +1,111 @@
+# Using extra CSpell dictionaries with `pre-commit`
+
+## Common configuration
+
+### `pre-commit-config.yaml` configuration
+
+Extend the `pre-commit` hook config from the [README.md](../README.md) with
+`additional_dependencies`. For example:
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/streetsidesoftware/cspell-cli
+    rev: v6.2.0
+    hooks:
+      - id: cspell
+        additional_dependencies:
+          - "@cspell/dict-fr-fr"
+          - "@cspell/dict-fr-reforme"
+
+```
+
+For a complete list of available dictionaries,
+see: <https://github.com/streetsidesoftware/cspell-dicts>.
+
+## Using French as the locale
+
+Use a `cspell.json` such as the following:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
+  "import": [
+    "@cspell/dict-fr-fr/cspell-ext.json",
+    "@cspell/dict-fr-reforme/cspell-ext.json"
+  ],
+  "language": "fr",
+  "version": "0.2"
+}
+```
+
+A file such as `test2.md` containing:
+
+```markdown
+# Testing french in Markdown
+
+## Les mots
+
+Voici, nous avons les mots française.
+```
+
+When `cspell` is invoked `test2.md` should not show errors
+
+## Applying to specific files
+
+And to apply those dictionaries to files with the `.md` extension (Markdown),
+use a `cspell.json` such as:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
+  "import": [
+    "@cspell/dict-fr-fr/cspell-ext.json",
+    "@cspell/dict-fr-reforme/cspell-ext.json"
+  ],
+  "overrides": [
+    {
+      "filename": "**/{*.md,*.txt}",
+      "language": "fr,fr-fr,fr-90"
+    }
+  ],
+  "version": "0.2"
+}
+```
+
+And the following, as `test2.md` and as `test2.err`:
+
+``` markdown
+# Testing french in Markdown
+
+## Les mots
+
+Voici, nous avons les mots française
+```
+
+When `cspell` is invoked `test2.md` should not show errors, but `test2.err`
+should.
+
+## Invoking CSpell
+
+### `pre-commit`
+
+With [pre-commit](https://pre-commit.com) installed:
+
+1. Use a config such as the one above
+2. Stage all files (e.g. `git add --all .`)
+3. Execute:
+
+   ``` bash
+   pre-commit run --all-files
+   ```
+
+   OR commit the changes
+
+   ``` bash
+   git commit
+   ```
+
+### Command line
+
+`cspell ./test2.*`