Skip to content

Offline, privacy-first grammar checker. Fast, open-source, Rust-powered

docs: wrote page about contributing to the curated dictionary

Elijah Potter5540f2ca7a34
diff --git a/packages/harper.js/examples/commonjs-simple/yarn.lock b/packages/harper.js/examples/commonjs-simple/yarn.lock
index 9ebc976ec..f54ca7e98 100644
--- a/packages/harper.js/examples/commonjs-simple/yarn.lock
+++ b/packages/harper.js/examples/commonjs-simple/yarn.lock
@@ -2,13 +2,7 @@
# yarn lockfile v1
-harper.js@^0.13.0:
- version "0.13.0"
- resolved "https://registry.yarnpkg.com/harper.js/-/harper.js-0.13.0.tgz#f9e945c842f4e07e1b7042e3eef00a8040b2e0dd"
- integrity sha512-XjiQG7kpooKCU2xp46mvNra9PUq5n3z5kXOaWvKjOBRyWIllvuEwvDv40cEUODhWD2ABVTEMea8odXRORfyruw==
- dependencies:
- wasm "link:../../../../../../.cache/yarn/v6/npm-harper-js-0.13.0-f9e945c842f4e07e1b7042e3eef00a8040b2e0dd-integrity/harper-wasm/pkg"
-
-"wasm@link:../../../../../../.cache/yarn/v6/npm-harper-js-0.13.0-f9e945c842f4e07e1b7042e3eef00a8040b2e0dd-integrity/harper-wasm/pkg":
- version "0.0.0"
- uid ""
+harper.js@^0.14.0:
+ version "0.14.0"
+ resolved "https://registry.yarnpkg.com/harper.js/-/harper.js-0.14.0.tgz#16d511070d4474dca501d4de1c76f7849ec0accb"
+ integrity sha512-WRzop2PmFK2AZiqNMHHWDFIqFmS7DeoNVhyibyu7T6wuSe24E1Tunolz8ZzMPfcaKuBB2SY+yGbyTOyj+/QD8g==
diff --git a/packages/web/src/routes/docs/contributors/architecture/+page.md b/packages/web/src/routes/docs/contributors/architecture/+page.md
index 2a891c6fd..f8a00915b 100644
--- a/packages/web/src/routes/docs/contributors/architecture/+page.md
+++ b/packages/web/src/routes/docs/contributors/architecture/+page.md
@@ -20,7 +20,7 @@ In this vein, Harper serves the role of a [Linter](<https://en.wikipedia.org/wik
## `harper-core`
`harper-core` is where all the magic happens.
-It contains the code need to tokenize, parse, analyze and lint English text.
+It contains the code needed to tokenize, parse, analyze and lint English text.
At a high level, there are just a couple types you need to worry about.
@@ -47,3 +47,5 @@ You can read more about it [here](../integrations/language-server).
`harper.js` is a JavaScript/TypeScript module that enables developers to use Harper on any platform that supports JavaScript and WebAssembly.
Most of the JavaScript code in `harper.js` exists to load and manage the underlying WebAssembly module (otherwise known as `harper-wasm`).
+
+[There are more details about it in the documentation.](../harperjs/introduction)
diff --git a/packages/web/src/routes/docs/contributors/dictionary/+page.md b/packages/web/src/routes/docs/contributors/dictionary/+page.md
new file mode 100644
index 000000000..8e4d18b21
--- /dev/null
+++ b/packages/web/src/routes/docs/contributors/dictionary/+page.md
@@ -0,0 +1,57 @@
+---
+title: Updating the Curated Dictionary
+---
+
+The curated dictionary is the English dictionary Harper uses as reference internally when analyzing or modifying English text.
+It is common, especially with technical language, to come across words that are not in this dictionary.
+If this happens to you, please open a PR to get it in.
+
+There are two files you need to worry about.
+[`harper-core/dictionary.dict`](https://github.com/Automattic/harper/blob/master/harper-core/dictionary.dict) and [`harper-core/affixes.json`](https://github.com/Automattic/harper/blob/master/harper-core/affixes.json).
+The first is a list of words, tagged with modifiers defined in the second.
+
+For example, all words, such as "move", tagged with `L`, will be expanded to two dictionary entries, "move" and "movement".
+In `affixes.json`, this expansion rule looks like this:
+
+```js title=affixes.json
+{
+ "L": {
+ // Denotes that the area of interest is at the _end_ of the base word.
+ "suffix": true,
+ // Declare that it is OK to use the result of the expansion with other expansions.
+ "cross_product": true,
+ // The actual replacement rules that result in an expansion.
+ "replacements": [
+ {
+ // If present, remove this text from the area of interest before expansion.
+ "remove": "",
+ "add": "ment",
+ // A simplified regex-like pattern that describes what the area of interest must look like in order for this particular replacement to be applied.
+ "condition": "."
+ }
+ ],
+ // The word metadata that should be applied to the expanded word.
+ "adds_metadata": {},
+ // The word metadata that should be applied to the base word.
+ "gifts_metadata": {}
+ }
+}
+```
+
+Those familiar with `hunspell` might notice some similarities with their dictionary format.
+The main difference are the [metadata fields.](https://docs.rs/harper-core/latest/harper_core/struct.WordMetadata.html)
+
+Most words in `dictionary.dict` have simple rules applied to them that result in no expansion, but apply metadata through the `gifts_metadata`.
+Those particular rules are done automatically.
+When adding words to the dictionary, just worry about expansions, not metadata.
+
+## Adding Nouns
+
+You don't need to know any of the nitty-gritty details to add nouns to the dictionary.
+Use the tool we have in the repo:
+
+```bash
+just addnoun <YOUR NOUN HERE>
+```
+
+If this command doesn't look familiar, [read our setup documentation for contributors](./environment).
diff --git a/packages/web/src/routes/docs/contributors/environment/+page.md b/packages/web/src/routes/docs/contributors/environment/+page.md
index d94e4d75b..3d0ee5e0e 100644
--- a/packages/web/src/routes/docs/contributors/environment/+page.md
+++ b/packages/web/src/routes/docs/contributors/environment/+page.md
@@ -13,7 +13,7 @@ To use the tooling required to build and debug Harper, you'll need to the follow
- [`wasm-pack`](https://rustwasm.github.io/wasm-pack/installer/)
- `zip`
-We develop a series of tools, accessible via `just`, to build and debug Harper's algorithm (otherwise known as `harper-core`) and its various integrations.
+We develop a set of tools, accessible via `just`, to build and debug Harper's algorithm (otherwise known as `harper-core`) and its various integrations.
To get see all the tools in your toolbox run:
```bash
diff --git a/packages/web/src/routes/docs/integrations/language-server/+page.md b/packages/web/src/routes/docs/integrations/language-server/+page.md
index 82e5d2834..7c3944920 100644
--- a/packages/web/src/routes/docs/integrations/language-server/+page.md
+++ b/packages/web/src/routes/docs/integrations/language-server/+page.md
@@ -64,5 +64,4 @@ The static dictionary is built into the binary and is (as of now) immutable.
It contains almost all words you could possibly encounter.
I _do_ take pull requests or issues for adding words to the static dictionary.
-It is composed of two files: `harper-core/dictionary.dict` and `harper-core/affixes.json`
-If you just want to add a proper noun, try running `just addnoun <your noun>`.
+[Read the documentation on the matter before you do.](../contributors/dictionary)
diff --git a/packages/web/vite.config.ts b/packages/web/vite.config.ts
index 8f5adb17f..3c0f49ceb 100644
--- a/packages/web/vite.config.ts
+++ b/packages/web/vite.config.ts
@@ -108,6 +108,10 @@ export default defineConfig({
{
title: 'Architecture',
to: '/docs/contributors/architecture'
+ },
+ {
+ title: 'Dictionary',
+ to: '/docs/contributors/dictionary'
}
]
},