Merge pull request #44 from barrettruth/fix/doc

fix(doc): move hl documentation to the vimdoc

.github/workflows/quality.yaml

@@ -1,6 +1,7 @@
 name: quality
 
 on:
+  workflow_call:
   pull_request:
     branches: [main]
   push:

README.md

@@ -24,14 +24,11 @@ highlighting.
 
 ## Installation
 
-Using [lazy.nvim](https://github.com/folke/lazy.nvim):
+Install with your package manager of choice or via
+[luarocks](https://luarocks.org/modules/barrettruth/diffs.nvim):
 
-```lua
+```
-{
+luarocks install diffs.nvim
-  'barrettruth/diffs.nvim',
-  dependencies = { 'tpope/vim-fugitive' },
-  opts = {},
-}
 ```
 
 ## Documentation
@@ -40,26 +37,6 @@ Using [lazy.nvim](https://github.com/folke/lazy.nvim):
 :help diffs.nvim
 ```
 
-## Highlight Groups
-
-diffs.nvim defines the following highlight groups. All use `default = true`, so
-colorschemes can override them.
-
-| Group             | Purpose                                            |
-| ----------------- | -------------------------------------------------- |
-| `DiffsAdd`        | Background for `+` lines in fugitive unified diffs |
-| `DiffsDelete`     | Background for `-` lines in fugitive unified diffs |
-| `DiffsAddNr`      | Line number highlight for `+` lines                |
-| `DiffsDeleteNr`   | Line number highlight for `-` lines                |
-| `DiffsDiffAdd`    | Background-only `DiffAdd` for `&diff` windows      |
-| `DiffsDiffDelete` | Background-only `DiffDelete` for `&diff` windows   |
-| `DiffsDiffChange` | Background-only `DiffChange` for `&diff` windows   |
-| `DiffsDiffText`   | Background-only `DiffText` for `&diff` windows     |
-
-By default, these are computed from your colorscheme's `DiffAdd`, `DiffDelete`,
-`DiffChange`, `DiffText`, and `Normal` groups. To customize, define them in your
-colorscheme before diffs.nvim loads, or link them to existing groups.
-
 ## Known Limitations
 
 - Syntax "flashing": diffs.nvim hooks into the `FileType fugitive` event

doc/diffs.nvim.txt

@@ -194,8 +194,9 @@ To minimize the flash, use a low debounce value: >lua
 ==============================================================================
 HIGHLIGHT GROUPS                                          *diffs-highlights*
 
-diffs.nvim defines custom highlight groups. All are set with `default = true`,
+diffs.nvim defines custom highlight groups. Fugitive unified diff groups use
-so colorschemes can override them by defining them first.
+`default = true`, so colorschemes can override them. Diff mode groups are
+always derived from the corresponding `Diff*` groups.
 
 Fugitive unified diff highlights: ~
                                                                   *DiffsAdd*
@@ -215,20 +216,24 @@ Fugitive unified diff highlights: ~
                         `diffRemoved`, background from `DiffsDelete`.
 
 Diff mode window highlights: ~
-These are background-only variants used for |winhighlight| remapping in
+These are used for |winhighlight| remapping in `&diff` windows.
-`&diff` windows, allowing treesitter syntax to show through.
 
                                                              *DiffsDiffAdd*
-    DiffsDiffAdd        Background-only version of `DiffAdd`.
+    DiffsDiffAdd        Background-only. Derived from `DiffAdd` bg.
+                        Treesitter provides foreground syntax highlighting.
 
                                                           *DiffsDiffDelete*
-    DiffsDiffDelete     Background-only version of `DiffDelete`.
+    DiffsDiffDelete     Foreground and background from `DiffDelete`.
+                        Used for filler lines (`/////`) which have no real
+                        code content to highlight.
 
                                                           *DiffsDiffChange*
-    DiffsDiffChange     Background-only version of `DiffChange`.
+    DiffsDiffChange     Background-only. Derived from `DiffChange` bg.
+                        Treesitter provides foreground syntax highlighting.
 
                                                             *DiffsDiffText*
-    DiffsDiffText       Background-only version of `DiffText`.
+    DiffsDiffText       Background-only. Derived from `DiffText` bg.
+                        Treesitter provides foreground syntax highlighting.
 
 To customize these in your colorscheme: >lua
     vim.api.nvim_set_hl(0, 'DiffsAdd', { bg = '#2e4a3a' })