where :key is a keywordp not among the primitive keyword hints
listed in *hint-keywords*, the :checker argument is optional, and
term1 and (if supplied) term2 are terms with certain free-variable
and signature restrictions described below. Henceforth, :key is
treated as a custom keyword hint, e.g., the user can employ :key in hints
to defthm, such as:

(defthm name ...
:hints (("Subgoal *1/1'" ... :key val ...))).

Custom keyword hints are complicated. To use them you must understand
state, multiple values (e.g., mv and mv-let), ACL2's notion
of error triples (see programming-with-state), how to generate ``soft''
errors with er, how to use fmt-strings to control output, how to
use computed hints (see computed-hints) and some aspects of ACL2's internal
event processing. Furthermore, it is possible to implement a custom keyword
hint that can make an event non-reproducible! So we recommend that these
hints be developed by ACL2 experts. Basically the custom keyword feature
allows the implementors and other experts to extend the hint facility without
modifying the ACL2 sources.

Term1 is called the ``generator'' term and term2 is called the
``checker'' term of the custom keyword hint :key. Together they specify
the semantics of the new custom keyword hint :key. Roughly speaking,
when a custom keyword hint is supplied by the user, as in

(defthm name ...
:hints (("Subgoal *1/1'" ... :my-hint val ...))).

the checker term is evaluated on val to check that val is of the
expected shape. Provided val passes the check, the generator term is
used to compute a standard hint. Like computed hints, the generator of a
custom keyword hint is allowed to inspect the actual clause on which it is
being fired. Indeed, it is allowed to inspect the entire list of hints
(standard and custom) supplied for that clause. Thus, in the most general
case, a custom keyword hint is just a very special kind of computed hint.