git.iko.soy/helix
on master help sign in
Touch up docs for adding new language (#1002)
e0e227dGokul Soumya
book/src/guides/adding_languages.md+15−8
compare with master
unifiedsplit
@@ -2,13 +2,14 @@
2
2
3## Submodules
3## Submodules
4
4
5−To add a new langauge, you should first add a tree-sitter submodule. To do this, you can run the command
5+To add a new langauge, you should first add a tree-sitter submodule. To do this,
6+you can run the command
6```sh
7```sh
7−$ git submodule add -f <repository> helix-syntax/languages/tree-sitter-<name>
8+git submodule add -f <repository> helix-syntax/languages/tree-sitter-<name>
8```
9```
9For example, to add tree-sitter-ocaml you would run
10For example, to add tree-sitter-ocaml you would run
10```sh
11```sh
11−$ git submodule add -f https://github.com/tree-sitter/tree-sitter-ocaml helix-syntax/languages/tree-sitter-ocaml
12+git submodule add -f https://github.com/tree-sitter/tree-sitter-ocaml helix-syntax/languages/tree-sitter-ocaml
12```
13```
13Make sure the submodule is shallow by doing
14Make sure the submodule is shallow by doing
14```sh
15```sh
@@ -19,7 +20,10 @@ or you can manually add `shallow = true` to `.gitmodules`.
19
20
20## languages.toml
21## languages.toml
21
22
23+Next, you need to add the language to the [`languages.toml`][languages.toml] found in the root of
22−Next, you need to add the language to the `languages.toml` found in the root of the repository; this `languages.toml` file is included at compilation time, and is distinct from the `language.toml` file in the user's [configuration directory](../configuration.md).
24+the repository; this `languages.toml` file is included at compilation time, and
25+is distinct from the `language.toml` file in the user's [configuration
26+directory](../configuration.md).
23
27
24These are the available keys and descriptions for the file.
28These are the available keys and descriptions for the file.
25
29
@@ -27,7 +31,7 @@ These are the available keys and descriptions for the file.
27| ---- | ----------- |
31| ---- | ----------- |
28| name | The name of the language |
32| name | The name of the language |
29| scope | A string like `source.js` that identifies the language. Currently, we strive to match the scope names used by popular TextMate grammars and by the Linguist library. Usually `source.<name>` or `text.<name>` in case of markup languages |
33| scope | A string like `source.js` that identifies the language. Currently, we strive to match the scope names used by popular TextMate grammars and by the Linguist library. Usually `source.<name>` or `text.<name>` in case of markup languages |
30−| injection-regex | regex pattern that will be tested against a language name in order to determine whether this language should be used for a potential language injection site. [link](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection) |
34+| injection-regex | regex pattern that will be tested against a language name in order to determine whether this language should be used for a potential [language injection][treesitter-language-injection] site. |
31| file-types | The filetypes of the language, for example `["yml", "yaml"]` |
35| file-types | The filetypes of the language, for example `["yml", "yaml"]` |
32| roots | A set of marker files to look for when trying to find the workspace root. For example `Cargo.lock`, `yarn.lock` |
36| roots | A set of marker files to look for when trying to find the workspace root. For example `Cargo.lock`, `yarn.lock` |
33| auto-format | Whether to autoformat this language when saving |
37| auto-format | Whether to autoformat this language when saving |
@@ -42,11 +46,14 @@ For a language to have syntax-highlighting and indentation among other things, y
42## Common Issues
46## Common Issues
43
47
44- If you get errors when building after switching branches, you may have to remove or update tree-sitter submodules. You can update submodules by running
48- If you get errors when building after switching branches, you may have to remove or update tree-sitter submodules. You can update submodules by running
45−```sh
49+ ```sh
46−$ git submodule sync; git submodule update --init
50+ git submodule sync; git submodule update --init
47−```
51+ ```
48- Make sure to not use the `--remote` flag. To remove submodules look inside the `.gitmodules` and remove directories that are not present inside of it.
52- Make sure to not use the `--remote` flag. To remove submodules look inside the `.gitmodules` and remove directories that are not present inside of it.
49
53
50- If a parser is segfaulting or you want to remove the parser, make sure to remove the submodule *and* the compiled parser in `runtime/grammar/<name>.so`
54- If a parser is segfaulting or you want to remove the parser, make sure to remove the submodule *and* the compiled parser in `runtime/grammar/<name>.so`
51
55
52- The indents query is `indents.toml`, *not* `indents.scm`. See [this](https://github.com/helix-editor/helix/issues/114) issue for more information.
56- The indents query is `indents.toml`, *not* `indents.scm`. See [this](https://github.com/helix-editor/helix/issues/114) issue for more information.
57+
58+[treesitter-language-injection]: https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection
59+[languages.toml]: https://github.com/helix-editor/helix/blob/master/languages.toml
book/src/guides/textobject.md+1−1
@@ -5,7 +5,7 @@ require an accompanying tree-sitter grammar and a `textobjects.scm` query file
5to work properly. Tree-sitter allows us to query the source code syntax tree
5to work properly. Tree-sitter allows us to query the source code syntax tree
6and capture specific parts of it. The queries are written in a lisp dialect.
6and capture specific parts of it. The queries are written in a lisp dialect.
7More information on how to write queries can be found in the [official tree-sitter
7More information on how to write queries can be found in the [official tree-sitter
8−documentation](tree-sitter-queries).
8+documentation][tree-sitter-queries].
9
9
10Query files should be placed in `runtime/queries/{language}/textobjects.scm`
10Query files should be placed in `runtime/queries/{language}/textobjects.scm`
11when contributing. Note that to test the query files locally you should put
11when contributing. Note that to test the query files locally you should put