Document using extra dicts with pre-commit

README.md

@@ -8,42 +8,17 @@ 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
 ```
 
-## Setup Custom Dictionary
+## How-To Guides and Configuration Examples
 
-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".
+* [Use Dictionaries from `cspell-dicts`](docs/use-dictionaries-from-cspell-dicts.md)
+* [Use a Custom Dictionary](docs/use-a-custom-dictionary.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
 

docs/file-or-folder-based-overrides.md

@@ -0,0 +1,168 @@
+# 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.
+
+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.7.0
+    hooks:
+    - id: cspell
+  ```
+
+#### Triggering CSpell using `pre-commit`
+
+* Stage all files
+
+  ```
+  git add --all .
+  ```
+
+* Check all files in `git` against `pre-commit` hooks
+
+  ``` bash
+  pre-commit run --all-files
+  ```
+
+* OR commit the changes
+
+  ``` bash
+  git commit
+  ```
+
+### Via Command line
+
+* Execute
+
+  ``` bash
+  cspell '**'
+  ```

docs/pre-commit-example-setup-for-french.md

@@ -0,0 +1,148 @@
+# Example `pre-commit` setup for French
+<!--- 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.7.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 `mots-française.md` containing:
+
+```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
+
+## 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",
+      "language": "fr,fr-fr,fr-90"
+    }
+  ],
+  "version": "0.2"
+}
+```
+
+And the following, as `mots-française.md`:
+
+``` markdown
+# Testing french in Markdown
+
+## Les mots
+
+Voici, nous avons les mots française
+```
+
+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
+
+### 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 .
+  ```
+
+* Check all files in `git` against `pre-commit` hooks
+
+  ``` bash
+  pre-commit run --all-files
+  ```
+
+* OR commit the changes
+
+  ``` bash
+  git commit
+  ```
+
+### Via Command line
+
+* Execute
+
+  ``` bash
+  cspell '**'
+  ```

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".
+