branch: externals/corfu
commit 6cfa4e982758030e9793c8376dd577870bc24b81
Author: Daniel Mendler <m...@daniel-mendler.de>
Commit: Daniel Mendler <m...@daniel-mendler.de>
Indent README
---
README.org | 238 ++++++++++++++++++++++++++++++-------------------------------
1 file changed, 119 insertions(+), 119 deletions(-)
diff --git a/README.org b/README.org
index 1182dab..fd64b55 100644
--- a/README.org
+++ b/README.org
@@ -11,146 +11,146 @@
* Introduction
-Corfu enhances the default completion in region function with a completion
-overlay. The current candidates are shown in a popup below or above the point.
-Corfu can be considered the minimalistic ~completion-in-region~ counterpart of
-the [[https://github.com/minad/vertico][Vertico]] minibuffer UI.
+ Corfu enhances the default completion in region function with a completion
+ overlay. The current candidates are shown in a popup below or above the
point.
+ Corfu can be considered the minimalistic ~completion-in-region~ counterpart
of
+ the [[https://github.com/minad/vertico][Vertico]] minibuffer UI.
-Corfu is a minimal package, which relies on the Emacs completion facilities and
-concentrates on providing a polished completion UI. Completions are either
-provided by commands like ~dabbrev-completion~ or by pluggable backends
-(~completion-at-point-functions~, Capfs). Many programming language major modes
-implement a Capf. Furthermore the language server packages,
[[https://github.com/joaotavora/eglot][Eglot]] and
[[https://github.com/emacs-lsp/lsp-mode][Lsp-mode]],
-both use Capfs which talk to the LSP server to retrieve the completions.
+ Corfu is a minimal package, which relies on the Emacs completion facilities
and
+ concentrates on providing a polished completion UI. Completions are either
+ provided by commands like ~dabbrev-completion~ or by pluggable backends
+ (~completion-at-point-functions~, Capfs). Many programming language major
modes
+ implement a Capf. Furthermore the language server packages,
[[https://github.com/joaotavora/eglot][Eglot]] and
[[https://github.com/emacs-lsp/lsp-mode][Lsp-mode]],
+ both use Capfs which talk to the LSP server to retrieve the completions.
-Corfu does not include custom completion backends. In contrast, the complex
-Company package includes custom completion backends, which deviate from the
-Emacs completion infrastructure.
+ Corfu does not include custom completion backends. In contrast, the complex
+ Company package includes custom completion backends, which deviate from the
+ Emacs completion infrastructure.
-*NOTE*: Corfu uses child frames to show the popup; on non-graphical displays it
-will fall back to the default setting of the ~completion-in-region-function~.
+ *NOTE*: Corfu uses child frames to show the popup; on non-graphical displays
it
+ will fall back to the default setting of the ~completion-in-region-function~.
-[[https://github.com/minad/corfu/blob/main/screenshot.png?raw=true]]
+ [[https://github.com/minad/corfu/blob/main/screenshot.png?raw=true]]
* Features
-- Timer-based auto-completions (off by default, set ~corfu-auto~)
-- Popup display with scrollbar indicator and arrow key navigation
-- The popup must be summoned explicitly by pressing =TAB=
-- The current candidate is inserted with =TAB= and selected with =RET=
-- Candidates sorting by prefix, string length and alphabetically
-- Completion is automatically terminated after candidate selection
-- Filter string can contain arbitrary characters and spaces, if
- ~corfu-quit-at-boundary~ is nil. This is needed when filtering with the
- [[https://github.com/oantolin/orderless][Orderless]] completion style.
-- Deferred completion style highlighting for performance
-- Jumping to location/documentation of current candidate (Company extension)
-- Support for ~annotation-function~ and ~affixation-function~
+ - Timer-based auto-completions (off by default, set ~corfu-auto~)
+ - Popup display with scrollbar indicator and arrow key navigation
+ - The popup must be summoned explicitly by pressing =TAB=
+ - The current candidate is inserted with =TAB= and selected with =RET=
+ - Candidates sorting by prefix, string length and alphabetically
+ - Completion is automatically terminated after candidate selection
+ - Filter string can contain arbitrary characters and spaces, if
+ ~corfu-quit-at-boundary~ is nil. This is needed when filtering with the
+ [[https://github.com/oantolin/orderless][Orderless]] completion style.
+ - Deferred completion style highlighting for performance
+ - Jumping to location/documentation of current candidate (Company extension)
+ - Support for ~annotation-function~ and ~affixation-function~
* Configuration
-Corfu is available from [[http://elpa.gnu.org/packages/corfu.html][GNU ELPA]],
such that it can be installed directly via
-~package-install~. After installation, the local minor mode can be enabled with
-=M-x corfu-mode=. In order to configure Corfu and other packages in your
-init.el, you may want to use ~use-package~. I recommend to give Orderless
-completion a try, which is different from the familiar prefix TAB completion.
-However Corfu works well with the default completion styles, the use of
-Orderless is not a necessity. Here is an example configuration:
-
-#+begin_src emacs-lisp
- (use-package corfu
- ;; Optional customizations
- ;; :custom
- ;; (corfu-cycle t) ;; Enable cycling for `corfu-next/previous'
- ;; (corfu-auto t) ;; Enable auto completion
- ;; (corfu-quit-at-boundary t) ;; Automatically quit at word boundary
- ;; (corfu-quit-no-match t) ;; Automatically quit if there is no match
-
- ;; Optionally use TAB for cycling, default is `corfu-complete'.
- ;; :bind (:map corfu-map
- ;; ("TAB" . corfu-next)
- ;; ([tab] . corfu-next)
- ;; ("S-TAB" . corfu-previous)
- ;; ([backtab] . corfu-previous))
-
- ;; You may want to enable Corfu only for certain modes.
- ;; :hook ((prog-mode . corfu-mode)
- ;; (shell-mode . corfu-mode)
- ;; (eshell-mode . corfu-mode))
-
- ;; Recommended: Enable Corfu globally.
- ;; This is recommended since dabbrev can be used globally (M-/).
- :init
- (corfu-global-mode))
-
- ;; Optionally use the `orderless' completion style.
- ;; Enable `partial-completion' for files to allow path expansion.
- ;; You may prefer to use `initials' instead of `partial-completion'.
- (use-package orderless
- :init
- (setq completion-styles '(orderless)
- completion-category-defaults nil
- completion-category-overrides '((file (styles .
(partial-completion))))))
-
- ;; Dabbrev works with Corfu
- (use-package dabbrev
- ;; Swap M-/ and C-M-/
- :bind (("M-/" . dabbrev-completion)
- ("C-M-/" . dabbrev-expand)))
-
- ;; A few more useful configurations...
- (use-package emacs
- :init
- ;; TAB cycle if there are only few candidates
- (setq completion-cycle-threshold 3)
-
- ;; Enable indentation+completion using the TAB key.
- ;; `completion-at-point' is often bound to M-TAB.
- (setq tab-always-indent 'complete))
-#+end_src
+ Corfu is available from [[http://elpa.gnu.org/packages/corfu.html][GNU
ELPA]], such that it can be installed directly via
+ ~package-install~. After installation, the local minor mode can be enabled
with
+ =M-x corfu-mode=. In order to configure Corfu and other packages in your
+ init.el, you may want to use ~use-package~. I recommend to give Orderless
+ completion a try, which is different from the familiar prefix TAB completion.
+ However Corfu works well with the default completion styles, the use of
+ Orderless is not a necessity. Here is an example configuration:
+
+ #+begin_src emacs-lisp
+ (use-package corfu
+ ;; Optional customizations
+ ;; :custom
+ ;; (corfu-cycle t) ;; Enable cycling for `corfu-next/previous'
+ ;; (corfu-auto t) ;; Enable auto completion
+ ;; (corfu-quit-at-boundary t) ;; Automatically quit at word boundary
+ ;; (corfu-quit-no-match t) ;; Automatically quit if there is no match
+
+ ;; Optionally use TAB for cycling, default is `corfu-complete'.
+ ;; :bind (:map corfu-map
+ ;; ("TAB" . corfu-next)
+ ;; ([tab] . corfu-next)
+ ;; ("S-TAB" . corfu-previous)
+ ;; ([backtab] . corfu-previous))
+
+ ;; You may want to enable Corfu only for certain modes.
+ ;; :hook ((prog-mode . corfu-mode)
+ ;; (shell-mode . corfu-mode)
+ ;; (eshell-mode . corfu-mode))
+
+ ;; Recommended: Enable Corfu globally.
+ ;; This is recommended since dabbrev can be used globally (M-/).
+ :init
+ (corfu-global-mode))
+
+ ;; Optionally use the `orderless' completion style.
+ ;; Enable `partial-completion' for files to allow path expansion.
+ ;; You may prefer to use `initials' instead of `partial-completion'.
+ (use-package orderless
+ :init
+ (setq completion-styles '(orderless)
+ completion-category-defaults nil
+ completion-category-overrides '((file (styles .
(partial-completion))))))
+
+ ;; Dabbrev works with Corfu
+ (use-package dabbrev
+ ;; Swap M-/ and C-M-/
+ :bind (("M-/" . dabbrev-completion)
+ ("C-M-/" . dabbrev-expand)))
+
+ ;; A few more useful configurations...
+ (use-package emacs
+ :init
+ ;; TAB cycle if there are only few candidates
+ (setq completion-cycle-threshold 3)
+
+ ;; Enable indentation+completion using the TAB key.
+ ;; `completion-at-point' is often bound to M-TAB.
+ (setq tab-always-indent 'complete))
+ #+end_src
* Key bindings
-Corfu uses a transient keymap ~corfu-map~ which is active while the popup is
shown.
-The keymap defines the following remappings and bindings:
-
-- ~beginning-of-buffer~ -> ~corfu-first~
-- ~end-of-buffer~ -> ~corfu-last~
-- ~scroll-down-command~ -> ~corfu-scroll-down~
-- ~scroll-up-command~ -> ~corfu-scroll-up~
-- ~next-line~, =down=, =M-n= -> ~corfu-next~
-- ~previous-line~, =up=, =M-p= -> ~corfu-previous~
-- ~completion-at-point~, =TAB= -> ~corfu-complete~
-- =RET= -> ~corfu-insert~
-- =M-g= -> ~corfu-show-location~
-- =M-h= -> ~corfu-show-documentation~
-- =C-g=, =ESC ESC ESC= -> ~corfu-quit~
+ Corfu uses a transient keymap ~corfu-map~ which is active while the popup is
shown.
+ The keymap defines the following remappings and bindings:
+
+ - ~beginning-of-buffer~ -> ~corfu-first~
+ - ~end-of-buffer~ -> ~corfu-last~
+ - ~scroll-down-command~ -> ~corfu-scroll-down~
+ - ~scroll-up-command~ -> ~corfu-scroll-up~
+ - ~next-line~, =down=, =M-n= -> ~corfu-next~
+ - ~previous-line~, =up=, =M-p= -> ~corfu-previous~
+ - ~completion-at-point~, =TAB= -> ~corfu-complete~
+ - =RET= -> ~corfu-insert~
+ - =M-g= -> ~corfu-show-location~
+ - =M-h= -> ~corfu-show-documentation~
+ - =C-g=, =ESC ESC ESC= -> ~corfu-quit~
* Complementary packages
-Corfu works well together with all packages providing code completion via the
-~completion-at-point-functions~. Furthermore it supports various completion
-styles, including the advanced
[[https://github.com/oantolin/orderless][Orderless]] completion style, where
the filtering
-expressions are separated by spaces (see ~corfu-quit-at-boundary~).
+ Corfu works well together with all packages providing code completion via the
+ ~completion-at-point-functions~. Furthermore it supports various completion
+ styles, including the advanced
[[https://github.com/oantolin/orderless][Orderless]] completion style, where
the filtering
+ expressions are separated by spaces (see ~corfu-quit-at-boundary~).
-You may also want to look into my
[[https://github.com/minad/vertico][Vertico]] package. Vertico is the minibuffer
-counterpart of Corfu.
+ You may also want to look into my
[[https://github.com/minad/vertico][Vertico]] package. Vertico is the minibuffer
+ counterpart of Corfu.
* Caveats
-Corfu works in most scenarios. However there are a few known technical caveats.
+ Corfu works in most scenarios. However there are a few known technical
caveats.
-- Corfu falls back to the default Completion buffer on non-graphical displays,
- since Corfu requires child frames.
-- The abort handling could be improved, for example the input could be undone.
-- Company kind icons, docsig and match data are not supported
- (~company-kind~, ~company-docsig~, ~company-match~).
-- No support for multi-backends like Company. A possible multi-capf backend
- could be implemented.
-- No sorting by history, since ~completion-at-point~ does not
- maintain a history (See branch =history= for a possible solution).
+ - Corfu falls back to the default Completion buffer on non-graphical
displays,
+ since Corfu requires child frames.
+ - The abort handling could be improved, for example the input could be
undone.
+ - Company kind icons, docsig and match data are not supported
+ (~company-kind~, ~company-docsig~, ~company-match~).
+ - No support for multi-backends like Company. A possible multi-capf backend
+ could be implemented.
+ - No sorting by history, since ~completion-at-point~ does not
+ maintain a history (See branch =history= for a possible solution).
* Contributions
-Since this package is part of [[http://elpa.gnu.org/packages/corfu.html][GNU
ELPA]] contributions require a copyright
-assignment to the FSF.
+ Since this package is part of [[http://elpa.gnu.org/packages/corfu.html][GNU
ELPA]] contributions require a copyright
+ assignment to the FSF.
