README: Clarification about completion-category-* variables (Fix #117)

2 files changed, 14 insertions, 8 deletions

diff --git a/README.org b/README.org
index 49a08cc..ec56d2f 100644
--- a/README.org
+++ b/README.org
@@ -41,10 +41,13 @@ from [[https://github.com/minad/consult][Consult]].
 
 To use a completion style with any of the above mentioned completion
 UIs simply add it as an entry in the variables =completion-styles= and
-=completion-category-overrides= (see their documentation). You may also
-want to modify the =completion-category-defaults= variable, which serves
-as a default value for =completion-category-overrides=: if you want to
-use =orderless= exclusively, set both variables to =nil=.
+=completion-category-overrides= and =completion-category-defaults= (see
+their documentation).
+
+The =completion-category-defaults= variable serves as a default value
+for =completion-category-overrides=. If you want to use =orderless=
+exclusively, set both variables to =nil=, but be aware that
+=completion-category-defaults= is modified by packages at load time.
 
 With a bit of effort, it might still be possible to use =orderless= with
 other completion UIs, even if those UIs don't support the standard
diff --git a/orderless.texi b/orderless.texi
index c62037d..74fc048 100644
--- a/orderless.texi
+++ b/orderless.texi
@@ -91,10 +91,13 @@ from @uref{https://github.com/minad/consult, Consult}.
 
 To use a completion style with any of the above mentioned completion
 UIs simply add it as an entry in the variables @samp{completion-styles} and
-@samp{completion-category-overrides} (see their documentation). You may also
-want to modify the @samp{completion-category-defaults} variable, which serves
-as a default value for @samp{completion-category-overrides}: if you want to
-use @samp{orderless} exclusively, set both variables to @samp{nil}.
+@samp{completion-category-overrides} and @samp{completion-category-defaults} (see
+their documentation).
+
+The @samp{completion-category-defaults} variable serves as a default value
+for @samp{completion-category-overrides}. If you want to use @samp{orderless}
+exclusively, set both variables to @samp{nil}, but be aware that
+@samp{completion-category-defaults} is modified by packages at load time.
 
 With a bit of effort, it might still be possible to use @samp{orderless} with
 other completion UIs, even if those UIs don't support the standard