update documentation of libraries

doc/tikzpingus-doc.tex

@@ -41,6 +41,7 @@
 
 \newlist{inlist}{enumerate*}{1}
 \setlist[inlist]{itemjoin={{, }},itemjoin*={{, and }},label=$\roman*$),mode=boxed}
+
 \let\say\enquote
 \def\DTLlistformatoxford{,}
 \def\DTLandname{and}
@@ -152,7 +153,7 @@
 
 \def\ShowcasePengu#1=#2;{{\hypersetup{linkcolor=.}%
 \hyperref[pk:/pingu/#1]{%
-	\parbox[b][\pingu@showcase@height]{.166\linewidth}{\centering\ifx!#2!\def\Arg{}\else\def\Arg{=#2}\fi\edef\MakeShowcase{\noexpand\RawShowcase{#1}{\Arg}}\MakeShowcase}%
+	\parbox[b][\pingu@showcase@height]{.14\linewidth}{\centering\ifx!#2!\def\Arg{}\else\def\Arg{=#2}\fi\edef\MakeShowcase{\noexpand\RawShowcase{#1}{\Arg}}\MakeShowcase}%
 }}}
 \def\pengu@all@showcases{}
 % we mix them somewhat funny
@@ -165,16 +166,12 @@
 \RedeclareSectionCommand[runin=false,afterskip=-2mm]{subsection}
 
 \tcbset{%
-	colframe=gray,enhanced,breakable,
-	arc=2mm, arc is angular,
-	fonttitle=\bfseries,
-	sidebyside,
+	colframe=gray,enhanced,breakable, arc=2mm, arc is angular,
+	fonttitle=\bfseries, sidebyside,
 	listing options={style=lstpingu,language=pingulang},
 	center lower,segmentation at break=false,
-	righthand width=4.75cm,
-	bottom=0pt,top=0pt,boxsep=2.25pt,
-	before lower app={},
-	colback=white
+	righthand width=4.75cm, bottom=0pt,top=0pt,boxsep=2.25pt,
+	before lower app={}, colback=white
 }
 \lstMakeShortInline[style=lstpingu,language=pingulang,basicstyle=\relsize{-1}\ttfamily\@declaredcolor{black!90!white},moredelim={[s][\itshape]{<}{>}}]{|}
 
@@ -203,7 +200,8 @@
 		\ifx\@tmpb\@empty\lpingu{#1#2}\else\lpingu{#1#2 =\ }\texttt{<\textit{\@tmpb}>}\fi\hfill
 				\ifx\@tmp\@empty\else{\@declaredcolor{gray}(}#4{\@declaredcolor{gray})}\fi
 		}
-	}\par\endgroup}
+	}\ifcsname pingu@@lib@#2@\endcsname\index{Libraries!\textit{\csname pingu@@lib@#2@\endcsname}!#2?\hyperref[pk:#1#2]{\protect\lpingu{#2}}}\rlap{~\quad$\underset{\text{\tiny\smash{\raisebox{3pt}{\textsf{\hyperref[Libraries]{\color{gray}Library}}}}}}{\text{\textit{\footnotesize\strut\csname pingu@@lib@#2@\endcsname}}}$}\fi\par\endgroup
+}
 {\endminipage\smallskip\par}
 
 \def\singleshortcut#1#2"#3"#4{\def\cursub{#2?\hyperref[pk:#1#2]{\protect\lpingu{#2}}!}\keyexplain[#1]{#2 #3}{\csname pinguopt#4\endcsname}{\csname pingudefa#4\endcsname}%
@@ -246,8 +244,6 @@
 	{\@declaredcolor{gray}\footnotesize This is an alias for \keyref[#1]{#3}.}%
 \endkeyexplain\endgroup}
 
-\def\lib#1{\tikz[baseline=-.6ex]\node[draw=teal,fill=teal!3!white,thin,rounded corners=2pt,inner ysep=0pt,outer ysep=.33em]{\sffamily\strut#1};}
-
 \def\lib#1{\tikz[baseline=-.6ex]\node[draw=teal,fill=teal!3!white,very thick,rounded corners=2pt,inner ysep=0pt]{\sffamily\strut#1};}
 
 \def\TikZ{Ti\textit{k}Z}
@@ -270,9 +266,8 @@
 	\fi% csx kill to stop infinite
 	\global\advance\count@\@ne
 }%
