diff --git a/org-ql.el b/org-ql.el
index 4c67cf3..95d6d02 100644
--- a/org-ql.el
+++ b/org-ql.el
@@ -905,40 +905,52 @@ PREDICATES should be the value of `org-ql-predicates'."
 (cl-defmacro org-ql-defpred (name args docstring &key body preambles normalizers)
   "Define an `org-ql' selector predicate named `org-ql--predicate-NAME'.
 NAME may be a symbol or a list of symbols: if a list, the first
-is used as NAME and the rest are aliases (which should be
-normalized to the name using NORMALIZERS).  ARGS is a
-`cl-defun'-style argument list.  DOCSTRING is the function's
-docstring.  BODY is the body of the predicate.
+is used as NAME and the rest are aliases.  A function is only
+created for NAME, not for aliases, so a normalizer should be used
+to replace aliases with NAME in queries (keep reading).
 
-Predicate bodies will be evaluated with point on the beginning of
-an Org heading and should return non-nil if the heading's entry
-is a match.
+ARGS is a `cl-defun'-style argument list.  DOCSTRING is the
+function's docstring.
+
+BODY is the body of the predicate.  It will be evaluated with
+point on the beginning of an Org heading and should return
+non-nil if the heading's entry is a match.
 
 PREAMBLES and NORMALIZERS are lists of `pcase' forms matched
-against Org QL query sexps.
+against Org QL query sexps.  They are spliced into `pcase' forms
+in the definitions of the functions `org-ql--query-preamble' and
+`org-ql--normalize-query', which see.  Those functions are
+redefined when this macro is expanded, unless variable
+`org-ql-defpred-defer' is non-nil, in which case those functions
+should be redefined manually after defining predicates by calling
+`org-ql--define-preamble-fn' and `org-ql--define-normalize-query'.
 
-NORMALIZERS are used to normalize queries to standard forms.  For
-example, predicate aliases are replaced with predicate names.
+NORMALIZERS are used to normalize query expressions to standard
+forms.  For example, when the predicate has aliases, the aliases
+should be replaced with predicate names using a normalizer.
 Also, predicate arguments may be put into a more optimal form so
 that the predicate has less work to do at query time.
 
 PREAMBLES refer to regular expressions which may be used to
-search through a buffer directly to a potential match (rather
-than testing the predicate body on each heading).  (Naming things
-is hard.)  In each `pcase' form in PREAMBLES, the expression
-should be a plist with the following keys, each value of which
-should be an expression which may refer to variables bound in the
-pattern:
+search through a buffer directly to a potential match rather than
+testing the predicate body on each heading.  (Naming things is
+hard.)  In each `pcase' form in PREAMBLES, the `pcase'
+expression (not the pattern) should be a plist with the following
+keys, each value of which should be an expression which may refer
+to variables bound in the pattern:
 
   :regexp     Regular expression which searches directly to a
               potential match.
   :case-fold  Bound to `case-fold-search' around the regexp search.
 
-  :query      Expression which should replace the query, or `query'
-              if it should not be changed (e.g. if the regexp is
-              insufficient to determine whether a heading
-              matches, in which case the predicate's body needs
-              to be tested on the heading).
+  :query      Expression which should replace the query expression,
+              or `query' if it should not be changed (e.g. if the
+              regexp is insufficient to determine whether a
+              heading matches, in which case the predicate's body
+              needs to be tested on the heading).  If the regexp
+              guarantees a match, this may be simply t, leaving the
+              query expression with no work to do, which improves
+              performance.
 
 For convenience, within the `pcase' patterns, the symbol
 `predicate-names' is a special form which is replaced with a