From 0c8c6c5d5a3e902b7728ba8cb21a55a6dec7b4e3 Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 02:00:58 -0400
Subject: [PATCH 01/14] Add doc of using overrides with pre-commit

Document using included dictionaries on files for which they are not normally used
(for example, Bash words on Markdown or text files), when using `pre-commit`.

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 README.md                | 11 +++++-
 docs/README-OVERRIDES.md | 78 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 88 insertions(+), 1 deletion(-)
 create mode 100644 docs/README-OVERRIDES.md

diff --git a/README.md b/README.md
index bd65c31..b6cad74 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,16 @@ repos:
       - id: cspell
 ```
 
-## Setup Custom Dictionary
+## Using additional dictionaries
+
+### Using included dictionaries on non-standard files
+
+For example, using Bash dictionary with Markdown or text files, by filename (the
+default is to only apply from within VSCode for files of type `shellscript`).
+
+[Using CSpell overrides](docs/README-OVERRIDES.md)
+
+### 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.
 
diff --git a/docs/README-OVERRIDES.md b/docs/README-OVERRIDES.md
new file mode 100644
index 0000000..8b48ed8
--- /dev/null
+++ b/docs/README-OVERRIDES.md
@@ -0,0 +1,78 @@
+# Using CSpell overrides
+
+This is the same for use with `pre-commit` as with other methods of invoking
+`cspell`, namely configuring an `overrides` section on your `cspell.json`
+or equivalent file.
+
+The [current overrides documentation on the
+website](https://cspell.org/configuration/overrides/) is rather sparse, so here
+is another example.
+
+## Using Bash dictionary with Markdown or text files by filename
+
+Given a `cspell.json` as follows:
+
+``` json
+{
+  "language": "en",
+  "overrides": [
+      {
+          "dictionaries": [
+              "bash"
+          ],
+          "filename": "**/{*.md,*.txt}"
+      }
+  ],
+  "version": "0.2"
+}
+```
+
+And the following, as `test1.md` and as `test1.err`:
+
+``` markdown
+## Sample code block
+
+    if grep -r "something" .; then
+        echo "Found"
+    fi
+
+    case "a string with 3" in
+    with)
+        echo "Why?"
+        ;;
+    esac
+
+    . ./.bash_aliases
+
+    # We should use getopts
+
+    shopt -p
+
+## And another topic
+
+Words, many words.
+```
+
+When `cspell` is invoked `test1.md` should not show errors, but `test1.err`
+should.
+
+## Invoking CSpell
+
+### `pre-commit`
+
+Use a config such as the one in the [README.md](../README.md), stage all files
+(e.g. `git add --all .`), and execute:
+
+``` bash
+pre-commit run --all-files
+```
+
+or commit the changes
+
+``` bash
+git commit
+```
+
+### Command line
+
+`cspell ./test1.*`

From 5206efb20ff33a2d1481b5d4175fb818b062a7f1 Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 02:06:53 -0400
Subject: [PATCH 02/14] Document using extra dictionaries with pre-commit

This closes #206 and stems from
https://github.com/streetsidesoftware/cspell/discussions/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 <dfdpublic@wildtechgarden.ca>
---
 README.md                             |  10 +++
 docs/README-PRE-COMMIT-EXTRA-DICTS.md | 111 ++++++++++++++++++++++++++
 2 files changed, 121 insertions(+)
 create mode 100644 docs/README-PRE-COMMIT-EXTRA-DICTS.md

diff --git a/README.md b/README.md
index b6cad74..5af44f2 100644
--- a/README.md
+++ b/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.
diff --git a/docs/README-PRE-COMMIT-EXTRA-DICTS.md b/docs/README-PRE-COMMIT-EXTRA-DICTS.md
new file mode 100644
index 0000000..a7a1660
--- /dev/null
+++ b/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.*`

From 35653cba0439df1667bf89aa1f003a51c162eca9 Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 08:04:08 -0400
Subject: [PATCH 03/14] Fix nested code block (use Markdown nesting syntax)

Use Markdown nesting syntax rather than indented code block for
for the nested code block.

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 docs/README-OVERRIDES.md | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/docs/README-OVERRIDES.md b/docs/README-OVERRIDES.md
index 8b48ed8..24542a4 100644
--- a/docs/README-OVERRIDES.md
+++ b/docs/README-OVERRIDES.md
@@ -29,29 +29,31 @@ Given a `cspell.json` as follows:
 
 And the following, as `test1.md` and as `test1.err`:
 
