Debian Codegraph @

texmf-dist/source/latex/adjustbox/adjcalc.dtx

raw
1 % \iffalse meta-comment
2 %<=*COPYRIGHT>
3 %% Copyright C 2011-2022 by Martin Scharrer <[email protected]>
4 %% -----------------------------------------------------------------
5 %% This work may be distributed and/or modified under the
6 %% conditions of the LaTeX Project Public License, either version 1.3
7 %% of this license or (at your option) any later version.
8 %% The latest version of this license is in
9 %% http://www.latex-project.org/lppl.txt
10 %% and version 1.3 or later is part of all distributions of LaTeX
11 %% version 2005/12/01 or later.
12 %%
13 %% This work has the LPPL maintenance status `maintained'.
14 %%
15 %% The Current Maintainer of this work is Martin Scharrer.
16 %%
17 %% This work consists of the files adjcalc.dtx, adjustbox.ins
18 %% and the derived file adjcalc.sty.
19 %% It is part of the larger adjustbox bundle.
20 %%
21 %<=/COPYRIGHT>
22 % \fi
23 %
24 % \iffalse
25 %<*driver>
26 \ProvidesFile{adjcalc.dtx}[%
27 %<=*DATE>
28 2012/05/16
29 %<=/DATE>
30 %<=*VERSION>
31 v1.1
32 %<=/VERSION>
33 DTX file for the adjcalc package]
34 \documentclass[a4paper]{ydoc}[2011/11/16]
35 \usepackage{amsmath}
36 \usepackage[T1]{fontenc}
37 \usepackage[utf8]{inputenc}
38 \usepackage{fourier}
39 \usepackage{newverbs}
40 \MakeSpecialShortVerb\qverb\"
41 %\AtBeginDocument{\MakeShortMacroArgs\`\relax}
42 %\AtEndDocument{\DeleteShortVerb\`}
43 \GetFileInfo{adjcalc.dtx}
44 \usepackage{adjcalc}[\filedate]
45 \usepackage{tikz}
46 \normalmarginpar
47
48
49 %\EnableCrossrefs
50 %\CodelineIndex
51 %\RecordChanges
52 \OnlyDescription
53 \begin{document}
54 \DocInput{\jobname.dtx}
55 \PrintChanges
56 %\newpage\PrintIndex
57 \end{document}
58 %</driver>
59 % \fi
60 %
61 % \CheckSum{274}
62 %
63 % \CharacterTable
64 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
65 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
66 % Digits \0\1\2\3\4\5\6\7\8\9
67 % Exclamation \! Double quote \" Hash (number) \#
68 % Dollar \$ Percent \% Ampersand \&
69 % Acute accent \' Left paren \( Right paren \)
70 % Asterisk \* Plus \+ Comma \,
71 % Minus \- Point \. Solidus \/
72 % Colon \: Semicolon \; Less than \<
73 % Equals \= Greater than \> Question mark \?
74 % Commercial at \@ Left bracket \[ Backslash \\
75 % Right bracket \] Circumflex \^ Underscore \_
76 % Grave accent \` Left brace \{ Vertical bar \|
77 % Right brace \} Tilde \~}
78 %
79 %
80 % \changes{v1.0}{2011/11/16}{First version after extraction from \pkg{adjustbox} package.}
81 % \changes{v1.1}{2012/05/16}{Better separation from the \pkg{adjustbox} package. Added own manual.}
82 %
83 % \GetFileInfo{adjcalc.dtx}
84 %
85 % \DoNotIndex{\newcommand,\newenvironment,\def,\edef,\xdef,\gdef,\let}
86 % \bundle{adjustbox}
87 % \author{Martin Scharrer}
88 % \email{[email protected]}
89 % \ydocpdfsettings
90 % \maketitle
91 %
92 % \begin{abstract}
93 % This package provides macros to assign or to add algebraic expressions to \LaTeX lengths and counters.
94 % It either uses $\epsilon$-\TeX, the \pkg{calc} package or the \pkg{pgfmath} package internally to achieve this.
95 % This package is part of the \pkg{adjustbox} bundle and was originally part of the \pkg{adjustbox} package before
96 % it was extracted to a dedicated package.
97 % \end{abstract}
98 %
99 % \section{Introduction}
100 % \LaTeX\ lengths and counters can be set using \Macro\setlength and \Macro\setcounter,
101 % and values can be added to these using \Macro\addtoclength and \Macro\addtocounter, respectively.
102 % By default these macros await a single length or integer value to be assigned or added.
103 % However, often it is beneficial to use a short algebraic expression, like a sum of two values, instead.
104 % The \pkg{calc} package was created for this and redefines the above macros to parse the given expression.
105 % Another possibility is to use $\epsilon$-\TeX's \Macro\dimexpr or \Macro\glueexpr which also allows for
106 % several algebraic operations and is more efficient than the higher-level \pkg{calc} package.
107 % Finally PGF/TikZ provides a large math engine with the \pkg{pgfmath} package. It allows even
108 % for complicated functions like $\log$ or $\sin$. However, \pkg{pgfmath} is rather large, especially because
109 % with PGF v2.10 it cannot be loaded on its own due to a bug, which forces the whole \pkg{pgf} package to be loaded.
110 %
111 % Package authors which like to write macros which allow algebraic expressions for its length arguments
112 % now face the dilemma which math interface they should use. Either they exclude users which do not have an
113 % $\epsilon$-TeX distribution (even if they are very rare) or require to load a large package.
114 % This was the case with the \pkg{adjustbox} package and therefore own wrapper macros were used instead which
115 % will use one of the different math engine mentioned above.
116 % Because this functionality was deemed useful for other packages of the same and other authors it was
117 % extracted into the dedicated package \pkg{adjcalc}. The idea is that the user can choose the used math engine
118 % using package options.
119 %
120 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
121 % \section{Package Options}\label{sec:options} ^^A (((
122 % The following options define the way length values are processed by the provided macros.
123 % The first group can be either used as package options and as local setting using \Macro\adjcalcset or as keys
124 % for \Macro\adjustbox or the \env{adjustbox} environment (but not for \Macro\includegraphics even if the \opt{export}
125 % option of \pkg{adjustbox} was used).
126 % The only difference between using them as package options or keys is that as package option they also load required packages.
127 % Therefore all keys used in the document should be used as package options first or the required packages must be loaded
128 % manually.
129 %
130 % \begin{description}\def\oitem#1{\item[{\normalfont\opt{#1}}]}
131 % \oitem{etex} Uses the $\epsilon$-\TeX\ primitive \Macro\glueexpr to parse length values. This allows for additions,
132 % subtractions as well as multiplications and devision by a numeric factor. See the official \pkg{etex\_man} document
133 % for more details. This setting is the default if $\epsilon$-\TeX\ is detected (which should be the case with all
134 % modern \LaTeX\ distributions).
135 % \oitem{calc} Uses the \pkg{calc} package to parse length values. It supports all operations mentioned for \opt{etex} and
136 % also some other operation like \Macro\widthof{<text>}.
137 % See the \pkg{calc} package manual for more details.
138 % This is the default setting if $\epsilon$-TeX is not detected.
139 % \oitem{pgfmath} Uses the \pkg{pgfmath} package of the \pkg{pgf} bundle to parse length values. It supports all basic
140 % numeric operations and also advanced mathematical functions.
141 % See the \pkg{pgf} manual for more details.
142 % Because the \pkg{pgfmath} package can't be loaded
143 % independently in the current version (v2.10) the whole \pkg{pgf} package will be loaded.
144 % \oitem{overwrite} This option will overwrite the standard macros with the macros of this package.
145 % This e.g.\ sets \Macro\setlength to be identical to \Macro\adjsetlength.
146 % Any package option used after \opt{overwrite} will still take affect before the redefinition,
147 % i.e.\ the order in which \opt{overwrite} is used is not meaningful.
148 % \oitem{defaultunit}\MacroArgs!{\hspace*{-1ex}}!'='<unit>\relax
149 % This sets the default unit used for macros and keys which allow for unit-less values,
150 % e.g.\ the \Key{trim} key of \Macro\adjustbox or the \Macro\trimbox macro of the \pkg{trimclip} package.
151 % The standard default unit is the same as for \Macro\includegraphics: "bp" (big points, PostScript points).
152 % However, for \LaTeX\ material \TeX\ normal unit "pt" (\TeX\ points) are better suited and will avoid rounding
153 % errors which otherwise get introduced by the internal conversion.
154 % The default unit is only used if the particular value is only a single number without unit,
155 % but not if any mathematical operations are used.
156 % If the special value |none| is used no default unit is applied and the internal check if the value is a single number
157 % is by-passed. This gives a small speed bonus and can be used to avoid potential issues with complex values.
158 % At this moment this setting will disable the default unit feature for the rest of the current group (i.e.\ all
159 % further \Macro\adjustbox keys or globally if used as a package option) and further usages of this option will
160 % have no affect. This might change in future versions of this package.
161 % \end{description}
162 %
163 % \noindent
164 % The following option can only be used as package option:
165 % \begin{description}\def\oitem#1{\item[{\normalfont\opt{#1}}]}
166 % \oitem{none} Disables the features of this package and makes all macros use the normal \LaTeX\ equivalents,
167 % e.g.\ \Macro\adjsetlength will expand to \Macro\setlength, etc.
168 % This option also disables any previous set option as well as any future use of \opt{overwrite}.
169 % \end{description}
170 %
171 %
172 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
173 %
174 % \section{Macros}
175 %
176 % \DescribeMacro\adjcalcset{<key=value, \ldots>}
177 % This configuration macro allows to change the above mentioned options during the document.
178 % Any changes are only locally to the current group/environment.
179 % Please see the descriptions of the options for any limitations.
180 %
181 %
182 % \DescribeMacro\adjsetlength{<\textbackslash lengthmacro>}{<length expression>}
183 % \DescribeMacro\adjaddtolength{<\textbackslash lengthmacro>}{<length expression>}
184 % \DescribeMacro\adjsetcounter{<counter name>}{<integer expression>}
185 % \DescribeMacro\adjaddtocounter{<counter name>}{<integer expression>}
186 % These macros can be used to set and add to \LaTeX\ length registers and counters like with the normal
187 % macros \Macro\setlength, \Macro\addtolength, \Macro\setcounter and \Macro\addtocounter.
188 % However, these macros allow the use of algebraic expressions, like sums and multiplications, while
189 % the standard macros only await a single value.
190 %
191 %
192 % \DescribeMacro\adjsetlengthdefault{<\textbackslash lengthmacro>}{<length expression with or without unit>}
193 % This macro set the length macro but does also support length values without an explicit unit.
194 % If no unit is used the default unit set by the \opt{defaultunit} option is used. The initial default unit
195 % is `|bp|' (big points, i.e.\ PostScript/PDF points, 72bp=1inch).
196 %
197 %
198 % \StopEventually{}
199 % \clearpage
200 % \section{Implementation}
201 %
202 % \iffalse
203 %<*adjcalc.sty>
204 % \fi
205 % \begin{macrocode}
206 %<!COPYRIGHT>
207 \ProvidesPackage{adjcalc}[%
208 %<!DATE>
209 %<!VERSION>
210 %<*DRIVER>
211 2099/01/01 develop
212 %</DRIVER>
213 Provides advanced setlength with multiple back-ends (calc, etex, pgfmath)]
214 % \end{macrocode}
215 %
216 %
217 % \begin{macrocode}
218 \RequirePackage{xkeyval}
219 % \end{macrocode}
220 %
221 %
222 % Use e-TeX by default if available, otherwise the \pkg{calc} package.
223 % \begin{macrocode}
224 \def\adjcalc@atend{%
225 \begingroup
226 \expandafter\ifx\csname glueexpr\endcsname\relax
227 \endgroup
228 \RequirePackage{calc}%
229 \adjcalc@calc
230 \def\adjcalc@etex{\PackageError{adjcalc}{e-TeX not available for current compiler!}}%
231 \else
232 \endgroup
233 \adjcalc@etex
234 \fi
235 }
236 % \end{macrocode}
237 %
238 % Initial definitions for the package options. This macros are later redefined because the same keys
239 % can be used as macro options.
240 % \begin{macrocode}
241 \def\adjcalc@pgfmath{\AtEndOfPackage{\RequirePackage{pgf}}\def\adjcalc@atend{\adjcalc@pgfmath}}
242 \def\adjcalc@etex{\def\adjcalc@atend{\adjcalc@etex}}
243 \def\adjcalc@calc{\AtEndOfPackage{\RequirePackage{calc}}\def\adjcalc@atend{\adjcalc@calc}}
244 \def\adjcalc@overwrite{\AtEndOfPackage{\adjcalc@overwrite}}
245 % \end{macrocode}
246 %
247 % The initial default unit is `|bp|' like for \pkg{graphicx}.
248 % \begin{macrocode}
249 \def\adjcalc@defaultunit{bp}%
250 % \end{macrocode}
251 %
252 %
253 % Options:
254 % \begin{macrocode}
255 \DeclareOptionX<adjcalc>{pgfmath}{\adjcalc@pgfmath}
256 \DeclareOptionX<adjcalc>{etex}{\adjcalc@etex}
257 \DeclareOptionX<adjcalc>{calc}{\adjcalc@calc}
258 \DeclareOptionX<adjcalc>{none}{%
259 \let\adjcalc@atend\relax
260 \let\adjcalc@overwrite\relax
261 \def\adjsetlength{\setlength}%
262 \def\adjaddtolength{\addtolength}%
263 \def\adjsetcounter{\setcounter}%
264 \def\adjaddtocounter{\addtocounter}%
265 }
266 \DeclareOptionX<adjcalc>{overwrite}{\adjcalc@overwrite}
267 \DeclareOptionX<adjcalc>{defaultunit}[bp]{%
268 \begingroup
269 \def\@tempa{#1}%
270 \def\@tempb{none}%
271 \ifx\@tempa\@tempb% 'none':
272 \endgroup
273 \def\adjsetlengthdefault{\adjsetlength}%
274 \else
275 \ifx\@tempb\adjcalc@defaultunit
276 \endgroup
277 % was 'none' before
278 \let\adjsetlengthdefault\adjsetlengthdefault@
279 \else
280 \endgroup
281 \fi
282 \fi
283 \def\adjcalc@defaultunit{#1}%
284 }
285 \ProcessOptionsX*<adjcalc>
286 \disable@keys{adjcalc}{none}
287 % \end{macrocode}
288 %
289 %
290 % \begin{macro}{\adjcalcset}
291 % User level settings macro.
292 % \begin{macrocode}
293 \def\adjcalcset{%
294 \setkeys{adjcalc}%
295 }
296 % \end{macrocode}
297 % \end{macro}
298 %
299 %
300 % \begin{macro}{\adjcalc@etex}
301 % \begin{macrocode}
302 \def\adjcalc@etex{%
303 \protected\def\adjsetlength##1##2{%
304 ##1=\glueexpr(##2)\relax
305 }%
306 \protected\def\adjaddtolength##1##2{%
307 \advance##1 by \glueexpr(##2)\relax
308 }%
309 \protected\def\adjsetcounter##1##2{%
310 \@ifundefined{c@##1}%
311 {\@nocounterr{##1}}%
312 {\global\csname c@##1\endcsname\numexpr(##2)\relax}%
313 }%
314 \protected\def\adjaddtocounter##1##2{%
315 \@ifundefined{c@##1}%
316 {\@nocounterr{##1}}%
317 {\global\advance\csname c@##1\endcsname\numexpr(##2)\relax}%
318 }%
319 \def\adjsetlengthdefault@##1##2{%
320 \@defaultunits##1=\glueexpr##2 \adjcalc@defaultunit\relax\@nnil
321 }%
322 \let\adjsetlengthdefault\adjsetlengthdefault@
323 }
324 % \end{macrocode}
325 % \end{macro}
326 %
327 % \begin{macrocode}
328 \newif\if@adjcalc@needsdefault
329 % \end{macrocode}
330 %
331 %
332 % \begin{macro}{\adjcalc@calc}
333 % This uses the underlying (re-)definitions of the normal macros (\Macro\setlength, ...) done by the \pkg{calc} package.
334 % This allows to locally redefine \Macro\setlength to call \Macro\adjsetlength, etc., without causing an infinite loop.
335 % \begin{macrocode}
336 \def\adjcalc@calc{%
337 \DeclareRobustCommand\adjsetlength{\calc@assign@skip}%
338 \DeclareRobustCommand\adjaddtolength[1]{\calc@assign@skip{\advance ##1}}%
339 \DeclareRobustCommand\adjsetcounter[2]{\@ifundefined{c@##1}{\@nocounterr{##1}}{\calc@assign@count{\global\csname c@##1\endcsname}{##2}}}%
340 \DeclareRobustCommand\adjaddtocounter[2]{\@ifundefined{c@##1}{\@nocounterr{##1}}{\calc@assign@count{\global\advance\csname c@##1\endcsname}{##2}}}%
341 \def\adjsetlengthdefault@##1##2{%
342 \begingroup
343 \def\calc@post@scan####1!{%
344 \def\@tempa{####1}%
345 \ifx\@tempa\@empty
346 \endgroup% to end calc processing
347 % is number only
348 \global\@adjcalc@needsdefaulttrue
349 \else
350 \endgroup% to end calc processing
351 % full expression
352 \global\@adjcalc@needsdefaultfalse
353 \fi
354 }%
355 \calc@assign@skip{##1}{##2 \adjcalc@defaultunit}%
356 \endgroup
357 \if@adjcalc@needsdefault
358 ##1=##2 \adjcalc@defaultunit\relax
359 \else
360 \calc@assign@skip{##1}{##2}%
361 \fi
362 }%
363 \def\adjcalc@checkdefault##1\@nnil##2##3{%
364 \ifx\relax##1\relax\else
365 \calc@assign@skip{##2}{##3}%
366 \fi
367 }%
368 \let\adjsetlengthdefault\adjsetlengthdefault@
369 }
370 % \end{macrocode}
371 % \end{macro}
372 %
373 %
374 % \begin{macro}{\adjcalc@pgfmath}
375 % \begin{macrocode}
376 \def\adjcalc@pgfmath{%
377 \DeclareRobustCommand\adjsetlength{\pgfmathsetlength}%
378 \DeclareRobustCommand\adjaddtolength{\pgfmathaddtolength}%
379 \DeclareRobustCommand\adjsetcounter{\pgfmathsetcounter}%
380 \DeclareRobustCommand\adjaddtocounter{\pgfmathaddtocounter}%
381 \def\adjsetlengthdefault@##1##2{%
382 \edef\pgfmathresultunitscale{1\adjcalc@defaultunit}%
383 \let\pgfmathpostparse\pgfmathscaleresult
384 \pgfmathparse{##2}%
385 ##1=\pgfmathresult pt\relax
386 }%
387 \let\adjsetlengthdefault\adjsetlengthdefault@
388 }
389 % \end{macrocode}
390 % \end{macro}
391 %
392 %
393 % \begin{macro}{\adjbox@settobp}
394 % \begin{macrocode}
395 \def\adjcalc@settobp#1#2{%
396 \begingroup
397 \adjsetlength\@tempdima{#2}%
398 \@tempdima=0.99626\@tempdima
399 \edef\@tempa{\endgroup\def\noexpand#1{\strip@pt\@tempdima\space}}%
400 \@tempa
401 }%
402 % \end{macrocode}
403 % \end{macro}
404 %
405 %
406 % \begin{macro}{\adjcalc@overwrite}
407 % \begin{macrocode}
408 \def\adjcalc@overwrite{%
409 \let\setlength\adjsetlength
410 \let\addtolength\adjaddtolength
411 \let\setcounter\adjsetcounter
412 \let\addtocounter\adjaddtocounter
413 }
414 % \end{macrocode}
415 % \end{macro}
416 %
417 % Execute at-end code.
418 % \begin{macrocode}
419 \adjcalc@atend
420 % \end{macrocode}
421 % \iffalse
422 %</adjcalc.sty>
423 % \fi
424 %
425 % \Finale
426 % \endinput