-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathadjustbox.dtx
2192 lines (2187 loc) · 108 KB
/
adjustbox.dtx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% \iffalse meta-comment
%<=*COPYRIGHT>
%% Copyright (C) 2011-2022 by Martin Scharrer <martin.scharrer@web.de>
%% -------------------------------------------------------------------
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
%% of this license or (at your option) any later version.
%% The latest version of this license is in
%% http://www.latex-project.org/lppl.txt
%% and version 1.3 or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
%%
%% The Current Maintainer of this work is Martin Scharrer.
%%
%% This work consists of the files adjustbox.dtx, adjustbox.ins
%% and the derived file adjustbox.sty.
%%
%<=/COPYRIGHT>
% \fi
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% ^^A DRIVER (((
% \iffalse
%<*driver>
\ProvidesFile{adjustbox.dtx}[%
%<=*DATE>
2022/10/17
%<=/DATE>
%<=*VERSION>
v1.3a
%<=/VERSION>
DTX file for the adjustbox package]
\documentclass[a4paper]{ydoc}[2011/08/11]
\usepackage{amsmath}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{fourier}
\usepackage{newverbs}
\usepackage{xparse}
\MakeSpecialShortVerb\qverb\"
%\AtBeginDocument{\MakeShortMacroArgs\`\relax}
%\AtEndDocument{\DeleteShortVerb\`}
\GetFileInfo{adjustbox.dtx}
\usepackage{adjustbox}[\filedate]
\usepackage{tikz}
\renewenvironment{example}[1][Example:]{%
\subsubsection*{#1}%
}{%
\par
}
\newenvironment{examples}[1][Examples:]{%
\subsubsection*{#1}%
}{%
\par
}
\global\optionaloff
\let\optionalon\relax
\lstdefinelanguage{none}{}%
\lstdefinelanguage{adjustbox}{%
moretexcs={%
begin,end,adjustbox
},
emph={%
frame,fbox,cframe,cfbox,minipage,raise
},
}%
\lstdefinestyle{examplecode}{%
basicstyle=\ttfamily\small,
numbers=none,language=none,
classoffset=1,
morekeywords={begin,end},
keywordstyle=\bfseries,
classoffset=0,
morekeywords={adjustbox,minsizebox,maxsizebox,lapbox,marginbox,phantombox},
keywordstyle=\macrodescstyle,
emph={viewport, trim, Trim, Viewport, Clip, Clip*, frame, fbox, cframe, cfbox, reflect, lap, margin, margin*, dpi,
pxdim, execute, raise, valign, bgcolor, set, height, depth, vsize, width, totalheight, center, left, right, outer, inner, min, max,
size, totalsize,
minipage, varwidth, innerenv, innercode, env, Addcode, addcode, precode, Precode, appcode, angle, scale, height, width, totalheight, resolution,
},
emphstyle=\keydescstyle,
}
\makeatletter
\def\PrintExample{%
\begingroup
\par\smallskip\noindent
\leavevmode
\BoxExample
\@tempdima=\textwidth
\advance\@tempdima by -\wd\examplecodebox\relax
\advance\@tempdima by -\wd\exampleresultbox\relax
\advance\@tempdima by -15pt\relax
\ifdim\@tempdima>\bigskipamount
\hbox to \textwidth{%
\null\hss
\minipage[c]{\wd\examplecodebox}\usebox\examplecodebox\endminipage
\hfill\hskip\bigskipamount\hfill
\minipage[c]{\wd\exampleresultbox}%
\EXAMPLERESULT
\endminipage
\hss\null
}%
\else
\vbox{%
\leftline{\usebox\examplecodebox}%
\vspace{\bigskipamount}%
\rightline{\EXAMPLERESULT}%
}%
\fi
\par\smallskip
\endgroup
}
\def\EXAMPLERESULT{%
\leavevmode\hbox{%
\textcolor{exampleborder}{%
\boxframe
{\dimexpr\wd\exampleresultbox+2\fboxrule\relax}%
{\dimexpr\ht\exampleresultbox+\fboxrule\relax}%
{\dimexpr\dp\exampleresultbox+\fboxrule\relax}%
\hskip-\wd\exampleresultbox
\hskip-\fboxrule
}%
\usebox\exampleresultbox
}%
}%
\makeatother
\colorlet{exampleborder}{black!33}
\def\Descsep{\par\vskip-2.5ex\relax}
%\EnableCrossrefs
%\CodelineIndex
%\RecordChanges
\OnlyDescription
\renewcommand{\bottomfraction}{0.5}
\begin{document}
\DocInput{adjustbox.dtx}
\PrintChanges
%\newpage\PrintIndex
\end{document}
%</driver>
% \fi
% ^^A )))
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% ^^A Title page (((
% \CheckSum{3488}
%
% \CharacterTable
% {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
% 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
% Digits \0\1\2\3\4\5\6\7\8\9
% Exclamation \! Double quote \" Hash (number) \#
% Dollar \$ Percent \% Ampersand \&
% Acute accent \' Left paren \( Right paren \)
% Asterisk \* Plus \+ Comma \,
% Minus \- Point \. Solidus \/
% Colon \: Semicolon \; Less than \<
% Equals \= Greater than \> Question mark \?
% Commercial at \@ Left bracket \[ Backslash \\
% Right bracket \] Circumflex \^ Underscore \_
% Grave accent \` Left brace \{ Vertical bar \|
% Right brace \} Tilde \~}
%
%
% \changes{v0.1}{2011/01/24}{First internal version}
% \changes{v0.2}{2011/01/27}{First released version}
% \changes{v0.3}{2011/03/20}{Bug fix for wrong baseline placed on the bottom}
% \changes{v0.4}{2011/07/xx}{Added pdftex driver}
% \changes{v0.5}{2011/08/13}{Added more macros and keys}
% \changes{v0.5a}{2011/08/21}{Fixed \Key{left} and \Key{right} keys. Fixed \Key{valign}'='t}
% \changes{v0.6}{2011/09/04}{Added tabular support.}
% \changes{v0.6a}{2011/10/29}{Fixed issue with keys affecting the content in an unwanted way.}
% \changes{v0.7}{2011/10/30}{Added \cs{adjustboxset} and \cs{adjustimage} macros.}
% \changes{v0.8}{2011/11/14}{
% Added driver files for dvips and xelatex. Moved pdftex driver code to own file.
% Fixed and improved default unit code for the \opt{calc} option.
% Changed \cs{adjustimage} code to use internals of \cs{includegraphics}. This allows the redefinition of \cs{includegraphics}.
% Added manual for \Key{bgcolor} and added \Key{bgcolor*}.
% Changed \Key{bgimage} to use \cs{adjustimage}.
% Added manual entries for \Key{cfbox} and \Key{cframe}.
% Removed loading of non-mandatory \pkg{storebox} package for now.
% Added \Key{set vsize}.
% Added shortcuts \Key{rlap} and \Key{llap}.
% Added \adjincludegraphics and the Export option.
% Fix for \Key{innerenv} argument.
% Added lengths \cs{Width}, \cs{Height}, \cs{Depth} and \cs{Totalheight} for the original dimensions of the content.
% Added own \cs{raisebox} variant to support math expressions even for \cs{includegraphics}.
% Some code cleanup.
% Added \Key{varwidth} key as an alternative to \Key{minipage}.
% Added \stackbox and \Key{stack} key and \env{stackbox} environment (similar to \cs{shortstack})
% Added check for \pkg{xcolor} package.
% }
% \changes{v0.9}{2012/05/16}{
% Basic trim and clip macros and driver files are now placed in a dedicated minimal package 'trimclip'.
% Special thanks goes to Joseph Wright (LaTeX3 project) for his work on the driver files.
% Clipping drivers are provided for 'pdftex' (incl. LuaTeX), 'dvips' and 'xetex' as well as a PGF fall-back
% driver.
% Packages: New dedicated 'trimclip' package with own manual.
% Better separation between 'adjcalc' and 'adjustbox' package.
% Review of manuals
% New adjustbox keys:
% * content
% * gstore
% * gstore*
% * gstore width/height/depth/totalheight/sizes
% * gobble/discard
% * phantom
% * warn width
% * float
% * nofloat
% * figure
% * label
% * caption
% * vspace
% * vspace*
% * padding (alias of 'margin')
% * padding* (alias of 'margin*')
% Fixes: env key now works correctly; Fixed raise box code.
% Macro changes: Added third optional argument to \stackbox.
% }
% \changes{v1.0}{2012/05/21}{%^^A
% * Updated manual to contain all new keys and macro.
% * Code optimisations.
% * Improvements of (re-)boxing code.
% * Added user-level macros to define keys.
% * Changed horizontal alignment keys to box the content and added matching macros.
% * Changed horizontal inner/outer side keys to use 'ifodd' package and added matching macros.
% * Added missing \cs{leavevmode} for "raise" key.
% * Simplified code for "valign" key. Fixed spurious space for "valign=v".
% * Fixed min/max size keys to double a single value correctly.
% * Code cleanup with "warn width" key.
% }
% \changes{v1.1}{2018/04/08}{%^^A
% * Several bug fixes.
% * Support for round corners and frames.
% }
% \changes{v1.2}{2019/01/04}{%^^A
% * Added missing 'clip' feature for rounded frames.
% * Changed order of corner values for rounded frames. This includes an update to the clipping drivers.
% * Corrected 'adjnofloat' environment used by the 'nofloat' key to support the 'hypcap' feature of the 'caption' and 'hypcap' packages.
% * Updated manual description of `export` option as requested by Issue #9.
% * Updated manual to use (left, bottom, right, top) for the side values instead of (llx, lly, urx, ury).
% * Some other improvements in the manual.
% * Added keys and matching commands and environments to align to the page margins and text area borders:
% 'pagecenter', 'pageleft', 'pageright', 'pageinner', 'pageouter',
% 'textareacenter', 'textarealeft', 'textarearight', 'textareainner', 'textareaouter'.
% * Added 'noindent' key.
% * Added \newadjustimage and \NewAdjustImage commands to define custom versions of \adjustimage with predefined key
% lists. This include variation to renew, provide and declare such macros.
% * Added \provideadjustboxenv and \declareadjustboxenv.
% * Added \provideadjustboxcmd and \declareadjustboxcmd.
% }
% \changes{v1.3}{2020/08/19}{%^^A
% * Added support for (hopefully) all 'graphicx' keys.
% * Added missing \leavevmode for framing keys.
% * Added key "leavevmode" on request of Frank Mittelbach.
% * Added 'process' key.
% * Added 'clap' key on user request.
% * Removed old graphicx key 'print'.
% * trimclip: Added explicit luatex driver which uses the pdftex driver to avoid the fallback to PGF driver.
% }
% \changes{v1.3a}{2022/10/17}{%^^A
% * Updated documentation with new repository URL and new email address.
% * Added dependency file for texlive.
% }
%
% \GetFileInfo{adjustbox.dtx}
%
% \DoNotIndex{\newcommand,\newenvironment,\def,\edef,\xdef,\gdef,\let}
%
% \author{Martin Scharrer}
% \email{martin.scharrer@web.de}
% \repository{https://github.com/MartinScharrer/adjustbox/}
% \ydocpdfsettings
% \maketitle
%
% \makeatletter
% \def\LATeX{\texorpdfstring{(L\kern -.36em{\sbox \z@ T\vbox to\ht \z@ {\hbox {\check@mathfonts
% \fontsize \sf@size \z@ \math@fontsfalse \selectfont A}\vss }}\kern -.15em)\TeX}{(La)TeX}}
% \makeatother
%
% \begin{abstract}
% This package allows to adjust general \LATeX\ material in several ways using a key=value interface.
% It got inspired by the interface of \Macro\includegraphics from the \pkg{graphicx} package.
% This package also loads the \pkg{trimclip} package which code was once included in this package.
% \end{abstract}
% \clearpage% \tableofcontents
%
% ^^A )))
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \clearpage\section{Introduction} ^^A (((
% The standard \LaTeX{} package \pkg{graphicx} (the extended version of \pkg{graphics}) provides the macro
% \Macro\includegraphics[<options>]{<file name>} which can be used to include graphic files. Several options can be used
% to scale, resize, rotate, trim and/or clip the graphic.
% The macros \Macro\scalebox, \Macro\resizebox and \Macro\rotatebox are also provided to apply the corresponding
% operation on \LATeX{} material, which is subsequently placed inside a \Macro\hbox.
% However no macros are provided to trim or clip \LATeX{} material, most likely because this operations
% are not done by \TeX{} but by the output format, i.e.\ using PostScript (PS) or PDF operations.
%
% This package started by providing the missing macros \Macro\clipbox and \Macro\trimbox.
% Then a general \Macro\adjustbox macro which allows to combine many operations using a key=value syntax was added and
% further extended until it represented the main feature of this package. Newly added keys are also provided as
% dedicated macros and corresponding environments.
% The \Macro\clipbox and \Macro\trimbox macros were then moved together with the required output driver code to a
% dedicated package \pkg{trimclip}. This allows documents and other packages to use these basic features without
% loading the full \pkg{adjustbox} package.
%
%
% ^^A )))2
% \subsection{Dependencies} ^^A (((2
% The \pkg{adjustbox} package and its \pkg{trimclip} sub-package require the author's other packages \pkg{adjcalc}
% (bundled with \pkg{adjustbox}) and \pkg{collectbox}, as well as the packages \pkg{xkeyval}, \pkg{graphicx} and \pkg{ifpdf}.
% The \pkg{varwidth} package is automatically loaded if installed, otherwise the \Key{varwidth} and \Key{stack} keys are
% disables as well as \Macro\stackbox and the \env{stackbox} environment.
% The \pkg{ifoddpage} package is automatically loaded if installed, otherwise the \Key{outer} and \Key{inner} keys are
% disables as well as \Macro\outersidebox and \Macro\innersidebox macros and corresponding environments.
% For features which use colors the \pkg{xcolor} package must also be loaded manually (the \pkg{color} package is fine, too).
% The experimental |split| and |pagebreak| features also require the \pkg{storebox} package to be loaded manually.
%
% ^^A )))2
% \subsection{Verbatim Support}\label{sec:verbatim} ^^A (((2
% The macros provided by \pkg{adjustbox} and \pkg{trimclip} read the content as a horizontal \TeX{} box and not as an
% macro argument in order to support verbatim content.
% This means that the braces around the content can also be written as \Macro\bgroup and \Macro\egroup:
% \begin{macroquote}
% \adjustbox{key=value,\ldots}\AlsoMacro\bgroup~<content>\AlsoMacro\egroup
% \end{macroquote}
% Special care is taken to allow the \meta{content} to be a single macro (except \Macro\bgroup) without any braces:
% \begin{macroquote}
% \adjustbox{key=value,\ldots}\AlsoMacro\somemacro
% \end{macroquote}
% This is to support the habit of some \LaTeX{} users to drop the braces for single token arguments.
% All environments support verbatim content.
% Note that the plain\TeX{} syntax for environments (\Macro\adjustbox\ldots\Macro\endadjustbox) can not be used
% because it will trigger \Macro\adjustbox as a macro. However, the braces around the content can be replaced
% by \Macro\bgroup and \Macro\egroup.
%
% ^^A )))2
% ^^A )))
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \clearpage\section{Package Options}\label{sec:options} ^^A (((
% This package accepts the following options:
%
% \begin{description}\def\oitem#1{\item[{\normalfont\opt{#1}}]}
% \oitem{export} Exports the keys of \Macro\adjustbox to \Macro\includegraphics so that they can be used with this
% macro as well. Note that not all keys will works properly with \Macro\includegraphics as its internal
% code does not support all features. If problems occur the option |Export| should be used.
% For new documents it is recommended to use the macro \Macro\adjustimage{<keys>}{<filename>} instead.
% \oitem{Export} Sets \Macro\includegraphics to be identical to \Macro\adjincludegraphics, which also allows the usage
% of all \Macro\adjustbox keys.
% \oitem{pgf} This option is passed to \pkg{trimclip} and makes it to use the \pkg{pgf} package for all clip operations.
% This overrides all automatically detected drivers.
% \oitem{PGF} This option will pass the \opt{pgf} to \pkg{trimclip} and enable the \opt{pgfmath} option of
% \pkg{adjcalc}, i.e.\ the \pkg{pgf}
% package is used for clip operations and the \pkg{pgfmath} pacakge is used to parse length arguments.
% \oitem{minimal} Only load a minimal set of code, i.e.\ \pkg{trimclip} and \Macro\adjustbox/\env{adjustbox}
% but no additional keys and macros.
% \end{description}
%
% \noindent
% The following options define the way length values are processed by the provided macros.
% They are passed to the \Macro\adjcalcset macro of the \pkg{adjcalc} package and load any required packages.
% These options can also be used as local keys on \Macro\adjustbox. See the \pkg{adjcalc} manual for more details on
% them.
%
% \begin{description}\def\oitem#1{\item[{\normalfont\opt{#1}}]}
% \oitem{etex} Uses the $\epsilon$-\TeX\ primitive \Macro\glueexpr to parse length values.
% \oitem{calc} Uses the \pkg{calc} package to parse length values.
% \oitem{pgfmath} Uses the \pkg{pgfmath} package of the \pkg{pgf} bundle to parse length values.
% \oitem{defaultunit}\MacroArgs!{\hspace*{-1ex}}!'='<unit>\relax
% This sets the default unit used for values which accept length without units, e.g.\ \Key{trim}.
% \end{description}
%
% \noindent
% In addition, all driver options of the \pkg{trimclip} package are also accepted and passed to it.
% All unknown options are passed to the \pkg{graphicx} package, which might pass them down to the \pkg{graphics}
% package.
%
% ^^A )))
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \clearpage\section{Main Macros}^^A (((
% The following macros and environments represent the main functionality of this package.
% Special care is taken so that the macros and the environments can have the same name.
% For starred environments the star can be either part of the name or an optional argument.
%
% \subsection{Adjust Box Content} ^^A (((2
% \vskip-\lastskip
% \DescribeMacro\adjustbox{<key=value, \ldots>}{<content>}
% The \Macro\adjustbox macro allows the modification of general \LATeX\ content using a key=value syntax.
% This can be seen as an extension of the \Macro\includegraphics macro from images to any \LATeX{} material.
% The macro supports the all \Macro\includegraphics keys and many more.
% However, they are provided as a mandatory not as an optional argument, because an \Macro\adjustbox without options
% would not make sense and can be replaced by a simple \Macro\mbox.
% As already stated the content is read as a box, not as a macro argument, therefore verbatim or other special
% content is supported and the braces can also be replaced by \Macro\bgroup and \Macro\egroup.
% There is no starred version of this macro.
%
% \DescribeEnv[<content>]{adjustbox}{<key=value, \ldots>}
% The environment version of \Macro\adjustbox. A difference to the macro is that it includes \Macro\noindent
% to suppress paragraph indention.
%
% \Needspace*{5\baselineskip}
% \clearpage\subsection{Adjust Images}
% \vskip-\lastskip
% \DescribeMacro\adjustimage{<key=value, \ldots>}{<image filename>}
% This macro can be used as an extension of \Macro\includegraphics.
% While \Macro\adjustbox is based on the same interface as \Macro\includegraphics it provides more keys and allows
% global keys set by \Macro\adjustboxset. Most keys can be exported to \Macro\includegraphics using the \opt{export}
% option, but there is no support for global keys\footnote{However some keys, but not all, can be set globally using
% \Macro\setkeys{Gin}{<includegraphic key=value pairs>}}. Therefore it can make sense to use
% \Macro\adjustbox{<key/value pairs>}{\AlsoMacro\includegraphics{<filename>}}, which is the definition of
% \Macro\adjustimage.
% However, it does not use \Macro\includegraphics directly, but an internal macro, to allow the redefinition of
% \Macro\includegraphics.
% This macro does not require the \opt{export} option and therefore helps to avoid option clashes
% if \pkg{adjustbox} is loaded at several places.
%
%
% \DescribeMacro\adjincludegraphics[<key/value pairs>]{<image filename>}
% Like \Macro\adjustimage but in the same format as \Macro\includegraphics, i.e.\ with an optional argument. This macro
% allows to use all features of \Macro\adjustbox on images, however special care must be taken if the values include
% `|[ ]|'. In this case either the whole value or the while optional argument must be wrapped in `|{ }|':
% \Macro\adjincludegraphics['key='{[..]},...]{..} or \\\Macro\adjincludegraphics[{key=[..],...}]{..}. \\
% It is possible to redefine \Macro\includegraphics to \Macro\adjincludegraphics and this is done by
% the \opt{Export} option (not to be confused with the \opt{export} option).
%
% ^^A )))2
% \clearpage\subsection{Defining custom environments and macros} ^^A (((2
% After \pkg{adjustbox} is used to define custom environments to format specific content.
% If an environment contains other environments these are often written in the plain form \Macro\foo \ldots
% \Macro\endfoo to avoid the overhead of \Macro\begin and \Macro\end and to keep the outer environment name for
% meaningful error messages. As mentioned, the dual nature of \Macro\adjustbox which will detect if it is used
% as environment of macro does not permit this plain form, which can be a pitfall for custom environment definitions.
% Instead the macro form \Macro\adjustbox{<key=value>}\AlsoMacro\bgroup \ldots \Macro\egroup should be used.
% To simplify custom environment definitions based on \Macro\adjustbox/\env{adjustbox} the following macros are
% provided.
%
%
% \DescribeMacro\newadjustboxenv{<name>}[<num>][<default>]{<key=value,\ldots>}
% This declaration defines an environment and macro with the given name which will apply the given \pkg{adjustbox} keys
% to its content. The environment/macro can also posses arguments, including one leading optional argument, which can be
% used inside the key=value pairs. It is recommended to wrap the arguments into braces, e.g.\ use `|{#1}|' instead of
% `|#1|' etc., to avoid issues with potentially included commas and equal signs.
% The number and type of arguments are defined using two optional arguments in the same
% way as for \Macro\newcommand and \Macro\newenvironment.
%
%
% \DescribeMacro\newadjustboxenv*{<name>}[<num>][<default>]{<key=value,\ldots>}
% This declaration works similar to the unstarred version but only defines an environment.
% This environment can therefore be used like any other normal \LaTeX\ environment, including in its plain
% form {\macrodescstyle\textbackslash\meta{name}} \ldots {\macrodescstyle{\textbackslash end\meta{name}}}.
%
%
% \DescribeMacro\renewadjustboxenv{<name>}[<num>][<default>]{<key=value,\ldots>}
% \DescribeMacro\renewadjustboxenv*{<name>}[<num>][<default>]{<key=value,\ldots>}
% Like \Macro\newadjustboxenv and \Macro\newadjustboxenv* but will redefine an existing macro/environment and cause an
% error if it was not yet defined.
%
%
% \DescribeMacro\provideadjustboxenv{<name>}[<num>][<default>]{<key=value,\ldots>}
% \DescribeMacro\provideadjustboxenv*{<name>}[<num>][<default>]{<key=value,\ldots>}
% Like \Macro\newadjustboxenv and \Macro\newadjustboxenv* but will define a macro/environment only if it does not exists
% yet.
%
%
% \DescribeMacro\declareadjustboxenv{<name>}[<num>][<default>]{<key=value,\ldots>}
% \DescribeMacro\declareadjustboxenv*{<name>}[<num>][<default>]{<key=value,\ldots>}
% Like \Macro\newadjustboxenv and \Macro\newadjustboxenv* but will always define a macro/environment even if it does already exist.
%
%
% \DescribeMacro\newadjustboxcmd{<\textbackslash macro>}[<num>][<default>]{<key=value,\ldots>}
% This declaration defines a macro which applies the given \pkg{adjustbox} keys to its content.
% As with \Macro\adjustbox the content is read as box, not as macro argument.
% The macro arguments (if any) are defined in the same way as with \Macro\newcommand.
% The arguments can then be used inside the key=value pairs. The number of arguments does not
% include the content.
% This declaration is intended if no environment form is required and is more efficient than the dual declaration.
%
% \begin{example}
% \begin{examplecode}
% \newadjustboxcmd{\frotate}[1]{rotate={#1},fbox}%
% \frotate{30}{Text}
% \end{examplecode}
% \end{example}
%
% \DescribeMacro\renewadjustboxcmd{<\textbackslash macro>}[<num>][<default>]{<key=value,\ldots>}
% Like \Macro\newadjustboxcmd but will redefine an existing macro and cause an
% error if it was not yet defined.
%
%
% \DescribeMacro\provideadjustboxcmd{<\textbackslash macro>}[<num>][<default>]{<key=value,\ldots>}
% Like \Macro\newadjustboxcmd but will define the macro only if it does not exist yet.
%
%
% \DescribeMacro\declareadjustboxcmd{<\textbackslash macro>}[<num>][<default>]{<key=value,\ldots>}
% Like \Macro\newadjustboxcmd but will define the macro in any case even if it does exist yet.%
%
%
% \DescribeMacro\newadjustimage{<\textbackslash macro>}[<num>][<default>]{<key=value,\ldots>}
% \DescribeMacro\renewadjustimage{<\textbackslash macro>}[<num>][<default>]{<key=value,\ldots>}
% \DescribeMacro\provideadjustimage{<\textbackslash macro>}[<num>][<default>]{<key=value,\ldots>}
% These macros allow to define new versions of \Macro\adjustimage with predefined key lists.
% The new define image macros can also have arguments which can be used in the predefined key list to
% substitude values or one or multiple keys.
%
% They work like \Macro\newcommand, \Macro\renewcommand and \Macro\providecommand, respectively, where
% \meta{num} is the number of arguments and \meta{default} provides a default value for the then optional
% first argument. However, instead of a macro content a \meta{key=value} list must be present, which can
% contain the arguments (|#1|, |#2|, etc). If arguments are used as values they should be wrapped in braces.
% If there are only part of a value the whole value should be wrapped in braces. This is to avoid causes commas
% inside the arguments to cause issues with the key=value list.
%
% \begin{example}
% \begin{examplecode}
% \newadjustimage{\myimage}[2][red]{width={#2},cfbox={#1}}%
% \myimage{2cm}{example-image}
% \myimage[blue]{2cm}{example-image}
% \end{examplecode}
% \end{example}
%
% \DescribeMacro\declareadjustimage{<\textbackslash macro>}[<num>][<default>]{<key=value,\ldots>}
% Like \Macro\newadjustimage but will not cause an error if the macro is already defined.
%
%
% \DescribeMacro\NewAdjustImage{<\textbackslash macro>}{<xparse argument specification>}{<key=value,\ldots>}
% \DescribeMacro\RenewAdjustImage{<\textbackslash macro>}{<xparse argument specification>}{<key=value,\ldots>}
% \DescribeMacro\ProvideAdjustImage{<\textbackslash macro>}{<xparse argument specification>}{<key=value,\ldots>}
% \DescribeMacro\DeclareAdjustImage{<\textbackslash macro>}{<xparse argument specification>}{<key=value,\ldots>}
% These macros also allow to define new versions of \Macro\adjustimage with predefined key lists, but use
% the \pkg{xparse} package (which must be loaded separately!) and its macros \Macro\NewDocumentCommand, \Macro\RenewDocumentCommand,
% \Macro\ProvideDocumentCommand and \Macro\DeclareDocumentCommand instead of the standard \LaTeX\ macro creation
% macros. This allows a larger variety of optional and mandatory arguments. Please see the \pkg{xparse} manual
% for more details.
%
% \begin{example}
% \begin{examplecode}
% \NewAdjustImage{\myimage}{O{red}m}{width={#2},cfbox={#1}}%
% \myimage{2cm}{example-image}
% \myimage[blue]{2cm}{example-image}
% \end{examplecode}
% \end{example}
%
%
% ^^A )))2
% \clearpage\subsection{Setting keys globally} ^^A (((2
% \vskip-\lastskip
% \DescribeMacro\adjustboxset{<global keys to be executed \emph{before} local keys>}
% \DescribeMacro\adjustboxset*{<global keys to be executed \emph{after} local keys>}
% Using these two macros all keys can be set globally, i.e.\ for all future \Macro\adjustbox macros and \env{adjustbox}
% environments. Note that these settings are actually \emph{local} to the current \TeX\ group and only really global if
% used in the preamble or outside any group. The normal macro will place all given keys before the keys used in first
% argument of \Macro\adjustbox\ / \env{adjustbox}, while the starred version will place them afterwards.
%
% If these macros are used several times there keys are accumulated. This happens in the given order for the normal
% version and in reversed order for the starred version, i.e.\ the keys of further \Macro\adjustboxset or
% \Macro\adjustboxset* are always added so they face inwards. If used without any keys but an empty argument, all keys
% previously set with the same macro are removed (from the current \TeX\ scope). This means \Macro\adjustboxset{}
% clears all keys set be previously usages of \Macro\adjustboxset{<keys>} and \Macro\adjustboxset*{} clears all set by
% \Macro\adjustboxset*{<keys>}. Such resets are again local to the current \TeX\ group.
%
%
% \begin{examples}
% The macros:
% \begin{macroquote}
% \adjustboxset{keya=1} \\
% \adjustboxset*{keyc=3}\\
% \adjustbox{keyb=2}{content}
% \end{macroquote}
% are effectively the same as:
% \begin{macroquote}
% \adjustbox{keya=1,keyb=2,keyc=3}{content}
% \end{macroquote}
% \par\medskip\noindent
% The macros:
% \begin{macroquote}
% \adjustboxset{keya=1,keyb=2} \\
% \adjustboxset{keyc=3,keyd=4} \\
% \adjustboxset*{keyg=7,keyh=8}\\
% \adjustboxset*{keyi=9,keyj=10}\\
% \adjustbox{keye=5,keyf=6}{content}
% \end{macroquote}
% are effectively the same as:
% \begin{codequote}
% \AlsoMacro\adjustbox'{keya=1,keyb=2,keyc=3,keyd=4,keye=5,keyf=6,'\\
% !\hskip0pt!' keyi=9,keyj=10,keyg=7,keyh=8}'{content}
% \end{codequote}
% \end{examples}
%
% ^^A )))2
% \clearpage\subsection{Argument Values}\label{sec:argval} ^^A (((2
% All length values given in the arguments of all macros and keys provided by this package are parsed
% by and advanced version of \Macro\setlength\relax (called \Macro\adjsetlength) which uses either $\epsilon$-\TeX\
% expressions (default), the \pkg{calc} package (default fall-back) or the \Macro\pgfmathparse of the \pkg{pgf} package.
% This allows for arithmetic expressions in these arguments. See the package options in \autoref{sec:options} to learn
% how to change the used length parser. Note that early versions of this package used \Macro\pgfmathparse by default.
% Older documents therefore might need now use the \opt{pgfmath} option to compile correctly.
%
% Note that the four values for \Macro\trimbox and \Macro\clipbox as well as for the
% \Key{trim} and \Key{viewport} option of \Macro\adjustbox are separated by spaces. If the expression of any of this
% values holds a space or ends with a macro (eats trailing spaces!) it must be wrapped into braces "{ }".
%
%
% \DescribeMacros
% \hbox{\Macro\width~~~\Macro\height~~~\Macro\depth~~~\Macro\totalheight}%
% \endDescribeMacros
% These \LaTeX{} lengths hold the current dimensions of the content and can be used as part all length arguments. When
% the size of the content is changed by a key these lengths will be adjusted to hold the new size for all further keys.
% The totalheight is the height plus depth. With the \pkg{patch} option these lengths can also be used for
% \Macro\includegraphics.
%
% \DescribeMacros
% \hbox{\Macro\Width~~~\Macro\Height~~~\Macro\Depth~~~\Macro\Totalheight}%
% \endDescribeMacros
% These \LaTeX{} lengths hold the original dimension of original unchanged content and are not modified. They are
% useful if the size of the content is modified by several keys, but further keys should still work relative to the
% original content.
%
%
% \DescribeMacro\smallestside
% This macro expands to either \Macro\width or \Macro\totalheight whatever is smaller.
%
% \DescribeMacro\largestside
% This macro expands to either \Macro\width or \Macro\totalheight whatever is larger.
%
% \DescribeMacro\Smallestside
% This macro expands to either \Macro\Width or \Macro\Totalheight whatever is smaller.
%
% \DescribeMacro\Largestside
% This macro expands to either \Macro\Width or \Macro\Totalheight whatever is larger.
%
%
% \subsubsection*{Default unit}
% If no unit is provided for of the bounding box coordinates (left, bottom, right, top) in the trim and clip features then
% PostScript points (\emph{big points}, bp, $72\,\text{bp}=1\,\text{inch}$) are used, as it is the default behaviour of
% the \Key{trim} and \Key{viewport} options of \pkg{graphicx}'s \Macro\includegraphics. Note that \pkg{graphicx}
% converts all values, independent if a unit is provided or not, internally to bp, because graphics where traditionally
% stored in Encapsulated PostScript (EPS) files. The more modern PDF files also use bp instead of pt. Because the
% \pkg{adjustbox} package macros target \LATeX{} material and users will mostly use pt values this internal conversion
% to bp got disabled for them to avoid unnecessary rounding errors. Since v0.5 the default unit can be changed using the
% |defaultunit|\MacroArgs'='<unit>\relax key (which is also usable as global package option).
%
% ^^A )))2
% ^^A )))
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \clearpage\section{Adjustbox Keys} ^^A (((
% This packages provides the following \Macro\adjustbox keys with matching macros and environments.
%
%
% \subsection{Trimming and Clipping} ^^A (((2
% The following keys allow content to be trimmed (i.e.\ the official size is made smaller, so the remaining material
% laps over the official boundaries) or clipped (overlapping material is not displayed).
% These keys come in different variants, where the lower-case keys represent the behavior of
% the corresponding \Macro\includegraphics keys. The corresponding macros (\Macro\trimbox, \Macro\clipbox, etc.)
% and environments (\env{trimbox}, \env{clipbox}, etc.) are included in the
% accompanying \pkg{trimclip} package and are explained in its manual.
%
% \DescribeKey{trim}'='<all sites>
% \DescribeKey{trim}'='<left/right>~<top/bottom>
% \DescribeKey{trim}'='<left>~<bottom>~<right>~<top>
% This key represents the original \Key{trim} key of \Macro\includegraphics but accepts its value in different forms.
% Unlike most other keys it always acts on the original content independent in which order it is used with other keys.
% If only one value is given it will be used for all four sites.
% If only two values are given, seperated by a space, the first one will be used for the left and right side and the second for the
% bottom and top side.
%
%
% \DescribeKey{viewport}'='<left>~<bottom>~<right>~<top>
% This key represents the original \Key{viewport} key of \Macro\includegraphics.
% It always trims the original content to the given view port independent from its position.
%
% \DescribeKey{clip}
% \DescribeKey{clip}'=true|false'
% This boolean key represents the original \Key{clip} key of \Macro\includegraphics.
% It is intended to be used to make \Key{trim} or \Key{viewport} clip the trimmed material.
% Note that the material will still be part of the output file but is simply not shown.
% It might be exported from the output file using special tools, so using it to censor classified information is a
% bad idea.
%
%
% \DescribeKey{Trim}'='<all sites>
% \DescribeKey{Trim}'='<left/right>~<top/bottom>
% \DescribeKey{Trim}'='<left>~<bottom>~<right>~<top>
% \DescribeKey{Viewport}'='<left>~<bottom>~<right>~<top>
% The normal \Key{trim} and \Key{viewport} keys are applied on the original content before any resizing or (most) other
% keys take effect. This is because for \Macro\includegraphics the trimming is done by the internal graphic driver,
% while the effects can be applied later (but can also be driver dependent).
% If the \Key{trim} and \Key{viewport} keys are used multiple times only the last values will be used for the trimming,
% i.e. the content is only trimmed once. The upper case variants \Key{Trim} and \Key{Viewport} will wrap the content
% internally in a \Macro\trimbox or \Macro\trimbox*\relax macro which can be applied multiple times, e.g.\ before and
% after the content is rotated. These two keys awaits the same format as the original keys. However, the \Key{clip} key
% has no effect on them.
%
%
% \DescribeKey{Clip}'='<all sites>
% \DescribeKey{Clip}'='<left/right>~<top/bottom>
% \DescribeKey{Clip}'='<left>~<bottom>~<right>~<top>
% \DescribeKey{Clip*}'='<left>~<bottom>~<right>~<top>
% The \Key{Clip} key will clip the given amounts from the current content and can be used several times if required.
% The starred version will use the given coordinates as \Key{viewport}.
% These keys work by wrapping the content internally in a \Macro\clipbox or \Macro\clipbox*\relax macro.
%
%
% \DescribeKey{rndcorners}'='<radius for all four corners>
% \DescribeKey{rndcorners}'='<left corners>~<right corners>
% \DescribeKey{rndcorners}'='<upper left>~<upper right>~<lower left>~<lower right>
% This key produces round corners by clipping the content. This is done using the same way as the
% above clipping keys but instead of a rectangle clipping path one with quarter circles is used.
% The radius of the every round corner can be given separately if wanted. If only one value is given
% it is used for all four corners. If only two values are given they will be used for the left and right side, respectively.
% A value of 0pt will produce a normal rectangular corner.
% No radius should be larger than half the smallest side (minimum of \Macro\width and \Macro\totalheight).
%
% Please see also the related keys \Key{rndfbox} and \Key{rndframe}, which allow to add a rounded frame around the content as well.
%
%
% ^^A )))2
% \clearpage\subsection{Margins and Vertical Spacing} ^^A (((2
% \vspace{-\baselineskip}
%
% \DescribeKey{margin}'='<all sites>
% \DescribeKey{margin}'='<left/right>~<top/bottom>
% \DescribeKey{margin}'='<left>~<bottom>~<right>~<top>
% This key can be used to add a margin (white space) around the content. It can be seen as the opposite of \Key{Trim}.
% The original baseline of the content is preserved because \meta{bottom} is added to the depth.
% It is also available under the alternative name \Key{padding}, which can be used to more visually distinguish an inner
% margin from an outer margin e.g.\ if a frame is added.
%
% \begin{example}
% \begin{examplecode}
% Before \adjustbox{padding=1ex 2ex 3ex 4ex,frame,margin=1ex 2ex 3ex 4ex}{Text} After
% \end{examplecode}
% \end{example}
%
% \DescribeKey{margin*}'='<all sites>
% \DescribeKey{margin*}'='<left/right>~<top/bottom>
% \DescribeKey{margin*}'='<left>~<bottom>~<right>~<top>
% This starred version is almost identical to the normal \Key{margin} key, but also raises the content by the \MacroArgs<bottom>
% amount, so that the original depth is preserved instead of the original baseline.
% Note that while \Key{margin} is basically the opposite of \Key{Trim}, \Key{margin*} is not the opposite of \Key{Trim*}.
% Instead it also takes the same values as the unstarred key and not viewport values like \Key{Trim*}.
% An alternative name of \Key{margin*} is \Key{padding*}.
%
% \begin{example}
% \begin{examplecode}
% Before \adjustbox{padding*=1ex 2ex 3ex 4ex,frame,margin*=1ex 2ex 3ex 4ex}{Text} After
% \end{examplecode}
% \end{example}
%
%
% \DescribeKey{vspace}'='<above/below>
% \DescribeKey{vspace}'='<above>~<below>
% The \Key{vspace} key adds a vertical space before and after the content.
% This is done by adding paragraph breaks and \Macro\vspace macros, which will yield better spacing between
% paragraphs then when using the \Key{margin} key.
% However \Key{vspace} forces vertical mode around the content. Adding further keys after \Key{vspace} will force
% restricted horizontal mode again and the vertical space will be ignored. For this situation the \Key{margin} key is
% better suited.
%
% \DescribeKey{vspace*}'='<above/below>
% \DescribeKey{vspace*}'='<above>~<below>
% Identical to \Key{vspace} but uses \Macro\vspace'*' instead.
% The difference is that the vertical space is not ignored at page breaks, but its full amount is always forced.
%
%
% ^^A )))2
% \clearpage\subsection{Minimum and Maximum Size} ^^A (((2
% The following keys allow to set a minimum or maximum size.
% The content will be scaled down or up if required.
%
%
% \DescribeKey{min width}'='<width>
% \DescribeKey{max width}'='<width>
% \DescribeKey{min height}'='<height>
% \DescribeKey{max height}'='<height>
% \DescribeKey{min totalheight}'='<total height>
% \DescribeKey{max totalheight}'='<total height>
% These keys allow to set the minimum and maximum width, height or totalheight of the content.
% The current size of the content is measured and the content is resized if the constraint is not already met,
% otherwise the content is unchanged. Multiple usages of these keys are checked one after each other, and therefore
% it is possible that a later one is undoing the size changes of an earlier one.
% A good example is \Key{max width}'='\AlsoMacro\textwidth which will limit large content to the text width but will not affect smaller
% content.
%
% \DescribeKey{min size}'='{<width>}{<height>}
% \DescribeKey{max size}'='{<width>}{<height>}
% \DescribeKey{min totalsize}'='{<width>}{<total height>}
% \DescribeKey{max totalsize}'='{<width>}{<total height>}
% These keys allow to specify the minimum or maximum width and (total)height of the content together,
% which is more efficient than using the width and (total)height keys described earlier.
%
%
%
% \DescribeMacro\minsizebox{<width>}{<height>}{<content>}
% \DescribeMacro\minsizebox'*'{<width>}{<totalheight>}{<content>}
% This macro is like \Macro\resizebox of the \pkg{graphics/x} package, but only resizes the content if its natural size is smaller
% than the given \meta{width} or \meta{height}.
% If only one value should be set the other one can be replaced by "!".
% If required the content is scaled up so that the width and height is equal or larger than the given values, but does not change
% the aspect ratio.
% The star variant uses the total height instead of only the height.
% This macro is used internally for the \Key{min width}, \Key{min height}, \Key{min totalheight} and \Key{min totalsize} keys.
%
% \begin{examples}
% \begin{examplecode}
% \minsizebox{3cm}{2ex}{Some Text} which will be enlarged
% \end{examplecode}
% \begin{examplecode}
% \minsizebox{!}{4ex}{\fbox{Some Text}} which will be enlarged
% \end{examplecode}
% \begin{examplecode}
% \minsizebox*{!}{4ex}{\fbox{Some Text}} which will be enlarged
% \end{examplecode}
% \begin{examplecode}
% \minsizebox{3cm}{!}{Some Text} which will be enlarged
% \end{examplecode}
% \begin{examplecode}
% \minsizebox{1cm}{1ex}{Some Text}, already large enough
% \end{examplecode}
% \end{examples}
%
%
% \DescribeMacro\maxsizebox{<width>}{<height>}{<content>}
% \DescribeMacro\maxsizebox'*'{<width>}{<totalheight>}{<content>}
% This macro is like \Macro\resizebox of the \pkg{graphics/x} package, but only resizes the content if its natural size is larger
% than the given \meta{width} or \meta{height}.
% If only one value should be set the other one can be replaced by "!".
% If required the content is scaled down so that the width and height is equal or smaller than the given values, but does not change
% the aspect ratio.
% The star variant uses the total height instead of only the height.
% This macro is used internally for the \Key{max width}, \Key{max height}, \Key{max totalheight} and \Key{max totalsize} keys.
%
% \begin{examples}
% \begin{examplecode}
% \maxsizebox{1cm}{1ex}{Some Text} which will be reduced
% \end{examplecode}
% \begin{examplecode}
% \maxsizebox{!}{1ex}{\fbox{Some Text}} which will be reduced
% \end{examplecode}
% \begin{examplecode}
% \maxsizebox*{!}{1ex}{\fbox{Some Text}} which will be reduced
% \end{examplecode}
% \begin{examplecode}
% \maxsizebox{1cm}{!}{Some Text} which will be reduced
% \end{examplecode}
% \begin{examplecode}
% \maxsizebox{3cm}{1cm}{Some Text}, already small enough
% \end{examplecode}
% \end{examples}
%
%
% \DescribeKey{warn width}
% \DescribeKey{warn width}=<max width>
% If this key is used the current width of the content is measured and compared with the given maximum width (default is
% \Macro\linewidth).
% If the content is wider than this value by more than the \TeX\ length \Macro\hfuzz\relax (by default 0.1pt)
% an \emph{Overfull hbox} warning is produced.
% The warning will include the source code position and the information that it was an |adjustbox| not a normal
% paragraph:
% \par\smallskip\par
% {\ttfamily Overfull |\hbox| (X.Ypt too wide) in adjustbox at line N}
%
% {\ttfamily Overfull |\hbox| (X.Ypt too wide) in adjustbox at lines N-M}
% \par\smallskip\par\noindent
% Note that this key is not able to take any horizontal space before the |adjustbox|
% into account. This includes a paragraph indention which might be present with \Macro\adjustbox.
%
% This key is useful to be used before the horizontal alignment keys which change the official width of the content
% and prevent the normal \emph{Overfull} warnings to take affect.
%
%
% ^^A )))2
% \Needspace*{8\baselineskip}
% \clearpage\subsection{Scaling} ^^A (((2
% \vspace{-\baselineskip}
%
% \DescribeKey{scale}'='<factor>
% \DescribeKey{scale}'='{<h-factor>}{<v-factor>}
% The normal \Key{scale} key of \pkg{graphicx} only allows for one scale factor which is used for both the horizontal and vertical scaling.
% With \pkg{adjustbox} it is also possible to provide the horizontal and vertical scale factors separately.
%
% \begin{examples}
% \begin{examplecode}
% \adjustbox{scale=2}{Some text!}
% \end{examplecode}
% \begin{examplecode}
% \adjustbox{scale={2}{1}}{Some text!}
% \end{examplecode}
% \end{examples}
%
%
% \DescribeKey{reflect}
% This key reflects the content by using \Macro\reflectbox internally, which is identical to \Macro\scalebox{-1}[1],
% i.e.\ this key is identical to \Key{scale}'='{-1}{1}.
%
% \begin{examples}
% \begin{examplecode}
% \adjustbox{reflect}{Some text!}
% \end{examplecode}
% \end{examples}
%
%
% \DescribeMacro\scalebox{<h-factor>}[<v-factor>]{<content>}
% \DescribeMacro\reflectbox{<content>}
% These macros is provided by the loaded \pkg{graphicx} package and only mentioned here for the sake of completeness.
% See the |grfguide| for more details.
%
%
% ^^A )))2
% \clearpage\subsection{Frame} ^^A (((2
% The following keys can be used to draw frames around the content.
%
% \DescribeKey{fbox}
% \DescribeKey{fbox}'='<rule width>
% \DescribeKey{fbox}'='<rule width>~<sep>
% \DescribeKey{fbox}'='<rule width>~<sep>~<margin>
% Draws a framed box around the content like \Macro\fbox would do.
% Using the optional space separated values the rule width, the separation (inner padding) and the outer margin can be set.
% If not they default to the values \Macro\fbox uses by default: \Macro\fboxrule, \Macro\fboxsep and zero margin.
%
% \begin{examples}
% \begin{examplecode}
% \adjustbox{fbox}{Like \cs{fbox}}
% \end{examplecode}
% \begin{examplecode}
% \adjustbox{fbox=1pt}{With 1pt rule width}
% \end{examplecode}
% \begin{examplecode}
% \adjustbox{fbox=1pt 2pt}{With 1pt rule width and 2pt separation}
% \end{examplecode}
% \begin{examplecode}
% \adjustbox{fbox={\fboxrule} 1pt}{With normal rule width and 1pt separation}
% \end{examplecode}
% \begin{examplecode}
% \adjustbox{fbox=1pt 1pt 1pt}{With 1pt for rule width, separation and outer margin}
% \end{examplecode}
% \end{examples}
%
%
% \DescribeKey{frame}
% \DescribeKey{frame}'='<rule width>
% \DescribeKey{frame}'='<rule width>~<sep>
% \DescribeKey{frame}'='<rule width>~<sep>~<margin>
% The \Key{frame} key has the same effect as the \Key{fbox} key but is modeled after \LaTeX's \Macro\frame macro (not the version \cls{beamer} defines).
% This means it adds a tight frame with zero separation around the content by default. Besides that it accepts the same space separated values.
% This key is useful to easily add a tight frame around images where the normal separation wouldn't fit.
%
% \begin{examples}
% \begin{examplecode}
% \adjustbox{frame}{Tight box}
% \end{examplecode}
% \end{examples}
%
%
% \DescribeKey{cfbox}'='<color>
% \DescribeKey{cfbox}'='<color>~<rule width>
% \DescribeKey{cfbox}'='<color>~<rule width>~<sep>
% \DescribeKey{cfbox}'='<color>~<rule width>~<sep>~<margin>
% Identical to \Key{fbox} but uses the given color for the frame.
% The \pkg{xcolor} package must be loaded manually in order for this key to work.
% \begin{example}
% \begin{examplecode}
% \adjustbox{cfbox=blue 1pt}{Like a blue \cs{fbox} with \cs{fboxrule}=1pt}
% \end{examplecode}
% \end{example}
%
%
% \DescribeKey{cframe}'='<color>
% \DescribeKey{cframe}'='<color>~<rule width>
% \DescribeKey{cframe}'='<color>~<rule width>~<sep>
% \DescribeKey{cframe}'='<color>~<rule width>~<sep>~<margin>
% Identical to \Key{frame} but uses the given color for the frame.
% The \pkg{xcolor} package must be loaded manually in order for this key to work.
% \begin{example}
% \begin{examplecode}
% \adjustbox{cframe=blue!50!green}
% {Like a blue and green \cs{frame}}
% \end{examplecode}
% \end{example}
%
%
% \DescribeKey{rndframe}'='<radius for all four corners>
% \DescribeKey{rndframe}'='<left corners>~<right corners>
% \DescribeKey{rndframe}'='<upper left>~<upper right>~<lower left>~<lower right>
% \DescribeKey{rndframe}'='{<options>}{<radius for all four corners>}
% \DescribeKey{rndframe}'='{<options>}{<left corners>~<right corners>}
% \DescribeKey{rndframe}'='{<options>}{<upper left>~<upper right>~<lower left>~<lower right>}
%
% \begingroup
% \colorlet{keydesc}{keydesc!50!green}
% \DescribeKey{color}'='{<color>}
% \DescribeKey{color*}'='{<color command>}
% \DescribeKey{width}'='{<rule width>}
% \DescribeKey{sep}'='{<rule separation>}
%
% \DescribeKey{clip}