From f857fc8f4e2aa72e90bbeeeb645ef05d35cbb3d2 Mon Sep 17 00:00:00 2001
From: Fritz Webering <fritz.webering@ims.uni-hannover.de>
Date: Thu, 10 Mar 2022 00:12:58 +0100
Subject: [PATCH] docs: improve /handler config docs

Add missing 'only existing' exceptions.
Expand the example explaining the interaction
between '.search also' and '/handler config'.

Signed-off-by: Fritz Webering <fritz@webering.eu>
---
 doc/generic/pgf/pgfmanual-en-pgfkeys.tex | 34 +++++++++++++++++++-----
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/doc/generic/pgf/pgfmanual-en-pgfkeys.tex b/doc/generic/pgf/pgfmanual-en-pgfkeys.tex
index ba0f6267a..6ebe7d985 100644
--- a/doc/generic/pgf/pgfmanual-en-pgfkeys.tex
+++ b/doc/generic/pgf/pgfmanual-en-pgfkeys.tex
@@ -810,8 +810,9 @@ \subsubsection{Keys That Are Handled}
 \begin{key}{/handler config/only existing/add exception=\marg{key handler name}}
     Allows to add exceptions to the |/handler config=only existing| feature.
     Initially exceptions for the key handlers |/.cd|, |/.try|, |/.retry|,
-    |/.lastretry| and |/.unknown| are defined. The value \marg{key handler
-    name} should be the name of a key handler.
+    |/.lastretry|, |/.unknown|, |/.expand once|, |/.expand twice| and
+    |/.expanded| are defined. The value \marg{key handler name} should be
+    the name of a key handler.
 \end{key}
 
 
@@ -1249,7 +1250,7 @@ \subsubsection{Defining Value-, Macro-, If- and Choice-Keys}
     and, thus, |\pgfkeysnovalue| will be stored in |/my key|.
 
     To retrieve the value stored in a key, the handler |/.get| is used.
-    
+
     \medskip
     \emph{Remark:} A key can both store a value and execute commands%
     \footnote{This behavior was partially changed in \pgfname{} 3.1.6 and then
@@ -1623,10 +1624,31 @@ \subsubsection{Handlers for Forwarding}
     |/handler config=full or existing| when you use |/.search also|, that is,
     use
     %
-\begin{codeexample}[code only]
+\begin{codeexample}[]
+\pgfkeys{
+    /main path/.search also={/second path, /third path},
+    /handlers/.unknown/.code={Unknown key `\pgfkeyscurrentkey'},
+    /handler config=full or existing,
+    % This works, because these are a full keys:
+    /second path/key/.code={Original value},
+    /third path/other key/.code={Other value},
+}
+
 \pgfkeys{
-   /main path/.search also={/secondary path},
-   /handler config=full or existing}
+    /main path/.cd,
+    % This works, because the keys are found in '.search also'.
+    key/.code={value1},
+    other key/.code={value2},
+}
+\texttt{key} = \pgfkeys{/second path/key},
+\texttt{other key} = \pgfkeys{/third path/other key},
+
+\pgfkeys{
+    /main path/.cd,
+    % The '.code' handler is not executed because 'undefined key'
+    % does not exist in either of the '.search also' paths.
+    undefined key/.code={New value},
+}
 \end{codeexample}
     %
 \end{handler}