Merge pull request pgf-tikz#961 from muzimuzhi/improve-doc

Document \pgfpointtransformed and the relation of /.code and /.initial

doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex

@@ -522,6 +522,16 @@ \subsubsection{Saving and Restoring the Coordinate Transformation Matrix}
 \end{command}
 
 
+\subsubsection{Applying Coordinate Transformation to Points}
+
+\begin{command}{\pgfpointtransformed\marg{point}}
+    Applies current transformation matrix to \marg{point} $(x,y)$ and returns a
+    transformed point $(ax+cy+s,bx+dy+t)$. Normally, this is done automatically
+    by commands like |\pgfpathlineto| or |\pgfpathmoveto|, but sometimes you
+    may wish to access a transformed point yourself.
+\end{command}
+
+
 \subsubsection{Computing Adjustments for Coordinate Transformations}
 \label{section-adjustment-transformations}
 

doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex

@@ -1253,6 +1253,25 @@ \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
+    restored in 3.1.7.  For compatibility reasons, this behavior will not be
+    changed in future releases anymore.}.
+    If so, using \meta{key} will \emph{always} execute commands with the passed
+    value, or the default value |\pgfkeysnovalue| if no value is provided.
+    Note that the stored value is never used. To update the stored value, the
+    handler |/.initial| or command |\pgfkeyssetvalue| is used.
+    %
+\begin{codeexample}[]
+\pgfkeys{/my key/.initial=red}
+\pgfkeys{/my key/.code=#1}
+% "/my key" now both stores the value "red" and executes commands
+\pgfkeys{/my key=blue}
+% "/my key" now still stores the value "red"
+\end{codeexample}
+    %
 \end{handler}
 
 \begin{handler}{{.get}|=|\meta{macro}}