-``` markdown
+```` markdown
 ## Sample code block
 
-    if grep -r "something" .; then
-        echo "Found"
-    fi
+```sh
+if grep -r "something" .; then
+    echo "Found"
+fi
 
-    case "a string with 3" in
-    with)
-        echo "Why?"
-        ;;
-    esac
+case "a string with 3" in
+with)
+    echo "Why?"
+    ;;
+esac
 
-    . ./.bash_aliases
+. ./.bash_aliases
 
-    # We should use getopts
+# We should use getopts
 
-    shopt -p
+shopt -p
+```
 
 ## And another topic
 
 Words, many words.
-```
+````
 
 When `cspell` is invoked `test1.md` should not show errors, but `test1.err`
 should.

From b81a51cc6c4745f0458d756ceb728509d3db6549 Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 09:25:53 -0400
Subject: [PATCH 04/14] Ignore other dict words in examples when doing CI

Prevent GitHub workflow (CI) from failing on run of CSpell over the examples
of words not in the default dictionaries, when the workflow is using only
the default dictionaries.

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 docs/README-OVERRIDES.md              | 1 +
 docs/README-PRE-COMMIT-EXTRA-DICTS.md | 1 +
 2 files changed, 2 insertions(+)

diff --git a/docs/README-OVERRIDES.md b/docs/README-OVERRIDES.md
index 24542a4..ae22277 100644
--- a/docs/README-OVERRIDES.md
+++ b/docs/README-OVERRIDES.md
@@ -1,4 +1,5 @@
 # Using CSpell overrides
+<!--- cspell:ignore esac getopts shopt --->
 
 This is the same for use with `pre-commit` as with other methods of invoking
 `cspell`, namely configuring an `overrides` section on your `cspell.json`
diff --git a/docs/README-PRE-COMMIT-EXTRA-DICTS.md b/docs/README-PRE-COMMIT-EXTRA-DICTS.md
index a7a1660..9730f14 100644
--- a/docs/README-PRE-COMMIT-EXTRA-DICTS.md
+++ b/docs/README-PRE-COMMIT-EXTRA-DICTS.md
@@ -1,4 +1,5 @@
 # Using extra CSpell dictionaries with `pre-commit`
+<!--- cspell:ignore Voici nous avons française reforme --->
 
 ## Common configuration
 

From 0afd640534b82b007d56d7f00dad9ccba580cb85 Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 19:47:54 -0400
Subject: [PATCH 05/14] Use an extensible how-to and examples section

Per review comments, tidy up the README references to the how-tos and
configuration examples, and use a title / format to which more docs can
be easily added.

In the process, add a preliminary version of an example setup for French.
Currently a copy of the extra-dics example/how-to but will become a
unique document.

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 README.md                                    |  21 +---
 docs/README-PRE-COMMIT-EXAMPLE-FOR-FRENCH.md | 112 +++++++++++++++++++
 2 files changed, 116 insertions(+), 17 deletions(-)
 create mode 100644 docs/README-PRE-COMMIT-EXAMPLE-FOR-FRENCH.md

diff --git a/README.md b/README.md
index 5af44f2..ce67e56 100644
--- a/README.md
+++ b/README.md
@@ -13,24 +13,11 @@ repos:
       - id: cspell
 ```
 
-## Using additional dictionaries
+## How-To Guides and Configuration Examples
 
-### Using included dictionaries on non-standard files
-
-For example, using Bash dictionary with Markdown or text files, by filename (the
-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`.
+* [Use Dictionaries from `cspell-dicts`](docs/README-PRE-COMMIT-EXTRA-DICTS.md)
+* [Use a Different Dictionary Based Upon the Filename](docs/README-OVERRIDES.md)
+* [Example `pre-commit` Setup for French](docs/README-PRE-COMMIT-EXAMPLE-FOR-FRENCH.md)
 
 ### Setup Custom Dictionary
 
diff --git a/docs/README-PRE-COMMIT-EXAMPLE-FOR-FRENCH.md b/docs/README-PRE-COMMIT-EXAMPLE-FOR-FRENCH.md
new file mode 100644
index 0000000..9730f14
--- /dev/null
+++ b/docs/README-PRE-COMMIT-EXAMPLE-FOR-FRENCH.md
@@ -0,0 +1,112 @@
+# Using extra CSpell dictionaries with `pre-commit`
+<!--- cspell:ignore Voici nous avons française reforme --->
+
+## 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.*`

