From da26523acca4654e1d77fdbbd095a75d5bf17e69 Mon Sep 17 00:00:00 2001
From: Uros Mrkobrada <59397844+uros-5@users.noreply.github.com>
Date: Mon, 12 Feb 2024 01:04:47 +0100
Subject: [PATCH] update README.md
---
README.md | 141 ++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 104 insertions(+), 37 deletions(-)
diff --git a/README.md b/README.md
index 55eaf72..b6673f6 100644
--- a/README.md
+++ b/README.md
@@ -1,65 +1,132 @@
its so over
-## LSP
+## Installation
-Right now this is very much so a work in progress and currently provides basic autocomplete for _most_ HTMX attributes. We have reached a point where I could use help! If you want to fill in documentation or help with autocompletes please open an issue/pr!
+```console
+cargo install htmx-lsp2
+```
-## Integration
+## Configuration
-### Neovim
+```json
+{
+ "lang": "rust",
+ "template_ext": "jinja",
+ "templates": ["./templates"],
+ "js_tags": ["./frontend"],
+ "backend_tags": ["./backend"]
+}
+```
-`htmx-lsp` can be installed via Mason. And can be configured with `lspconfig`
+## Supported languages
-```lua
-local lspconfig = require('lspconfig')
--- ...
-lspconfig.htmx.setup{}
-```
+Go, Python, JavaScript, TypeScript, Rust
-Another option is to use [lsp-debug-tools](https://github.com/ThePrimeagen/lsp-debug-tools.nvim)
+## When to use htmx-lsp or this lsp ?
-### VSCode
+If you are working on small hello world example web app, then you probably don't need this improved version of htmx-lsp.
-No published extension yet, but there is a development extension in the [`clients/vscode`](client/vscode/README.md) folder (with setup instructions)
+For bigger projects(many templates, many backend routes, few JavaScript modules) you should try this.
-## Development
+## Difference between htmx-lsp and this lsp
-### General
+### Backend/frontend tags
-As of right now the general goal is just to provide completion for any `-`
-character received without even looking at the context.
+Tags are similar to JSDoc comments. In some sense they act like documentation for htmx part of your application.
+They are helpful when you arrive at some htmx project. In order to understand codebase you constantly need to browse
+through files or use global search for every part of project.
+With tags you can simply use goto definition feature for that attribute and _you are exactly where you need to be_.
-After that, would be to perform some code actions that make sense and allow for
-amazing utility around htmx.
+#### Example
-```console
-htmx-lsp -f /path/to/file --level [OFF | TRACE | DEBUG | INFO | WARN | ERROR]
+```rust
+fn example() {
+ // some code ...
+
+ // part of app that is 'connected' with htmx template
+ // this is tag hx@tag1
+ // ...
+}
+```
+
+```html
+
+hello world
```
-### Build
+It is also possible to have multiple tags on one element. Some tag is in your Go function, other can be in JavaScript.
+This improves _locality of behavior_, you don't need to think too much, you just quickly read and act.
-```console
-cargo build
+If you use editor that behind the scenes uses TreeSitter, then you can include one query in `textobjects.scm`
+that can move your cursor to hx-lsp tag:
-# OR auto-build on file save, requires `cargo-watch`
-cargo install cargo-watch
-cargo watch -x build
+```scheme
+(
+ (attribute_name) @attr
+ (quoted_attribute_value
+ (attribute_value) @class.inside
+ ) @class.around
+ (#eq? @attr "hx-lsp")
+)
```
-## Contributors
+To have syntax highlighting for tags in your backend language or JavaScript use this query(it's _comment grammar_, `highlights.scm`):
-
+```scheme
+("text" @hint
+ (#match? @hint "^(hx@)"))
+```
+
+And here is one for template(it's _html grammar_, `highlights.scm`):
+
+```scheme
+((attribute_name) @keyword
+ (quoted_attribute_value
+ (attribute_value) @function
+ )
+ (#eq? @keyword "hx-lsp")
+)
+```
+
+#### Goto reference
+
+There are situations where you tag is used in multiple places in one template or in many templates that are located deep in your directory tree.
+To avoid messing with global search just call goto reference on tag definition and you can check each htmx-lsp instance.
+
+https://github.com/uros-5/htmx-lsp2/assets/59397844/786c9312-6792-4d22-b1b8-c4b00bdc58f3
+
+If there is only one reference for tag, then you will be redirected directy to that location.
+
+#### Goto definition
+
+https://github.com/uros-5/htmx-lsp2/assets/59397844/dc744a59-8902-44bf-9bd0-1a1d6188d4ca
+
+#### Goto implementation
+
+If your editor doesn't support TreeSitter, you can use goto implementation feature for navigating between `htmx-lsp` attributes.
+When you are deep in some template, searching for `htmx-lsp` attribute can be tedious, so this feature can help use navigating to our target much faster.
+
+https://github.com/uros-5/htmx-lsp2/assets/59397844/032c32f8-2c5f-4401-8999-2792383dc49c
+
+#### Incremental parsing for TreeSitter
+
+One problem with htmx-lsp is that it doesn't use full power of TreeSitter, and that is incremental parsing.
+Right now for every change inside of template entire file is sent and parsed by TreeSitter. And second problem is that only takes first
+change that is sent by text editor.
+So what if you use multiple cursors and you start applying changes for text document ? And what if client only supports
+incremental synchronization for `didChange` lsp feature ?
+This forked version of htmx-lsp aims to fix this issues, not just for template part, but also for backend languages.
+
+#### VSCode plugin
+
+It's still work in progress. Right now it's usable in debug mode.
- 
+ 
- 
+ 
+ 