T-F-S / tcolorbox

A LaTeX package to create highly customizable colored boxes.
http://www.ctan.org/pkg/tcolorbox
LaTeX Project Public License v1.3c
213 stars 15 forks source link

Mention `pgfkeys` in doc #241

Closed muzimuzhi closed 6 months ago

muzimuzhi commented 11 months ago

In latest (v6.0.4) package doc, the 4th section "Options Keys" starts with

For the ⟨options⟩ in tcolorbox→P. 12 respectively \tcbset→P. 13 the following pgf keys can be applied. The key tree path /tcb/ is not to be used inside these macros.

https://github.com/T-F-S/tcolorbox/blob/6d98db4263c612279cca47efde22d1ef8404e573/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex#L4-L10

Since tcolorbox is based on pgf, it's understandable that the phrase "pgf keys" is used here. But from a stricter point of view, what tcolorbox's key-value scheme is based on is actually the pgfkeys package (CTAN page and corresponding section in unofficial online pgfmanual). Note pgfkeys can be used independently of pgf. Therefore all /tcb/xxx keys are actually pgfkeys keys.

T-F-S commented 11 months ago

I am not sure what you suggest to alter or add to the documentation. On https://ctan.org/pkg/pgfkeys there is pointed to the pgf/tikz manual where are documented in Section 87. I also point to this document in my text.

I could replace the following pgf keys by the following pgfkeys or the following pgfkeys keys, but I do not know, if that is really better...

muzimuzhi commented 9 months ago

Maybe

diff --git a/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex b/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex
index 9144696..5289f85 100644
--- a/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex
+++ b/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex
@@ -4,7 +4,11 @@
 \section{Option Keys}\label{sec:optkeys}%
 \tcbset{external/prefix=external/coreoptions_}%
 For the \meta{options} in \refEnv{tcolorbox} respectively \refCom{tcbset}
-the following |pgf| keys can be applied. The key tree path |/tcb/| is not to
+the following |pgf| keys can be applied%
+  \footnote{Strictly speaking, they are \texttt{pgfkeys} keys.
+    \texttt{pgfkeys} package is auto-loaded by \texttt{pgf} and
+    documented in \cite[Part~VII]{tantau:tikz_and_pgf}.}%
+. The key tree path |/tcb/| is not to
 be used inside these macros. It is easy to add your own style keys using
 the syntax for |pgf| keys, see \cite{tantau:tikz_and_pgf,sturm:latex} or the examples
 starting from page~\pageref{sec:latextutorial}.
T-F-S commented 9 months ago

I still do not see the importance of this addition, but it certainly does not hurt to add this explanation. Thank your for the formulation. I will put it with nearly unchanged into the next version.

T-F-S commented 6 months ago

Done with https://github.com/T-F-S/tcolorbox/releases/tag/v6.2.0

muzimuzhi commented 5 months ago

I still do not see the importance of this addition, but it certainly does not hurt to add this explanation.

One benefit might be, it would be more natural when the keys like /tcb/IfBlankTF and /tcb/IfEmptyTF are exported to a pgfkeys library some day in the future.

pgfkeys gained support for libraries in pgf v3.10.0, see