From 9909f3ee72d140d96c0459630530be1f43db9638 Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 19:57:39 -0400
Subject: [PATCH 06/14] Document file/folder-based overrides

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 README.md                                 |   2 +-
 docs/README-FILE-FOLDER-BASED-OVERRIDE.md | 165 ++++++++++++++++++++++
 docs/README-OVERRIDES.md                  |  81 -----------
 3 files changed, 166 insertions(+), 82 deletions(-)
 create mode 100644 docs/README-FILE-FOLDER-BASED-OVERRIDE.md
 delete mode 100644 docs/README-OVERRIDES.md

diff --git a/README.md b/README.md
index ce67e56..95dfbf6 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ repos:
 ## How-To Guides and Configuration Examples
 
 * [Use Dictionaries from `cspell-dicts`](docs/README-PRE-COMMIT-EXTRA-DICTS.md)
-* [Use a Different Dictionary Based Upon the Filename](docs/README-OVERRIDES.md)
+* [Use a Different Dictionary Based Upon the Filename](docs/README-FILE-FOLDER-BASED-OVERRIDE.md)
 * [Example `pre-commit` Setup for French](docs/README-PRE-COMMIT-EXAMPLE-FOR-FRENCH.md)
 
 ### Setup Custom Dictionary
diff --git a/docs/README-FILE-FOLDER-BASED-OVERRIDE.md b/docs/README-FILE-FOLDER-BASED-OVERRIDE.md
new file mode 100644
index 0000000..a1ff538
--- /dev/null
+++ b/docs/README-FILE-FOLDER-BASED-OVERRIDE.md
@@ -0,0 +1,165 @@
+# Using Different Dictionaries Based on Filename
+<!--- cspell:ignore esac getopts shopt --->
+
+For example, using Bash dictionary with Markdown or text files, by filename (the
+default is to only apply from within VSCode for files of type `shellscript`).
+
+This is the same for use with `pre-commit` as with other methods of invoking
+`cspell`, namely configuring an `overrides` section on your `cspell.json`
+or equivalent file.
+
+The [current overrides documentation on the
+website](https://cspell.org/configuration/overrides/) covers a different type of
+scenario, so here is an example of selecting adding a dictionary to apply to
+specific folders.
+
+## Using Bash dictionary with Markdown or text files by filename
+
+Given a `cspell.json` as follows:
+
+``` json
+{
+  "overrides": [
+      {
+          "filename": ["**/bash_examples/**", "**/bash_docs/**.md"],
+          "dictionaries": [
+              "bash"
+          ]
+      }
+  ],
+  "version": "0.2"
+}
+```
+
+Add the following code as `docs/bash_docs/a-silly-bash-code-block.md`
+
+```` markdown
+## Sample code block
+
+```sh
+if grep -r "something" .; then
+    echo "Found"
+fi
+
+case "a string with 3" in
+with)
+    echo "Why?"
+    ;;
+esac
+
+. ./.bash_aliases
+
+# We should use getopts
+
+shopt -p
+```
+
+## And another topic
+
+Words, many words.
+````
+
+Add the following file as `examples/bash_examples/a-silly-bash-script`
+
+``` markdown
+#!/bin/bash
+
+if grep -r "something" .; then
+    echo "Found"
+fi
+
+case "a string with 3" in
+with)
+    echo "Why?"
+    ;;
+esac
+
+. ./.bash_aliases
+
+# We should use getopts
+
+shopt -p
+```
+
+And add the following code as `docs/about.md`
+
+```` markdown
+# Just a rather eccentric bash and markdown example for documentation purposes
+
+## Sample code block
+
+```sh
+if grep -r "something" .; then
+    echo "Found"
+fi
+
+case "a string with 3" in
+with)
+    echo "Why?"
+    ;;
+esac
+
+. ./.bash_aliases
+
+# We should use getopts
+
+shopt -p
+```
+
+## And another topic
+
+Words, many words.
+````
+
+When `cspell` is invoked only `docs/about.md` should show errors.
+
+## Invoking CSpell
+
+### Via [`pre-commit`](https://pre-commit.com)
+
+#### Prerequisites
+
+* Project folder initialized as a git repository via `git init` or as part of a
+git repository cloned via `git clone`
+* ['pre-commit' installed](https://pre-commit.com/#install)
+* A `.pre-commit-config.yaml` such as:
+
+  ```yaml
+  fail_fast: true
+  minimum_pre_commit_version: 2.18.1
+
+  repos:
+  - repo: "https://github.com/streetsidesoftware/cspell-cli"
+    rev: v6.5.0
+    hooks:
+    - id: cspell
+  ```
+
+#### Triggering CSpell using `pre-commit`
+
+* Stage all files
+
+  ```
+  git add --all .
+  ```
+
+* Execute:
+
+  ``` bash
+  pre-commit run --all-files
+  ```
+
+  OR commit the changes
+
+  ``` bash
+  git commit
+  ```
+
+### Via Command line
+
+* Execute
+
+  ``` bash
+  cspell '**'
+  ```
+
diff --git a/docs/README-OVERRIDES.md b/docs/README-OVERRIDES.md
deleted file mode 100644
index ae22277..0000000
--- a/docs/README-OVERRIDES.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# Using CSpell overrides
-<!--- cspell:ignore esac getopts shopt --->
-
-This is the same for use with `pre-commit` as with other methods of invoking
-`cspell`, namely configuring an `overrides` section on your `cspell.json`
-or equivalent file.
-
-The [current overrides documentation on the
-website](https://cspell.org/configuration/overrides/) is rather sparse, so here
-is another example.
-
-## Using Bash dictionary with Markdown or text files by filename
-
-Given a `cspell.json` as follows:
-
-``` json
-{
-  "language": "en",
-  "overrides": [
-      {
-          "dictionaries": [
-              "bash"
-          ],
-          "filename": "**/{*.md,*.txt}"
-      }
-  ],
-  "version": "0.2"
-}
-```
-
-And the following, as `test1.md` and as `test1.err`:
-
-```` markdown
-## Sample code block
-
-```sh
-if grep -r "something" .; then
-    echo "Found"
-fi
-
-case "a string with 3" in
-with)
-    echo "Why?"
-    ;;
-esac
-
-. ./.bash_aliases
-
-# We should use getopts
-
-shopt -p
-```
-
-## And another topic
-
-Words, many words.
-````
-
-When `cspell` is invoked `test1.md` should not show errors, but `test1.err`
-should.
-
-## Invoking CSpell
-
-### `pre-commit`
-
-Use a config such as the one in the [README.md](../README.md), stage all files
-(e.g. `git add --all .`), and execute:
-
-``` bash
-pre-commit run --all-files
-```
-
-or commit the changes
-
-``` bash
-git commit
-```
-
-### Command line
-
-`cspell ./test1.*`

From d4b1cf8c6cb4f055bc6b587562cdf7bb63a6dd14 Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 22:13:16 -0400
Subject: [PATCH 07/14] Use lowercase filenames in docs folder

And drop the README- prefix. This looks better and is more easily transferred
to the main docs.

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 README.md                                                   | 6 +++---
 ...-BASED-OVERRIDE.md => file-or-folder-based-overrides.md} | 0
 ...FOR-FRENCH.md => pre-commit-example-setup-for-french.md} | 0
 ...EXTRA-DICTS.md => use-dictionaries-from-cspell-dicts.md} | 0
 4 files changed, 3 insertions(+), 3 deletions(-)
 rename docs/{README-FILE-FOLDER-BASED-OVERRIDE.md => file-or-folder-based-overrides.md} (100%)
 rename docs/{README-PRE-COMMIT-EXAMPLE-FOR-FRENCH.md => pre-commit-example-setup-for-french.md} (100%)
 rename docs/{README-PRE-COMMIT-EXTRA-DICTS.md => use-dictionaries-from-cspell-dicts.md} (100%)

