What is the difference between "(no default, initially xxx)" and "(default xxx)" in the TikZ manual?
The pgfkeys
documentation gives some clue: .initial
is the value stored to the key at the time of definition, .default
is the value that is used, if the user does not specify a value for the key
Example with tcolorbox
(which uses pgfkeys
and tikz
in the backend)
The key lower separated
is a boolean key, which is set to true
in the beginning (initially), but it is sufficient to say lower separated
only as the key, omitting =true
, this way it is not necessary to remember the default value.
Now, the colframe
key option is initially set to black!75!white
, so this color will be used if colframe
is not specified otherwise, but it has no default value, so just saying colframe
is no valid syntax then.
The example from the O.P. does not compile for me, but initially lineto
means that the key is set to lineto
from the beginning and is used this way, but no default
means, that it is not possible to say just pre
, i.e a value must be specified with this key then.
We see the same behaviour in almost any key-value
interface codes.
\documentclass{article}
\usepackage[most]{tcolorbox}
\begin{document}
\begin{tcolorbox}[lower separated]
Foo
\tcblower
foobar
\end{tcolorbox}
\end{document}
To complement Christian's answer, it may help to distinguish "code keys" (which have a /.code
handler) and "value keys" (which merely store a value). Indeed, a single key can be both (and more), but the key point is that the /.default
handler takes care of default arguments for /.code
handlers, while the /.initial
handler takes care of the initial value (stored in \pgfkeys@<key>
and accessed through e.g. \pgfkeysvalueof
and \pgfkeyssetvalue
). This answer may help to grasp the distinction.
Anyway, let us consider an example, with only pgfkeys
:
\documentclass{article}
\usepackage{pgfkeys}
\begin{document}
\pgfkeys{/code key with initial/.initial={initial value}, /code key with initial/.code={code key with initial(#1)}}
\pgfkeys{/code key with default/.default={default value}, /code key with default/.code={code key with default(#1)}}
\pgfkeys{/value key with initial/.initial={initial value}}
\pgfkeys{/value key with default/.default={default value}}
\begin{enumerate}
\item \pgfkeys{/code key with initial}
% => code key with initial()
\item \pgfkeys{/code key with default}
% => code key with default(default value)
\item \pgfkeys{/code key with initial=argument}
% => code key with initial(argument)
\item \pgfkeys{/code key with default=argument}
% => code key with default(argument)
\item \pgfkeysvalueof{/value key with initial}
% => initial value
\item \pgfkeysvalueof{/value key with default}
% => (nothing!)
\item \pgfkeyssetvalue{/value key with initial}{new value} \pgfkeysvalueof{/value key with initial}
% => new value
\item \pgfkeyssetvalue{/value key with default}{new value} \pgfkeysvalueof{/value key with default}
% => new value
\end{enumerate}
\end{document}
I defined two "code keys" so that they merely print their name and argument. When there is no argument, the default value is used instead (when defined) [and the initial value is not used at all]. When an argument is given, the default value is indeed not used.
Now, we can also use keys to store values, and retrieve them with \pgfkeysvalueof
(among other possibilities). In this case, the value of the key is set to the value given to /.initial
when the key is defined, as explained by Christian, and the default value has no effect.
Lastly, we could write a /.code
handler for a key using the value of the same key, but then you enter a world of doom because you overload the default \pgfkeys@<key>/.@cmd
(set by /.code
) which would (temporarily! see the documentation of /.initial
and this answer) set the value of the key to something ...
Concerning your example, what the documentation calls a "default value" is in fact an initial value, as we can check on the source, tikzlibrarydecorations.code.tex
, where we find /pgf/decoration/pre/.initial=lineto
. This key is used several lines after through \pgfkeysvalueof
.
Here, using pre=[something]
in tikz will modify the value of the key only locally (through the default handler) because everything is executed inside a group. We can reproduce this with a simple pgfkeys
example,
\documentclass{article}
\usepackage{pgfkeys}
\begin{document}
\def\pgfkeysingroup#1{
\bgroup
\pgfkeys{#1}
\egroup
}
\pgfkeys{/val/.initial={initial}, /do/.code={val=\pgfkeysvalueof{/val}}}
\pgfkeysingroup{do}
% => val=initial
\pgfkeysingroup{val=argument,do}
% => val=argument
\pgfkeysingroup{do}
% => val=initial
\end{document}
Contrast with the following:
\documentclass{article}
\usepackage{pgfkeys}
\begin{document}
\pgfkeys{/val/.initial={initial}, /do/.code={val=\pgfkeysvalueof{/val}}}
\pgfkeys{do}
% => val=initial
\pgfkeys{val=argument,do}
% => val=argument
\pgfkeys{do}
% => val=argument
\end{document}