From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/adjustbox/README | 26 + macros/latex/contrib/adjustbox/adjcalc.dtx | 426 ++ macros/latex/contrib/adjustbox/adjcalc.pdf | Bin 0 -> 152773 bytes macros/latex/contrib/adjustbox/adjustbox.dtx | 6203 ++++++++++++++++++++++++++ macros/latex/contrib/adjustbox/adjustbox.ins | 23 + macros/latex/contrib/adjustbox/adjustbox.pdf | Bin 0 -> 380505 bytes macros/latex/contrib/adjustbox/trimclip.dtx | 2351 ++++++++++ macros/latex/contrib/adjustbox/trimclip.pdf | Bin 0 -> 213356 bytes 8 files changed, 9029 insertions(+) create mode 100644 macros/latex/contrib/adjustbox/README create mode 100644 macros/latex/contrib/adjustbox/adjcalc.dtx create mode 100644 macros/latex/contrib/adjustbox/adjcalc.pdf create mode 100644 macros/latex/contrib/adjustbox/adjustbox.dtx create mode 100644 macros/latex/contrib/adjustbox/adjustbox.ins create mode 100644 macros/latex/contrib/adjustbox/adjustbox.pdf create mode 100644 macros/latex/contrib/adjustbox/trimclip.dtx create mode 100644 macros/latex/contrib/adjustbox/trimclip.pdf (limited to 'macros/latex/contrib/adjustbox') diff --git a/macros/latex/contrib/adjustbox/README b/macros/latex/contrib/adjustbox/README new file mode 100644 index 0000000000..fb560d38ef --- /dev/null +++ b/macros/latex/contrib/adjustbox/README @@ -0,0 +1,26 @@ +LaTeX bundle adjustbox +======================== +Copyright (c) 2011-2019 by Martin Scharrer +WWW: (incl. bug tracker) + +This bundle contains the the adjustbox package and its auxiliary packages trimclip and adjcalc. +The initial purpose of adjustbox was to supplement the standard graphics/x package, +which defines the macros \resizebox, \scalebox and \rotatebox, with the macros \trimbox and \clipbox. +An additional \marginbox macro is also provided. +These macros are now placed in the dedicated package trimclip which is loaded by adjustbox. +The package comes with clipping driver files are provided for pdftex (incl. LuaLaTeX), dvips and xetex. A +fall-back driver which uses the pgf package is still included. +The driver files got written by Joseph Wright (LaTeX3 project) and the package author. + +The main feature of adjustbox is the general \adjustbox macro which extends the key=value +interface of \includegraphics from the graphicx package, and applies it to general text +content. It also provides further text/box modifications keys, macros and envionments. + +Both adjustbox and trimclip use the adjcalc package to allow for algebraic expressions for all length +arguments. The adjcalc package can use either e-TeX, the calc package or the pgfmath package. + +All macros use the authors other package collectbox to read the content as box and not as +macro argument. This allows for all forms of content including special material like verbatim content. +A special feature of collectbox is used to provide matching environments with the identical names as the +macros. + diff --git a/macros/latex/contrib/adjustbox/adjcalc.dtx b/macros/latex/contrib/adjustbox/adjcalc.dtx new file mode 100644 index 0000000000..318bda128f --- /dev/null +++ b/macros/latex/contrib/adjustbox/adjcalc.dtx @@ -0,0 +1,426 @@ +% \iffalse meta-comment +%<=*COPYRIGHT> +%% Copyright (C) 2011-2018 by Martin Scharrer +%% ---------------------------------------------------------------------- +%% 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 adjcalc.dtx, adjustbox.ins +%% and the derived file adjcalc.sty. +%% It is part of the larger adjustbox bundle. +%% +%<=/COPYRIGHT> +% \fi +% +% \iffalse +%<*driver> +\ProvidesFile{adjcalc.dtx}[% +%<=*DATE> + 2012/05/16 +%<=/DATE> +%<=*VERSION> + v1.1 +%<=/VERSION> + DTX file for the adjcalc package] +\documentclass[a4paper]{ydoc}[2011/11/16] +\usepackage{amsmath} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{fourier} +\usepackage{newverbs} +\MakeSpecialShortVerb\qverb\" +%\AtBeginDocument{\MakeShortMacroArgs\`\relax} +%\AtEndDocument{\DeleteShortVerb\`} +\GetFileInfo{adjcalc.dtx} +\usepackage{adjcalc}[\filedate] +\usepackage{tikz} +\normalmarginpar + + +%\EnableCrossrefs +%\CodelineIndex +%\RecordChanges +\OnlyDescription +\begin{document} + \DocInput{\jobname.dtx} + \PrintChanges + %\newpage\PrintIndex +\end{document} +% +% \fi +% +% \CheckSum{274} +% +% \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{v1.0}{2011/11/16}{First version after extraction from \pkg{adjustbox} package.} +% \changes{v1.1}{2012/05/16}{Better separation from the \pkg{adjustbox} package. Added own manual.} +% +% \GetFileInfo{adjcalc.dtx} +% +% \DoNotIndex{\newcommand,\newenvironment,\def,\edef,\xdef,\gdef,\let} +% \bundle{adjustbox} +% \author{Martin Scharrer} +% \email{martin@scharrer-online.de} +% \ydocpdfsettings +% \maketitle +% +% \begin{abstract} +% This package provides macros to assign or to add algebraic expressions to \LaTeX lengths and counters. +% It either uses $\epsilon$-\TeX, the \pkg{calc} package or the \pkg{pgfmath} package internally to achieve this. +% This package is part of the \pkg{adjustbox} bundle and was originally part of the \pkg{adjustbox} package before +% it was extracted to a dedicated package. +% \end{abstract} +% +% \section{Introduction} +% \LaTeX\ lengths and counters can be set using \Macro\setlength and \Macro\setcounter, +% and values can be added to these using \Macro\addtoclength and \Macro\addtocounter, respectively. +% By default these macros await a single length or integer value to be assigned or added. +% However, often it is beneficial to use a short algebraic expression, like a sum of two values, instead. +% The \pkg{calc} package was created for this and redefines the above macros to parse the given expression. +% Another possibility is to use $\epsilon$-\TeX's \Macro\dimexpr or \Macro\glueexpr which also allows for +% several algebraic operations and is more efficient than the higher-level \pkg{calc} package. +% Finally PGF/TikZ provides a large math engine with the \pkg{pgfmath} package. It allows even +% for complicated functions like $\log$ or $\sin$. However, \pkg{pgfmath} is rather large, especially because +% 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. +% +% Package authors which like to write macros which allow algebraic expressions for its length arguments +% now face the dilemma which math interface they should use. Either they exclude users which do not have an +% $\epsilon$-TeX distribution (even if they are very rare) or require to load a large package. +% This was the case with the \pkg{adjustbox} package and therefore own wrapper macros were used instead which +% will use one of the different math engine mentioned above. +% Because this functionality was deemed useful for other packages of the same and other authors it was +% extracted into the dedicated package \pkg{adjcalc}. The idea is that the user can choose the used math engine +% using package options. +% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \section{Package Options}\label{sec:options} ^^A ((( +% The following options define the way length values are processed by the provided macros. +% The first group can be either used as package options and as local setting using \Macro\adjcalcset or as keys +% for \Macro\adjustbox or the \env{adjustbox} environment (but not for \Macro\includegraphics even if the \opt{export} +% option of \pkg{adjustbox} was used). +% The only difference between using them as package options or keys is that as package option they also load required packages. +% Therefore all keys used in the document should be used as package options first or the required packages must be loaded +% manually. +% +% \begin{description}\def\oitem#1{\item[{\normalfont\opt{#1}}]} +% \oitem{etex} Uses the $\epsilon$-\TeX\ primitive \Macro\glueexpr to parse length values. This allows for additions, +% subtractions as well as multiplications and devision by a numeric factor. See the official \pkg{etex\_man} document +% for more details. This setting is the default if $\epsilon$-\TeX\ is detected (which should be the case with all +% modern \LaTeX\ distributions). +% \oitem{calc} Uses the \pkg{calc} package to parse length values. It supports all operations mentioned for \opt{etex} and +% also some other operation like \Macro\widthof{}. +% See the \pkg{calc} package manual for more details. +% This is the default setting if $\epsilon$-TeX is not detected. +% \oitem{pgfmath} Uses the \pkg{pgfmath} package of the \pkg{pgf} bundle to parse length values. It supports all basic +% numeric operations and also advanced mathematical functions. +% See the \pkg{pgf} manual for more details. +% Because the \pkg{pgfmath} package can't be loaded +% independently in the current version (v2.10) the whole \pkg{pgf} package will be loaded. +% \oitem{overwrite} This option will overwrite the standard macros with the macros of this package. +% This e.g.\ sets \Macro\setlength to be identical to \Macro\adjsetlength. +% Any package option used after \opt{overwrite} will still take affect before the redefinition, +% i.e.\ the order in which \opt{overwrite} is used is not meaningful. +% \oitem{defaultunit}\MacroArgs!{\hspace*{-1ex}}!'='\relax +% This sets the default unit used for macros and keys which allow for unit-less values, +% e.g.\ the \Key{trim} key of \Macro\adjustbox or the \Macro\trimbox macro of the \pkg{trimclip} package. +% The standard default unit is the same as for \Macro\includegraphics: "bp" (big points, PostScript points). +% However, for \LaTeX\ material \TeX\ normal unit "pt" (\TeX\ points) are better suited and will avoid rounding +% errors which otherwise get introduced by the internal conversion. +% The default unit is only used if the particular value is only a single number without unit, +% but not if any mathematical operations are used. +% If the special value |none| is used no default unit is applied and the internal check if the value is a single number +% is by-passed. This gives a small speed bonus and can be used to avoid potential issues with complex values. +% At this moment this setting will disable the default unit feature for the rest of the current group (i.e.\ all +% further \Macro\adjustbox keys or globally if used as a package option) and further usages of this option will +% have no affect. This might change in future versions of this package. +% \end{description} +% +% \noindent +% The following option can only be used as package option: +% \begin{description}\def\oitem#1{\item[{\normalfont\opt{#1}}]} +% \oitem{none} Disables the features of this package and makes all macros use the normal \LaTeX\ equivalents, +% e.g.\ \Macro\adjsetlength will expand to \Macro\setlength, etc. +% This option also disables any previous set option as well as any future use of \opt{overwrite}. +% \end{description} +% +% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% \section{Macros} +% +% \DescribeMacro\adjcalcset{} +% This configuration macro allows to change the above mentioned options during the document. +% Any changes are only locally to the current group/environment. +% Please see the descriptions of the options for any limitations. +% +% +% \DescribeMacro\adjsetlength{<\textbackslash lengthmacro>}{} +% \DescribeMacro\adjaddtolength{<\textbackslash lengthmacro>}{} +% \DescribeMacro\adjsetcounter{}{} +% \DescribeMacro\adjaddtocounter{}{} +% These macros can be used to set and add to \LaTeX\ length registers and counters like with the normal +% macros \Macro\setlength, \Macro\addtolength, \Macro\setcounter and \Macro\addtocounter. +% However, these macros allow the use of algebraic expressions, like sums and multiplications, while +% the standard macros only await a single value. +% +% +% \DescribeMacro\adjsetlengthdefault{<\textbackslash lengthmacro>}{} +% This macro set the length macro but does also support length values without an explicit unit. +% If no unit is used the default unit set by the \opt{defaultunit} option is used. The initial default unit +% is `|bp|' (big points, i.e.\ PostScript/PDF points, 72bp=1inch). +% +% +% \StopEventually{} +% \clearpage +% \section{Implementation} +% +% \iffalse +%<*adjcalc.sty> +% \fi +% \begin{macrocode} +% +\ProvidesPackage{adjcalc}[% +% +% +%<*DRIVER> + 2099/01/01 develop +% + Provides advanced setlength with multiple back-ends (calc, etex, pgfmath)] +% \end{macrocode} +% +% +% \begin{macrocode} +\RequirePackage{xkeyval} +% \end{macrocode} +% +% +% Use e-TeX by default if available, otherwise the \pkg{calc} package. +% \begin{macrocode} +\def\adjcalc@atend{% +\begingroup +\expandafter\ifx\csname glueexpr\endcsname\relax + \endgroup + \RequirePackage{calc}% + \adjcalc@calc + \def\adjcalc@etex{\PackageError{adjcalc}{e-TeX not available for current compiler!}}% +\else + \endgroup + \adjcalc@etex +\fi +} +% \end{macrocode} +% +% Initial definitions for the package options. This macros are later redefined because the same keys +% can be used as macro options. +% \begin{macrocode} +\def\adjcalc@pgfmath{\AtEndOfPackage{\RequirePackage{pgf}}\def\adjcalc@atend{\adjcalc@pgfmath}} +\def\adjcalc@etex{\def\adjcalc@atend{\adjcalc@etex}} +\def\adjcalc@calc{\AtEndOfPackage{\RequirePackage{calc}}\def\adjcalc@atend{\adjcalc@calc}} +\def\adjcalc@overwrite{\AtEndOfPackage{\adjcalc@overwrite}} +% \end{macrocode} +% +% The initial default unit is `|bp|' like for \pkg{graphicx}. +% \begin{macrocode} +\def\adjcalc@defaultunit{bp}% +% \end{macrocode} +% +% +% Options: +% \begin{macrocode} +\DeclareOptionX{pgfmath}{\adjcalc@pgfmath} +\DeclareOptionX{etex}{\adjcalc@etex} +\DeclareOptionX{calc}{\adjcalc@calc} +\DeclareOptionX{none}{% + \let\adjcalc@atend\relax + \let\adjcalc@overwrite\relax + \def\adjsetlength{\setlength}% + \def\adjaddtolength{\addtolength}% + \def\adjsetcounter{\setcounter}% + \def\adjaddtocounter{\addtocounter}% +} +\DeclareOptionX{overwrite}{\adjcalc@overwrite} +\DeclareOptionX{defaultunit}[bp]{% + \begingroup + \def\@tempa{#1}% + \def\@tempb{none}% + \ifx\@tempa\@tempb% 'none': + \endgroup + \def\adjsetlengthdefault{\adjsetlength}% + \else + \ifx\@tempb\adjcalc@defaultunit + \endgroup + % was 'none' before + \let\adjsetlengthdefault\adjsetlengthdefault@ + \else + \endgroup + \fi + \fi + \def\adjcalc@defaultunit{#1}% +} +\ProcessOptionsX* +\disable@keys{adjcalc}{none} +% \end{macrocode} +% +% +% \begin{macro}{\adjcalcset} +% User level settings macro. +% \begin{macrocode} +\def\adjcalcset{% + \setkeys{adjcalc}% +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\adjcalc@etex} +% \begin{macrocode} +\def\adjcalc@etex{% + \protected\def\adjsetlength##1##2{% + ##1=\glueexpr(##2)\relax + }% + \protected\def\adjaddtolength##1##2{% + \advance##1 by \glueexpr(##2)\relax + }% + \protected\def\adjsetcounter##1##2{% + \@ifundefined{c@##1}% + {\@nocounterr{##1}}% + {\global\csname c@##1\endcsname\numexpr(##2)\relax}% + }% + \protected\def\adjaddtocounter##1##2{% + \@ifundefined{c@##1}% + {\@nocounterr{##1}}% + {\global\advance\csname c@##1\endcsname\numexpr(##2)\relax}% + }% + \def\adjsetlengthdefault@##1##2{% + \@defaultunits##1=\glueexpr##2 \adjcalc@defaultunit\relax\@nnil + }% + \let\adjsetlengthdefault\adjsetlengthdefault@ +} +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +\newif\if@adjcalc@needsdefault +% \end{macrocode} +% +% +% \begin{macro}{\adjcalc@calc} +% This uses the underlying (re-)definitions of the normal macros (\Macro\setlength, ...) done by the \pkg{calc} package. +% This allows to locally redefine \Macro\setlength to call \Macro\adjsetlength, etc., without causing an infinite loop. +% \begin{macrocode} +\def\adjcalc@calc{% + \DeclareRobustCommand\adjsetlength{\calc@assign@skip}% + \DeclareRobustCommand\adjaddtolength[1]{\calc@assign@skip{\advance ##1}}% + \DeclareRobustCommand\adjsetcounter[2]{\@ifundefined{c@##1}{\@nocounterr{##1}}{\calc@assign@count{\global\csname c@##1\endcsname}{##2}}}% + \DeclareRobustCommand\adjaddtocounter[2]{\@ifundefined{c@##1}{\@nocounterr{##1}}{\calc@assign@count{\global\advance\csname c@##1\endcsname}{##2}}}% + \def\adjsetlengthdefault@##1##2{% + \begingroup + \def\calc@post@scan####1!{% + \def\@tempa{####1}% + \ifx\@tempa\@empty + \endgroup% to end calc processing + % is number only + \global\@adjcalc@needsdefaulttrue + \else + \endgroup% to end calc processing + % full expression + \global\@adjcalc@needsdefaultfalse + \fi + }% + \calc@assign@skip{##1}{##2 \adjcalc@defaultunit}% + \endgroup + \if@adjcalc@needsdefault + ##1=##2 \adjcalc@defaultunit\relax + \else + \calc@assign@skip{##1}{##2}% + \fi + }% + \def\adjcalc@checkdefault##1\@nnil##2##3{% + \ifx\relax##1\relax\else + \calc@assign@skip{##2}{##3}% + \fi + }% + \let\adjsetlengthdefault\adjsetlengthdefault@ +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\adjcalc@pgfmath} +% \begin{macrocode} +\def\adjcalc@pgfmath{% + \DeclareRobustCommand\adjsetlength{\pgfmathsetlength}% + \DeclareRobustCommand\adjaddtolength{\pgfmathaddtolength}% + \DeclareRobustCommand\adjsetcounter{\pgfmathsetcounter}% + \DeclareRobustCommand\adjaddtocounter{\pgfmathaddtocounter}% + \def\adjsetlengthdefault@##1##2{% + \edef\pgfmathresultunitscale{1\adjcalc@defaultunit}% + \let\pgfmathpostparse\pgfmathscaleresult + \pgfmathparse{##2}% + ##1=\pgfmathresult pt\relax + }% + \let\adjsetlengthdefault\adjsetlengthdefault@ +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\adjbox@settobp} +% \begin{macrocode} +\def\adjcalc@settobp#1#2{% + \begingroup + \adjsetlength\@tempdima{#2}% + \@tempdima=0.99626\@tempdima + \edef\@tempa{\endgroup\def\noexpand#1{\strip@pt\@tempdima\space}}% + \@tempa +}% +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\adjcalc@overwrite} +% \begin{macrocode} +\def\adjcalc@overwrite{% + \let\setlength\adjsetlength + \let\addtolength\adjaddtolength + \let\setcounter\adjsetcounter + \let\addtocounter\adjaddtocounter +} +% \end{macrocode} +% \end{macro} +% +% Execute at-end code. +% \begin{macrocode} +\adjcalc@atend +% \end{macrocode} +% \iffalse +% +% \fi +% +% \Finale +% \endinput diff --git a/macros/latex/contrib/adjustbox/adjcalc.pdf b/macros/latex/contrib/adjustbox/adjcalc.pdf new file mode 100644 index 0000000000..f8bb78c491 Binary files /dev/null and b/macros/latex/contrib/adjustbox/adjcalc.pdf differ diff --git a/macros/latex/contrib/adjustbox/adjustbox.dtx b/macros/latex/contrib/adjustbox/adjustbox.dtx new file mode 100644 index 0000000000..ebcfeb7176 --- /dev/null +++ b/macros/latex/contrib/adjustbox/adjustbox.dtx @@ -0,0 +1,6203 @@ +% \iffalse meta-comment +%<=*COPYRIGHT> +%% Copyright (C) 2011-2019 by Martin Scharrer +%% ---------------------------------------------------------------------- +%% 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> + 2019/01/04 +%<=/DATE> +%<=*VERSION> + v1.2 +%<=/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} +% +% \fi +% ^^A ))) +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% ^^A Title page ((( +% \CheckSum{3447} +% +% \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. +% } +% +% \GetFileInfo{adjustbox.dtx} +% +% \DoNotIndex{\newcommand,\newenvironment,\def,\edef,\xdef,\gdef,\let} +% +% \author{Martin Scharrer} +% \email{martin@scharrer-online.de} +% \repository{https://bitbucket.org/martin_scharrer/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[]{} 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~\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{}{} 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}}!'='\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{}{} +% 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[]{adjustbox}{} +% 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{}{} +% 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}{}}. Therefore it can make sense to use +% \Macro\adjustbox{}{\AlsoMacro\includegraphics{}}, 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[]{} +% 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{}\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{}[][]{} +% 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*{}[][]{} +% 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{}[][]{} +% \DescribeMacro\renewadjustboxenv*{}[][]{} +% 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{}[][]{} +% \DescribeMacro\provideadjustboxenv*{}[][]{} +% Like \Macro\newadjustboxenv and \Macro\newadjustboxenv* but will define a macro/environment only if it does not exists +% yet. +% +% +% \DescribeMacro\declareadjustboxenv{}[][]{} +% \DescribeMacro\declareadjustboxenv*{}[][]{} +% Like \Macro\newadjustboxenv and \Macro\newadjustboxenv* but will always define a macro/environment even if it does already exist. +% +% +% \DescribeMacro\newadjustboxcmd{<\textbackslash macro>}[][]{} +% 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>}[][]{} +% Like \Macro\newadjustboxcmd but will redefine an existing macro and cause an +% error if it was not yet defined. +% +% +% \DescribeMacro\provideadjustboxcmd{<\textbackslash macro>}[][]{} +% Like \Macro\newadjustboxcmd but will define the macro only if it does not exist yet. +% +% +% \DescribeMacro\declareadjustboxcmd{<\textbackslash macro>}[][]{} +% Like \Macro\newadjustboxcmd but will define the macro in any case even if it does exist yet.% +% +% +% \DescribeMacro\newadjustimage{<\textbackslash macro>}[][]{} +% \DescribeMacro\renewadjustimage{<\textbackslash macro>}[][]{} +% \DescribeMacro\provideadjustimage{<\textbackslash macro>}[][]{} +% 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>}[][]{} +% Like \Macro\newadjustimage but will not cause an error if the macro is already defined. +% +% +% \DescribeMacro\NewAdjustImage{<\textbackslash macro>}{}{} +% \DescribeMacro\RenewAdjustImage{<\textbackslash macro>}{}{} +% \DescribeMacro\ProvideAdjustImage{<\textbackslash macro>}{}{} +% \DescribeMacro\DeclareAdjustImage{<\textbackslash macro>}{}{} +% 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{} +% \DescribeMacro\adjustboxset*{} +% 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{} and \Macro\adjustboxset*{} clears all set by +% \Macro\adjustboxset*{}. 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'='\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}'=' +% \DescribeKey{trim}'='~ +% \DescribeKey{trim}'='~~~ +% 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}'='~~~ +% 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}'=' +% \DescribeKey{Trim}'='~ +% \DescribeKey{Trim}'='~~~ +% \DescribeKey{Viewport}'='~~~ +% 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}'=' +% \DescribeKey{Clip}'='~ +% \DescribeKey{Clip}'='~~~ +% \DescribeKey{Clip*}'='~~~ +% 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}'=' +% \DescribeKey{rndcorners}'='~ +% \DescribeKey{rndcorners}'='~~~ +% 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}'=' +% \DescribeKey{margin}'='~ +% \DescribeKey{margin}'='~~~ +% 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*}'=' +% \DescribeKey{margin*}'='~ +% \DescribeKey{margin*}'='~~~ +% This starred version is almost identical to the normal \Key{margin} key, but also raises the content by the \MacroArgs +% 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}'=' +% \DescribeKey{vspace}'='~ +% 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*}'=' +% \DescribeKey{vspace*}'='~ +% 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}'=' +% \DescribeKey{max width}'=' +% \DescribeKey{min height}'=' +% \DescribeKey{max height}'=' +% \DescribeKey{min totalheight}'=' +% \DescribeKey{max totalheight}'=' +% 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}'='{}{} +% \DescribeKey{max size}'='{}{} +% \DescribeKey{min totalsize}'='{}{} +% \DescribeKey{max totalsize}'='{}{} +% 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{}{}{} +% \DescribeMacro\minsizebox'*'{}{}{} +% 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{}{}{} +% \DescribeMacro\maxsizebox'*'{}{}{} +% 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}= +% 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}'=' +% \DescribeKey{scale}'='{}{} +% 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{}[]{} +% \DescribeMacro\reflectbox{} +% 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}'=' +% \DescribeKey{fbox}'='~ +% \DescribeKey{fbox}'='~~ +% 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}'=' +% \DescribeKey{frame}'='~ +% \DescribeKey{frame}'='~~ +% 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}'=' +% \DescribeKey{cfbox}'='~ +% \DescribeKey{cfbox}'='~~ +% \DescribeKey{cfbox}'='~~~ +% 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}'=' +% \DescribeKey{cframe}'='~ +% \DescribeKey{cframe}'='~~ +% \DescribeKey{cframe}'='~~~ +% 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}'=' +% \DescribeKey{rndframe}'='~ +% \DescribeKey{rndframe}'='~~~ +% \DescribeKey{rndframe}'='{}{} +% \DescribeKey{rndframe}'='{}{~} +% \DescribeKey{rndframe}'='{}{~~~} +% +% \begingroup +% \colorlet{keydesc}{keydesc!50!green} +% \DescribeKey{color}'='{} +% \DescribeKey{color*}'='{} +% \DescribeKey{width}'='{} +% \DescribeKey{sep}'='{} +% +% \DescribeKey{clip} +% \DescribeKey{clip}'=true|false' +% \endgroup +% +% \begin{example} +% \begin{examplecode} +% \adjustbox{scale=3,bgcolor=gray,rndframe={color=red,width=2\fboxrule,sep=2\fboxsep}{15pt}} +% {\Huge XXXX}% +% \end{examplecode} +% \end{example} +% +% \DescribeKey{rndcornersbox} +% Like \Key{rndframe} (see argument list there) but only clips the corners without drawing a frame. +% +% \DescribeKey{rndfbox} +% Like \Key{rndframe} (see argument list there) but with preset +% \begingroup +% \colorlet{keydesc}{keydesc!50!green} +% \Key{sep}'='0pt. +% \endgroup +% +% \DescribeMacro\rndcornersbox +% \DescribeMacro\rndframebox +% \DescribeMacro\rndfbox +% Standalone macro versions of the corresponding keys. See there for the list of arguments. +% +% ^^A )))2 +% \clearpage\subsection{Vertical Alignment} ^^A (((2 +% The following keys can be used to adjust the vertical alignment and size of the content. +% +% \DescribeKey{valign}'=' +% This key allows to vertically align the content to the top, middle and bottom. The uppercase letters |T|, |M| and |B| +% align to the content top (i.e. all depth, no height), the geometric, vertical center (equal height and depth) and to +% the bottom (all height, no depth), respectively. This allows the alignment of content of different size, but will not +% result in good alignment with text. The lowercase letters |t|, |m| and |b| are aligning the content again to the top, +% center and bottom but take the current text size in account. +% The |t| letter leaves a certain height given by the macro\footnote{A macro and not a length is used to allow for +% font size relative values like \texttt{1ex}.} \Macro\adjboxvtop\relax +% (by default set to the height of \Macro\strut\relax, i.e.\ |\ht\strutbox|, which is |.7\baselineskip|), +% while |b| sets a certain depth given (as negative length) by the macro \Macro\adjboxvbottom\relax +% (by default equal to the (negated) \Macro\strut depth, i.e.\ |-\dp\strutbox|, which is |.3\baselineskip|). +% The |m| letter will center towards the vertical center of the text line which is determined by the macro +% \Macro\adjboxvcenter\relax (by default \texttt{1ex}). +% +% The following table shows the different alignments for three different sized blocks: +% +% \bigskip +% \begingroup +% \def\vr{% +% \unskip +% \tikz [gray] {\useasboundingbox (0,0); +% \draw (-13.5em,0) -- (2.25em,0); +% \draw (-13.5em,\adjboxvcenter) -- (2.25em,\adjboxvcenter); +% }% +% \unskip\ignorespaces +% }% +% \centerline{% +% \begin{tabular}{cccm{2em}} +% \toprule +% \texttt{T} & \texttt{M} & \texttt{B} & Text \\ +% \adjustbox{valign=T}{\textcolor{red}{\rule{1em}{2em}\unskip}}\unskip +% \adjustbox{valign=T}{\textcolor{green}{\rule{1em}{3em}\unskip}}\unskip +% \adjustbox{valign=T}{\textcolor{blue}{\rule{1em}{1ex}\unskip}} & +% \adjustbox{valign=M}{\textcolor{red}{\rule{1em}{2em}\unskip}}\unskip +% \adjustbox{valign=M}{\textcolor{green}{\rule{1em}{3em}\unskip}}\unskip +% \adjustbox{valign=M}{\textcolor{blue}{\rule{1em}{1ex}\unskip}} & +% \adjustbox{valign=B}{\textcolor{red}{\rule{1em}{2em}\unskip}}\unskip +% \adjustbox{valign=B}{\textcolor{green}{\rule{1em}{3em}\unskip}}\unskip +% \adjustbox{valign=B}{\textcolor{blue}{\rule{1em}{1ex}\unskip}} & +% Mxy \newline \mbox{\vr Mxy}\newline Mxy \\ +% \midrule +% \texttt{t} & \texttt{m} & \texttt{b} & Text \\ +% \adjustbox{valign=t}{\textcolor{red}{\rule{1em}{2em}\unskip}}\unskip +% \adjustbox{valign=t}{\textcolor{green}{\rule{1em}{3em}\unskip}}\unskip +% \adjustbox{valign=t}{\textcolor{blue}{\rule{1em}{1ex}\unskip}} & +% \adjustbox{valign=m}{\textcolor{red}{\rule{1em}{2em}\unskip}}\unskip +% \adjustbox{valign=m}{\textcolor{green}{\rule{1em}{3em}\unskip}}\unskip +% \adjustbox{valign=m}{\textcolor{blue}{\rule{1em}{1ex}\unskip}} & +% \adjustbox{valign=b}{\textcolor{red}{\rule{1em}{2em}\unskip}}\unskip +% \adjustbox{valign=b}{\textcolor{green}{\rule{1em}{3em}\unskip}}\unskip +% \adjustbox{valign=b}{\textcolor{blue}{\rule{1em}{1ex}\unskip}} & +% Mxy \newline \mbox{\vr Mxy}\newline Mxy \\ +% \bottomrule +% \end{tabular}} +% \endgroup +% +% +% \DescribeKey{raise}'=' +% \DescribeKey{raise}'='{}{} +% \DescribeKey{raise}'='{}{}{} +% This key uses +% \Macro\raisebox{}{\ldots} to raise the content upwards for the given \meta{amount} (length). +% A negative length moves the content down. +% The two optional arguments of \Macro\raisebox{}[][]{\ldots}\relax are also available +% as optional brace arguments. They can be used to set the official height and depth of the content. +% This is also possible using the \Key{set height} and \Key{set depth} keys. +% +% \begin{examples} +% \begin{examplecode} +% Is \adjustbox{raise=1ex}{higher} +% than the normal text +% \end{examplecode} +% \begin{examplecode} +% Is \adjustbox{raise={1ex}{\height}}{higher} +% than the normal text but sill has +% its original official height +% \end{examplecode} +% \begin{examplecode} +% Is \adjustbox{raise={1ex}{1ex}{0pt}}{higher and +% \rotatebox{-90}{deeper}} but with limited official +% height and no depth. +% \end{examplecode} +% \end{examples} +% +% +% \DescribeKey{set height}'=' +% This sets the official height of the content without actual changing it. This can be seen as a form of trimming. +% It uses the same internal code as\\ +% \Macro\raisebox{'0pt'}[]{}. +% +% \begin{example} +% \begin{examplecode} +% \adjustbox{set height=.5\height} +% {\shortstack{some stacked\\content}} +% \end{examplecode} +% \end{example} +% +% \DescribeKey{set depth}'=' +% This sets the official depth of the content without actual changing it. This can be seen as a form of trimming. +% It uses the same internal code as\\ +% \Macro\raisebox{'0pt'}['\height'][]{}. +% +% \begin{example} +% \begin{examplecode} +% \adjustbox{set depth=0pt} +% {\shortstack{some stacked\\content +% with \raisebox{-1ex}{depth}}} +% \end{examplecode} +% \end{example} +% +% \DescribeKey{set vsize}'='{}{} +% This sets the official height of depth of the content without actual changing it. +% This key is simply the combination of \Key{set height} and \Key{set depth}. +% +% \begin{example} +% \begin{examplecode} +% \adjustbox{set vsize={2pt}{1pt}} +% {\shortstack{some stacked\\content +% with \raisebox{-1ex}{depth}}} +% \end{examplecode} +% \end{example} +% +% +% ^^A )))2 +% \clearpage\subsection{Horizontal Alignment} ^^A (((2 +% The following keys can be used to adjust the horizontal alignment and size of the content. +% +% \DescribeKey{center} +% \DescribeKey{center}'=' +% This key places +% the content in a horizontal box which is by default \Macro\linewidth wide (i.e.\ as wide as a normal text paragraph) +% and centers it in it. The effect is very similar to \Macro\centerline. The original content is unchanged, but simply identical +% white space is added as a left and right margin. This is useful if the content is a figure or table and can be used as a replacement +% for \Macro\centering. One important difference is that the content will then have the given width which might influence (sub-)caption +% placement. +% If the content is wider than the available width it will stick out on both sides equally without causing an overfull hbox warning. +% Note that when \Macro\adjustbox paragraph is used at the beginning of a paragraph the normal paragraph indention is added, which +% will push the while box to the right and might cause an overfull line. In such cases a \Macro\noindent must be added beforehand. +% The \env{adjustbox} environment already uses this macro. +% +% \begin{examples} +% \begin{examplecode} +% \adjustbox{center}{Some content} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{center=5cm}{Some content} +% \end{examplecode} +% \end{examples} +% +% +% \DescribeKey{right} +% \DescribeKey{right}'=' +% Like \Key{center} this key +% places the content in a box with the given width (by default \Macro\linewidth) but right aligns it. +% If the content is wider than the available width it will stick out into the left side without causing an overfull hbox warning. +% +% \begin{examples} +% \begin{examplecode} +% \adjustbox{right}{Some content} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{right=5cm}{Some content} +% \end{examplecode} +% \end{examples} +% +% +% \DescribeKey{left} +% \DescribeKey{left}'=' +% Like \Key{center} this key +% places the content in a box with the given width (by default \Macro\linewidth) but left aligns it. +% If the content is wider than the available width it will stick out into the right side without causing an overfull hbox warning. +% +% \begin{examples} +% \begin{examplecode} +% \adjustbox{left}{Some content} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{left=5cm}{Some content} +% \end{examplecode} +% \end{examples} +% +% +% \DescribeKey{inner} +% \DescribeKey{inner}'=' +% Like \Key{center}, \Key{left} and \Key{right} this key +% places the content in a box with the given width (by default \Macro\linewidth) but aligns it towards the inner margin. +% If the content is wider than the available width it will stick into the outer margin without causing an overfull hbox warning. +% In |twoside| mode this key is equal to \Key{left} for odd pages and equal to \Key{right} for even pages. +% For |oneside| mode it is equal to \Key{left}. +% Note that the page-is-odd test might not always lead to correct results for some material close to a page boundary, because \TeX\ +% might not have decided on which page it will be placed. This can be improved by loading the \pkg{changepage} package with the +% \opt{strict} option, which uses a reference to determine the correct page number (and requires the usual additional compiler run). +% +% +% \DescribeKey{outer} +% \DescribeKey{outer}'=' +% Identical to \Key{inner} but aligns the content towards the outer margin. +% For |oneside| mode it is equal to \Key{right}. +% If the content is wider than the available width it will stick into the outer inner without causing an overfull hbox warning. +% +% +% \DescribeKey{pagecenter} +% \DescribeKey{pagecenter}'=' +% This key centers the content relative to the page and independent from the text area. Afterwards the content has the same distance to the +% left and right page borders. It differs from the \Key{center} key when the left and right page margins are different which is the case in +% |twoside| documents or in environments which change the margins. +% +% Note that the content will look misalign to the text paragraphs before and afterwards and is therefore only +% pleasing for overwide images or similar content. +% +% The optional width defaults to \Macro\linewidth and determines the official width of the content. If a smaller value is selected +% following material will be placed on the same line while maybe overlapping the content. +% Larger values will cause an |Overfull \hbox| warning. +% +% \DescribeKey{pageleftalign} +% \DescribeKey{pageleftalign}'=' +% Similar to \Key{pagecenter}\relax{} (see remarks there) but aligns the content on the left side of the page instead of centering it. +% +% \DescribeKey{pagerightalign} +% \DescribeKey{pagerightalign}'=' +% Similar to \Key{pagecenter}\relax{} (see remarks there) but aligns the content on the left side of the page instead of centering it. +% +% \DescribeKey{pageinner} +% \DescribeKey{pageinner}'=' +% Similar to \Key{pagecenter}\relax{} (see remarks there) but aligns the content on the inner side of the page instead of centering it. +% This assumes that the document is compiled in |twoside| mode. +% In |oneside| mode the macro is identical to \Key{pageleftalign}, i.e. always aligns to the left of the page. +% +% \DescribeKey{pageouter} +% \DescribeKey{pageouter}'=' +% Similar to \Key{pagecenter}\relax{} (see remarks there) but aligns the content on the outer side of the page instead of centering it. +% This assumes that the document is compiled in |twoside| mode. +% In |oneside| mode the macro is identical to \Key{pagerightalign}, i.e. always aligns to the right of the page. +% +% +% \DescribeKey{textareacenter} +% \DescribeKey{textareacenter}'=' +% This key centers the content on the text area (the box with size \Macro\textwidth$\times$\Macro\textheight containing the text on a page) +% even if the box is inside an indending environment like \env{enumerate}. For this it is assumed that the adjusted box is on the start +% of a line or paragraph. If this is not the case the content will be overlapping the material on its left side. +% +% The optional width defaults to \Macro\linewidth and determines the official width of the content. If a smaller value is selected +% following material will be placed on the same line while maybe overlapping the content. +% Larger values will cause an |Overfull \hbox| warning.% +% +% +% \DescribeKey{textareatalign} +% \DescribeKey{textareatalign}'=' +% Similar to \Key{textareacenter}\relax{} (see remarks there) but aligns the content on the left side of the text area instead of centering it. +% +% \DescribeKey{textareatalign} +% \DescribeKey{textareatalign}'=' +% Similar to \Key{textareacenter}\relax{} (see remarks there) but aligns the content on the left side of the text area instead of centering it. +% +% \DescribeKey{textareainner} +% \DescribeKey{textareainner}'=' +% Similar to \Key{textareacenter}\relax{} (see remarks there) but aligns the content on the inner side of the text area instead of centering it. +% This assumes that the document is compiled in |twoside| mode. +% In |oneside| mode the macro is identical to \Key{pageleftalign}, i.e. always aligns to the left of the text area. +% +% \DescribeKey{textareaouter} +% \DescribeKey{textareaouter}'=' +% Similar to \Key{textareacenter}\relax{} (see remarks there) but aligns the content on the outer side of the text area instead of centering it. +% This assumes that the document is compiled in |twoside| mode. +% In |oneside| mode the macro is identical to \Key{pagerightalign}, i.e. always aligns to the right of the text area. +% +% +% +% \DescribeKey{noindent} +% This key will issue an \Macro\noindent for the \Macro\adjustbox to avoid a paragraph indention if it starts a paragraph. +% It does not expect a value and will ignore it if provided. +% +% +% \DescribeMacro\centerbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{centerbox}[] +% Macro and environment version of the \Key{center} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% +% \DescribeMacro\leftalignbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{leftalignbox}[] +% Macro and environment version of the \Key{left} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% +% \DescribeMacro\rightalignbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{rightalignbox}[] +% Macro and environment version of the \Key{rightalign} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% +% \DescribeMacro\innersidebox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{innersidebox}[] +% Macro and environment version of the \Key{inner} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% +% \DescribeMacro\outersidebox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{outersidebox}[] +% Macro and environment version of the \Key{outer} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% +% \DescribeMacro\centerpagebox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{centerpagebox}[] +% Macro and environment version of the \Key{centerpage} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% +% \DescribeMacro\pagecenterbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{pagecenterbox}[] +% Macro and environment version of the \Key{pagecenterbox} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% \DescribeMacro\pageleftalignbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{pageleftalignbox}[] +% Macro and environment version of the \Key{pageleftalignbox} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% \DescribeMacro\pagerightalignbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{pagerightalignbox}[] +% Macro and environment version of the \Key{pagerightalignbox} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% \DescribeMacro\pageinnerbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{pageinnerbox}[] +% Macro and environment version of the \Key{pageinnerbox} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% \DescribeMacro\pageouterbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{pageouterbox}[] +% Macro and environment version of the \Key{pageouterbox} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% \DescribeMacro\textareacenterbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{textareacenterbox}[] +% Macro and environment version of the \Key{textareacenterbox} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% \DescribeMacro\textareatalignbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{textareatalignbox}[] +% Macro and environment version of the \Key{textareatalignbox} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% \DescribeMacro\textareatalignbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{textareatalignbox}[] +% Macro and environment version of the \Key{textareatalignbox} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% \DescribeMacro\textareainnerbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{textareainnerbox}[] +% Macro and environment version of the \Key{textareainnerbox} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% \DescribeMacro\textareaouterbox[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{textareaouterbox}[] +% Macro and environment version of the \Key{textareaouterbox} key. The optional width argument defaults to \Macro\linewidth. +% Both include a \Macro\noindent to avoid paragraph indention. If an paragraph indention is wanted it can be created by +% placing a |\mbox{}| or the identical |\null| macro before it. +% +% \clearpage\subsection*{Lapping} ^^A (((3 +% The following features can be used to make the content lap over its left or right boundary. This is basically the same +% as trimming, but provides a different, more dedicated interface. +% +% +% \DescribeKey{lap}'=' +% \DescribeKey{lap}'='{}{} +% This key will make the content lap over the surrounding elements to the right or left by the given amount.. +% A positive amount will make the content lap over to the right +% and a negative one to the left. The optional \meta{length} argument allows to set the final width. +% If not used the resulting width will be the original width minus the absolute lap amount. +% This key internally uses \Macro\lapbox{}{\ldots} and \Macro\lapbox[]{}{\ldots}, respectively. +% +% \begin{examples} +% \begin{examplecode} +% \adjustbox{lap=.5\width}{Some content} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{lap=-.5\width}{Some content} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{lap=\width}{Some content} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{lap=-\width}{Some content} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{lap={\width}{\width}}{Some content} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{lap={\width}{-\width}}{Some content} +% \end{examplecode} +% \end{examples} +% +% +% \DescribeKey{rlap} +% \DescribeKey{llap} +% This makes the content to be officially 0pt wide and lap over to the right or left, respectively, like the \LaTeX\ macros \Macro\rlap and \Macro\llap do. +% These are shortcuts for \Key{lap}'='\AlsoMacro\width and \Key{lap}'=-'\AlsoMacro\width, respectively. The values for these keys are ignored and should not be used. +% +% \begin{examples} +% \begin{examplecode} +% \adjustbox{rlap}{Some content} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{llap}{Some content} +% \end{examplecode} +% \end{examples} +% +% +% \DescribeMacro\lapbox[]{}{} +% This macro is a generalisation of the \LaTeX\ core macros \Macro\rlap{} and \Macro\llap{} which lap the +% text to the right or left without taking any official space. The \Macro\lapbox macro can be used to only partially lap +% the content to the right (positive amount) or left (negative amount). As with all macros of this package the original width +% can be references using \Macro\width. The resulting official width of the box is normally the original width minus the absolute +% lap amount. However, it can also be set explicitly using the option argument. +% It is also possible to use lap amount which absolute values are larger than the original width. In this case the resulting +% official width will be zero by default and the content will padded with the required white space. +% Note that the lap amount always states the distance between the right side of the official box and the right side of the actual +% content for positive amounts or the distance between the left side of the official box and the left side of the actual content +% for negative values. +% +% \begin{examples} +% General lapping: +% \begin{examplecode} +% \lapbox{1cm}{Some Text} +% \end{examplecode} +% \vspace{-2\smallskipamount}% +% \begin{examplecode} +% \lapbox{-1cm}{Some Text} +% \end{examplecode} +% \vspace{-2\smallskipamount}% +% \begin{examplecode} +% \lapbox[4cm]{1cm}{Some Text} +% \end{examplecode} +% \vspace{-2\smallskipamount}% +% \begin{examplecode} +% \lapbox[3cm]{2cm}{Some Text} +% \end{examplecode} +% \vspace{\smallskipamount}% +% Like \Macro\rlap: +% \vspace{-\smallskipamount}% +% \begin{examplecode} +% \lapbox[0pt]{\width}{Some Text} +% \end{examplecode} +% \vspace{\smallskipamount}% +% Like \Macro\llap: +% \vspace{-\smallskipamount}% +% \begin{examplecode} +% \lapbox[0pt]{-\width}{Some Text} +% \end{examplecode} +% \vspace{\smallskipamount}% +% A centering \Macro\clap macro can be achieved using: +% \vspace{-\smallskipamount}% +% \begin{examplecode} +% \lapbox[0pt]{-.5\width}{Some Text} +% \end{examplecode} +% \vspace{-2\smallskipamount}% +% \begin{examplecode} +% \lapbox[0pt]{.5\width}{Some Text} +% \end{examplecode} +% +% \end{examples} +% +% +% ^^A )))3 +% ^^A )))2 +% \clearpage\subsection{Support for \pkg{graphicx} keys} ^^A (((2 +% +% \DescribeKey{bbllx}'=' +% \DescribeKey{bblly}'=' +% \DescribeKey{bburx}'=' +% \DescribeKey{bbury}'=' +% \DescribeKey{decodearray} +% \DescribeKey{intent} +% \DescribeKey{interpolate} +% \DescribeKey{maskarray} +% \DescribeKey{natheight}'=' +% \DescribeKey{natwidth}'=' +% \DescribeKey{ocobjnum} +% \DescribeKey{ocobjref} +% \DescribeKey{page}'=' +% \DescribeKey{pagebox} +% \DescribeKey{print} +% \DescribeKey{quiet} +% \DescribeKey{resetcolor} +% \DescribeKey{resolution} +% \DescribeKey{xmpfile} +% The above \pkg{graphicx} keys are also supported by \cs{adjustbox}. This is done by relying on the original +% \pkg{graphicx} code, i.e. the key code is copied into the \pkg{adjustbox} namespace. These keys are therefore +% mostly for use with images and might not work well with other content. +% For more details on these keys see the \pkg{graphicx} manual. +% +% ^^A )))2 +% \clearpage\subsection{Colors} ^^A (((2 +% \vspace{-\baselineskip} +% +% \DescribeKey{color}'=' +% \DescribeKey{color}'='{}{} +% This key sets the color for all material. Both the content and further material added by other keys will be affected. +% The color change is immediate and will occur before basically every other key takes effect. +% The order in which this key is used is therefore meaningless. +% Using this key several times will cause several color changes with the last one be used for the remaining material. +% Note that \Key{color} will not influence any \Key{fgcolor} or \Key{bgcolor} beside the fact that it changes the +% \emph{current color} accessible using the special name `|.|'. +% +% \DescribeKey{color*}'=' +% Like \Key{color} but awaits a full color macro as value. This allows to use other macros as \Macro\color like \Macro\blendcolors. +% See the \pkg{xcolor} manual for more details. A \Macro\blendcolors will affect both \Key{fgcolor} and \Key{bgcolor}. +% +% +% \DescribeKey{fgcolor}'=' +% \DescribeKey{fgcolor}'='{}{} +% This key sets the color for the content. +% The value is passed to an internal \Macro\color macro. +% This is done using \Key{innercode} because the color must be set before the content is boxed. +% Further material added using keys, e.g.\ a \Key{frame}, is not affected by this key. +% The \pkg{xcolor} package (or \pkg{color} or \pkg{xxcolor}) needs to be loaded otherwise an error will be raised. +% +% \DescribeKey{fgcolor*}'=' +% Like \Key{fgcolor} but awaits a full color macro as value. This allows to use other macros as \Macro\color like \Macro\blendcolors. +% See the \pkg{xcolor} manual for more details. +% +% +% \DescribeKey{bgcolor}'=' +% \DescribeKey{bgcolor}'='{}{} +% This key adds a colored background to the content. The \pkg{xcolor} package (or \pkg{color} or \pkg{xxcolor}) needs to be loaded +% as well in order for this to work. The value is passed to an internal \Macro\color macro. +% \begin{examples} +% \begin{examplecode} +% \adjustbox{bgcolor=blue}{Text with blue background.} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{bgcolor={rgb}{0 0 1}}{Text with blue background in the RGB color model.} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{margin=1ex,bgcolor=green}{green with a little more margin} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{margin=1ex,bgcolor=green,margin=1pt,bgcolor=yellow}{Emulation of colored frame} +% \end{examplecode} +% \end{examples} +% +% \DescribeKey{bgcolor*}'=' +% Like \Key{bgcolor} but awaits a full color macro as value. This allows to use other macros as \Macro\color like \Macro\blendcolors. +% See the \pkg{xcolor} manual for more details. +% +% \begin{examples} +% \begin{examplecode} +% \color{blue}Blue text +% \adjustbox{bgcolor*=\blendcolors{!10!yellow}\color{.}}{with a yellow-bluish background} +% \end{examplecode} +% \begin{examplecode} +% \color{green}Green text +% \adjustbox{bgcolor*=\blendcolors{!10!yellow}\color{.}}{with a yellow-greenish background} +% \end{examplecode} +% \end{examples} +% +% \DescribeMacro{\bgcolorbox}[]{} +% \DescribeMacro{\bgcolorbox}*{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{bgcolorbox}[]{} +% \vspace{-1.5\baselineskip}\nopagebreak +% \DescribeEnv[]{bgcolorbox*}{} +% Standalone macro and environment versions of the \Key{bgcolorbox} and \Key{bgcolorbox*} keys. +% +% +% +% ^^A )))2 +% \clearpage\subsection{Background and Forground Images and Text} ^^A (((2 +% The following keys, macros and environment allow to add background and foreground layers. +% These layers are placed on the baseline of the original content and are horizontally centered, but can be adjusted +% using own \Macro\adjustbox or \Macro\includegraphics keys. +% The following dimension registers can be used to refer to the dimensions of the original content. +% +% \DescribeMacros +% \hbox{\Macro\pwidth~~~\Macro\pheight~~~\Macro\pdepth~~~\Macro\ptotalheight}% +% \endDescribeMacros +% These dimension registers hold the width, height, depth and total height (height+depth) of the parent box and can be used +% to resize a background or foreground layer accordantly. They are only defined inside the key=value arguments of the +% following keys, macros and environments. +% +% \DescribeKey{bgimage}'=' +% \DescribeKey{bgimage}'='{}{} +% Adds a background image to the content. The image is stretched if required to fit exactly to the content. +% It is also possible to provide \Macro\adjustbox or \Macro\includegraphics keys to modify the image (before the resizing is done). +% \begin{examples} +% \begin{examplecode} +% \adjustbox{bgimage=example-grid-100x100bp}{Some text} +% \end{examplecode} +% \end{examples} +% +% \DescribeKey{bgimage*}'=' +% \DescribeKey{bgimage*}'='{}{} +% Adds a background image to the content like \Key{bgimage} but the image is not stretched to fit the content. +% Instead it is added in its natural size but can be adjusted using \Macro\adjustbox or \Macro\includegraphics keys. +% The image is placed on the baseline of the content and horizontally centered. It can be lowered to the lower edge of +% the content using \Key{raise}'=-'\AlsoMacro\pdepth and left aligned using \Key{left}'='\AlsoMacro\pwidth etc. +% +% \DescribeMacro{\bgimagebox}[]{} +% \DescribeMacro{\bgimagebox}*[]{} +% \DescribeEnv[]{bgimagebox}[]{} +% \DescribeEnv[]{bgimagebox*}[]{} +% Standalone macro and environment versions of the \Key{bgimage} and \Key{bgimage*} keys. +% +% +% \DescribeKey{fgimage}'=' +% \DescribeKey{fgimage}'='{}{} +% Adds a foreground image to the content. The image is stretched to fit exactly to the content. +% It is also possible to provide \Macro\adjustbox or \Macro\includegraphics keys to modify the image (before the resizing is done). +% The image is assumed to have transparent elements, otherwise the existing content is fully covered. +% +% \DescribeKey{fgimage*}'=' +% \DescribeKey{fgimage*}'='{}{} +% Adds a foreground image to the content like \Key{fgimage} but the image is not stretched to fit the content. +% Instead it is added in its natural size but can be adjusted using \Macro\adjustbox or \Macro\includegraphics keys. +% The image is placed on the baseline of the content and horizontally centered. +% +% \DescribeMacro{\fgimagebox}[]{} +% \DescribeMacro{\fgimagebox}*[]{} +% \DescribeEnv[]{fgimagebox}[]{} +% \DescribeEnv[]{fgimagebox*}[]{} +% Standalone macro and environment versions of the \Key{fgimage} and \Key{fgimage*} keys. +% +% +% +% \DescribeKey{background}'=' +% \DescribeKey{background}'='{}{} +% Adds the given content as background layer to the main content. The background content is stretched to fit the size of +% the main content. It is also possible to provide \Macro\adjustbox or \Macro\includegraphics keys to modify the +% background content (before the resizing is done). +% \begin{examples} +% \begin{examplecode} +% \adjustbox{background={\color{red}xxx}}{Some text} +% \end{examplecode} +% \end{examples} +% +% \DescribeKey{background*}'=' +% \DescribeKey{background*}'='{}{} +% Like \Key{background} but does not resizes the background content. +% Instead it is added in its natural size but can be adjusted using \Macro\adjustbox or \Macro\includegraphics keys. +% +% \DescribeMacro{\backgroundbox}[]{} +% \DescribeMacro{\backgroundbox}*[]{} +% \DescribeEnv[]{backgroundbox}[]{} +% \DescribeEnv[]{backgroundbox*}[]{} +% Standalone macro and environment versions of the \Key{background} and \Key{background*} keys. +% +% +% \DescribeKey{foreground}'=' +% \DescribeKey{foreground}'='{}{} +% Adds the given content as foreground layer to the main content. The foreground content is stretched to fit the size of +% the main content. It is also possible to provide \Macro\adjustbox or \Macro\includegraphics keys to modify the +% foreground content (before the resizing is done). +% \begin{examples} +% \begin{examplecode} +% \adjustbox{foreground={\color{red}xxx}}{Some text} +% \end{examplecode} +% \end{examples} +% +% \DescribeKey{foreground*}'=' +% \DescribeKey{foreground*}'='{}{} +% Like \Key{foreground} but does not resizes the foreground content. +% Instead it is added in its natural size but can be adjusted using \Macro\adjustbox or \Macro\includegraphics keys. +% +% \DescribeMacro{\foregroundbox}[]{} +% \DescribeMacro{\foregroundbox}*[]{} +% \DescribeEnv[]{foregroundbox}[]{} +% \DescribeEnv[]{foregroundbox*}[]{} +% Standalone macro and environment versions of the \Key{foreground} and \Key{foreground*} keys. +% +% +% +% ^^A )))2 +% \clearpage\subsection{Density / Pixel size} ^^A (((2 +% The following keys allow to adjust the effective length of |pdftex| special |px| (pixel) unit. +% This can be required for images which do not have the correct DPI meta-data included. +% +% +% \DescribeKey{dpi}'=' +% The \Key{dpi} key provides a simple interface to set the pixel size to the given DPI (dots per inch) value. +% For |pdflatex| the length unit |px| can be used to specify pixels. However, the equivalent dimension (length) of one pixel must be +% set using the \Macro\pdfpxdimen length register. To set a specific DPI value this length must be set using +% \Macro\setlength\AlsoMacro\pdfpxdimen{'1in/'}, which is done by the \Key{dpi}'=' key. +% Note that the key won't affect the setting for the content but only for the further used keys. +% However, it is possible to use \Macro\setkeys{adjbox}{'dpi='} inside the content or anywhere else in the document to +% set \Macro\pdfpxdimen using this interface. +% +% \begin{example} +% \begin{examplecode} +% \adjustbox{dpi=72,trim=10px,frame}{% +% \setkeys{adjbox}{dpi=72}% +% \textcolor{green}{\rule{50px}{50px}}% +% } +% \end{examplecode} +% \end{example} +% +% \DescribeKey{pxdim}'=' +% Alternatively +% to the \Key{dpi} key the \Macro\pdfpxdimen length can be set directly to the given value. Afterwards |1px| will stand +% for the given \meta{length}. +% +% \begin{example} +% \begin{examplecode} +% \adjustbox{pxdim=2pt,trim=2px,frame} +% {\textcolor{green}{\rule{20pt}{20pt}}} +% \end{examplecode} +% \end{example} +% +% +% ^^A )))2 +% \clearpage\subsection{Minipage or other inner environments which change the processing of the content}\label{sec:inner} ^^A (((2 +% The following keys set the way the content is processed before it is stored it in a box. +% These keys will overwrite each other and only the latest used key will take effect. +% Because they affect the inner content directly their order relative to other, normal keys is not meaningful. +% Also they are only defined for \env{adjustbox} but do not apply for \Macro\includegraphics. +% Because they are therefore only used inside a mandatory argument and never in an optional these keys allow for optional bracket arguments. +% +% \DescribeKey{minipage}'=' +% \DescribeKey{minipage}'='[][][]{} +% This key wraps the inner content in a \env{minipage} with the given \meta{width} before it is stored as horizontal box. +% Its order relative to other keys is not meaningful (except that future keys of this sub-section will overwrite it). +% This allows for line breaks and footnotes in the \env{adjustbox}. +% All optional arguments of \env{minipage} are supported. I only the width is given it does not have to be enclosed in braces. +% The \meta{position} argument must be "t" for top baseline, "b" for bottom baseline and "c" for center alignment relative to other +% text, i.e.\ defines the resulting baseline. If a \meta{height} is defined the \meta{inner position} defaults to \meta{position} but +% can also be "s" to stretch the content over the whole height. This requires the content to include some vertical stretchable material. +% Note that all length arguments can include arithmetic expressions like for other keys. +% +% \begin{examples} +% \begin{examplecode} +% \adjustbox{minipage=5cm,angle=-10}{% +% Some example code which will +% be automatically broken or can include \\ +% line breaks\footnote{AND footnotes!!}\\ +% or verbatim \verb+@%^&}_+!% +% } +% \end{examplecode} +% \begin{examplecode} +% Before \begin{adjustbox}{minipage=[b][3cm][s]{5cm}} +% Some example code +% +% \vfill +% with line breaks\footnote{AND footnotes!!} +% +% \vfill +% or verbatim \verb+@%^&}_+!% +% \end{adjustbox} After +% \end{examplecode} +% \end{examples} +% +% +% \DescribeKey{varwidth}'=' +% Adds a \env{varwidth} environment from the \pkg{varwidth} package around the content. This is similar to the +% \env{minipage} environment but the final width of the content will be as large as the widest line in the content up to +% the maximum amount given by the width argument. +% This environment key is vert useful if the content produces some paragraph material which can't be stored in an +% horizontal box directly. +% +% +% \DescribeKey{tabular}'='[]{} +% \DescribeKey{tabular*}'='[]{}{} +% \DescribeKey{array}'='[]{} +% Places the content in a \env{tabular}, \env{tabular*} or \env{array} environment, respectively. +% These keys require different implementations for macro (\Macro\adjustbox) and environment mode (\env{adjustbox} environment) in order to insert +% the end code correctly. Note that the environment mode is more efficient and fully stable, while the macro mode requires the last row to end with +% an explicit |\\| (which can be followed by \Macro\hline or any other macro which uses \Macro\noalign internally). In macro mode the |\\| is internally redefined +% to check for the closing brace. While this was successful tested for normal usages it might still cause issues with unusual or complicated cases. +% Note that these environments are taken as part of the content and so the usage of arithmetic expressions for length arguments is not supported. +% +% \begin{examples} +% \begin{examplecode} +% \adjustbox{tabular=lll}{% +% \hline +% A & B & C \\\hline +% a & b & c \\\hline +% } +% \end{examplecode} +% \begin{examplecode} +% \begin{adjustbox}{tabular=lll} +% A & B & C \\ +% a & b & c +% \end{adjustbox} +% \end{examplecode} +% \end{examples} +% +% +% \DescribeKey{stack} +% \DescribeKey{stack}'=' +% \DescribeKey{stack}'='{}{} +% \Descsep +% \DescribeMacro\stackbox!\optionaloff![][]{} +% \Descsep +% \DescribeEnv[]{stackbox}[][] +% The \Key{stack} key and its corresponding macro and environment can be used to stack multiple lines similar to the \Macro\shortstack macro, but +% both the horizontal and vertical alignment can be selected by a single letter each. Also a proper baseline skip is inserted. +% This is implemented using the \env{varwidth} environment which is based on the \env{minipage} environment. +% Its maximal width arguments is fixed internally to \Macro\linewidth. +% +% Possible horizontal alignments are: "l" (left), "r" (right), "c" (centered, default), "j" (justified). +% Possible vertical alignments are the same as for \env{minipage}: "t" (top baseline), "b" (bottom baseline, default), "c" (vertical centered). +% Because these arguments are always single letters the "{ }" around them can be skipped, so that the value can simple be two concatenated letters. +% +% \begin{example} +% \begin{examplecode} +% .\adjustbox{stack}{A\\B\\CC}. +% \end{examplecode} +% \begin{examplecode} +% .\adjustbox{stack=r}{A\\B\\CC}. +% \end{examplecode} +% \begin{examplecode} +% .\adjustbox{stack=ct}{A\\B\\CC}. +% \end{examplecode} +% \end{example} +% +% +% \DescribeKey{innerenv}'=' +% \DescribeKey{innerenv}'='{} +% Wraps the inner content in the given \meta{environment} before it is stored as horizontal box. +% It should be kept in mind that there is some internal code between the begin of the environment and the content. For this reason +% a \env{tabular}, \env{array} or similar environment will not work here, because that code will be taken as part of the first cell. +% Note that such a environment is taken as part of the content and so the usage of arithmetic expressions for length arguments is not supported. +% +% \begin{example} +% \begin{examplecode} +% \newenvironment{myenv}[2][]{Before [#1](#2)}{After} +% \adjustbox{innerenv={myenv}[ex]{amble}}{Content} +% \end{examplecode} +% \newenvironment{myenv}[2][]{Before [#1](#2)}{After} +% \begin{examplecode} +% \adjustbox{innerenv={myenv}{amble}}{Content} +% \end{examplecode} +% \end{example} +% +% +% \DescribeKey{innercode}'='{}{} +% Places the given code before and after the inner content before it is stored as horizontal box. +% Note that such code is taken as part of the content and so the usage of arithmetic expressions for length arguments is not supported. +% +% \begin{example} +% \begin{examplecode} +% \adjustbox{innercode={\color{green}}{!}}{Content} +% \end{examplecode} +% \end{example} +% +% ^^A )))2 +% \clearpage\subsection{Floats and non-float replacements} ^^A (((2 +% The following keys can be used to turn an adjusted box into a float or a non-floating replacement which also allows +% for a caption. These keys must be used last and no other normal keys must be used afterwards, otherwise an error will +% occur because the added floating environment is boxed again. +% +% +% \DescribeKey{caption}= +% \DescribeKey{caption}=[]{} +% Defines a caption which will be used by a following \Key{figure}, \Key{float} or \Key{nofloat} key. +% The position of the caption defaults to top for a |table| (non-)float and bottom for every other type. +% +% \DescribeKey{captionabove}= +% \DescribeKey{captionabove}=[]{} +% Like the \Key{caption} key but forces the placement of the caption above the content. +% The vertical skip above and below a normal below caption are reversed in this case to get proper +% spacing. However, this is not done if the \pkg{caption} package is loaded. +% It is recommended to load this package with the |tableposition=above| option. +% +% +% \DescribeKey{captionbelow}= +% \DescribeKey{captionbelow}=[]{} +% Like the \Key{caption} key but forces the placement of the caption below the content. +% +% +% \DescribeKey{label}=