diff --git a/README.md b/README.md
index 95dfbf6..5e294b9 100644
--- a/README.md
+++ b/README.md
@@ -15,9 +15,9 @@ repos:
 
 ## How-To Guides and Configuration Examples
 
-* [Use Dictionaries from `cspell-dicts`](docs/README-PRE-COMMIT-EXTRA-DICTS.md)
-* [Use a Different Dictionary Based Upon the Filename](docs/README-FILE-FOLDER-BASED-OVERRIDE.md)
-* [Example `pre-commit` Setup for French](docs/README-PRE-COMMIT-EXAMPLE-FOR-FRENCH.md)
+* [Use Dictionaries from `cspell-dicts`](docs/use-dictionaries-from-cspell-dicts.md)
+* [Use a Different Dictionary Based Upon the Filename](docs/file-or-folder-based-overrides.md)
+* [Example `pre-commit` Setup for French](docs/pre-commit-example-setup-for-french.md)
 
 ### Setup Custom Dictionary
 
diff --git a/docs/README-FILE-FOLDER-BASED-OVERRIDE.md b/docs/file-or-folder-based-overrides.md
similarity index 100%
rename from docs/README-FILE-FOLDER-BASED-OVERRIDE.md
rename to docs/file-or-folder-based-overrides.md
diff --git a/docs/README-PRE-COMMIT-EXAMPLE-FOR-FRENCH.md b/docs/pre-commit-example-setup-for-french.md
similarity index 100%
rename from docs/README-PRE-COMMIT-EXAMPLE-FOR-FRENCH.md
rename to docs/pre-commit-example-setup-for-french.md
diff --git a/docs/README-PRE-COMMIT-EXTRA-DICTS.md b/docs/use-dictionaries-from-cspell-dicts.md
similarity index 100%
rename from docs/README-PRE-COMMIT-EXTRA-DICTS.md
rename to docs/use-dictionaries-from-cspell-dicts.md

