add 'use-grammars' to languages.toml

The vision with 'use-grammars' is to allow the long-requested feature
of being able to declare your own set of grammars that you would like.
A simple schema with only/except grammar names controls the list
of grammars that is fetched and built. It does not (yet) control which
grammars may be loaded at runtime if they already exist.

1 files changed, 10 insertions, 1 deletions

diff --git a/book/src/languages.md b/book/src/languages.md
index c5a7708f..3372a120 100644
--- a/book/src/languages.md
+++ b/book/src/languages.md
@@ -28,4 +28,13 @@ name = "c"
 source = { path = "/path/to/tree-sitter-c" }
 ```
 
-If a user has a `languages.toml`, only the grammars in that `languages.toml` are evaluated when running `hx --fetch-grammars` and `hx --build-grammars`. Otherwise the [default `languages.toml`](https://github.com/helix-editor/helix/blob/master/languages.toml) is used.
+You may use a top-level `use-grammars` key to control which grammars are fetched and built.
+
+```toml
+# Note: this key must come **before** the [[language]] and [[grammar]] sections
+use-grammars = { only = [ "rust", "c", "cpp" ] }
+# or
+use-grammars = { except = [ "yaml", "json" ] }
+```
+
+When omitted, all grammars are fetched and built.