From 6f9e5bf23f651dc1437d9b43220a4f44a122865f Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 27 Jul 2020 09:23:42 -0500 Subject: [PATCH] Docs: format and fixes Format the docs to be consisted and some typos. --- CONTRIBUTING.md | 42 ++++--- README.md | 119 ++++++++++--------- doc/nvim-treesitter.txt | 250 +++++++++++++++++++++++----------------- 3 files changed, 235 insertions(+), 176 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cae75f0e4..13497b475 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,8 +6,9 @@ If you haven't already, you should really come and reach out to us on our [gitte room, so we can help you with any question you might have! As you know, `nvim-treesitter` is roughly splitted in two parts : - - Parser configurations : for various things like `locals`, `highlights` - - What we like to call *modules* : tiny lua modules that provide a given feature, based on parser configurations + +- Parser configurations : for various things like `locals`, `highlights` +- What we like to call *modules* : tiny lua modules that provide a given feature, based on parser configurations Depending on which part of the plugin you want to contribute to, please read the appropriate section. @@ -26,12 +27,13 @@ ln -s ../../scripts/pre-push .git/hooks/pre-push ## Adding new modules If you want to see a new functionality added to `nvim-treesitter` feel free to first open an issue -to that we can track our solution ! +to that we can track our solution! Thus far, there is basically two types of modules: - - Little modules (like `incremental selection`) that are built in `nvim-treesitter`, we call them - `builtin modules`. - - Bigger modules (like `completion-treesitter`, or `nvim-tree-docs`), or modules that integrate - with other plugins, that we call `remote modules`. + +- Little modules (like `incremental selection`) that are built in `nvim-treesitter`, we call them + `builtin modules`. +- Bigger modules (like `completion-treesitter`, or `nvim-tree-docs`), or modules that integrate + with other plugins, that we call `remote modules`. In any case, you can build your own module ! To help you started in the process, we have a template repository designed to build new modules [here](https://github.com/nvim-treesitter/module-template). @@ -46,17 +48,19 @@ Before going any further, we highly suggest that you [read more about tree-sitte Each query has an appropriate name, which is then used by modules to extract data from the syntax tree. For now two types of queries are used by `nvim-treesitter`: - - `highlights.scm` : used for syntax highlighting, using the `highlight` module. - - `locals.scm` : used to extract keyword definitions, scopes, references,... using the `locals` module. + +- `highlights.scm` : used for syntax highlighting, using the `highlight` module. +- `locals.scm` : used to extract keyword definitions, scopes, references, etc, using the `locals` module. For both of these types there is a *norm* you will have to follow so that features work fine. Here are some global advices : - - If your language is listed [here](https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries), - you can debug and experiment with your queries there. - - If not, you should consider installing the [tree-sitter cli](https://github.com/tree-sitter/tree-sitter/tree/master/cli), - you should then be able to open a local playground using `tree-sitter build-wasm && tree-sitter web-ui` within the - parsers repo. - - An Example of somewhat complex highlight queries can be found in queries/ruby/highlights.scm (Maintained by @TravonteD) + +- If your language is listed [here](https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries), + you can debug and experiment with your queries there. +- If not, you should consider installing the [tree-sitter cli](https://github.com/tree-sitter/tree-sitter/tree/master/cli), + you should then be able to open a local playground using `tree-sitter build-wasm && tree-sitter web-ui` within the + parsers repo. +- An Example of somewhat complex highlight queries can be found in queries/ruby/highlights.scm (Maintained by @TravonteD) ### Highlights @@ -64,8 +68,8 @@ As languages differ quite a lot, here is a set of captures available to you when One important thing to note is that many of these capture groups are not supported by `neovim` for now, and will not have any effect on highlighting. We will work on improving highlighting in the near future though. - #### Misc + ``` @comment @error for error (ERROR` nodes. @@ -75,13 +79,16 @@ effect on highlighting. We will work on improving highlighting in the near futur Some captures are related to language injection (like markdown code blocks). As this is not supported by neovim yet, these are optional and will not have any effect for now. + ``` @embedded @injection language content ``` + #### Constants + ``` @constant builtin @@ -96,6 +103,7 @@ are optional and will not have any effect for now. ``` #### Functions + ``` @function builtin @@ -109,6 +117,7 @@ are optional and will not have any effect for now. ``` #### Keywords + ``` @conditional @repeat @@ -161,4 +170,3 @@ Mainly for markup languages. @scope @reference ``` - diff --git a/README.md b/README.md index 01d498602..93123af46 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,9 @@ Traditionnal highlighting (left) vs Treesitter-based highlighting (right). [![Gitter](https://badges.gitter.im/nvim-treesitter/community.svg)](https://gitter.im/nvim-treesitter/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) ![Linting and style checking](https://github.com/nvim-treesitter/nvim-treesitter/workflows/Linting%20and%20style%20checking/badge.svg?branch=master) ![Check loading of syntax files](https://github.com/nvim-treesitter/nvim-treesitter/workflows/Check%20loading%20of%20syntax%20files/badge.svg) + # nvim-treesitter + Treesitter configurations and abstraction layer for Neovim. **Warning: Treesitter and Treesitter highlighting are an experimental feature of nightly versions of Neovim. @@ -13,9 +15,10 @@ Please consider the experience with this plug-in as experimental until Neovim 0. # Quickstart ## Requirements - - Neovim [nightly](https://github.com/neovim/neovim#install-from-source) - - `git` in your path. - - A C compiler in your path. + +- Neovim [nightly](https://github.com/neovim/neovim#install-from-source) +- `git` in your path. +- A C compiler in your path. ## Installation @@ -24,6 +27,7 @@ You can install `nvim-treesitter` with your favorite package manager, or using t ### Using a package manager Simply add these lines to your `init.vim` : + ```vim Plug 'nvim-treesitter/nvim-treesitter' ``` @@ -31,6 +35,7 @@ Plug 'nvim-treesitter/nvim-treesitter' ### Using neovim `pack` feature We highly recommend reading `:h packages` to learn more about this feature, but you can still follow these steps: + ```sh $ mkdir -p ~/.local/share/nvim/site/pack/nvim-treesitter/start $ cd ~/.local/share/nvim/site/pack/nvim-treesitter/start @@ -45,6 +50,7 @@ provides two command to tackle this issue: - `TSInstallInfo` to know which parser is installed. Let's say you need parsers for `lua`, `c`, and `python`, this is how you do with these commands: + ```vim :TSInstall c Downloading... @@ -63,6 +69,7 @@ Treesitter parser for python has been installed ``` Cool, lets see which parsers are installed: + ```vim :TSInstallInfo csharp [✗] not installed @@ -91,27 +98,27 @@ And now you should be able to use every functionality `nvim-treesitter` provides ## Setup -in your `init.vim`: +In your `init.vim`: ```lua lua </after/queries/lua/highlights You can also manually add query paths to the runtime path by adding this to your vim config `set rtp+='path/to/queries'`. ## Troubleshooting + Before doing anything run `:checkhealth nvim_treesitter`. This will help you find where the bug might come from. ### Feature `X` does not work for language `Y`... + First, check the `## Y parser healthcheck` section of `:checkhealth` if you have any warning. If you do, it's highly possible that this is the cause of the problem. If everything is okay, then it might be an actual error. @@ -307,7 +320,9 @@ In both cases, feel free to open an issue here. This is a well known issue, which arise when the tree and the buffer are getting out of sync. \ As this issue comes from upstream, we don't have any finite fix. To get around this, you can force reparsing the buffer with this command: + ```vim :write | edit | TSBufEnable highlight ``` - This will save, restore and enable highlighting for the current buffer, fixing the issue. + +This will save, restore and enable highlighting for the current buffer, fixing the issue. diff --git a/doc/nvim-treesitter.txt b/doc/nvim-treesitter.txt index 82a6539b3..7bf4b5780 100644 --- a/doc/nvim-treesitter.txt +++ b/doc/nvim-treesitter.txt @@ -5,13 +5,13 @@ Minimum version of neovim: nightly Authors: Yazdani Kiyan , Vigouroux Thomas ============================================================================== -INTRODUCTION *nvim-treesitter-intro* +INTRODUCTION *nvim-treesitter-intro* nvim-treesitter wraps the neovim treesitter api to provide functionnalities such as highlighting and incremental selection, and a command to easily install parsers. ============================================================================== -QUICK START *nvim-treesitter-quickstart* +QUICK START *nvim-treesitter-quickstart* Install the parser for your language @@ -30,71 +30,79 @@ By default, everything is disabled. To enable support for features, in your `ini > lua < @@ -228,7 +264,7 @@ Note: This is highly experimental, and folding can break on some types of HIGHLIGHTS *nvim-treesitter-highlights* `TSError` - *hl-TSError* + *hl-TSError* For syntax/parser errors. You can deactivate highlighting of syntax errors by adding this to your @@ -389,4 +425,4 @@ Literal text. *hl-TSURI* Any URI like a link or email. - vim:tw=78:ts=8:noet:ft=help:norl: +vim:tw=78:ts=8:noet:ft=help:norl: