[elpa] externals/kind-icon c69da89 18/51: Updated docs

[ELPA Syncer]

branch: externals/kind-icon
commit c69da894374fc1c3aeb8d4d748bbc1d25b758296
Author: JD Smith <93749+jdtsmith@users.noreply.github.com>
Commit: JD Smith <93749+jdtsmith@users.noreply.github.com>

    Updated docs
---
 README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 44 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 13bfdf2..fa80dad 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,66 @@
 # kind-icon
 Supplies a _kind_ icon or short-text prefix for emacs completion in the buffer.
 
-This emacs package adds icon or text-based completion prefixes based on the 
`:company-kind` property many completion backends (such as lsp-mode) provide.  
It works by creating a custom `affixation-function` for in-buffer completion, 
if the backend does not already provide one.  An affixation function specifies 
a prefix and suffix to go along with completion candidate text.
+This emacs package adds icon or text-based completion prefixes based on the 
`:company-kind` property many completion backends (such as lsp-mode) provide.  
It works either as a "kind-formatter" function (e.g. for corfu) or by wrapping 
the completion function for other completion UI's which handle the Emacs 28+ 
`affixation-function` completion property. 
 
 ## Installation 
 
-Get it from melpa (TBD), which should install `svg-lib` as well if necessary.  
Enable in any buffer with completion using `kind-icon-mode`.  E.g., to enable 
for the completion UI [corfu](https://github.com/minad/corfu):
+Get it from melpa (TBD), which should install `svg-lib` as well if necessary.  
Enable in any buffer with completion using `kind-icon-mode`.  E.g., to enable 
for the completion UI [corfu](https://github.com/minad/corfu), which has a 
kind-formatter configuration:
 
 ```elisp
 (use-package kind-icon ;package availability TBD
   :ensure t
-  :hook (corfu-mode . kind-icon-mode))
+  :after corfu
+  :custom
+  (kind-icon-default-face 'corfu-background)
+  (corfu-kind-formatter #'kind-icon-formatted))
+```
+
+The more generic approach of wrapping the `completion-in-region-function` 
would look like:
+
+```elisp
+(use-package kind-icon
+  :ensure t
+  :config
+  (add-hook 'my-completion-ui-mode-hook
+           (lambda ()
+             (setq completion-in-region-function
+                   (kind-icon-enhance-completion
+                    completion-in-region-function)))))
 ```
 
 ## Configuration
 
+The configuration defaults should work fine, but kind-icon can be customized 
to change the colors, preference of icons vs. short-text (or mixed) prefixes, 
and more. 
+
 ### Variables
 
-The defaults should normally work fine, but some of the important 
configuration variables include:
+`kind-icon` has a few customization variables that allows you to configure its 
appearance. Note that since the styled icons are cached, changes to the 
mapping, font size, or other variables in an initialized buffer should be 
followed by `M-x kind-icon-reset-cache` (or just restart Emacs).
+
+**Key configurations:**
+
+- `kind-icon-use-icons`: If non-nil (the default), prefer icons for prefix 
badges.  Otherwise, use text labels.  Individual kind entries can also have 
their icons disabled by removing the `:icon` property in the mapping (see 
below). 
+
+- `kind-icon-mapping`: This is the top level configuration mapping 
`:company-kind` "types" like `'variable` and `'function`.  Each item in this 
list has the format `(sym short-text :keyword value ...)` where `sym` is the 
kind (a symbol), and `short-text` is the abbreviated text to display (if icons 
are not used).  The rest of the list is a property list with optional keys 
`:icon` and `:face`.  The latter will be used to set the text foreground and 
(possibly) background colors on the badg [...]
+
+- `kind-icon-default-face`: A face from which the icon background color will 
be taken and blended with the `:face` foreground color in the mapping table to 
create a custom background color.  If not set, the frame default background 
color will be used for this purpose.  Similarly, the foreground color for this 
face, if set, will be used if a `:face` foreground is missing from the mapping. 
+
+- `kind-icon-blend-background`: If non-nil, computes a blend between a nominal 
background color (from either the background property of 
`kind-icon-default-face`, if set, or frame background color) and the foreground 
:face.  If `kind-icon-blend-background` is nil, the background is taken from 
the :face background, `kind-icon-default-face`, or frame background-color.
+
+- `kind-icon-blend-frac`: The fractional blend between custom badge `:face` 
foreground and background (see above) color to use as a custom background for 
each badge.  A value of 0.0 simply replicates the background color.  Values 
should likely stay below 0.3 or so.
+
+### Colors
+
+If you don't like the default colors used to go along with the icons, you can 
customize the associated face, choose another, or build your own. You can also 
change how the background color is displayed. 
 
-- `kind-icon-use-icons`: If non-nil (the default), prefer icons for prefix 
badges.
+**Foreground color:**
 
-- `kind-icon-mapping`: This is the top level configuration mapping 
`:company-kind` "types" like `'variable` and `'function`.  Each item in this 
list has the format `(sym short-text :keyword value ...)` where `sym` is the 
kind (a symbol), and `short-text` is the abbreviated text to display (if icons 
are not used).  The rest of the list is a property list with optional keys 
`:icon` and `:face`.  The latter will be used to set the text foreground and 
background colors on the badge.  The for [...]
+Icon foreground colors are matched by default to the default colors in 
programming modes (variables, function names, etc.).  This gives consistency 
with in-buffer highlighting.  These colors are taken from the `:face` mapping's 
`:foreground` color.  If no `:face` is set, the foreground is taken from 
`kind-icon-default-face` foreground, or, as a backup the default frame 
foreground.
 
-- `kind-icon-default-face`: A face from which background color will be taken 
and blended with the `:face` foreground color in the mapping table to create a 
custom background color.  If not set, the frame default background color will 
be used for this purpose.  Similarly, the foreground color for this face, if 
set, will be used if a `:face` foreground is missing from the mapping. 
+**Background color:**
 
-- `kind-icon-blend-frac`: The fractional blend between custom badge
-`:face` foreground and background (see above) color to use as a custom
-background for each badge.  A value of 0.0 simply replicates the
-background color.  Values should likely stay below 0.3 or so.
+By default, `kind-icon` creates a blended background color that is a mix of a 
bit of the foreground color and the background.  Note that if your completion 
UI uses a different background color from your normal buffer, you should 
configure the face it uses in `kind-icon-default-face`. If you turn off 
`kind-icon-blend-background`, `kind-icon` will use both the foreground _and_ 
background from the configured `:face` for each kind, allowing you to configure 
arbitrary colors.
 
-### Icons and Colors
+### Icons 
 
-Check the [material icon library](https://materialdesignicons.com) for the SVG 
icons you can use.  All you need is the name of the icon! Icon colors are 
matched by default to the default colors in programming modes (variables, 
function names, etc.). If you don't like the default colors used to go along 
with the icons, you can customize the associated face, or build your own.  See 
`M-x list-faces-display`.  You can `M-x customize-group kind-icon` to update 
the mapping. 
+Check the [material icon library](https://materialdesignicons.com) for the SVG 
icons you can use.  All you need to "use" an icon is its name! Note that on 
first use, icons are auto-downloaded by `svg-lib`, so you'll need a network 
connection.  After that they are cached locally.