From fcdc2a6e2babdd165e0f08357942994de69fc8e1 Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 22:14:29 -0400
Subject: [PATCH 08/14] Tweak file/folder overrides doc

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 docs/file-or-folder-based-overrides.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/file-or-folder-based-overrides.md b/docs/file-or-folder-based-overrides.md
index a1ff538..c726027 100644
--- a/docs/file-or-folder-based-overrides.md
+++ b/docs/file-or-folder-based-overrides.md
@@ -143,13 +143,13 @@ git repository cloned via `git clone`
   git add --all .
   ```
 
-* Execute:
+* Check all files in `git` against `pre-commit` hooks
 
   ``` bash
   pre-commit run --all-files
   ```
 
-  OR commit the changes
+* OR commit the changes
 
   ``` bash
   git commit

From 228514b499ecd51b19bb6ce95765f5eb92d2162a Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 22:19:03 -0400
Subject: [PATCH 09/14] Move using a custom dictionary to file under 'docs'

This is more consistent with the other dictionary examples and how-tos.

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 README.md                       | 33 +--------------------------------
 docs/use-a-custom-dictionary.md | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 32 deletions(-)
 create mode 100644 docs/use-a-custom-dictionary.md

diff --git a/README.md b/README.md
index 5e294b9..1766162 100644
--- a/README.md
+++ b/README.md
@@ -16,41 +16,10 @@ repos:
 ## How-To Guides and Configuration Examples
 
 * [Use Dictionaries from `cspell-dicts`](docs/use-dictionaries-from-cspell-dicts.md)
+* [Use a Custom Dictionary](docs/use-a-custom-dictionary.md)
 * [Use a Different Dictionary Based Upon the Filename](docs/file-or-folder-based-overrides.md)
 * [Example `pre-commit` Setup for French](docs/pre-commit-example-setup-for-french.md)
 
-### 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.
-
-`cspell.config.yaml`
-
-```yaml
-dictionaryDefinitions:
-  - name: myWords
-    path: ./path/to/cSpell_dict.txt
-    addWords: true
-dictionaries:
-  - myWords
-```
-
-`cSpell.json`
-
-```json
-{
-  "dictionaryDefinitions": [
-    {
-      "name": "myWords",
-      "path": "./path/to/cSpell_dict.txt",
-      "addWords": true
-    }
-  ],
-  "dictionaries": ["myWords"]
-}
-```
-
-If you installed the [Code Spell Checker extension](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) for VS Code, this can be done automatically from the command palette by running "Spell: Create a CSpell configuration file".
-
 ## Install from GitHub
 
 This repo also allows installing the `cspell-cli` directly from GitHub:
diff --git a/docs/use-a-custom-dictionary.md b/docs/use-a-custom-dictionary.md
new file mode 100644
index 0000000..f847724
--- /dev/null
+++ b/docs/use-a-custom-dictionary.md
@@ -0,0 +1,32 @@
+# 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.
+
+`cspell.config.yaml`
+
+```yaml
+dictionaryDefinitions:
+  - name: myWords
+    path: ./path/to/cSpell_dict.txt
+    addWords: true
+dictionaries:
+  - myWords
+```
+
+`cSpell.json`
+
+```json
+{
+  "dictionaryDefinitions": [
+    {
+      "name": "myWords",
+      "path": "./path/to/cSpell_dict.txt",
+      "addWords": true
+    }
+  ],
+  "dictionaries": ["myWords"]
+}
+```
+
+If you installed the [Code Spell Checker extension](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) for VS Code, this can be done automatically from the command palette by running "Spell: Create a CSpell configuration file".
+

