What is the difference between "(no default, initially xxx)" and "(default xxx)" in the TikZ manual?

Question

This is not the first time I encounter this problem. Are there any differences between "(no default, initially xxx)" and "(default xxx)"? Thank you.

Answer 1

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}

Answer 2

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 /.codehandlers, 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}