branch: externals/cape
commit 1a3775a8907254fd997a1c5c7be1775fa781b9aa
Author: Daniel Mendler <m...@daniel-mendler.de>
Commit: Daniel Mendler <m...@daniel-mendler.de>
Update README
---
README.org | 28 +++++++++++++++-------------
1 file changed, 15 insertions(+), 13 deletions(-)
diff --git a/README.org b/README.org
index 64039582d4..b687172d1e 100644
--- a/README.org
+++ b/README.org
@@ -189,23 +189,25 @@ then be used as a Capf via ~cape-company-to-capf~.
/Throw multiple Capfs under the Cape and get a Super-Capf!/
-Cape supports merging multiple Capfs using the function ~cape-super-capf~.
-*This feature is EXPERIMENTAL and should only be used carefully in special
scenarios. Due to some technical details, not all Capfs can be merged. Add
Capfs one by one and make sure that you get the desired outcome.*
+Cape supports merging multiple Capfs using the function ~cape-super-capf~. This
+feature is *EXPERIMENTAL* and should only be used carefully in special
scenarios.
+Due to some technical details, only a subset of Capfs can be merged. Merge
Capfs
+one by one and make sure that you get the desired outcome on each step.
Note that ~cape-super-capf~ is not needed if you want to use multiple Capfs
which
-are tried one by one, e.g., it is perfectly possible to use ~cape-file~
together
-with the Lsp-mode Capf or other programming mode Capfs by adding ~cape-file~ to
-the ~completion-at-point-functions~ list. The file completion will be
available in
-comments and string literals. ~cape-super-capf~ is only needed if you want to
-combine multiple Capfs, such that the candidates from multiple sources appear
-/together/ in the completion list at the same time.
-
-Completion table merging works only for tables which are sufficiently
-well-behaved and tables which do not define completion boundaries.
+are tried one after the other, for example you can use ~cape-file~ together
with
+programming mode Capfs by adding ~cape-file~ to the
~completion-at-point-functions~
+list. File completion will then be available in comments and string literals,
+but not in normal code. ~cape-super-capf~ is only necessary if you want to
combine
+multiple Capfs, such that the candidates from multiple sources appear
/together/
+in the completion list at the same time.
+
+Capf merging works only for completion functions which are sufficiently
+well-behaved and completion functions which do not define completion
boundaries.
~cape-super-capf~ has the same restrictions as ~completion-table-merge~ and
~completion-table-in-turn~. As a simple rule of thumb, ~cape-super-capf~ works
only
-well for static completion functions like ~cape-dabbrev~, ~cape-keyword~,
~cape-dict~,
-etc., but not for complex multi-step completions like ~cape-file~.
+for static completion functions like ~cape-dabbrev~, ~cape-keyword~,
~cape-dict~,
+etc., but not for multi-step completions like ~cape-file~.
#+begin_src emacs-lisp
;; Merge the dabbrev, dict and keyword capfs, display candidates together.