From 8720b5c2336ed7771f19ff80052504eba59985aa Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 22:47:24 -0400
Subject: [PATCH 10/14] Update documentation examples to cspell v6.7.0

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 README.md                                   | 2 +-
 docs/file-or-folder-based-overrides.md      | 2 +-
 docs/pre-commit-example-setup-for-french.md | 2 +-
 docs/use-dictionaries-from-cspell-dicts.md  | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 1766162..3625233 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ This repository enables using [cspell](https://github.com/streetsidesoftware/csp
 # .pre-commit-config.yaml
 repos:
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v6.2.0
+    rev: v6.7.0
     hooks:
       - id: cspell
 ```
diff --git a/docs/file-or-folder-based-overrides.md b/docs/file-or-folder-based-overrides.md
index c726027..b31c140 100644
--- a/docs/file-or-folder-based-overrides.md
+++ b/docs/file-or-folder-based-overrides.md
@@ -130,7 +130,7 @@ git repository cloned via `git clone`
 
   repos:
   - repo: "https://github.com/streetsidesoftware/cspell-cli"
-    rev: v6.5.0
+    rev: v6.7.0
     hooks:
     - id: cspell
   ```
diff --git a/docs/pre-commit-example-setup-for-french.md b/docs/pre-commit-example-setup-for-french.md
index 9730f14..ad814e0 100644
--- a/docs/pre-commit-example-setup-for-french.md
+++ b/docs/pre-commit-example-setup-for-french.md
@@ -12,7 +12,7 @@ Extend the `pre-commit` hook config from the [README.md](../README.md) with
 # .pre-commit-config.yaml
 repos:
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v6.2.0
+    rev: v6.7.0
     hooks:
       - id: cspell
         additional_dependencies:
diff --git a/docs/use-dictionaries-from-cspell-dicts.md b/docs/use-dictionaries-from-cspell-dicts.md
index 9730f14..ad814e0 100644
--- a/docs/use-dictionaries-from-cspell-dicts.md
+++ b/docs/use-dictionaries-from-cspell-dicts.md
@@ -12,7 +12,7 @@ Extend the `pre-commit` hook config from the [README.md](../README.md) with
 # .pre-commit-config.yaml
 repos:
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v6.2.0
+    rev: v6.7.0
     hooks:
       - id: cspell
         additional_dependencies:

From b814e437ac705af940d55d4e91afa46b5b2f0420 Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 23:04:32 -0400
Subject: [PATCH 11/14] Update file/folder example to note it adds a dictionary

That it is, the configuration does not disable any dictionaries
that otherwise apply.

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 README.md                              | 2 +-
 docs/file-or-folder-based-overrides.md | 5 ++++-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 3625233..7dbe2b0 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ repos:
 
 * [Use Dictionaries from `cspell-dicts`](docs/use-dictionaries-from-cspell-dicts.md)
 * [Use a Custom Dictionary](docs/use-a-custom-dictionary.md)
-* [Use a Different Dictionary Based Upon the Filename](docs/file-or-folder-based-overrides.md)
+* [Use an Extra Dictionary Based on the Folder or Filename](docs/file-or-folder-based-overrides.md)
 * [Example `pre-commit` Setup for French](docs/pre-commit-example-setup-for-french.md)
 
 ## Install from GitHub
diff --git a/docs/file-or-folder-based-overrides.md b/docs/file-or-folder-based-overrides.md
index b31c140..2e0039d 100644
--- a/docs/file-or-folder-based-overrides.md
+++ b/docs/file-or-folder-based-overrides.md
@@ -1,9 +1,12 @@
-# Using Different Dictionaries Based on Filename
+# Use an Extra Dictionary Based on the Folder or Filename
 <!--- cspell:ignore esac getopts shopt --->
 
 For example, using Bash dictionary with Markdown or text files, by filename (the
 default is to only apply from within VSCode for files of type `shellscript`).
 
+**Note**: This adds the Bash dictionary to the list of dictionaries against
+which to check the files, it does not check only against the Bash dictionary.
+
 This is the same for use with `pre-commit` as with other methods of invoking
 `cspell`, namely configuring an `overrides` section on your `cspell.json`
 or equivalent file.

From 58558528fccc62c121c639fc08991e0e2b4fc007 Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 23:24:22 -0400
Subject: [PATCH 12/14] Tweak whitespace

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 docs/file-or-folder-based-overrides.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/file-or-folder-based-overrides.md b/docs/file-or-folder-based-overrides.md
index 2e0039d..9340518 100644
--- a/docs/file-or-folder-based-overrides.md
+++ b/docs/file-or-folder-based-overrides.md
@@ -20,6 +20,7 @@ specific folders.
 
 Given a `cspell.json` as follows:
 
+
 ``` json
 {
   "overrides": [
@@ -165,4 +166,3 @@ git repository cloned via `git clone`
   ``` bash
   cspell '**'
   ```
-

From a42b76b87dcafbac50183f0b29fd29cf1189964b Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Fri, 19 Aug 2022 23:25:10 -0400
Subject: [PATCH 13/14] Improve example setup for French

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 docs/pre-commit-example-setup-for-french.md | 78 +++++++++++++++------
 1 file changed, 57 insertions(+), 21 deletions(-)

diff --git a/docs/pre-commit-example-setup-for-french.md b/docs/pre-commit-example-setup-for-french.md
index ad814e0..d8a6530 100644
--- a/docs/pre-commit-example-setup-for-french.md
+++ b/docs/pre-commit-example-setup-for-french.md
@@ -1,4 +1,4 @@
-# Using extra CSpell dictionaries with `pre-commit`
+# Example `pre-commit` setup for French
 <!--- cspell:ignore Voici nous avons française reforme --->
 
 ## Common configuration
@@ -40,7 +40,7 @@ Use a `cspell.json` such as the following:
 }
 ```
 
-A file such as `test2.md` containing:
+A file such as `mots-française.md` containing:
 
 ```markdown
 # Testing french in Markdown
@@ -50,7 +50,7 @@ A file such as `test2.md` containing:
 Voici, nous avons les mots française.
 ```
 
-When `cspell` is invoked `test2.md` should not show errors
+When `cspell` is invoked `mots-française.md` should not show errors
 
 ## Applying to specific files
 
@@ -66,7 +66,7 @@ use a `cspell.json` such as:
   ],
   "overrides": [
     {
-      "filename": "**/{*.md,*.txt}",
+      "filename": "**/*.md",
       "language": "fr,fr-fr,fr-90"
     }
   ],