-\llap{\phantom{x}}% this is somewhat of a hack and i do not know why
-% it is needed to show penguins
-\@tempcnta\z@
+}
+\def\TypesetShowcases{\@tempcnta\z@
 \begingroup\parskip\z@ \parindent\z@
 \@for\@elem:=\pengu@all@showcases\do{%
 	\advance\@tempcnta\@ne
@@ -281,19 +276,18 @@
 	% space to space cmd
 	\edef\@tmp{\noexpand\ShowcasePengu\@elem;}\hfill\@tmp\hfill
 \fi}%
-\endgroup\global\let\pengu@all@showcases\@empty
-}
+\endgroup\global\let\pengu@all@showcases\@empty}
 
 \title{The \texorpdfstring{\tikzpingus}{tikzpingus} package}
-\subtitle{penguins in \TikZ}
+% \subtitle{Penguins with \TikZ}
 \author{%
-	\texorpdfstring{Florian Sihler\\[.4em]
-		\url{https://github.com/EagleoutIce/tikzpingus}
+	\texorpdfstring{Florian Sihler\\*
+		\hypersetup{colorlinks=false}\url{https://github.com/EagleoutIce/tikzpingus}
 	}{Florian Sihler}}
 \date{Version v1.0 \textendash\ 2022/08/14}
 
 \begin{document}
-{\let\newpage\relax\maketitle} % kill page break?
+\maketitle
 
 \section{Motivation}
 
@@ -325,24 +319,21 @@ \subsection{Copyright}
 The shown example penguins are purely fictional characters, any resemblance to real penguins or real persons is purely coincidental and no copyright infringement is intended.
 
 \subsection{Libraries}
-With Version $1.1$, I've split the penguin features into a set of libraries.
-To stay backwards compatible, all of them are loaded by default so nothing changes when using tikzpingus. However, the |bare| package-option disables the automatic loading of all libraries. They can be loaded (locally to the current group) using |\pinguloadlibrary| and |\pinguloadlibraries| passing on a comma separated list of desired libraries.
-At the moment, there are the following libraries:
-{\newif\iffirstss\begin{description}
-	\itemsep0pt
-	\foreach \l/\xs in \pingu@defaultlibs {
-		\ifx\l\@empty\else
-		\item[\lib{\l}:] \firstsstrue\foreach \s in \xs {%
-			\iffirstss\global\firstssfalse\else~~{\@declaredcolor{gray}\textbullet}~~\fi\expandafter\dkeyref\expandafter{\s}%
-		}\relax
-		\fi
-	}
-\end{description}
-All keys that do not appear in this list are always available.}
 
-\begin{center}
-	\textit{Options which are not marked in blue and which are no hyperlinks are currently undocumented. Currently, only added extras are shown. Packages like \lib{emotions} do add eyes and such. They will be listed soon.}
-\end{center}
+\label{Libraries}\index{Libraries}I've split the penguin features into a set of libraries. While all of them are loaded by default, the |bare| package-option disables the automatic loading of all libraries. They can be loaded (locally to the current group) using |\pinguloadlibrary| and |\pinguloadlibraries| passing on a comma separated list of desired libraries.
+See the full reference or the index to learn which key comes from which library.
+Please note that~--- at the moment~--- not all components of a library are labeled correctly.
+
+% TODO: already count that? % global let?
+\foreach[count=\i] \l/\xs in \pingu@defaultlibs{\xdef\pingu@defaultlibs@count{\i}}%
+Currently there are the following libraries:
+\foreach[count=\i] \l/\xs in \pingu@defaultlibs{%
+	\ifx\l\empty\else
+	\index{Libraries!\textit{\l}}\textit{\l}\ifnum\numexpr\pingu@defaultlibs@count-1>\i,\space\else
+	\ifnum\pingu@defaultlibs@count=\i\else,~and\space\fi\fi
+	\fi
+}.
+
 \section{Usage}
 
 If you just want a penguin, use the following syntax:
@@ -352,7 +343,7 @@ \section{Usage}
 \end{tikzpicture}
 \end{tcblisting}
 
-There are \textit{a lot} of configuration-options which can be passed as an optional argument via the known |<key>=<value>|-style.
+There are \textit{a lot} of configuration-options which can be passed as an optional argument via the known |<key>=<value>|-style. See \autoref{Gadget-Overview} for an gadget overview.
 % TODO: click reference to full list; TODO: glow option
 \begin{tcblisting}{title={Happy penguin with cup!},externalize listing=happy-cup}
 \begin{tikzpicture}
@@ -436,14 +427,15 @@ \subsection{Using the Coordinates}
 		\PinguCoords{}%
 	}
 \end{center}
+\newpage
 
 \paragraph{The Wings}
 This view excluded a lot of special data collected on the wings!
 While there is more information stored for each wing, the following five coordinates are the most important to place items into penguins hand:
 \begin{center}
 	\null\hfill\parbox[c]{2.5\wd\pinguwingright}{\scalebox{2.5}{\usebox\pinguwingright}}\hfill\parbox[c]{4cm}{\centering\small\@declaredcolor{gray}\sffamily And yes, the wings are deliberately placed asymmetrical.\endgraf}\hfill
 	\parbox[c]{2.5\wd\pinguwingleft}{\scalebox{2.5}{\usebox\pinguwingleft}}\hfill\null
-\end{center}\newpage
+\end{center}
 
 \paragraph{The Body} Similarly to the wing position, different
 body types can change the coordinates (left the \keyref{body type} \textit{chubby} and right the \keyref{body type} \textit{legacy}):
@@ -636,24 +628,28 @@ \subsection{Clothing}
 \end{tikzpicture}
 \end{tcblisting}
 
-\section{Examples}
+% \section{Examples}
 
 \appendix
-\section{Full Reference}\label{sec:full-ref}
+\section{Gadget Overview}\label{Gadget-Overview}
 
-\begin{center}
-	\textit{Please note, that all preview-penguins have been reduced in scale by \(40\,\%\) to save space and make the documentation more concise.}
-\end{center}
+\TypesetShowcases
 
-Aliases may set custom defaults. Those defaults are not listed as they may change.
+\section{Full Reference}\label{sec:full-ref}
 
-\def\lstfnsize{-1.65}
+\def\percenttargetreductionpengus{63}\def\lstfnsize{-1.65}
 \tcbset{%
-	before lower={\begin{adjustbox}{scale=.75}},
+	before lower={\begin{adjustbox}{scale=.\percenttargetreductionpengus}},
 	after lower={\end{adjustbox}},%
 	boxsep=1pt%
 }
 
+\begin{center}
+	\textit{Please note, that all preview-penguins have been reduced in scale to \percenttargetreductionpengus\,\% to save space and make the documentation more concise.}
+\end{center}
+
+Aliases may set custom defaults. Those defaults are not listed as they may change.
+
 \subsection{Penguin Keys}
 
 \keyexplain{name}{text}{\pingu@name}

tex/tikzpingus.sty

@@ -1141,7 +1141,10 @@ coordinate[pos=\pinguanglehl] (\pingu@name-head-left);
 }
 % #endregion
 
-\def\pingu@@dummy@lib#1#2{\pgfqkeys{/pingu}{#1/.code={\PackageError{\tikzpingus@filename}{To use '#1' you need to load the '#2' library via '\string\pinguloadlibrary{#2}'}}}}
+\def\pingu@@dummy@lib#1#2{%
+    \pgfqkeys{/pingu}{#1/.code={\PackageError{\tikzpingus@filename}{To use '#1' you need to load the '#2' library via '\string\pinguloadlibrary{#2}'}}}%
+    \expandafter\def\csname pingu@@lib@#1@\endcsname{#2}%
+}
 \def\pingu@dummy@lib#1#2{\edef\tmp@list{#2}\@for\@current:=\tmp@list\do{\expandafter\pingu@@dummy@lib\expandafter{\@current}{#1}}\xappto\pingu@defaultlibs{,{#1}/{#2}}\xappto\pingu@@defaultlibs{,#1}}
 \def\pingu@defaultlibs{}\def\pingu@@defaultlibs{}
 \def\pingu@load@library#1{%