Changes for info organization, consistency, and other small details.

- Update extension package blurbs at top of file to all be "prescient.el + FRAMEWORK". This was already the case for Company and Ivy. - Don't check the length of the first line in files. The first line, with the package name, description, and file-local variables, can easily get past the recommended 80 characters, so don't try to restrict it so strongly. - Describe faces in their own section. Update references elsewhere. Move example of face customization to Face section. - Mention the faces in the docs of `prescient-completion-highlight-matches`. - Add some blank lines for consistency in README. - Minor correction to changelog entry regarding how library `char-fold` is required. - Add some info about the algorithm from the Selectrum readme into the Prescient readme. - Mention `prescient-sort-length-enable` in the README. - Describe the toggling commands before saying where they're bound. Use is more important than location. - Formatting, phrasing, etc.
radian-software · Nov 18, 2022 · a000de7 · a000de7
1 parent 50b7b85
commit a000de7
Show file tree

Hide file tree

Showing 7 changed files with 88 additions and 59 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,9 +20,9 @@ The format is based on [Keep a Changelog].
 * Toggling off filter methods no longer accidentally changes the
   global value of `prescient-filter-method`.  See [#123], [#124].
 
-* For character folding, if `char-fold-table` isn't bound, we
-  `require` the library `char-fold`. This variable apparently isn't
-  always loaded when we call `char-fold-to-regexp`. See [#126].
+* Always `require` the library `char-fold` so that `char-fold-table`
+  is defined. This variable apparently isn't always loaded when we
+  call `char-fold-to-regexp`. See [#126], [#127].
 
 * Fix the filter methods `literal` and `literal-prefix` not being
   literal when `prescient-use-char-folding` was nil. This bug was

diff --git a/README.md b/README.md
@@ -80,15 +80,20 @@ undo.
 ## Algorithm
 
 `prescient.el` takes as input a list of candidates, and a query that
-you type. The query is first split on spaces into subqueries (two
-consecutive spaces match a literal space). Each subquery filters the
-candidates because it must match as either a substring of the
-candidate, a regexp, or an initialism (e.g. `ffap` matches
-`find-file-at-point`, and so does `fa`). The last few candidates you
-selected are displayed first, followed by the most frequently selected
-ones, and then the remaining candidates are sorted by length. If you
-don't like the algorithm used for filtering, you can choose a
-different one by customizing `prescient-filter-method`.
+you type.
+
+When filtering, the query is first split on spaces into subqueries
+(two consecutive spaces match a literal space). Each subquery filters
+the candidates according to the filter methods listed in
+`prescient-filter-method`. By default, a subquery must match as either
+a substring of the candidate, a regexp, or an initialism (e.g. `ffap`
+matches `find-file-at-point`, and so does `fa`). A candidate must
+match all subqueries to pass the filter and subqueries can be matched
+in any order.
+
+When sorting, the last few candidates you selected are displayed
+first, followed by the most frequently selected ones, and then the
+remaining candidates are sorted by length.
 
 If you would like `prescient.el` to forget about a candidate, use the
 command `prescient-forget`.
@@ -135,6 +140,9 @@ command `prescient-forget`.
   - `selectrum-prescient.el`
   - `vertico-prescient.el`
 
+* `prescient-sort-length-enable`: Whether to sort the candidates by
+  length in addition to recency and frequency.
+
 * `prescient-use-char-folding`: Whether the `literal` and
   `literal-prefix` filter methods use character folding.
 
@@ -143,24 +151,26 @@ command `prescient-forget`.
   This can be one of `nil`, `t`, or `smart` (the default). If `smart`,
   then case folding is disabled when upper-case characters are used.
 
-* Filter-method toggling commands: `selectrum-prescient.el` and
-  `vertico-prescient.el` will both bind commands to toggle filter
-  methods in the current completion buffer. `corfu-prescient.el` will
-  bind the commands while the Corfu pop-up is active.
+* Quickly adjusting filtering: Commands are available to temporarily
+  toggle filter methods on or off while you're completing candidates.
+  These commands are similar in usage to Isearch's own toggling
+  commands, except that multiple filtering methods can be active at
+  the same time.
 
   For example, to toggle regexp filtering on or off (perhaps you're
   searching for a long/complex candidate), you can press `M-s r`. If
   you wish to use *only* regexp filtering, you can use `C-u M-s r` to
   unconditionally turn on regexp filtering and turn off all other
   methods. This toggling is a buffer-local effect, and does not change
-  the default filter behavior. For that, customize
+  the default filtering behavior. For that, customize
   `prescient-filter-method`.
 
-  These commands are similar in usage to Isearch's own toggling
-  commands, except that multiple filtering methods can be active at
-  the same time. While the integration mode is enabled, `M-s` is bound
-  to `prescient-toggle-map` in the completion buffer or Corfu pop-up,
-  and is used as a prefix key to access the commands.
+  `selectrum-prescient.el` and `vertico-prescient.el` will both bind
+  commands to toggle filter methods in the current completion buffer.
+  `corfu-prescient.el` will bind the commands while the Corfu pop-up
+  is active. While the integration mode is enabled, `M-s` is bound to
+  `prescient-toggle-map` in the completion buffer or Corfu pop-up, and
+  is used as a prefix key to access the commands.
 
   | Key     | Command                           |
   |---------|-----------------------------------|
@@ -185,15 +195,56 @@ command `prescient-forget`.
 
   will bind a command for toggling the `my-foo` filter to `M-s M-f`.
 
+### Faces
+
+`prescient.el` defines two faces: `prescient-primary-highlight` and
+`prescient-secondary-highlight`. The primary highlight is used to
+highlight matches in candidates. The secondary highlight is used for
+important sections within each matched region. For example, the
+`initialism` filter method highlights the entire match with
+`prescient-primary-highlight` and each initial in the initialism with
+`prescient-secondary-highlight`.
+
+These faces are used by the `prescient` completion style (and so
+completion frameworks using that style, such as Corfu and Vertico) and
+Selectrum. `ivy-prescient.el` uses Ivy's faces.
+
+The following example shows customizing these faces. I use the
+[Zerodark](https://github.com/NicolasPetton/zerodark-theme) color
+theme, which includes colors for Ivy, but not for Selectrum. I
+inspected the theme source code to see what colors were being used for
+Ivy, and copied them to be used for Selectrum as well:
+
+```elisp
+(require 'zerodark-theme)
+
+(let ((class '((class color) (min-colors 89))))
+  (custom-theme-set-faces
+   'zerodark
+   `(selectrum-current-candidate
+     ((,class (:background "#48384c"
+                           :weight bold
+                           :foreground "#c678dd"))))
+   `(prescient-primary-highlight
+     ((,class (:foreground "#da8548"))))
+   `(prescient-secondary-highlight
+     ((,class (:foreground "#98be65"))))))
+
+(enable-theme 'zerodark)
+```
+
 ### For the completion style
+
 The following user options are specific to using the `prescient`
 completion style:
 
 * `prescient-completion-highlight-matches`: Whether the completion
-  style should highlight matches in the filtered candidates.
+  style should highlight matches in the filtered candidates using the
+  faces `prescient-primary-highlight` and `prescient-secondary-highlight`.
 
 ### For Corfu
-`corfu-prescient.el` configures filtering buffer locally in buffers in
+
+`corfu-prescient.el` configures filtering locally in buffers in
 which `corfu-mode` is active. To do this, it modifies the values of
 `completion-styles`, `completion-category-overrides`, and
 `completion-category-defaults`. Sorting is configured globally.
@@ -228,6 +279,7 @@ Corfu:
   made non-nil.
 
 ### For Company
+
 The following user options are specific to using `prescient.el`
 sorting with Company:
 
@@ -245,6 +297,7 @@ sorting with Company:
   otherwise leave candidate ordering alone.
 
 ### For Ivy
+
 The following user options are specific to using `prescient.el` with
 Ivy:
 
@@ -269,6 +322,7 @@ Ivy:
   and how to customize it manually.
 
 ### For Selectrum
+
 The following user options are specific to using `prescient.el` with
 Selectrum:
 
@@ -277,42 +331,16 @@ Selectrum:
   the Selectrum documentation for information on how Selectrum
   configures filtering by default, and how to customize it manually.
 
+  Additionally, when set, the matched part of each candidate is
+  highlighted using the faces described above.
+
 * `selectrum-prescient-enable-sorting`: If set to nil, then
   `selectrum-prescient.el` does not change sorting of Selectrum. See
   the Selectrum documentation for information on how Selectrum
   configures sorting by default, and how to customize it manually.
 
-With `selectrum-prescient-enable-filtering` set, the part of each
-candidate that matches your input is highlighted with the face
-`selectrum-prescient-primary-highlight`. There is also
-`selectrum-prescient-secondary-highlight` for additional highlighting
-of specific matched parts of the input.
-
-The following example shows customizing these faces, I use the
-[Zerodark](https://github.com/NicolasPetton/zerodark-theme) color
-theme, which includes colors for Ivy, but not for Selectrum. I
-inspected the theme source code to see what colors were being used for
-Ivy, and copied them to be used for Selectrum as well:
-
-```elisp
-(require 'zerodark-theme)
-
-(let ((class '((class color) (min-colors 89))))
-  (custom-theme-set-faces
-   'zerodark
-   `(selectrum-current-candidate
-     ((,class (:background "#48384c"
-                           :weight bold
-                           :foreground "#c678dd"))))
-   `(selectrum-prescient-primary-highlight
-   ((,class (:foreground "#da8548"))))
-   `(selectrum-prescient-secondary-highlight
-   ((,class (:foreground "#98be65"))))))
-
-(enable-theme 'zerodark)
-```
-
 ### For Vertico
+
 `vertico-prescient.el` configures filtering locally in the Vertico
 buffer. To do this, it modifies the values of `completion-styles`,
 `completion-category-overrides`, and `completion-category-defaults`.

diff --git a/corfu-prescient.el b/corfu-prescient.el
@@ -1,4 +1,4 @@
-;;; corfu-prescient.el --- Corfu integration -*- lexical-binding: t -*-
+;;; corfu-prescient.el --- prescient.el + Corfu -*- lexical-binding: t -*-
 
 ;; Copyright (C) 2022 Radian LLC and contributors
 

diff --git a/prescient.el b/prescient.el
@@ -223,7 +223,8 @@ contains no upper-case letters."
 (defcustom prescient-completion-highlight-matches t
   "Whether the `prescient' completion style should highlight matches.
 
-This affects the completion style, not other methods."
+See also the faces `prescient-primary-highlight' and
+`prescient-secondary-highlight'."
   :type 'boolean)
 
 (define-obsolete-face-alias 'selectrum-primary-highlight

diff --git a/scripts/check-line-length.bash b/scripts/check-line-length.bash
@@ -15,7 +15,7 @@ readarray -t files < <("${find[@]}" | sed 's#./##' | sort)
 
 code="$(cat <<"EOF"
 
-(length($0) >= 80 && $0 !~ /https?:\/\//) \
+(NR > 1 && length($0) >= 80 && $0 !~ /https?:\/\//) \
 { printf "%s:%d: %s\n", FILENAME, NR, $0 }
 
 EOF

diff --git a/selectrum-prescient.el b/selectrum-prescient.el
@@ -1,4 +1,4 @@
-;;; selectrum-prescient.el --- Selectrum integration -*- lexical-binding: t -*-
+;;; selectrum-prescient.el --- prescient.el + Selectrum -*- lexical-binding: t -*-
 
 ;; Copyright (C) 2019-2022 Radian LLC and contributors
 

diff --git a/vertico-prescient.el b/vertico-prescient.el
@@ -1,4 +1,4 @@
-;;; vertico-prescient.el --- Vertico integration -*- lexical-binding: t -*-
+;;; vertico-prescient.el --- prescient.el + Vertico -*- lexical-binding: t -*-
 
 ;; Copyright (C) 2022 Radian LLC and contributors