[elpa] externals/capf-autosuggest 8f091ce 26/63: Extend description

[ELPA Syncer]

branch: externals/capf-autosuggest
commit 8f091ce819a8a791b821b337e30dc57e7dbbdfd0
Author: jakanakaevangeli <jakanakaevangeli@chiru.no>
Commit: jakanakaevangeli <jakanakaevangeli@chiru.no>

    Extend description
---
 capf-autosuggest.el | 66 ++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 60 insertions(+), 6 deletions(-)

diff --git a/capf-autosuggest.el b/capf-autosuggest.el
index c1cb88e..d0dc3ed 100644
--- a/capf-autosuggest.el
+++ b/capf-autosuggest.el
@@ -24,12 +24,66 @@
 
 ;;; Commentary:
 
-;; capf-autosuggest-mode is a minor mode that lets you preview the first
-;; completion candidate of completion-at-point as an overlay.  This is very
-;; useful in combination with history-capf.el which implements
-;; completion-at-point functions for comint and eshell history.  Previewing the
-;; most recent matching history element gives you auto-suggestions, familiar to
-;; users of zsh-autosuggestions and fish.
+;; capf-autosuggest lets you preview the most recent matching history element,
+;; similar to zsh-autosuggestions or fish.  It works in eshell and in modes
+;; derived from comint-mode, for example M-x shell or M-x run-python
+;;
+;; Installation:
+;;
+;; Add the following to your Emacs init file:
+;;
+;;  (add-to-list 'load-path "/path/to/emacs-capf-autosuggest")
+;;  (require 'capf-autosuggest)
+;;  (add-hook 'comint-mode-hook #'capf-autosuggest-setup-comint)
+;;  (add-hook 'eshell-mode-hook #'capf-autosuggest-setup-eshell)
+;;
+;; Configuration:
+;;
+;; Use `capf-autosuggest-define-partial-accept-cmd' to make a command that can
+;; move point into an auto-suggested layer.
+;;
+;; Example: to make C-M-f (forward-sexp) movable into suggested text, put the
+;; following into you init file:
+;;
+;;  (with-eval-after-load 'capf-autosuggest
+;;    (capf-autosuggest-define-partial-accept-cmd
+;;     movable-forward-sexp forward-sexp)
+;;    (define-key capf-autosuggest-active-mode-map [remap forward-sexp]
+;;      #'movable-forward-sexp))
+;;
+;; Details:
+;;
+;; capf-autosuggest provides a minor mode, capf-autosuggest-mode, that lets you
+;; preview the first completion candidate for in-buffer completion as an
+;; overlay.  Instead of using the default hook `completion-at-point-functions',
+;; it uses its own hook `capf-autosuggest-capf-functions'.  However, by
+;; default, this hook contains a function that reads the default hook, but only
+;; if point is at end of line, because an auto-suggested overlay can be
+;; annoying in the middle of a line.  If you want, you can try enabling this
+;; minor mode in an ordinary buffer for previewing tab completion candidates at
+;; end of line.
+;;
+;; completion-at-point functions for comint and eshell history are also
+;; provided.  Because they are less useful for tab completion and more useful
+;; for auto-suggestion preview, they should be added to
+;; `capf-autosuggest-capf-functions', which doesn't interfere with tab
+;; completion.  The setup functions mentioned in "Installation" paragraph add
+;; them to this hook locally.  By default, if there are no matches for history
+;; completion and point is at end of line, we fall back to previewing the
+;; default tab completion candidates, as described in the previous paragraph.
+;;
+;; You can customize this behaviour by customizing
+;; `capf-autosuggest-capf-functions'. For example, you could add
+;; `capf-autosuggest-orig-capf' to enable auto-suggestions of tab completion
+;; candidates in the middle of a line.
+;;
+;; Alternatives:
+;;
+;; There is also esh-autosuggest[1] with similar functionality.  Differences:
+;; it optionally allows having a delay, it depends on emacs package company, it
+;; is implemented only for eshell.
+;;
+;; [1]: http://github.com/dieggsy/esh-autosuggest
 
 ;;; Code: