Debian Codegraph @

texmf-dist/doc/latex/xkeyval/xkvex2.tex

raw
1 %%
2 %% This is file `xkvex2.tex',
3 %% generated with the docstrip utility.
4 %%
5 %% The original source files were:
6 %%
7 %% xkeyval.dtx (with options: `xkvex2')
8 %%
9 %% ---------------------------------------
10 %% Copyright (C) 2004-2022 Hendri Adriaens
11 %% 2025 David Carlisle for latex-package-repositories
12 %% ---------------------------------------
13 %%
14 %% This work may be distributed and/or modified under the
15 %% conditions of the LaTeX Project Public License, either version 1.3
16 %% of this license or (at your option) any later version.
17 %% The latest version of this license is in
18 %% http://www.latex-project.org/lppl.txt
19 %% and version 1.3 or later is part of all distributions of LaTeX
20 %% version 2003/12/01 or later.
21 %%
22 %% This work has the LPPL maintenance status "maintained".
23 %%
24 %% This Current Maintainer of this work is Hendri Adriaens.
25 %%
26 %% This work consists of the file xkeyval.dtx and derived files
27 %% keyval.tex, xkvtxhdr.tex, xkeyval.sty, xkeyval.tex, xkvview.sty,
28 %% xkvltxp.sty, xkvutils.tex, pst-xkey.tex, pst-xkey.sty, xkveca.cls,
29 %% xkvecb.cls, xkvesa.sty, xkvesb.sty, xkvesc.sty, xkvex1.tex,
30 %% xkvex2.tex, xkvex3.tex and xkvex4.tex.
31 %%
32 %% The following files constitute the xkeyval bundle and must be
33 %% distributed as a whole: readme, xkeyval.pdf, keyval.tex,
34 %% pst-xkey.sty, pst-xkey.tex, xkeyval.sty, xkeyval.tex, xkvview.sty,
35 %% xkvltxp.sty, xkvtxhdr.tex, xkvutils.tex, pst-xkey.dtx and xkeyval.dtx.
36 %%
37 \documentclass{article}
38 \usepackage{xkeyval}
39 \usepackage{xcolor,calc}
40
41 %% Example of setting keyval options using xkeyval
42 \usepackage{hyperref}
43 \usepackage{helvet}
44 \setkeys{Hyp,Hel}{colorlinks,urlcolor=green,scaled=.85}
45
46 \title{\textsf{xkeyval} package\\\normalsize\emph{Example 2}}
47 \author{Hendri Adriaens}
48 \setlength{\parindent}{0cm}
49
50 \makeatletter
51
52 \begin{document}
53 \maketitle
54
55 This example demonstrates the use of the new macros for setting
56 keys of the \textsf{xkeyval} package. Below each piece of verbatim
57 code, you can find its output.
58
59 \section{Simple operations}
60
61 Define keys.
62 \begin{verbatim}
63 \define@key{fami}{keyi}{key 1: #1\space}
64 \define@key{famii}{keyii}{key 2: #1\space}
65 \define@key{famiii}{keyiii}[test 2]{key 3: #1\space}
66 \define@key{famiv}{keyi}{key 4: #1\space}
67 \end{verbatim}
68 \define@key{fami}{keyi}{key 1: #1\space}
69 \define@key{famii}{keyii}{key 2: #1\space}
70 \define@key{famiii}{keyiii}[test 2]{key 3: #1\space}
71 \define@key{famiv}{keyi}{key 4: #1\space}
72
73 Set keys from multiple families.
74 \begin{verbatim}
75 \setkeys{fami,famii,famiii}{keyi=test 1,keyiii}
76 \end{verbatim}
77 \begin{itemize}
78 \item[$\Rightarrow$]
79 \setkeys{fami,famii,famiii}{keyi=test 1,keyiii}
80 \end{itemize}
81
82 Multiplely defined keys will be taken from the first family on the
83 list that defines the key. When \verb|+| is used, all families
84 defining the key will set it.
85 \begin{verbatim}
86 \setkeys{fami,famiv}{keyi=test 3}
87 \setkeys{famiv,fami}{keyi=test 4}
88 \setkeys+{fami,famiv}{keyi=test 5}
89 \end{verbatim}
90 \begin{itemize}
91 \item[$\Rightarrow$]
92 \setkeys{fami,famiv}{keyi=test 3}\par
93 \setkeys{famiv,fami}{keyi=test 4}\par
94 \setkeys+{fami,famiv}{keyi=test 5}
95 \end{itemize}
96
97 Starred form sets keys that it can find in the families specified.
98 Keys that cannot be located will be put onto a list for later use
99 by \verb+\setrmkeys+.
100 \begin{verbatim}
101 \setkeys*{famiv}{keyi=test 9,keyii=\url{http://www.test10.com},
102 keyiii=this key has been set on page \thepage}
103 \end{verbatim}
104 \begin{itemize}
105 \item[$\Rightarrow$]
106 \setkeys*{famiv}{keyi=test 9,keyii=\url{http://www.test10.com},
107 keyiii=this key has been set on page \thepage}
108 \end{itemize}
109
110 Try to set the remaining keys from the previous step. The starred
111 version defines a new list in case there are still keys that
112 cannot be located in the given families. The command below does
113 not do anything since the \verb+keyi+ key has already been taken
114 from family \verb+famiv+ above.
115 \begin{verbatim}
116 \setrmkeys*{fami}
117 \end{verbatim}
118 \setrmkeys*{fami}\par
119
120 The normal version will complain (as \verb+\setkeys+) when it
121 cannot locate a key which was previously submitted to
122 \verb+\setkeys+ and hasn't been set yet by previous commands.
123 \textsf{xkeyval} commands can also be used to set \textsf{keyval}
124 options as is done to the color of the url created with the
125 \textsf{hyperref} package and the scaling of the font used for
126 `\textsf{xkeyval}' with the \textsf{helvet} package. (See the
127 preamble of the example for the code).
128 \begin{verbatim}
129 \setrmkeys{famii,famiii}
130 \end{verbatim}
131 \begin{itemize}
132 \item[$\Rightarrow$]
133 \setrmkeys{famii,famiii}
134 \end{itemize}
135
136 Set keys, excluding some keys.
137 \begin{verbatim}
138 \setkeys{fami,famii,famiii}[keyi,keyiii]{keyi=test 6,keyii=test 7,keyiii=test 8}
139 \end{verbatim}
140 \begin{itemize}
141 \item[$\Rightarrow$]
142 \setkeys{fami,famii,famiii}[keyi,keyiii]{keyi=test 6,keyii=test 7,keyiii=test 8}
143 \end{itemize}
144
145 Test whether a key is defined in a family from the list.
146 \begin{verbatim}
147 \key@ifundefined{fami,famii}{keyiii}
148 {keyiii is not defined in family `fami' or `famii'}
149 {keyiii is defined in family `fami' or `famii'}
150 \end{verbatim}
151 \begin{itemize}
152 \item[$\Rightarrow$]
153 \key@ifundefined{fami,famii}{keyiii}
154 {keyiii is not defined in family `fami' or `famii'}
155 {keyiii is defined in family `fami' or `famii'}
156 \end{itemize}
157
158 Define some keys and macros.
159 \begin{verbatim}
160 \define@cmdkey[my]{fama}[my@]{keya}[none]{}
161 \define@choicekey[my]{fama}{keyb}{a,b,c}[b]{correct input: #1}
162 \define@boolkey[my]{famb}{keyc}[true]{}
163 \def\testa{\setkeys[my]{fama}}
164 \def\testb{\setkeys[my]{famb}}
165 \def\testset{\setkeys[my]{fama,famb}}
166 \end{verbatim}
167 \define@cmdkey[my]{fama}[my@]{keya}[none]{}
168 \define@choicekey[my]{fama}{keyb}{a,b,c}[b]{correct input: #1}
169 \define@boolkey[my]{famb}{keyc}[true]{}
170 \def\testa{\setkeys[my]{fama}}
171 \def\testb{\setkeys[my]{famb}}
172 \def\testset{\setkeys[my]{fama,famb}}
173 Now \verb+\testa+ can only set \verb+keya+, \verb+\testb+ can only
174 set \verb+keyb+ and \verb+\testset+ can set both.
175 \begin{verbatim}
176 \testa{keya}
177 \my@keya\
178 \testa{keyb}
179 \testb{keyc}
180 \ifmy@famb@keyc true \else false \fi
181 \testset{keya=test 11,keyb=c,keyc=false}
182 \my@keya\space
183 \ifmy@famb@keyc true \else false \fi
184 \end{verbatim}
185 \begin{itemize}
186 \item[$\Rightarrow$]
187 \testa{keya}
188 \my@keya\
189 \testa{keyb}
190 \testb{keyc}
191 \ifmy@famb@keyc true \else false \fi
192 \testset{keya=test 11,keyb=c,keyc=false}
193 \my@keya\space
194 \ifmy@famb@keyc true \else false \fi
195 \end{itemize}
196
197 \section{Pointers and values}
198
199 First we (re)define some keys.
200 \begin{verbatim}
201 \define@key{fam}{keyi}{key 1: #1 }
202 \define@key{fam}{keyii}{key 2: #1 }
203 \define@key{fam}{keyiii}[test 2]{key 3: #1 }
204 \end{verbatim}
205 \define@key{fam}{keyi}{key 1: #1 }
206 \define@key{fam}{keyii}{key 2: #1 }
207 \define@key{fam}{keyiii}[test 2]{key 3: #1 }
208
209 Pointers can be used to copy the value of other keys in the same
210 family. This can be done in two ways. The first example shows `on
211 the spot' value saving.
212 \begin{verbatim}
213 \setkeys{fam}{\savevalue{keyi}=test 12,\savevalue{keyii}=\usevalue{keyi}}
214 \setkeys{fam}{keyiii=\usevalue{keyii}}
215 \end{verbatim}
216 \begin{itemize}
217 \item[$\Rightarrow$]
218 \setkeys{fam}{\savevalue{keyi}=test 12,\savevalue{keyii}=\usevalue{keyi}}
219 \setkeys{fam}{keyiii=\usevalue{keyii}}
220 \end{itemize}
221
222 However, you can also predefine the keys to be saved for the entire
223 document with a single command. Note that we force keys to be saved
224 globally. This is necessary here since the commands in the source of
225 this document appear in an environment.
226 \begin{verbatim}
227 \savekeys{fam}{\global{keyi},\global{keyii}}
228 \setkeys{fam}{keyi=test 13,keyii=\usevalue{keyi}}
229 \setkeys{fam}{keyiii=\usevalue{keyii}}
230 \end{verbatim}
231 \begin{itemize}
232 \item[$\Rightarrow$]
233 \savekeys{fam}{\global{keyi},\global{keyii}}
234 \setkeys{fam}{keyi=test 13,keyii=\usevalue{keyi}}
235 \setkeys{fam}{keyiii=\usevalue{keyii}}
236 \end{itemize}
237
238 Pointers can be used in default values as well. Remember that the
239 previous example used \verb+\savekeys+ for \verb+keyi+ and \verb+keyii+.
240 \begin{verbatim}
241 \define@key{fam}{keyi}{keyi: #1 }
242 \define@key{fam}{keyii}[\usevalue{keyi}]{keyii: #1 }
243 \define@key{fam}{keyiii}[\usevalue{keyii}]{keyiii: #1 }
244 \setkeys{fam}{keyi=test 14}
245 \setkeys{fam}{keyii}
246 \setkeys{fam}{keyiii}
247 \end{verbatim}
248 \begin{itemize}
249 \item[$\Rightarrow$]
250 \define@key{fam}{keyi}{keyi: #1 }
251 \define@key{fam}{keyii}[\usevalue{keyi}]{keyii: #1 }
252 \define@key{fam}{keyiii}[\usevalue{keyii}]{keyiii: #1 }
253 \setkeys{fam}{keyi=test 14}
254 \setkeys{fam}{keyii}
255 \setkeys{fam}{keyiii}
256 \end{itemize}
257
258 \section{Presetting keys}
259
260 Simple example of the preset system.
261 \begin{verbatim}
262 \define@key{fam}{keyi}{keyi: #1 }
263 \define@key{fam}{keyii}{keyii: #1 }
264 \presetkeys{fam}{keyi=blue}{keyii=\usevalue{keyi}}
265 \setkeys{fam}{}\par
266 \setkeys{fam}{keyi=red}\par
267 \setkeys{fam}{keyii=red}
268 \presetkeys{fam}{keyi=red}{}
269 \setkeys{fam}{keyii=\usevalue{keyi}}
270 \end{verbatim}
271 \begin{itemize}
272 \item[$\Rightarrow$]
273 \define@key{fam}{keyi}{keyi: #1 }
274 \define@key{fam}{keyii}{keyii: #1 }
275 \presetkeys{fam}{keyi=blue}{keyii=\usevalue{keyi}}
276 \setkeys{fam}{}\par
277 \setkeys{fam}{keyi=red}\par
278 \setkeys{fam}{keyii=red}
279 \presetkeys{fam}{keyi=red}{}\par
280 \setkeys{fam}{keyii=\usevalue{keyi}}
281 \end{itemize}
282
283 \section{Application of pointers, values and presets}
284
285 \setkeys{Hyp}{urlcolor=black}
286 More complicated example of the preset
287 system and pointer system. See for more information about this
288 example the
289 \textsf{xkeyval} article on\par
290 \url{http://www.tug.org/TUGboat/tb25-2/tb81adriaens.pdf}.
291 \begin{verbatim}
292 \newdimen\shadowsize
293 \define@boolkey{Fbox}{frame}[true]{}
294 \define@boolkey{Fbox}{shadow}[true]{}
295 \define@key{Fbox}{framecolor}{\def\Fboxframecolor{#1}}
296 \define@key{Fbox}{shadowcolor}{\def\Fboxshadowcolor{#1}}
297 \define@key{Fbox}{framesize}{\setlength\fboxrule{#1}}
298 \define@key{Fbox}{shadowsize}{\setlength\shadowsize{#1}}
299 \presetkeys{Fbox}{frame,framecolor=red,framesize=0.5pt}%
300 {shadow=\usevalue{frame},shadowcolor=\usevalue{framecolor}!40,%
301 shadowsize=\usevalue{framesize}*4}
302 \savekeys{Fbox}{frame,framecolor,framesize}
303 \newcommand*\Fbox[2][]{%
304 \setkeys{Fbox}{#1}%
305 {\ifKV@Fbox@frame\else\fboxrule0pt\fi
306 \ifKV@Fbox@shadow\else\shadowsize0pt\fi
307 \sbox0{\fcolorbox{\Fboxframecolor}{white}{#2}}%
308 \hskip\shadowsize
309 \color{\Fboxshadowcolor}%
310 \rule[-\dp0]{\wd0}{\ht0+\dp0}%
311 \llap{\raisebox{\shadowsize}%
312 {\box0\hskip\shadowsize}}}%
313 }
314 \Fbox{demo1}
315 \Fbox[framecolor=blue]{demo2}
316 \Fbox[shadow=false]{demo3}
317 \Fbox[framesize=1pt]{demo4}
318 \Fbox[frame=false,shadow]{demo5}
319 \end{verbatim}
320 \newdimen\shadowsize
321 \define@boolkey{Fbox}{frame}[true]{}
322 \define@boolkey{Fbox}{shadow}[true]{}
323 \define@key{Fbox}{framecolor}%
324 {\def\Fboxframecolor{#1}}
325 \define@key{Fbox}{shadowcolor}%
326 {\def\Fboxshadowcolor{#1}}
327 \define@key{Fbox}{framesize}%
328 {\setlength\fboxrule{#1}}
329 \define@key{Fbox}{shadowsize}%
330 {\setlength\shadowsize{#1}}
331 \presetkeys{Fbox}%
332 {frame,framecolor=red,framesize=0.5pt}%
333 {shadow=\usevalue{frame},
334 shadowcolor=\usevalue{framecolor}!40,
335 shadowsize=\usevalue{framesize}*4}
336 \savekeys{Fbox}{frame,framecolor,framesize}
337 \newcommand*\Fbox[2][]{%
338 \setkeys{Fbox}{#1}%
339 {\ifKV@Fbox@frame\else\fboxrule0pt\fi
340 \ifKV@Fbox@shadow\else\shadowsize0pt\fi
341 \sbox0{\fcolorbox{\Fboxframecolor}{white}{#2}}%
342 \hskip\shadowsize
343 \color{\Fboxshadowcolor}%
344 \rule[-\dp0]{\wd0}{\ht0+\dp0}%
345 \llap{\raisebox{\shadowsize}%
346 {\box0\hskip\shadowsize}}}%
347 }
348 \Fbox{demo1}
349 \Fbox[framecolor=blue]{demo2}
350 \Fbox[shadow=false]{demo3}
351 \Fbox[framesize=1pt]{demo4}
352 \Fbox[frame=false,shadow]{demo5}
353
354 \end{document}
355 \endinput
356 %%
357 %% End of file `xkvex2.tex'.