@@ -74,7 +74,7 @@ use a `cspell.json` such as:
 }
 ```
 
-And the following, as `test2.md` and as `test2.err`:
+And the following, as `mots-française.md`:
 
 ``` markdown
 # Testing french in Markdown
@@ -84,29 +84,65 @@ And the following, as `test2.md` and as `test2.err`:
 Voici, nous avons les mots française
 ```
 
-When `cspell` is invoked `test2.md` should not show errors, but `test2.err`
-should.
+as again as `mots-française.err`:
+
+``` markdown
+# Testing french in Markdown
+
+## Les mots
+
+Voici, nous avons les mots française
+```
+
+When `cspell` is invoked `mots-française.md` should not show errors, but
+`mots-française.err` should.
 
 ## Invoking CSpell
 
-### `pre-commit`
+### Via [`pre-commit`](https://pre-commit.com)
+
+#### Prerequisites
+
+* Project folder initialized as a git repository via `git init` or as part of a
+git repository cloned via `git clone`
+* ['pre-commit' installed](https://pre-commit.com/#install)
+* A `.pre-commit-config.yaml` such as:
+
+  ```yaml
+  fail_fast: true
+  minimum_pre_commit_version: 2.18.1
+
+  repos:
+  - repo: "https://github.com/streetsidesoftware/cspell-cli"
+    rev: v6.7.0
+    hooks:
+    - id: cspell
+  ```
+
+#### Triggering CSpell using `pre-commit`
+
+* Stage all files
+
+  ```
+  git add --all .
+  ```
 
-With [pre-commit](https://pre-commit.com) installed:
+* Check all files in `git` against `pre-commit` hooks
 
-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
+  ```
 
-   ``` bash
-   pre-commit run --all-files
-   ```
+* OR commit the changes
 
