diff --git a/doc/tikzpingus-doc.tex b/doc/tikzpingus-doc.tex index ba35fee..2db4165 100644 --- a/doc/tikzpingus-doc.tex +++ b/doc/tikzpingus-doc.tex @@ -8,7 +8,8 @@ \usepackage[utf8]{inputenc} \usepackage{babel} -\makeatletter\def\input@path{{../tex/}}\makeatother +\makeatletter +\def\input@path{{../tex/}} \usepackage[glows]{tikzpingus} % \definecolor{doc-main}{RGB}{204,0,25} @@ -19,7 +20,7 @@ \urlstyle{same} \expandafter\def\expandafter\UrlBreaks\expandafter{\UrlBreaks\do-} -\usepackage[tex,hyper]{listings} +\usepackage[hyper]{listings} \usepackage[skins,breakable,hooks,xparse,listingsutf8,external]{tcolorbox} \usepackage{lmodern} \usepackage{CrimsonPro} @@ -39,11 +40,14 @@ \usepackage{xstring} \usepackage{colorinfo} -\makeindex[title={Key Overview},columns=2,columnsep=.75cm,noautomatic=true,options=-s indexstyle.ist] +\makeindex[title={Key Overview},name=\jobname,columns=2,columnsep=.75cm,noautomatic=true] +\makeindex[title={Internals Overview},name=\jobname-internals,columns=2,columnsep=.75cm,noautomatic=true] +\def\current@indexfile{\jobname} + \deffootnote{1.5em}{1em}{\textsuperscript{\hyperref[\BackrefFootnoteTag]{\thefootnotemark}}\thinspace} \def\thefootnote{$\langle$\arabic{footnote}$\rangle$} % https://tex.stackexchange.com/questions/78423/how-to-use-the-footnotebackref-package-with-footnotemark-and-footnotetext -\makeatletter + \LetLtxMacro\BHFN@Old@footnotemark\@footnotemark \def\@footnotemark{% \refstepcounter{BackrefHyperFootnoteCounter}% @@ -62,21 +66,25 @@ \let\say\enquote \def\DTLlistformatoxford{,}\def\DTLandname{and} % TODO: do guard against same keys for different selectors -\long\def\ParseDTLListElement#1"#2"\@nil{\textsuperscript{\smash{\raisebox{2pt}{\ifcsname pingu@@lib@#2@\CurrentList @\endcsname\index{Libraries!\textit{\csname pingu@@lib@#2@\CurrentList @\endcsname}!#2?\hyperref[expl-list:\CurrentList]{\protect\lpingu{#2} {\tiny\sffamily(\MapDTLList{\CurrentList})}}}~$\underset{\text{\tiny\smash{\raisebox{3pt}{\textsf{\hyperref[Libraries]{\color{gray}Library}}}}}}{\text{\textit{\tiny\strut\csname pingu@@lib@#2@\CurrentList @\endcsname}}}$\fi}}}} +\long\def\ParseDTLListElement#1"#2"\@nil{\textsuperscript{\smash{\raisebox{2pt}{\ifcsname pingu@@lib@#2@\CurrentList @\endcsname\index[\current@indexfile]{Libraries!\textit{\csname pingu@@lib@#2@\CurrentList @\endcsname}!#2?\hyperref[expl-list:\CurrentList]{\protect\lpingu{#2} {\tiny\sffamily(\MapDTLList{\CurrentList})}}}~$\underset{\text{\tiny\smash{\raisebox{3pt}{\textsf{\hyperref[Libraries]{\color{gray}Library}}}}}}{\text{\textit{\tiny\strut\csname pingu@@lib@#2@\CurrentList @\endcsname}}}$\fi}}}} \def\DTLlistformatitem#1{\textit{#1\expandafter\ParseDTLListElement :#1\@nil}} \newcommand*\typesetselection[1][]{\begingroup\ifx!#1!\else\def\DTLlistformatitem##1{#1}\fi\dotypesetselection} \def\dotypesetselection#1{\label{expl-list:#1}\def\CurrentList{#1}\expandafter\DTLformatlist\expandafter{\csname @pingu@#1@\endcsname}\endgroup} -\makeatletter + +% this can be used to remove some prefixes of the keys if necessary +\let\@gobblekey\@gobble \addtokomafont{sectioning}{\@declaredcolor{gray}} \addtokomafont{title}{\@declaredcolor{doc-main}} \addtokomafont{author}{\normalsize} \addtokomafont{date}{\normalsize} -\def\optstyle{\@declaredcolor{@opcolor}\slshape} \colorlet{@softgray}{gray!60!white} \colorlet{@softgray@b}{gray!75!white} \colorlet{@darkerblue}{pingu@blue!40!black} + +\def\optstyle{\@declaredcolor{@opcolor}\slshape} +\def\cmdstyle{\@declaredcolor{@darkerblue}} \def\lstfnsize{-.7} \lstdefinestyle{lstpingu}{% tabsize=2, breaklines, @@ -87,9 +95,6 @@ emphstyle=[2]\optstyle, emphstyle=[3]\@declaredcolor{@softgray@b}, emphstyle=[4]\@declaredcolor{@darkerblue}, - texcsstyle=*\@declaredcolor{gray}\bfseries, - texcsstyle=*[2]\@declaredcolor{doc-main}\bfseries, - texcsstyle=*[3]\@declaredcolor{@softgray}, lineskip=2.5pt, keepspaces=true, moredelim=[s][\itshape]{<}{>}, @@ -98,13 +103,24 @@ \def\ipingu#1{\lstinline'#1'} \def\lpingu#1{\lstinline[style=lstpingu,language=pingulang]'#1'} \def\ltex#1{\lstinline[style=lstpingu,language=pinguinternallang]'#1'} +\def\doccmd#1{{\@declaredcolor{doc-main}\bfseries\textbackslash #1}} +\def\graycmd#1{{\@declaredcolor{gray}\bfseries\textbackslash #1}} +\def\ghostcmd#1{{\@declaredcolor{@softgray}\textbackslash #1}} \lstdefinelanguage{pinguinternallang}{ language={[LaTeX]TeX}, moreemph={tikzpicture}, alsoletter={@}, - moretexcs=[2]{pingu@block,pingu@draw}, - moretexcs={pingu@eye@shift,pingu@color@eye@left,pingu@color@eye@right,pingu@name,@pingu@eyes@s,@pingu@none} + add to literate= + {\\pingu@block}{{\doccmd{pingu@block}}}{12} + {\\pingu@draw}{{\doccmd{pingu@draw}}}{11} + {\\@pingu@none}{{\graycmd{@pingu@none}}}{11} + {\\path}{{\graycmd{path}}}5 + {\\pgfqkeys}{{\graycmd{pgfqkeys}}}9 + {\\@ifnextchar}{{\graycmd{@ifnextchar}}}9 + {\\csname}{{\graycmd{csname}}}6 + {\\endcsname}{{\graycmd{endcsname}}}9 + {/pingu/}{{\@declaredcolor{@softgray}/pingu/}}7 } \def\t@lst@addToLiterate#1{\protected@edef\lst@literate{\unexpanded\expandafter{\lst@literate}\unexpanded{#1}}} @@ -116,23 +132,36 @@ moreemph={tikzpicture}, alsoletter={.-!:0123456789},%disable number deletetexcs={begin,end}, % -> lift 3 - moretexcs=[2]{pingu,duck,node,pingudefaults,pingudefaultsappend,pinguloadlibrary,pinguloadlibraries}, - moretexcs=[3]{begin,end,pgfmathsetseed}, moreemph=[3]{!hide,.style}, add to literate={/pingu/}{{\@declaredcolor{gray}/pingu/}}7 {\{tikzpicture\}}{{\@declaredcolor{@softgray}\{tikzpicture\}}}{13} {\{\\number\\pdfrandomseed\}}{{\@declaredcolor{@softgray}\{\textbackslash number\textbackslash pdfrandomseed\}}}{23} % otherwise these would interfere with random {!random}{{\@declaredcolor{darkgray}\itshape!random}}7 + {\\node}{{\doccmd{node}}}5 + {\\duck}{{\doccmd{duck}}}5 + {\\pingudefaults}{{\doccmd{pingudefaults}}}{14} + {\\pingudefaultsappend}{{\doccmd{pingudefaultsappend}}}{20} + {\\pinguloadlibrary}{{\doccmd{pinguloadlibrary}}}{17} + {\\pinguloadlibraries}{{\doccmd{pinguloadlibraries}}}{19} + {\\begin}{{\ghostcmd{begin}}}6 + {\\end}{{\ghostcmd{end}}}4 + {\\pgfmathsetseed}{{\ghostcmd{pgfmathsetseed}}}{15} } -\def\@CreateCodeHyperLink#1#2#3{\lstset{add to literate={#2}{{\hyperref[#3]{\optstyle#2}}}{#1}}} +\def\@CreateCodeHyperLink#1#2#3#4#5{\lstset{add to literate={#2}{{\hyperref[#3]{#5#4}}}{#1}}} % #1 Keys | #2 length (optimized) \def\CreateCodeHyperLink#1#2{% \StrLen{\@elem}[\@cclen] \@for\@elem:=#1\do{\ifx\@elem\@empty\else % space to space cmd % TODO: do this on store and just keep store? \StrSubstitute{\@elem}{ }{\noexpand\ }[\@sub]\relax - \edef\@tmp{\noexpand\@CreateCodeHyperLink{#2}{\@sub}{pk:/pingu/\@elem}}\@tmp\fi}% + \let\hyperstyle\optstyle + \IfSubStr{\@sub}{_}{% update hypersyle + \let\hyperstyle\cmdstyle + \StrSubstitute{\@sub}{_}{\\}[\@sub]% + \StrSubstitute{\@sub}{\\}{\textbackslash}[\@subb]% deal with backslash + }{\let\@subb\@sub} + \edef\@tmp{\noexpand\@CreateCodeHyperLink{#2}{\@sub}{pk:/pingu/\@elem}{\@subb}{\expandonce{\hyperstyle}}}\@tmp\fi}% } % store all. we use their precalculated length to ensure prefixes we go from small to large on set \def\cmdsstore#1#2{\csxdef{allcmds@#1}{#2}} @@ -195,28 +224,38 @@ \def\explaincolor{@opcolor!8!white} \def\cursub{} \def\keyexplainindent{2.5em}% +\let\@explainsuff\@empty +\let\@labelhack\@empty % allow the oxes to have minor overlaps -\newenvironment{keyexplain}[4][/pingu/]{\minipage{\linewidth} - \parskip\smallskipamount +\newcommand\DefineKey[2][/pingu/]{% \StrSubstitute{#2}{ }{-}[\keyexternalname]% + % only use _ to keep the length intact when replace with the backslash + \StrSubstitute{\keyexternalname}{\\}{_}[\keyexternalname]% + {\def\\{_}\protected@xdef\@key{#2}}% + {\def\\{}\protected@xdef\@idxkey{#2}\@gobblekey{\@idxkey}}% backslash should not interfere with keys \tcbset{@/.style={externalize listing=key-\keyexternalname}}% set for externalize - \phantomsection\label{pk:#1#2}\index{\cursub#2?\hyperref[pk:#1#2]{\protect\lpingu{#2}}}% + \phantomsection\label{pk:#1\@labelhack\@key}\index[\current@indexfile]{\cursub\@idxkey?\hyperref[pk:#1\@key]{\protect\lpingu{#2}}}% % get its length: \StrLen{#2}[\@cclen]% - \csgappto{allcmds@\@cclen}{#2,}% + \protected@csxappto{allcmds@\@cclen}{\@key,}% % update the range \ifnum\@cclen>\allcmdsmax\relax \xdef\allcmdsmax{\@cclen}\fi \ifnum\@cclen<\allcmdsmin\relax \xdef\allcmdsmin{\@cclen}\fi - \expandafter\gdef\csname pinguopt#2\endcsname{#3}% - \expandafter\gdef\csname pingudefa#2\endcsname{#4}% +} + +\newenvironment{keyexplain}[4][/pingu/]{\minipage{\linewidth} + \parskip\smallskipamount + \DefineKey[#1]{#2}% + \expandafter\gdef\csname pinguopt\@key\endcsname{#3}% + \expandafter\gdef\csname pingudefa\@key\endcsname{#4}% \begingroup\pgfkeys{/pingu/.cd,defaults}\protected@edef\@tmp{#4}% \protected@edef\@tmpb{#3}% \hspace*{-\keyexplainindent}\tcbox[left=3pt,right=3pt,top=3pt,bottom=3pt,colframe=white,colback=\explaincolor,on line]{% \parbox{\dimexpr\linewidth-2\fboxsep+\keyexplainindent}{\small - \ifx\@tmpb\@empty\lpingu{#1#2}\else\lpingu{#1#2 =\ }\texttt{<\textit{\@tmpb}>}\fi\hfill + \ifx\@tmpb\@empty\lpingu{#1#2}\@explainsuff\else\lpingu{#1#2 =\ }\texttt{<\textit{\@tmpb}>}\fi\hfill \ifx\@tmp\@empty\else{\@declaredcolor{gray}(}#4{\@declaredcolor{gray})}\fi } - }\ifcsname pingu@@lib@#2@\endcsname\index{Libraries!\textit{\csname pingu@@lib@#2@\endcsname}!#2?\hyperref[pk:#1#2]{\protect\lpingu{#2}}}\rlap{~\quad\raisebox{2.75pt}{$\underset{\text{\tiny\smash{\raisebox{3pt}{\textsf{\hyperref[Libraries]{\color{gray}Library}}}}}}{\text{\textit{\footnotesize\strut\csname pingu@@lib@#2@\endcsname}}}$}}\fi\kern-\linewidth\par\endgroup + }\ifcsname pingu@@lib@\@key @\endcsname\index[\current@indexfile]{Libraries!\textit{\csname pingu@@lib@#2@\endcsname}!\@idxkey?\hyperref[pk:#1\@key]{\protect\lpingu{#2}}}\rlap{~\quad\raisebox{2.75pt}{$\underset{\text{\tiny\smash{\raisebox{3pt}{\textsf{\hyperref[Libraries]{\color{gray}Library}}}}}}{\text{\textit{\footnotesize\strut\csname pingu@@lib@#2@\endcsname}}}$}}\fi\kern-\linewidth\par\endgroup } {\endminipage\smallskip\par} @@ -232,6 +271,11 @@ \newcommand*\keyref[2][/pingu/]{\hyperref[pk:#1#2]{\lpingu{#1#2}}} \newcommand*\dkeyref[2][/pingu/]{\hyperref[pk:#1#2]{\lpingu{#2}}} +\newcommand*\cmdref[1]{\hyperref[pk:/pingu/:bs:#1]{\lpingu{\\#1}}} +\newcommand*\cmddef[1]{\DefineKey{\\#1}\cmdref{#1}\nobreak} +\newcommand*\cmdcoldef[1]{\cmddef{pingu@color@#1}} +\newcommand*\cmd[1]{\texttt{\smaller\doccmd{#1}}} + \colorlet{@softexplaincolor}{gray!8!white} \newenvironment{subkeyexplain}[5][/pingu/]{% \begingroup @@ -241,6 +285,28 @@ {\@declaredcolor{gray}\footnotesize This command is only in effect if \keyref[#1]{#2} is active.}\par }{\endkeyexplain\endgroup} +\newenvironment{commandexplain}[3][]{% +\begingroup +\def\@labelhack{/pingu/}% +\def\mand##1{\texttt{\{\textsf{\smaller##1}\}}}% +\def\@pingu@command@keypartner{#1}% +% #1 is the default +\newcommand\opt[2][]{\texttt{\textit{[\textsf{\smaller##2\ifx!##1!\else\textcolor{lightgray}{\smaller\sffamily=##1}\fi}]}}}% +\def\@explainsuff{#3}% +\keyexplain[]{\\#2}{}{}% +\ifx\@pingu@command@keypartner\@empty\else +{\@declaredcolor{gray}\footnotesize Do \textbf{not} redefine this command, it is controlled by \keyref{#1}.}\par\fi +}{\endkeyexplain\endgroup} + +\newenvironment{subcommandexplain}[4][]{% +\begingroup +\def\explaincolor{@softexplaincolor}\def\keyexplainindent{0em}% +{\def\\{}\protected@xdef\@subidxkey{#2}\@gobblekey{\@subidxkey}}%% backslash should not interfere with keys +\def\cursub{\@subidxkey?\hyperref[pk:_\@subidxkey]{\protect\lpingu{\\#2}}!}% +\commandexplain[#1]{#3}{#4}% + {\@declaredcolor{gray}\footnotesize This command is only usable in combination with \cmdref{#2}.}\par +}{\endcommandexplain\endgroup} + \def\consumeshowkeyexplain#1(#2){\ShowcaseThis[#2]{#1}} \newenvironment{showkeyexplain}[4][/pingu/]{% \keyexplain[#1]{#2}{#3}{#4}% @@ -411,11 +477,9 @@ \subsection{Dependencies} \subsection{Copyright} -Copyright \textcopyright\ \textit{Florian Sihler}. Permission is granted to copy, distribute and\slash or modify this software under the terms of the GNU General Public License, version~3.0 (to be found online at: \url{https://opensource.org/licenses/gpl-3.0.html}). - +Copyright \textcopyright\ \textit{Florian Sihler}. Permission is granted to copy, distribute and\slash or modify this software under the terms of the GNU General Public License, version~3.0 (to be found online at: \url{https://opensource.org/licenses/gpl-3.0.html}).\\* 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. -\vfill \section{Usage}\label{Usage} If you just want a penguin, import the package and start with the following: @@ -434,6 +498,10 @@ \section{Usage}\label{Usage} \end{tcblisting} Please note, that \say{left} and \say{right} have been chosen from the penguin-perspective. +\begin{commandexplain}{pingu}{\opt{penguin keys}} + The command to draw the penguin! +\end{commandexplain} + \clearpage Besides the keys defined by this package, you can use the keys of \TikZ\ and |pgf| as well (the duck was generated by the lovely \href{https://github.com/samcarter/tikzducks}{tikzducks} package): \begin{tcblisting}{title={The Reunion},externalize listing=pengu-duck} \begin{tikzpicture} @@ -460,7 +528,7 @@ \subsection{Using the Coordinates} \node at (paula-foot-left) {Foot}; \end{tikzpicture} \end{tcblisting} -Lets look at those coordinates in more detail (all labels are to be prefixed by |-|): +\phantomsection\label{pingu-coordinates}Lets look at those coordinates in more detail (all labels are to be prefixed by |<\keyref{name}>-|): \newsavebox\pinguwingright \savebox\pinguwingright{% \begin{tikzpicture}% @@ -476,7 +544,7 @@ \subsection{Using the Coordinates} \draw[teal,thin] (expl-\c) -- (pingu-\c); } \end{tikzpicture}} -\makeatletter + \newsavebox\pinguwingleft \savebox\pinguwingleft{% \begin{tikzpicture}% @@ -529,7 +597,7 @@ \subsection{Using the Coordinates} \end{center} \subsection{Colors} -A lot of options allow for a color to be passed. In general, you can provide any color that \TikZ\ is happy with! Yet, there are some predefined pingu-colors shipped with this package: +\label{Colors}A lot of options allow for a color to be passed. In general, you can provide any color that \TikZ\ is happy with! Yet, there are some predefined pingu-colors shipped with this package: \def\getCol#1{\pgfmathparse{int(round(#1*255))}\pgfmathresult} \def\parseRGB#1,#2,#3;{r:~\getCol{#1}, g:~\getCol{#2}, b:~\getCol{#3}} \begin{multicols}{4} @@ -543,7 +611,7 @@ \subsection{Colors} \item[] \footnotesize\strut% buffer \end{itemize} \end{multicols} -Furthermore, there is the special color {\makeatletter\say{\expandafter\ipingu\expandafter{\@pingu@none}}} which is available for most\footnote{Why just \say{most}? Well, this package is work in progress and I have added the option late, so I may have forgotten to patch some keys.} extras and wing-items. This color prohibits the compartments from being drawn. To be more precise, the package defines the macro \ltex{\\@pingu@none}, which is matched against the selected color. +Furthermore, there is the special color \say{\expandafter\ipingu\expandafter{\@pingu@none}} (\cmdref{@pingu@none}) which is available for most\footnote{Why just \say{most}? Well, this package is work in progress and I have added the option late, so I may have forgotten to patch some keys.} extras and wing-items. This color prohibits the compartments from being drawn. To be more precise, the package defines the macro \ltex{\\@pingu@none}, which is matched against the selected color. As an example, lets take a look at the \keyref{cup}-extra, which provides an additional key \keyref{cup straw} to color the straw: \begin{tcblisting}{title={Cup without a straw},externalize listing=extra-options} @@ -576,7 +644,7 @@ \subsection{Libraries} 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 + \index[\current@indexfile]{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 }. @@ -595,7 +663,7 @@ \subsection{Changing the wings} \pingu[left wing none, heart=green] \pingu[wings wave, heart=teal, xshift=3.5cm] \pingu[wings hug, heart=orange, xshift=7cm] - \pingu[left wing grab, right wing shock, heart=purple, xshift=10.5cm] + \pingu[left wing grab, right wing shock, heart=purple, xshift=10.5cm] \end{tikzpicture} \end{tcblisting} @@ -4904,5 +4972,101 @@ \subsubsection{The second shirt} \end{tcblisting} \endsubkeyexplain} -\lstset{breakatwhitespace}\printindex + +% set up for inclusion +\lstset{includerangemarker=false,rangeprefix={\%\ <}, rangesuffix={>}} +\newcommand\includecode[2][../tex/tikzpingus.sty]{\lstinputlisting[linerange=#2-@#2,style=lstpingu,language=pinguinternallang,numbers=left,numberstyle={\tiny\color{gray}\sffamily},numbersep=5pt]{#1}} +\def\current@indexfile{\jobname-internals} +% gobble leading pingu for indexing +\def\@gobblekey#1{\IfBeginWith{#1}{pingu@}{\StrDel[1]{#1}{pingu@}[#1]\protected@xdef#1{#1}}{}} + +\section{The Internals} +The goal of this section is to explain the inner workings of the package to aid other people in helping me extending and mainting the penguins. + +\subsection{General commands} + +\begin{commandexplain}[name]{pingu@name}{} + Holds the name of the penguin. +\end{commandexplain} + +\begin{commandexplain}{pingu@one}{} + Do not change this dimension as it represents one milli meter as the base unit. +\end{commandexplain} + +\subsubsection{Color} +\begin{commandexplain}{pingu@color}{\mand{name}\mand{color}} + Creates a macro \cmd{pingu@color@} that links to the given color: + \includecode{pingu@color} + I decided against the usage of \cmd{colorlet}, to support \cmdref{@pingu@none} +\end{commandexplain} + +\begin{commandexplain}{@pingu@none}{} + Holds the special color to hide the drawing of specific components as described within \autoref{Colors} (holds the value: \@pingu@none). + If you redefine this command, you redefine this hidden color. Hover, if done outside of the preamble, this may result in weird side effects due to expansions. +\end{commandexplain} + +\subsubsection{Selections} +TODO: explain selections + +\begin{commandexplain}{pingu@create@selection}{\mand{name}\mand{none default}} + Creates a new enumeration-like structure that can be used to register a family of options (see \autoref{internal:eyes} for an example). + The \textit{none default} is used for the default member of the selection: \textit{none} which is active, whenever no other key is selected by \cmdref{pingu@@select}. + You can add keys by using \cmdref{pingu@@add} and execute the selection by \cmdref{@pingu@drawer@@}. +\end{commandexplain} + +\begin{subcommandexplain}{pingu@create@selection}{pingu@@select}{\mand{select}} + +\end{subcommandexplain} + +\begin{subcommandexplain}{pingu@create@selection}{pingu@@add}{\mand{select}} + +\end{subcommandexplain} + +\begin{subcommandexplain}{pingu@create@selection}{@pingu@drawer@@}{} + +\end{subcommandexplain} + +\subsection{The Eyes}\label{internal:eyes} + +\subsubsection{Important Commands} + +\begin{commandexplain}{pingu@eye@shift}{} + This dimension holds a hardcoded value to be used as the offset for eyes. Its default value is \the\pingu@eye@shift. It may be removed in the future (or replaced by an option). +\end{commandexplain} + +\subsubsection{The Code} + +The eyes of the penguin are controlled by two selections for the left, and the right eye. As we still want the coordinates for the right and the left eye (as presented in \autoref{pingu-coordinates}), the \textit{none}-version of \cmdref{pingu@create@selection} creates those: +\includecode{eyes\ selectors} +With this code, we define the six following commands: \cmddef{pingu@righteye@select}, \cmddef{pingu@righteye@add}, \cmddef{@pingu@drawer@righteye@}, \cmddef{pingu@lefteye@select}, \cmddef{pingu@lefteye@add}, and \cmddef{@pingu@drawer@lefteye@}. + +Within the initialization of all penguin options, we use these keys. Furthermore, \keyref{eyes} acts as a comfort option which operates on both selectors: +% \pgfqkeys{/pingu}{ +\includecode{eyes\ keys} +Both eyes have two colors to work with: \cmdcoldef{eye@left}, \cmdcoldef{eye@second@left} for the left as well as \cmdcoldef{eye@right} and \cmdcoldef{eye@second@right} for the right eye. + +\subsection{Adding new Eyes} +Now on how to add new eyes. While it is possible to use \cmdref{pingu@lefteye@add} and \cmdref{pingu@righteye@add}, setting up the corresponding \say{eye} and \say{eyes} comfort-methods is rather tedious. +For this, i created the command \cmdref{pingu@eyes@s}\ldots + +\begin{commandexplain}{pingu@eyes@s}{\mand{name}\mand{left-eye}\mand{right-eye}\opt{default color}} + Allows to easily add new eyes. + \textit{Important:}\space Your code for the eyes \textit{must} create the coordinates \lpingu{\\pingu@name-eye-left} and \lpingu{\\pingu@name-eye-right} respectively. This is not checked! It is recommended to use the coordinates \lpingu{\\pingu@name-eye-back-left} and \lpingu{\\pingu@name-eye-back-right} for reference. +\end{commandexplain} +The macro \cmdref{pingu@eyes@s} is defined like this: +\includecode{pingu@eyes@s} + + +As an example, this is the definition of the \say{normal eyes} (\keyref{eyes normal}) in the code: +\includecode{eyes\ normal} +As another example, this is the definition of the \say{shiny eyes} (\keyref{eyes shiny}): +\includecode{eyes\ shiny} +The usage of \cmddef{eyebaseang} is outdated and will probably be removed in the future. + + +\lstset{breakatwhitespace} +\indexprologue{\label{normal-idx}This index shows all of the options and commands that a normal user of the package may use! See the \autoref{internal-idx} for an overview of keys and commands used behind the scenes.} +\printindex[\jobname] +\indexprologue{\label{internal-idx}The initial \cmd{pingu@} is ignored for indexing.} +\printindex[\jobname-internals] \end{document} diff --git a/tex/tikzpingus-devil.lib.tex b/tex/tikzpingus-devil.lib.tex index 58433a9..a1ec5f9 100644 --- a/tex/tikzpingus-devil.lib.tex +++ b/tex/tikzpingus-devil.lib.tex @@ -26,7 +26,7 @@ % wip hack \colorlet{pingu@devil@ring}{pingu@black} \def\pingu@devil@x@opacity{.75} -\@pingu@eyes@s{devil}{% +\pingu@eyes@s{devil}{% \pingu@layer{foreground}[] \pingu@block{pingu@devil@ring} ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left) coordinate (\pingu@name-eye-left) ellipse [x radius=.1535cm, y radius=.1575cm]; \pingu@block{\pingu@color@eye@second@left} ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left) coordinate (\pingu@name-eye-left) ellipse [x radius=.1325cm, y radius=.1375cm]; diff --git a/tex/tikzpingus-emotions.lib.tex b/tex/tikzpingus-emotions.lib.tex index a5226d0..2c92087 100644 --- a/tex/tikzpingus-emotions.lib.tex +++ b/tex/tikzpingus-emotions.lib.tex @@ -1,7 +1,7 @@ % Florian Sihler, 2022 % Licensed under GNU General Public License version 3 % https://opensource.org/licenses/gpl-3.0.html -\@pingu@eyes@s{sad}{% +\pingu@eyes@s{sad}{% \path (\pingu@name-eye-back-left)++(\pingu@eye@shift,.75mm) coordinate (\pingu@name-eye-left); \pingu@block{\pingu@color@eye@left} (\pingu@name-eye-left)++(15:.1225cm and .1275cm) arc (15:-245:.1225cm and .1275cm) to[out=-45,in=175] cycle; }{% @@ -9,7 +9,7 @@ \pingu@block{\pingu@color@eye@right} (\pingu@name-eye-right)++(165:.1225cm and .1275cm) arc (165:425:.1225cm and .1275cm) to[out=225,in=5] cycle; } -\@pingu@eyes@s{angry}{% +\pingu@eyes@s{angry}{% \path (\pingu@name-eye-back-left)++(\pingu@eye@shift,.75mm) coordinate (\pingu@name-eye-left); \pingu@block{\pingu@color@eye@left} (\pingu@name-eye-left) ellipse [x radius=.1225cm, y radius=.1275cm]; \pingu@block{\pingu@color@body@front} (\pingu@name-eye-left) ++(120:.1225cm and .1275cm) ellipse [x radius=1.5mm,y radius=.5mm]; @@ -37,7 +37,7 @@ \pingu@block[/pingu/@glow,opacity=\pingu@x@blush@opacity]{\pingu@color@blush@second} ([yshift=-2.7mm,xshift=1.85mm]\pingu@name-eye-left) ellipse [x radius=2.66mm,y radius=2.25mm]; } -\@pingu@eyes@s{hearts}{% +\pingu@eyes@s{hearts}{% \path (\pingu@name-eye-back-left)++(\pingu@eye@shift,.75mm) coordinate (\pingu@name-eye-left); \pingu@block[rounded corners=0pt]{\pingu@color@eye@left} ([yshift=.3mm]\pingu@name-eye-left) arc(0:180:.065cm) to[out=270,in=110] ++(.13cm,-.2cm) to[out=70,in=270] ++(.13cm,.2cm) arc (0:180:.065cm) -- cycle; diff --git a/tex/tikzpingus.sty b/tex/tikzpingus.sty index 42b928a..fcb8f76 100644 --- a/tex/tikzpingus.sty +++ b/tex/tikzpingus.sty @@ -106,12 +106,17 @@ \long\def\pingu@create@extra#1#2#3{\expandafter\newif\csname if@pingu@x@#1@\endcsname\pgfqkeys{/pingu}{#2,extra defaults/.append style={#3}}} \def\pingu@set@extra#1#2{\csname @pingu@x@#1@#2\endcsname} +% \pingu@create@selection{lefteye}{% - \path ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left) coordinate (\pingu@name-eye-left);% + \path ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left) + coordinate (\pingu@name-eye-left);% } \pingu@create@selection{righteye}{% - \path ([yshift=.75mm,xshift=-\pingu@eye@shift]\pingu@name-eye-back-right) coordinate (\pingu@name-eye-right);% + \path ([yshift=.75mm,xshift=-\pingu@eye@shift]\pingu@name-eye-back-right) + coordinate (\pingu@name-eye-right);% } +% <@eyes selectors> + \pingu@create@selection{leftwing}{% \path ([yshift=-6.5mm]\pingu@name-wings-side-left) coordinate (\pingu@name-wing-left-start) @@ -134,7 +139,11 @@ % #endregion % #region key setup -\def\pingu@color#1#2{\expandafter\def\csname pingu@color@#1\endcsname{#2}} +% +\def\pingu@color#1#2{% + \expandafter\def\csname pingu@color@#1\endcsname{#2}% +} +% <@pingu@color> % HACK: store scale \pgfqkeys{/tikz}{scale/.append code={\def\pingu@default@scale{#1}}} @@ -190,16 +199,26 @@ belly/.forward to = /pingu/belly text, belly text/.style = {/pingu/belly raw={\node[/pingu/@text,opacity=.2] {#1};}}, belly raw/.code = \def\pingu@belly@raw{#1}, - % eyes +% left eye/.code = \pingu@lefteye@select{#1}, left eye color/.code = \pingu@color{eye@left}{#1}, left eye second color/.code = \pingu@color{eye@second@left}{#1}, right eye/.code = \pingu@righteye@select{#1}, right eye color/.code = \pingu@color{eye@right}{#1}, right eye second color/.code = \pingu@color{eye@second@right}{#1}, - eyes/.style = {/pingu/left eye={#1}, /pingu/right eye={#1}}, - eyes color/.style = {/pingu/left eye color={#1}, /pingu/right eye color={#1}}, - eyes second color/.style = {/pingu/left eye second color={#1}, /pingu/right eye second color={#1}}, + eyes/.style = { + /pingu/left eye = {#1}, + /pingu/right eye = {#1} + }, + eyes color/.style = { + /pingu/left eye color = {#1}, + /pingu/right eye color = {#1} + }, + eyes second color/.style = { + /pingu/left eye second color = {#1}, + /pingu/right eye second color = {#1} + }, +% <@eyes keys> % wings left wing color/.code = \pingu@color{left@wing}{#1}, left wing/.code = \pingu@leftwing@select{#1}, @@ -570,43 +589,77 @@ coordinate[pos=\pinguanglehl] (\pingu@name-head-left); % #endregion % #region eyes % name core | left | right -\long\def\@pingu@eyes@s#1#2#3{\@ifnextchar[{\@pingu@eyes@s@{#1}{#2}{#3}}{\@pingu@eyes@s@{#1}{#2}{#3}[pingu@black]}} -\long\def\@pingu@eyes@s@#1#2#3[#4]{% +% +\long\def\pingu@eyes@s#1#2#3{% + \@ifnextchar[% + {\pingu@eyes@s@{#1}{#2}{#3}}% + {\pingu@eyes@s@{#1}{#2}{#3}[pingu@black]}% +} +\long\def\pingu@eyes@s@#1#2#3[#4]{% \pgfqkeys{/pingu}{% - left eye #1/.style = {/pingu/left eye={#1}, /pingu/left eye color={##1}},% - left eye #1/.default = {#4},% - right eye #1/.style = {/pingu/right eye={#1}, /pingu/right eye color={##1}},% - right eye #1/.default = {#4},% - eyes #1/.style = {/pingu/eyes={#1}, /pingu/eyes color={##1}},% - eyes #1/.default = {#4}% + left eye #1/.style = {/pingu/left eye={#1}, /pingu/left eye color={##1}}, + left eye #1/.default = {#4}, + right eye #1/.style = {/pingu/right eye={#1}, /pingu/right eye color={##1}}, + right eye #1/.default = {#4}, + eyes #1/.style = {/pingu/eyes={#1}, /pingu/eyes color={##1}}, + eyes #1/.default = {#4} }% \pingu@lefteye@add{#1}{#2}\pingu@righteye@add{#1}{#3}% } -\pgfqkeys{/pingu}{eyes none/.style={eyes=none},left eye none/.style={left eye=none},right eye none/.style={right eye=none}} % adding the alias - -\@pingu@eyes@s{normal}{% - \pingu@block{\pingu@color@eye@left} ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left) coordinate (\pingu@name-eye-left) ellipse [x radius=.1225cm, y radius=.1365cm]; +\pgfqkeys{/pingu}{% + eyes none/.style={eyes=none}, + left eye none/.style={left eye=none}, + right eye none/.style={right eye=none} +} % adding the alias +% <@pingu@eyes@s> + +% +\pingu@eyes@s{normal}{% + \pingu@block{\pingu@color@eye@left} + ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left) + coordinate (\pingu@name-eye-left) + ellipse [x radius=.1225cm, y radius=.1365cm]; }{% - \pingu@block{\pingu@color@eye@right} ([yshift=.75mm,xshift=-\pingu@eye@shift]\pingu@name-eye-back-right) coordinate(\pingu@name-eye-right) ellipse [x radius=.1225cm, y radius=.1365cm]; + \pingu@block{\pingu@color@eye@right} + ([yshift=.75mm,xshift=-\pingu@eye@shift]\pingu@name-eye-back-right) + coordinate(\pingu@name-eye-right) + ellipse [x radius=.1225cm, y radius=.1365cm]; } +% <@eyes normal> -\@pingu@eyes@s{vertical}{% +\pingu@eyes@s{vertical}{% \pingu@block{\pingu@color@eye@left} ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left) coordinate (\pingu@name-eye-left) ellipse [x radius=1.13mm, y radius=.145cm]; }{% \pingu@block{\pingu@color@eye@right} ([yshift=.75mm,xshift=-\pingu@eye@shift]\pingu@name-eye-back-right) coordinate(\pingu@name-eye-right) ellipse [x radius=1.13mm, y radius=.145cm]; } -\@pingu@eyes@s{shiny}{% - \pingu@block{\pingu@color@eye@left} ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left) coordinate(\pingu@name-eye-left) ellipse [x radius=.22cm, y radius=.26cm]; - \pingu@block{\pingu@color@eye@second@left} (\pingu@name-eye-left)++(\eyebaseang:.85mm and \pingu@one) ellipse [x radius=.8mm, y radius=\pingu@one]; - \pingu@block{\pingu@color@eye@second@left} (\pingu@name-eye-left)++(\eyebaseang+180:.12cm and .14cm) ellipse [x radius=.25mm, y radius=.35mm]; +% +\pingu@eyes@s{shiny}{% + \pingu@block{\pingu@color@eye@left} + ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left) + coordinate(\pingu@name-eye-left) + ellipse [x radius=.22cm, y radius=.26cm]; + \pingu@block{\pingu@color@eye@second@left} + (\pingu@name-eye-left)++(\eyebaseang:.85mm and \pingu@one) + ellipse [x radius=.8mm, y radius=\pingu@one]; + \pingu@block{\pingu@color@eye@second@left} + (\pingu@name-eye-left)++(\eyebaseang+180:.12cm and .14cm) + ellipse [x radius=.25mm, y radius=.35mm]; }{% - \pingu@block{\pingu@color@eye@right} ([yshift=.75mm,xshift=-\pingu@eye@shift]\pingu@name-eye-back-right) coordinate(\pingu@name-eye-right) ellipse [x radius=.22cm, y radius=.26cm]; - \pingu@block{\pingu@color@eye@second@right} (\pingu@name-eye-right)++(\eyebaseang:.85mm and \pingu@one) ellipse [x radius=.8mm, y radius=\pingu@one]; - \pingu@block{\pingu@color@eye@second@right} (\pingu@name-eye-right)++(\eyebaseang+180:.12cm and .14cm) ellipse [x radius=.25mm, y radius=.35mm]; + \pingu@block{\pingu@color@eye@right} + ([yshift=.75mm,xshift=-\pingu@eye@shift]\pingu@name-eye-back-right) + coordinate(\pingu@name-eye-right) + ellipse [x radius=.22cm, y radius=.26cm]; + \pingu@block{\pingu@color@eye@second@right} + (\pingu@name-eye-right)++(\eyebaseang:.85mm and \pingu@one) + ellipse [x radius=.8mm, y radius=\pingu@one]; + \pingu@block{\pingu@color@eye@second@right} + (\pingu@name-eye-right)++(\eyebaseang+180:.12cm and .14cm) + ellipse [x radius=.25mm, y radius=.35mm]; } +% <@eyes shiny> -\@pingu@eyes@s{wink}{% +\pingu@eyes@s{wink}{% \coordinate (\pingu@name-eye-left) at ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left); \pingu@block[rounded corners=.002cm,rotate around={-4:(\pingu@name-eye-left)}]{\pingu@color@eye@left} (\pingu@name-eye-left)++(174:.14cm and .14cm)++(0,-.065cm) arc (174:6:.14cm and .14cm) arc (-6:-174:.1mm and .08mm) arc (6:174:.12cm and .065cm) arc (-6:-174:.1mm and .08mm) -- cycle; }{% @@ -614,7 +667,7 @@ coordinate[pos=\pinguanglehl] (\pingu@name-head-left); \pingu@block[rounded corners=.002cm,rotate around={4:(\pingu@name-eye-right)}]{\pingu@color@eye@right} (\pingu@name-eye-right)++(174:.14cm and .14cm)++(0,-.065cm) arc (174:6:.14cm and .14cm) arc (-6:-174:.1mm and .08mm) arc (6:174:.12cm and .065cm) arc (-6:-174:.1mm and .08mm) -- cycle; } -\@pingu@eyes@s{shock}{% +\pingu@eyes@s{shock}{% \pingu@block{\pingu@color@eye@left} ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left) coordinate (\pingu@name-eye-left) ellipse [x radius=.1535cm, y radius=.1575cm]; \pingu@block{\pingu@color@eye@second@left} ([yshift=.75mm,xshift=\pingu@eye@shift]\pingu@name-eye-back-left) coordinate (\pingu@name-eye-left) ellipse [x radius=.1325cm, y radius=.1375cm]; }{% @@ -622,7 +675,7 @@ coordinate[pos=\pinguanglehl] (\pingu@name-head-left); \pingu@block{\pingu@color@eye@second@right} ([yshift=.75mm,xshift=-\pingu@eye@shift]\pingu@name-eye-back-right) coordinate(\pingu@name-eye-right) ellipse [x radius=.1325cm, y radius=.1375cm]; } -% \let\@pingu@eyes@s\relax +% \let\pingu@eyes@s\relax % #endregion % #region wings