Update README and split out feature list

README.md

@@ -1,4 +1,4 @@
-nil: Language server for Nix Expression Language
+# nil: Yet another language server for Nix
 
 [![CI](https://github.com/oxalica/nil/actions/workflows/ci.yml/badge.svg)](https://github.com/oxalica/nil/actions/workflows/ci.yml)
 
@@ -8,51 +8,26 @@ Super fast incremental analysis! Scans `all-packages.nix` in less than 0.1s and
 
 ## Features
 
-- [x] Goto definition. `textDocument/definition`
-  - [x] References to parameters, `let` and `rec {}` bindings.
-  - [x] Relative paths.
-- [x] Find references. `textDocument/reference`
-  - [x] Parameters, `let` and `rec {}` bindings.
-  - [x] With expression.
-- [x] Completion. `textDocument/completion`
-  - [x] Builtin names.
-    - With documentations.
-  - [x] Local bindings and rec-attrset fields.
-  - [x] Keywords.
-  - [ ] Attrset fields.
-- [x] Diagnostics. `textDocument/publishDiagnostics`
-  - Syntax errors. 
-    - Incomplete syntax errors are currently suppressed to avoid noisy outputs during typing.
-  - [x] Hard semantic errors reported as parse errors by Nix, like duplicated keys in attrsets.
-  - [x] Undefiend names.
-  - [x] Warnings of legacy syntax.
-  - [x] Warnings of unnecessary syntax.
-  - [x] Warnings of unused bindings, `with` and `rec`.
-  - [ ] Client pulled diagnostics.
-- [x] Expand selection. `textDocument/selectionRange`
-- [x] Renaming. `textDocument/renamme`, `textDocument/prepareRename`
-  - [x] Identifiers in parameters and bindings, from `let`, rec and non-rec attrsets.
-  - [x] Static string literal bindings.
-  - [x] Merged path-value binding names.
-  - [x] Names introduced by `inherit`.
-  - [x] Names used by `inherit`.
-  - [ ] Conflict detection.
-  - [x] Rename to string literals.
-- [x] Semantic highlighting. `textDocument/semanticTokens/{range,full}`
-  - [ ] Delta response. `textDocument/semanticTokens/full/delta`
-  - :warning: Currently it has performance issue in large files with [`coc.nvim`].
-    `vim` would consume 100% CPU and is slow to respond when editing `all-packages.nix`.
-    Though our LSP server's CPU usage is quite low.
-    Other LSP clients are not tested.
-- [x] Hover text. `textDocument/hover`.
-  - [x] Show kind of names.
-  - [x] Documentation for builtin names.
-- [ ] Cross-file analysis.
-- [ ] Multi-threaded.
+See [release notes][releases] for change log between tagged unstable versions.
+
+See [`doc/features.md`](doc/features.md) for an incomplete list of notable features currently
+implemented or planned.
+
+[releases]: https://github.com/oxalica/nil/releases
 
 ## Installation
 
-This repo is packaged via [Nix flakes][nix-flakes], the language server binary package is
+This program is already included in [NixOS/nixpkgs][nixpkgs] under attribute `nil`,
+and are regularly updated.
+
+[nixpkgs]: https://github.com/NixOS/nixpkgs
+
+- If you use `nix-env`, run `nix-env -iA nixpkgs.nil`
+- If you use `nix profile`, run `nix profile install nixpkgs#nil`
+
+## Flake
+
+This repo is also packaged via [Nix flakes][nix-flakes], the language server binary package is
 available through the default flake output `github:oxalica/nil#` with the path `bin/nil`.
 
 You can [enable flakes support][nix-flakes-install] in your nix configuration, and then
@@ -82,6 +57,8 @@ Flake output structure:
 
 We are officially supported by `nvim-lspconfig`, see [upstream docs](https://github.com/neovim/nvim-lspconfig/blob/0fafc3ef648bd612757630097c96b725a36a0476/doc/server_configurations.txt#nil_ls).
 
+See also [the example config for testing](dev/neovim-lsp.nix).
+
 ### Vim/Neovim via [`coc.nvim`]
 
 [`coc.nvim`]: https://github.com/neoclide/coc.nvim
@@ -100,6 +77,8 @@ Merge this setting into your `coc-settings.json`, which can be opened by `:CocCo
 }
 ```
 
+See also [the example config for testing](dev/vim-coc.nix).
+
 ### Emacs [`eglot`]
 
 [`eglot`]: https://github.com/joaotavora/eglot

doc/features.md

@@ -0,0 +1,54 @@
+## Features
+
+This incomplete list tracks noteble features currently implemented or planned.
+
+- [x] Goto definition. `textDocument/definition`
+  - [x] References to parameters, `let` and `rec {}` bindings.
+  - [x] Relative paths.
+- [x] Find references. `textDocument/reference`
+  - [x] Parameters, `let` and `rec {}` bindings.
+  - [x] With expression.
+- [x] Completion. `textDocument/completion`
+  - [x] Builtin names.
+    - With documentations.
+  - [x] Local bindings and rec-attrset fields.
+  - [x] Keywords.
+  - [ ] Attrset fields.
+- [x] Diagnostics. `textDocument/publishDiagnostics`
+  - [x] Syntax errors. 
+  - [x] Hard semantic errors reported as parse errors by Nix, like duplicated keys in attrsets.
+  - [x] Undefiend names.
+  - [x] Warnings of legacy syntax.
+  - [x] Warnings of unnecessary syntax.
+  - [x] Warnings of unused bindings, `with` and `rec`.
+  - [ ] Client pulled diagnostics.
+- [x] Expand selection. `textDocument/selectionRange`
+- [x] Renaming. `textDocument/renamme`, `textDocument/prepareRename`
+  - [x] Identifiers in parameters and bindings, from `let`, rec and non-rec attrsets.
+  - [x] Static string literal bindings.
+  - [x] Merged path-value binding names.
+  - [x] Names introduced by `inherit`.
+  - [x] Names used by `inherit`.
+  - [ ] Conflict detection.
+  - [x] Rename to string literals.
+- [x] Semantic highlighting. `textDocument/semanticTokens/{range,full}`
+  - [ ] Delta response. `textDocument/semanticTokens/full/delta`
+  - :warning: Currently it has performance issue for large files.
+    It may be slow to respond when editing `all-packages.nix`.
+
+    [`coc.nvim`] doesn't enable semantic highlighting by default.
+    You need to manually enable it in settings.
+    ```json
+    {
+      "semanticTokens": { "filetypes": ["nix"] }
+    }
+    ```
+
+    [`coc.nvim`]: https://github.com/neoclide/coc.nvim
+
+
+- [x] Hover text. `textDocument/hover`.
+  - [x] Show kind of names.
+  - [x] Documentation for builtin names.
+- [ ] Cross-file analysis.
+- [ ] Multi-threaded.