branch: externals/kind-icon
commit 918eb8996c94a3fe0bd442f5edd99c859a8f01fa
Author: JD Smith <93749+jdtsm...@users.noreply.github.com>
Commit: JD Smith <93749+jdtsm...@users.noreply.github.com>
Docs
---
README.md | 29 ++++++++++++++++++++++++++++-
kind-prefix.el | 18 ++++++++++--------
2 files changed, 38 insertions(+), 9 deletions(-)
diff --git a/README.md b/README.md
index 7f8ae03..9881e24 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,29 @@
# kind-prefix
-Completion kind text/icon prefix labelling for emacs in-region completion
+_Kind_ icon or short-text prefix badge labels for emacs in-region completion.
+
+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.
+
+## Installation
+
+Get it from melpa (TBD). Enable in any buffer with completion enabled using
`kind-prefix-mode`, e.g., to enable for the completion UI
[corfu](https://github.com/minad/corfu):
+
+```elisp
+(use-package kind-prefix ;package availability TBD
+ :ensure t
+ :hook (corfu-mode . kind-prefix-mode))
+```
+
+## Configuration
+
+Defaults should normally work fine, but some of the important configuration
variables include:
+
+`kind-prefix-use-icons`: If non-nil (the default), prefer icons for prefix
badges.
+
+`kind-prefix-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 plist` where `sym` is the kind (a symbol),
short-text is the abbreviated text to display (if icons are not used). The
`plist` 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 former is a string name from the [...]
+
+`kind-prefix-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 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-prefix-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.
diff --git a/kind-prefix.el b/kind-prefix.el
index c6b98cb..32a6399 100644
--- a/kind-prefix.el
+++ b/kind-prefix.el
@@ -10,14 +10,16 @@
;;; Commentary:
-;; This package adds a prefix based on :company-kind for compatible
-;; completion UI's which utilize completion-in-region. The "kind"
-;; prefix is typically used for differentiating variables, functions,
-;; etc. in completion results. It works by creating and setting into
-;; `completion-extra-properties' a custom affixation-function. This
-;; function creates and caches a short-text or icon-based "badge" for
-;; the kind of the candidate. Icons are by default from the
-;; "material" library provided by svg-lib, which is required.
+;; kind-prefix-mode adds a prefix badge based on :company-kind for
+;; compatible completion UI's utilizing completion-in-region. The
+;; "kind" prefix is typically used for differentiating variables,
+;; functions, etc. among completion results. It works by creating and
+;; setting into `completion-extra-properties' a custom
+;; affixation-function. This function creates, styles, and caches a
+;; short-text or icon-based "badge" representing the kind of the
+;; candidate. Icons are by default loaded from the "material" library
+;; provided by svg-lib, which is required (unless only short-text
+;; badges are desired, see `kind-prefix-use-icons').
;; kind-prefix is free software: you can redistribute it
;; and/or modify it under the terms of the GNU General Public License
