Debian Codegraph @

texmf-dist/source/latex/palette/palette.dtx

raw
1 % \iffalse meta-comment
2 % This package was written for pdfLaTeX.
3 % In particular, there is no guarantee that this works for other tex engines.
4 %
5 % Copyright (C) 2021 Dennis Chen <[email protected]>
6 %
7 % This work may be distributed and/or modified under
8 % the conditions the LaTeX Project Public License (LPPL),
9 % either version 1.3 of this license or (at your option)
10 % any later version. The latest version of this license
11 % can be found in
12 % http://www.latex-project.org/lppl.txt
13 % and version 1.3 or later is part of all distributions of LaTeX
14 % version 2005/12/01 or later.
15 %
16 %<*internal>
17 \iffalse
18 %</internal>
19 %<*readme>
20 # The LaTeX package palette - version 1.1.0 (2021/07/29)
21
22 **palette** provides the ability to create custom color palettes and symbol palettes ("symbol suites"), and swap one palette in for another easily. It also allows the user to create a variable that represents the selected palette, and provides checks in case the variable represents a palette that does not exist.
23
24 The package is split into `colorpalette` and `symbolpalette`.
25
26 ## Installation instructions
27
28 A working TeX installation is required.
29
30 This is a self-extracting dtx file, so run
31
32 pdflatex palette.dtx
33
34 to generate the README, documentation, and packages.
35 %</readme>
36 % \fi
37
38 % \iffalse
39
40 %<*internal>
41 \fi
42 \def\nameofplainTeX{plain}
43 \ifx\fmtname\nameofplainTeX\else
44 \expandafter\begingroup
45 \fi
46 %</internal>
47 %<*install>
48
49 \input docstrip.tex
50 \keepsilent
51 \askforoverwritefalse
52 \preamble
53
54 This is a generated file.
55
56 Copyright (C) 2021 Dennis Chen <[email protected]>
57
58 This work may be distributed and/or modified under
59 the conditions the LaTeX Project Public License (LPPL),
60 either version 1.3 of this license or (at your option)
61 any later version. The latest version of this license
62 can be found in
63
64 http://www.latex-project.org/lppl.txt
65
66 and version 1.3 or later is part of all distributions of LaTeX
67 version 2005/12/01 or later.
68
69 To produce the documentation, run palette.dtx through pdflatex.
70
71 \endpreamble
72 \postamble
73
74 This package consists of the file palette.dtx,
75 and the generated files colorpalette.sty,
76 symbolpalette.sty,
77 palette.pdf.
78 \endpostamble
79
80 \usedir{tex/latex/palette}
81 \generate{
82 \file{colorpalette.sty}{\from{\jobname.dtx}{color}}
83 \file{symbolpalette.sty}{\from{\jobname.dtx}{symbol}}
84 }
85
86 \obeyspaces
87 \Msg{*************************************************************}
88 \Msg{* *}
89 \Msg{* To finish the installation you have to move the following *}
90 \Msg{* files into a directory searched by TeX: *}
91 \Msg{* *}
92 \Msg{* colorpalette.sty *}
93 \Msg{* symbolpalette.sty *}
94 \Msg{* *}
95 \Msg{* To produce the documentation, run the file *}
96 \Msg{* palette.dtx through LaTeX. *}
97 \Msg{* *}
98 \Msg{* Happy TeXing! *}
99 \Msg{* *}
100 \Msg{*************************************************************}
101
102 %</install>
103 %<install>\endbatchfile
104 %<*internal>
105
106 \usedir{source/latex/palette}
107 \generate{
108 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
109 }
110 \nopreamble\nopostamble
111
112 \usedir{doc/latex/palette}
113 \generate{
114 \file{README.md}{\from{\jobname.dtx}{readme}}
115 }
116
117 \ifx\fmtname\nameofplainTeX
118 \expandafter\endbatchfile
119 \else
120 \expandafter\endgroup
121 \fi
122 %</internal>
123 %
124 %<color|symbol>\NeedsTeXFormat{LaTeX2e}
125 %<color>\ProvidesPackage{colorpalette}
126 %<symbol>\ProvidesPackage{symbolpalette}
127 %<color|symbol>[2021/07/29 v1.1.0 Create palettes for colors and symbols]
128 %<color>\RequirePackage{xcolor}
129 %<*color|symbol>
130 \RequirePackage{macrolist}
131 %</color|symbol>
132 %<*driver>
133 \ProvidesFile{\jobname.dtx}[2021/07/29 v1.1.0 Create palettes for colors and symbols]
134 \documentclass{ltxdoc}
135
136 \EnableCrossrefs
137 \CodelineIndex
138 \RecordChanges
139
140 \begin{document}
141 \DocInput{\jobname.dtx}
142 \PrintIndex
143 \PrintChanges
144 \end{document}
145 %</driver>
146 % \fi
147 %
148 % \GetFileInfo{\jobname.dtx}
149 %
150 % \changes{v1.1.0}{2021/07/29}{Update macrolist (to get compatibility with etoolbox)}
151 % \changes{v1.0.0}{2021/07/27}{Initial version}
152 %
153 % \title{\textsf{palette} -- Create palettes for colors and symbols}
154 % \author{Dennis Chen \\ [email protected]}
155 % \date{\fileversion{} (\filedate)}
156 %
157 % \maketitle
158 %
159 % \begin{abstract}
160 % The \textsf{palette} package provides \textsf{colorpalette.sty} and \textsf{symbolpalette.sty}, which can be used to create and manage palettes of colors and symbols, respectively.
161 % \end{abstract}
162 %
163 % \section{Overview}
164 % We will go over the basic structure of the user interface in broad terms first (i.e. no macros or environments yet). We will use \textsf{colorpalette} as our example here, but \textsf{symbolpalette} behaves virtually identically.
165 %
166 % First, the user can create palette \emph{themes}, which are independent from each other. Then, you can add colors to themes. Finally, you can make a palette associated with a theme and set its colors.
167 %
168 % \section{colorpalette.sty}
169 %
170 % \subsection{Usage}
171 %
172 % \DescribeMacro{\newpalettetheme}
173 % To create a new palette theme called \textsf{theme}, write |\newpalettetheme{theme}|.
174 %
175 % \iffalse
176 %<*color>
177 \newcommand\newpalettetheme[1]{
178 \macronewlist{colorpalette@theme@#1@palettes}
179 \macronewlist{colorpalette@theme@#1@colors}
180 }
181 %</color>
182 % \fi
183 % \DescribeMacro{\addcolortotheme}
184 % To add a color \textsf{color} to theme \textsf{theme}, write |\addcolortotheme{theme}{color}|.
185 %
186 % \iffalse
187 %<*color>
188 \newcommand\addcolortotheme[2]{
189 \colorpalette@themecheck{#1}
190 \macrolistadd{colorpalette@theme@#1@colors}{#2}
191 }
192 %</color>
193 % \fi
194 %
195 % \DescribeMacro{\newpalette}
196 % To create a new palette \textsf{palette} based on theme \textsf{theme}, write |\newpalette{theme}{palette}|.
197 %
198 % Palette names only need to be unique across the same theme. This means that you can have two palettes with the same name if they are associated with different themes.
199 %
200 % \iffalse
201 %<*color>
202 \newcommand\newpalette[2]{
203 % Check that the theme exists
204 \colorpalette@themecheck{#1}
205 \macrolistadd{colorpalette@theme@#1@palettes}{#2}
206 }
207 %</color>
208 % \fi
209 %
210 % \DescribeMacro{\setpalettecolor}
211 % To set the color \textsf{color} (which was defined with respect to the theme of the palette) as the color value \textsf{value} in the format \textsf{encoding} (which by default is HTML) of palette \textsf{palette} in theme \textsf{theme}, write \begin{verbatim}\setpalettecolor{theme}{palette}{color}[encoding]{value}\end{verbatim}
212 %
213 % \iffalse
214 %<*color>
215 \newcommand\setpalettecolor[3]{
216 \colorpalette@themecheck{#1}
217 \colorpalette@palettecheck{#1}{#2}
218 \colorpalette@colorcheck{#1}{#3}
219 \def\colorpalette@temp@themename{#1}
220 \def\colorpalette@temp@palettename{#2}
221 \def\colorpalette@temp@colorname{#3}
222 \colorpalette@setpalettecolor
223 }
224 \newcommand\colorpalette@setpalettecolor[2][HTML]{
225 \definecolor{colorpalette@\colorpalette@temp@themename @\colorpalette@temp@palettename @\colorpalette@temp@colorname}{#1}{#2}
226 }
227 %</color>
228 % \fi
229 %
230 % \DescribeMacro{\activepalette}
231 % This sets the active palette of a theme. (This is how palettes are ``swapped in'' with respect to a theme.) To set the active palette of theme \textsf{theme} as \textsf{palette}, write |\activepalette{theme}{palette}|.
232 %
233 % \iffalse
234 %<*color>
235 \newcommand\activepalette[2]{%
236 \colorpalette@themecheck{#1}
237 \colorpalette@palettecheck{#1}{#2}
238 \expandafter\def\csname colorpalette@#1@active\endcsname{#2}%
239 }
240 %</color>
241 % \fi
242 %
243 % \DescribeMacro{\getcolor}
244 % To use, write |\getcolor{theme}{color}|. This gets the \emph{internal} color name from the \emph{active} palette of \textsf{theme}. No errors will be thrown even if you pass in an undefined theme or color (with respect to the theme). This limitation is because we must be able to parse |\getcolor|.
245 %
246 % \iffalse
247 %<*color>
248 \newcommand\getcolor[2]{colorpalette@#1@\csname colorpalette@#1@active\endcsname @#2}
249 %</color>
250 % \fi
251 %
252 % \DescribeMacro{\applycolor}
253 % To use, write |\applycolor{theme}{color}|. This applies color \textsf{color} from the \emph{active} palette of theme \textsf{theme}. (This means that the newly defined color is passed into |\color|.) If \textsf{theme} has no active palette, an error will be thrown.
254 %
255 % To make it clearer what |\applycolor| does, we will just show the macro definition directly (since it is quite simple). (The macros |\colorpalette@themecheck| and |\colorpalette@colorcheck| are just for error handling.)
256 %
257 % \begin{macrocode}
258 %<*color>
259 \newcommand\applycolor[2]{%
260 \colorpalette@themecheck{#1}%
261 \colorpalette@colorcheck{#1}{#2}%
262 \color{\getcolor{#1}{#2}}%
263 }
264 %</color>
265 % \end{macrocode}
266 %
267 % \subsection{Error Messages}
268 % \iffalse
269 %<*color>
270 \newcommand\colorpalette@themecheck[1]{\macrolistexists{colorpalette@theme@#1@palettes}{}{\colorpalette@error@theme{#1}}}
271 \newcommand\colorpalette@palettecheck[2]{\macrolistcontains{colorpalette@theme@#1@palettes}{#2}{}{\colorpalette@error@palette{#1}{#2}}}
272 \newcommand\colorpalette@colorcheck[2]{\macrolistcontains{colorpalette@theme@#1@colors}{#2}{}{\colorpalette@error@color{#1}{#2}}}
273 %</color>
274 % \fi
275 %
276 % If a nonexistent theme is passed in, the following error will be thrown:
277 % \begin{verbatim}The palette passed in is not a defined palette of theme `#1'\end{verbatim}
278 % where |#1| is the name of the theme.
279 % \iffalse
280 %<color>\newcommand\colorpalette@error@theme[1]{\PackageError{colorpalette}{The theme `#1' passed in is not defined}{}}
281 % \fi
282 %
283 % If a palette that does not belong to a theme is passed in, the following error will be thrown:
284 % \begin{verbatim}The palette `#2' passed in is not a defined palette of theme `#1'\end{verbatim}
285 % where |#1| is the name of the theme and |#2| is the name of the palette.
286 % \iffalse
287 %<color>\newcommand\colorpalette@error@palette[2]{\PackageError{colorpalette}{The palette `#2' passed in is not a defined palette of theme `#1'}{}}
288 % \fi
289 %
290 % If a color that does not belong to a theme is passed in, the following error will be thrown:
291 % \begin{verbatim}The color `#2' passed in is not a defined color of theme `#1'\end{verbatim}
292 % where |#1| is the name of the theme and |#2| is the name of the color.
293 % \iffalse
294 %<color>\newcommand\colorpalette@error@color[2]{\PackageError{colorpalette}{The color `#2' passed in is not a defined color of theme `#1'}{}}
295 % \fi
296 %
297 % \section{symbolpalette.sty}
298 %
299 % Despite the name \textsf{symbolpalette} (which is used to identify it as one of the files of the package \textsf{palette}), the main keyword is a \emph{suite}. This is because the keyword \emph{palette} is already used for \textsf{colorpalette}.
300 %
301 % This package is nearly analogous to \textsf{colorpalette}. A \emph{suite} is analogous to a \emph{palette}, and a \emph{symbol} is analogous to a \emph{color}. \emph{Themes} are used in both packages.
302 %
303 % \subsection{Usage}
304 %
305 % \DescribeMacro{\newsuitetheme}
306 % To create a new suite theme called \textsf{theme}, write |\newsuitetheme{theme}|.
307 %
308 % \iffalse
309 %<*symbol>
310 \newcommand\newsuitetheme[1]{
311 \macronewlist{symbolsuite@theme@#1@suites}
312 \macronewlist{symbolsuite@theme@#1@symbols}
313 }
314 %</symbol>
315 % \fi
316 % \DescribeMacro{\addsymboltotheme}
317 % To add a symbol \textsf{symbol} to theme \textsf{theme}, write |\addsymboltotheme{theme}{symbol}|.
318 %
319 % \iffalse
320 %<*symbol>
321 \newcommand\addsymboltotheme[2]{
322 \symbolsuite@themecheck{#1}
323 \macrolistadd{symbolsuite@theme@#1@symbols}{#2}
324 }
325 %</symbol>
326 % \fi
327 %
328 % \DescribeMacro{\newsuite}
329 % To create a new suite \textsf{suite} based on theme \textsf{theme}, write |\newsuite{theme}{suite}|.
330 %
331 % Suite names only need to be unique across the same theme. This means that you can have two suites with the same name if they are associated with different themes.
332 %
333 % \iffalse
334 %<*symbol>
335 \newcommand\newsuite[2]{
336 \symbolsuite@themecheck{#1}
337 \macrolistadd{symbolsuite@theme@#1@suites}{#2}
338 }
339 %</symbol>
340 % \fi
341 %
342 % \DescribeMacro{\setsuitesymbol}
343 % To set the symbol \textsf{symbol} (which was defined with respect to the theme of the suite) as the icon \textsf{icon} of suite \textsf{suite} in theme \textsf{theme}, write \begin{verbatim}\setsuitesymbol{theme}{suite}{symbol}{icon}\end{verbatim}
344 %
345 % \iffalse
346 %<symbol>\newcommand\setsuitesymbol[4]{\expandafter\def\csname symbolsuite@#1@#2@#3\endcsname{#4}}
347 % \fi
348 %
349 % \DescribeMacro{\activesuite}
350 % This sets the active suite of a theme. (This is how suites are ``swapped in'' with respect to a theme.) To set the active suite of theme \textsf{theme} as \textsf{suite}, write |\activesuite{theme}{suite}|.
351 %
352 % \iffalse
353 %<*symbol>
354 \newcommand\activesuite[2]{
355 \symbolsuite@themecheck{#1}
356 \symbolsuite@suitecheck{#1}{#2}
357 \expandafter\def\csname symbolsuite@#1@active\endcsname{#2}
358 }
359 %</symbol>
360 % \fi
361 %
362 % \DescribeMacro{\printsymbol}
363 % To use, write |\printsymbol{theme}{symbol}|. This is similar to \textsf{colorpalette.sty}'s |\applycolor|.
364 % \iffalse
365 %<*symbol>
366 \newcommand\printsymbol[2]{%
367 \symbolsuite@themecheck{#1}%
368 \symbolsuite@symbolcheck{#1}{#2}%
369 \csname symbolsuite@#1@\csname symbolsuite@#1@active\endcsname @#2\endcsname%
370 }
371 %</symbol>
372 % \fi
373 %
374 % \subsection{Error Messages}
375 % \iffalse
376 %<*symbol>
377 \newcommand\symbolsuite@themecheck[1]{\macrolistexists{symbolsuite@theme@#1@suites}{}{\symbolsuite@error@theme{#1}}}
378 \newcommand\symbolsuite@suitecheck[2]{\macrolistcontains{symbolsuite@theme@#1@suites}{#2}{}{\symbolsuite@error@suite{#1}{#2}}}
379 \newcommand\symbolsuite@symbolcheck[2]{\macrolistcontains{symbolsuite@theme@#1@symbols}{#2}{}{\symbolsuite@error@symbol{#1}{#2}}}
380 %</symbol>
381 % \fi
382 %
383 % If a nonexistent theme is passed in, the following error will be thrown:
384 % \begin{verbatim}The palette passed in is not a defined palette of theme `#1'\end{verbatim}
385 % where |#1| is the name of the theme.
386 % \iffalse
387 %<symbol>\newcommand\symbolsuite@error@theme[1]{\PackageError{symbolpalette}{The theme `#1' passed in is not defined}{}}
388 % \fi
389 %
390 % If a suite that does not belong to a theme is passed in, the following error will be thrown:
391 % \begin{verbatim}The suite `#2' passed in is not a defined suite of theme `#1'\end{verbatim}
392 % where |#1| is the name of the theme and |#2| is the name of the suite.
393 % \iffalse
394 %<symbol>\newcommand\symbolsuite@error@suite[2]{\PackageError{symbolpalette}{The suite `#2' passed in is not a defined suite of theme `#1'}{}}
395 % \fi
396 %
397 % If a symbol that does not belong to a theme is passed in, the following error will be thrown:
398 % \begin{verbatim}The symbol `#2' passed in is not a defined symbol of theme `#1'\end{verbatim}
399 % where |#1| is the name of the theme and |#2| is the name of the symbol.
400 % \changes{v1.0.1}{2020/07/28}{Make error message refer to symbol, not color}
401 % \iffalse
402 %<symbol>\newcommand\symbolsuite@error@symbol[2]{\PackageError{symbolpalette}{The symbol `#2' passed in is not a defined symbol of theme `#1'}{}}
403 % \fi
404 % \Finale
405 %
406 \endinput