-   OR commit the changes
+  ``` bash
+  git commit
+  ```
 
-   ``` bash
-   git commit
-   ```
+### Via Command line
 
-### Command line
+* Execute
 
-`cspell ./test2.*`
+  ``` bash
+  cspell '**'
+  ```

From d03630d78a3449c0548fe18f4717f10def770980 Mon Sep 17 00:00:00 2001
From: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
Date: Sat, 20 Aug 2022 00:29:51 -0400
Subject: [PATCH 14/14] Add documentation for using `cspell-dict` dictionaries

As noted, this mostly (only?) applies to language dictionaries as other
dictionaries are generally included by default, but only applied to
certain contexts (often a VSCode languageId for the programming language
dictionaries).

Signed-off-by: Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
---
 docs/use-dictionaries-from-cspell-dicts.md | 101 ++++++++++-----------
 1 file changed, 47 insertions(+), 54 deletions(-)

diff --git a/docs/use-dictionaries-from-cspell-dicts.md b/docs/use-dictionaries-from-cspell-dicts.md
index ad814e0..09392cf 100644
--- a/docs/use-dictionaries-from-cspell-dicts.md
+++ b/docs/use-dictionaries-from-cspell-dicts.md
@@ -1,7 +1,39 @@
 # Using extra CSpell dictionaries with `pre-commit`
-<!--- cspell:ignore Voici nous avons française reforme --->
 
-## Common configuration
+## Using dictionaries from `cspell-dicts`
+
+This is mostly (only?) needed for language dictionaries. Most if not all other
+dictionaries are installed (but not active except in particular contexts) by
+default. For those dictionaries see [Using file or folder based
+overrides](file-or-folder-based-overrides.md)
+
+### More information on `cspell-dicts`
+
+For a complete list of available dictionaries,
+see: <https://github.com/streetsidesoftware/cspell-dicts>.
+
+To see when the dictionary is applied by default, view
+
+`https://github.com/streetsidesoftware/cspell-dicts/dictionaries/<dictionary-name>/cspell-ext.json`
+
+### Viewing a dictionary's default context in `cspell-dicts`
+
+View the file
+`https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries/<dictionary-name>/cspell-ext.json`
+
+For example: `https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries/public-licenses/cspell-ext.json`
+
+``` json
+// Turn on the dictionary by default.
+// It can be turned off using `"dictionaries": ["!public-licenses"]
+"dictionaries": ["public-licenses"],
+"languageSettings": []
+```
+
+## Using non-English language dictionaries
+
+For a non-English language dictionary, continue here, or the see the
+[`pre-commit` example setup for French](pre-commit-example-setup-for-french.md).
 
 ### `pre-commit-config.yaml` configuration
 
@@ -11,20 +43,15 @@ Extend the `pre-commit` hook config from the [README.md](../README.md) with
 ```yaml
 # .pre-commit-config.yaml
 repos:
-  - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v6.7.0
-    hooks:
-      - id: cspell
-        additional_dependencies:
-          - "@cspell/dict-fr-fr"
-          - "@cspell/dict-fr-reforme"
-
+- repo: https://github.com/streetsidesoftware/cspell-cli
+  rev: v6.7.0
+  hooks:
+  - id: cspell
+    additional_dependencies:
+    - "@cspell/dict-nl-nl"
 ```
 
-For a complete list of available dictionaries,
-see: <https://github.com/streetsidesoftware/cspell-dicts>.
-
-## Using French as the locale
+### To make the 'nl-nl' dictionary available
 
 Use a `cspell.json` such as the following:
 
@@ -32,61 +59,27 @@ Use a `cspell.json` such as the following:
 {
   "$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"
+    "@cspell/dict-nl-nl/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
+### To make 'nl-nl' the default locale and use `dict-nl-nl`:
 
-And to apply those dictionaries to files with the `.md` extension (Markdown),
-use a `cspell.json` such as:
+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"
-  ],
-  "overrides": [
-    {
-      "filename": "**/{*.md,*.txt}",
-      "language": "fr,fr-fr,fr-90"
-    }
+    "@cspell/dict-nl-nl/cspell-ext.json"
   ],
+  "language": "nl-nl",
   "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`
@@ -109,4 +102,4 @@ With [pre-commit](https://pre-commit.com) installed:
 
 ### Command line
 
-`cspell ./test2.*`
+`cspell '**'`