diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/adjustbox/adjustbox.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/adjustbox/adjustbox.dtx | 1907 |
1 files changed, 1189 insertions, 718 deletions
diff --git a/Master/texmf-dist/source/latex/adjustbox/adjustbox.dtx b/Master/texmf-dist/source/latex/adjustbox/adjustbox.dtx index 798254d9739..0f200d23afd 100644 --- a/Master/texmf-dist/source/latex/adjustbox/adjustbox.dtx +++ b/Master/texmf-dist/source/latex/adjustbox/adjustbox.dtx @@ -1,7 +1,7 @@ % \iffalse meta-comment %<=*COPYRIGHT> -%% Copyright (C) 2011 by Martin Scharrer <martin@scharrer-online.de> -%% --------------------------------------------------------------------------- +%% Copyright (C) 2011 by Martin Scharrer <martin@scharrer.me> +%% ------------------------------------------------------------------ %% 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. @@ -24,25 +24,13 @@ %<*driver> \ProvidesFile{adjustbox.dtx}[% %<=*DATE> - 2011/10/30 + 2011/11/14 %<=/DATE> %<=*VERSION> - v0.7 + v0.8 %<=/VERSION> DTX file for the adjustbox package] -\expandafter\ifx\csname ifenglish\endcsname\relax - \expandafter\newif\csname ifenglish\endcsname - \englishtrue -\fi -\ifenglish - \RequirePackage[english]{babel} -\else - \RequirePackage[ngerman]{babel} -\fi - -%\PassOptionsToPackage{ngerman}{hyperref} -%\RequirePackage[ngerman]{babel} -\documentclass{ydoc}[2011/08/11] +\documentclass[a4paper]{ydoc}[2011/08/11] \usepackage{amsmath} \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} @@ -66,18 +54,6 @@ }{% \par } - -\newcommand\babelfiledate{% - \expandafter\babelfileDate\filedate\relax -} -\def\babelfileDate#1/#2/#3\relax{% - \begingroup - \year#1 - \month#2 - \day#3 - \today - \endgroup -} \optionaloff \lstdefinelanguage{none}{}% @@ -100,7 +76,7 @@ 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, width, totalheight, center, left, right, outer, inner, min, max, + pxdim, execute, raise, valign, bgcolor, set, height, depth, vsize, width, totalheight, center, left, right, outer, inner, min, max, size, totalsize, minipage, innerenv, innercode, env, Addcode, addcode, precode, Precode, appcode, angle, scale, height, width, totalheight, resolution, }, @@ -145,13 +121,14 @@ {\dimexpr\ht\exampleresultbox+\fboxrule\relax}% {\dimexpr\dp\exampleresultbox+\fboxrule\relax}% \hskip-\wd\exampleresultbox - \hskip-2\fboxrule + \hskip-\fboxrule }% \usebox\exampleresultbox }% }% \makeatother \colorlet{exampleborder}{black!33} +\def\Descsep{\par\vskip-2.5ex\relax} %\EnableCrossrefs %\CodelineIndex @@ -166,7 +143,7 @@ %</driver> % \fi % -% \CheckSum{2207} +% \CheckSum{0} % % \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 @@ -194,14 +171,30 @@ % \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. +% } % % \GetFileInfo{adjustbox.dtx} % % \DoNotIndex{\newcommand,\newenvironment,\def,\edef,\xdef,\gdef,\let} % -% \ifenglish\else -% \title{Das \pkgtitle{adjustbox} Paket} -% \fi % \author{Martin Scharrer} % \email{martin@scharrer-online.de} % \ydocpdfsettings @@ -212,29 +205,19 @@ % \fontsize \sf@size \z@ \math@fontsfalse \selectfont A}\vss }}\kern -.15em)\TeX}{(La)TeX}} % \makeatother % -% \ifenglish % \begin{abstract} -% This package provides macros missing in \pkg{graphics} to trim, clip and generally adjust boxed \LaTeX{} material -% as well as further box modification macros and option keys usable for \Macro\adjustbox and \Macro\includegraphics. +% This package got inspired by the \pkg{graphics/x} package and extends it sets of macros and generalises its key=value syntax for graphics to arbitray \TeX\ material. +% Its main feature is the \Macro\adjustbox macro and the corresponding \env{adjustbox} environment which allow to adjust arbitrary \TeX\ material +% in a multitude of ways, similar like \Macro\includegraphics does it for image files. In addition to this a wide set of dedicated macros are provided to modify a box. +% This startet with the two macros \Macro\trimbox and \Macro\clipbox which are missing in \pkg{graphics} but was extended over time. +% % The macros use the \pkg{collectbox} package to allow for verbatim content. Equivalent environments are also provided. % The trim operation is now implemented in \TeX\ and the clip operation uses |pdftex| primitives if available. % Otherwise the \pkg{pgf} package is used for clipping, which supports both DVI/PS and PDF output. % \\ % \textcolor{yellow}{This package is still a little new and its implementation might not be fully stable yet.} % \end{abstract} -% \else -% \begin{abstract} -% Dieses Paket stellt einige Makros zur Verf^^c3^^bcgung die im \pkg{graphics} Paket vermisst werden -% und \LaTeX{} Material zu beschneiden (\emph{trim}, \emph{clip}) oder allgemein zu modifizieren. -% Die Makros erlauben Inhalt das im \emph{verbatim} Modus gesetzt ist. -% Ebenfalls werden passende Umgebungen f^^c3^^bcr die Makros bereitgestellt. -% Das Beschneiden wird durch eine \env{pgfpicture} Umgebung des Pakets \pkg{pgf} verwirklicht, -% dass sowohl das PS und PDF Ausgabeformat unterst^^c3^^bctzt.\\ -% \textcolor{red}{Dieses Paket ist noch neu und seine Implementieren kann sich in zuk^^c3^^bcnftigen Versionen noch ^^c3^^a4ndern!} -% \end{abstract} -% \fi % -% \ifenglish % \section{Introduction} % The standard \LaTeX{} package \pkg{graphicx} (the extended version of \pkg{graphics}) provides the macro \Macro\includegraphics[<options>]{<file name>} which can % be used to include graphic files. Several options can be used to scale, resize, rotate, trim and/or clip the graphic. @@ -243,25 +226,23 @@ % 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 provides the missing macros \Macro\clipbox and \Macro\trimbox -% as well as the general \Macro\adjustbox macro. The trim operation is implemented as \TeX\ code -% and the clip operation either using a |pdftex| or a \env{pgfpicture} environment from the \pkg{pgf} package -% which supports both PS and PDF output. All \LaTeX\ compilers should be supported, but |pdflatex| is the main target of the -% author. -% \else -% \section{Einleitung} -% Das \LaTeX{} Paket \pkg{graphicx} (die erweiterte Version von \pkg{graphics}) stellt das Macro \Macro\includegraphics[<Optionen>]{<Dateiname>} zur Verf^^c3^^bcgung -% mit dem Bilddateien eingebunden werden k^^c3^^b6nnen. Zahlreiche Optionen k^^c3^^b6nnen benutzt werden um das Bild zu skalieren, an eine vorgegebene Gr^^c3^^b6^^c3^^9fe anzupassen, es zu rotieren -% oder den Rand zu beschneiden. -% Ebenfalls stellt das Paket die Makros \Macro\scalebox\relax (skalieren), \Macro\resizebox\relax (Gr^^c3^^b6^^c3^^9fe ^^c3^^a4ndern) und \Macro\rotatebox\relax (rotieren) zur Verf^^c3^^bcgung um \LATeX{} Material, -% z.B.\ normalen Text, entsprechend anzupassen. Dies wird dazu in eine horizontale Box (\Macro\hbox) gesetzt. -% Allerdings fehlen Makros um \LATeX{} Material zu beschneiden, wobei der abgeschnittenen Rand entweder sichtbar bleibt (engl.: \emph{trim}) oder ausgeblendet wird (engl. \emph{clip}). -% Dies ist wahrscheinlich der Fall, weil diese Operationen nicht von \TeX{} selbst vorgenommen werden, sondern von dem verwendeten Ausgabeformat, z.B.\ durch PostScript (PS) -% oder PDF Operationen. -% -% Das \textsf{adjustbox} Paket definiert die Makros \Macro\clipbox und \Macro\trimbox, sowie das allgemeine \Macro\adjustbox Macro (engl.: \emph{adjust} = anpassen). -% Das Beschneiden wird durch eine \env{pgfpicture} Umgebung des Pakets \pkg{pgf} verwirklicht, dass sowohl das PS und PDF Ausgabeformat unterst^^c3^^bctzt. -% \fi +% 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. +% +% \subsection{Driver dependent implementation} +% Certain operations, like clipping, depend on the output driver used, because they must be implemented as part of the output format, e.g. PDF instructions for a PDF output file. +% The trim operation is now implemented as driver independent \TeX\ code. +% The clip operation now uses |pdftex| primitives if possible, which are taken from the |pdftex| driver file of \pkg{graphics}. +% For other output formats a \env{pgfpicture} environment from the \pkg{pgf} package is used, +% which supports both PS and PDF output and comes which is own clipping drivers. +% All \LaTeX\ compilers should be supported, but |pdflatex| is the main target of the author. +% +% \subsection{Dependencies} +% The \pkg{adjustbox} package requires the author's other package \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/\env{stackbox}. +% 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. % % \section{Package Option}\label{sec:options} % Following v0.5 from 2011/08/13 this package accepts the following package options. Some of them can also be used as @@ -272,9 +253,6 @@ % with previous versions before v0.5. % \oitem{export} Export the now keys of \Macro\adjustbox also to \Macro\includegraphics so that they can be used for % images as well. This option is meaningless if \opt{minimal} was used. -% \oitem{patch} Patch the internal \pkg{graphicx} code to allow the usage of size macros. -% This simply loads the small \pkg{adjgrfx} package which can also be used independently. -% (Not fully implemented and tested yet!) % \oitem{pgf} Uses the \pkg{pgf} package for all clip operations. This overrides all automatically detected drivers. % At the moment only a |pdftex| driver is provided, all other compilers and output formats use this option already. % \oitem{PGF} Uses the \pkg{pgf} package for clip operations and configures the macros to parse lengths using @@ -323,184 +301,42 @@ % have no affect. This might change in future versions of this package. % \end{description} % -% \ifenglish -% \def\llx{llx} -% \def\lly{lly} -% \def\urx{urx} -% \def\ury{ury} -% \def\TEXT{content} -% \def\height{height} -% \def\width{width} -% \def\totalheight{totalheight} -% \def\depth{depth} -% \def\factor{factor} -% \def\xfactor{x-factor} -% \def\yfactor{y-factor} -% \def\Angle{angle} -% \def\options{options} -% \else -% \def\llx{lux} -% \def\lly{luy} -% \def\urx{orx} -% \def\ury{ory} -% \def\TEXT{Inhalt} -% \def\height{H^^c3^^b6he} -% \def\width{Weite} -% \def\totalheight{Totale H^^c3^^b6he} -% \def\depth{Tiefe} -% \def\factor{Faktor} -% \def\xfactor{X-Faktor} -% \def\yfactor{Y-Faktor} -% \def\Angle{Winkel} -% \def\options{Optionen} -% \fi +% \subsection{Verbatim Support}\label{sec:verbatim} +% The macros read the content as a horizontal \TeX{} box and not as an macro argument in order to support verbatim content. +% This functionality is now provided as dedicated package \pkg{collectbox} which can also be used independently. +% This means that the braces around the content can also be written as \Macro\bgroup and \Macro\egroup: +% \begin{macroquote} +% \trimbox{1 2 3 4}\AlsoMacro\bgroup~<content>\AlsoMacro\egroup +% \end{macroquote} +% Special care is taken to allow the \meta{text} to be a single macro (except \Macro\bgroup) without any braces: +% \begin{macroquote} +% \clipbox{1 2 3 4}\AlsoMacro\somemacro +% \end{macroquote} +% This is to support the questionable habit of some \LaTeX{} users to drop the braces for single token arguments. +% All environments support verbatim content. % -% \ifenglish % \section{Usage} -% This section describes the usage of the provided macros, which are outlined in \autoref{sec:basicmacros}. -% Possible advanced values for the macro arguments are mentioned in \autoref{sec:argval}. The existing verbatim support -% is explained in \autoref{sec:verbatim}. Finally \autoref{sec:alternatives} compares the existing macros with the -% corresponding options of \Macro\adjustbox. -% Further box modification macros and keys are described in \autoref{sec:moremacros} and \autoref{sec:newkeys}, respectively. -% -% It is recommended to also read the \emph{Graphics Guide} (\pkg{grfguide}, i.e.~the manual of the \pkg{graphics}/|x| packages), -% to understand the existing options for \Macro\includegraphics. -% \else -% \newpage -% \section{Anleitung} -% Dieser Abschnitt beschreibt die Verwendung der Makros dieses Pakets. Diese werden zuerst im \autoref{sec:basicmacros} beschrieben. -% \autoref{sec:argval} erkl^^c3^^a4rt welche Werte in den Makroargumenten verwendet werden k^^c3^^b6nnen. Die Makros unterst^^c3^^bctzen sogenannten -% \emph{verbatim} (engl.: wortgetreu) Inhalt was im \autoref{sec:verbatim} erleutert wird. -% Schlussendlich wird im \autoref{sec:alternatives} die exisitierenden Makros mit den entsprechendem Optionen von \Macro\adjustbox -% verglichen. Beispiele f^^c3^^bcr die beschriebenen Makros befinden sich im folgendem \autoref{sec:example}. -% -% Dem Leser wird dar^^c3^^bcberhinaus die Lekt^^c3^^bcre der Anleitung der \pkg{graphic}/|x| Pakete, der \emph{Graphics Guide}, empfohlen wo -% die m^^c3^^b6glichen Optionen f^^c3^^bcr das Makro \Macro\includegraphics gelistet sind, die auch f^^c3^^bcr \Macro\adjustbox verwendet werden. -% \fi -% -% \ifenglish -% \Needspace*{7\baselineskip} -% \subsection{Basic Box Modification Macros}\label{sec:basicmacros} -% This section lists the provided macros \Macro\clipbox and \Macro\trimbox missing in the \pkg{graphicx} package -% as well as the general \Macro\adjustbox macro. If the package is loaded with the \opt{minimal} option no further macros or keys are defined. -% \else -% \subsection{Makros zur Modifikation von {\LaTeX} Material}\label{sec:basicmacros} -% \fi +% This sections explains the existing features of this package. +% Most features are available as matching macro, environment and key. % -% \ifenglish -% \subsubsection*{Trim Box Content} -% \else -% \subsubsection*{Rand beschneiden ohne ^^c3^^9cberhang auszublenden} -% \fi -% \vskip-\lastskip -% \DescribeMacro\trimbox{<all sites>}{<\TEXT>} -% \DescribeMacro\trimbox{<left/right>~<top/bottom>}{<\TEXT>} -% \DescribeMacro\trimbox{<\llx>~<\lly>~<\urx>~<\ury>}{<\TEXT>} -% \DescribeMacro\trimbox*{<\llx>~<\lly>~<\urx>~<\ury>}{<\TEXT>} -% \ifenglish -% The macro \Macro\trimbox trims the given amount from the lower left (ll) and the upper right (ur) corner of -% the box. This means that the amount \meta{llx} is trimmed from the left side, \meta{lly} from the bottom and -% \meta{urx} and \meta{ury} from the right and top of the box, respectively. -% If only one value is given it will be used for all four sites. -% If only two values are given the first one will be used for the left and right side (llx, urx) and the second for the bottom and top side (lly, ury). -% Trimming means that the official size of the box is reduced, but no material -% is actual removed. The material in the trimmed areas simply swaps over the official border. -% -% If the starred version is used the four coordinates are taken as the \Key{viewport} instead, i.e. the box -% is trimmed to the rectangle described by the coordinates. In this case using all four values must be specified. -% \else -% Das Makro \Macro\trimbox setzt den \meta{Text} in eine \TeX{} Box und reduziert dessen offizielle Gr^^c3^^b6^^c3^^9fe -% (\emph{bounding box}, engl.: begrenzende Box), so dass \TeX{} annimmt es w^^c3^^a4re entsprechend kleiner. ^^c3^^9cberstehendes Material -% ragt deswegen in den umgebenden Text hinein. -% Die angegebenen Werte im ersten Argument stehen f^^c3^^bcr die Betr^^c3^^a4ge die von der unteren linken (lu) und der oberen rechten (or) -% Ecke entfernt werden. Das heisst, dass der Wert \meta{lux} vom linken Rand, \meta{lly} vom unterem Rand und \meta{orx} und \meta{ory} -% von rechten bzw. oberen Rand abgezogen werden. -% Wird das Makro allerdings in der Sternvariante aufgerufen, stehen die vier Werte f^^c3^^bcr den Darstellungsbereich (\emph{viewport}) und -% alles ausserhalb wird von der offiziellen Gr^^c3^^b6^^c3^^9fe abgeschnitten. -% \fi -% -% -% \DescribeEnv[<\TEXT>]{trimbox}{<1, 2 or 4 trim values>} -% \vspace{-\baselineskip} -% \DescribeEnv[<\TEXT>]{trimbox*}{<\llx>~<\lly>~<\urx>~<\ury>} -% \ifenglish -% The \env{trimbox} and \env{trimbox*} environments do the same as the corresponding macros. % Special care is taken so that the macros and the environments can have the same name. -% Because of this the star can be either part of the name or an optional argument. -% Also the plain\TeX{} syntax for environments (|\trimbox ... \endtrimbox|) can not be used -% because it will trigger \Macro\trimbox as a macro. -% \else -% Die Umgebungen \env{trimbox} und \env{trimbox*} erzeugen den selben Effekt wie die gleichnamigen Makros. -% Ein spezieller Trick wird verwendet, damit der selbe Name f^^c3^^bcr ein Makro und f^^c3^^bcr eine Umgebung verwendet werden kann, -% was normallerweise nicht der Fall ist. Aufgrund dessen akzeptier die \env{trimbox} Umgebung auch einen optionallen Stern. -% Die plain\TeX{} Schreibweise f^^c3^^bcr Umgebungen (|\trimbox ... \endtrimbox|) kann allerdings nicht verwendet werden, -% da es \Macro\trimbox als Makro aufrufen w^^c3^^bcrde. -% \fi -% -% -% \ifenglish -% \subsubsection*{Clip Box Content} -% \else -% \subsubsection*{Rand beschneiden und ^^c3^^9cberhang ausblenden} -% \fi -% \vskip-\lastskip -% \DescribeMacro\clipbox{<all sites>}{<\TEXT>} -% \DescribeMacro\clipbox{<left/right>~<top/bottom>}{<\TEXT>} -% \DescribeMacro\clipbox{<\llx>~<\lly>~<\urx>~<\ury>}{<\TEXT>} -% \DescribeMacro\clipbox*{<\llx>~<\lly>~<\urx>~<\ury>}{<\TEXT>} -% \ifenglish -% The \Macro\clipbox macro works like the \Macro\trimbox and trims the given amounts from the \meta{text}. -% However, in addition the trimmed material is also clipped, i.e. it is not shown in the final document. -% Note that the material will still be part of the output file but is simply not shown. -% It might be exported using special tools, so using \Macro\clipbox\relax (or \Macro\includegraphics[clip,trim=...]) -% to censor classified information would be a bad idea. -% The starred version will again use the given coordinates as \Key{viewport}. -% \else -% Das \Macro\clipbox Makro arbeiten ^^c3^^a4hnlich wie \Macro\trimbox nur, dass der entfernte Rand auch wirklich -% ausgeblendet wird. Allerdings bleibt dieses Material Teil der Ausgabedatei und k^^c3^^b6nnte durch spezielle Software exportiert werden. -% Von der Verwendung von \Macro\clipbox\relax (oder \Macro\includegraphics'[clip,trim=...]') um vertrauliche Informationen zu zensieren -% kann deswegen nur abgeraten werden. -% Die Sternvariante verwendet die angegebenen Werte als den zu darstellenden Bereich wie bei \Macro\trimbox'*'. -% \fi -% -% \DescribeEnv[<\TEXT>]{clipbox}{<1, 2 or 4 trim values>} -% \vspace{-\baselineskip} -% \DescribeEnv[<\TEXT>]{clipbox*}{<\llx>~<\lly>~<\urx>~<\ury>} -% \iffalse -% The environment versions of \Macro\clipbox and \Macro\clipbox*. The same rules as for the trimming environments apply. -% \else -% Die obigen Makros als Umgebungen. Es gelten die gleichen Regeln wie bei den \env{trimbox} Umgebungen. -% \fi -% +% For starred environments the star can be either part of the name or an optional argument. +% Also the plain\TeX{} syntax for environments (|\foobar ... \endfoobar|) can not be used +% because it will trigger \Macro\foobar as a macro. % -% \ifenglish -% \subsubsection*{Adjust Box Content} -% \else -% \subsubsection*{Allgemeine Manipulationen von \LaTeX{} Material} -% \fi +% \subsection{Adjust Box Content} % \vskip-\lastskip -% \DescribeMacro\adjustbox{<key/value pairs>}{<\TEXT>} -% \ifenglish +% \DescribeMacro\adjustbox{<key/value pairs>}{<content>} % The \Macro\adjustbox macro is the general form of all box modifying macros mentioned in the introduction. % It can be thought as an extended \Macro\includegraphics for \LATeX{} material. % It supports the same \meta{key/value pairs} and many more. However, they are provided as a mandatory not as an optional argument. % An \Macro\adjustbox without options would not make sense and can be replaced by a simple \Macro\mbox. -% There is no starred version of this macro. See also \autoref{tab:alternatives} for a comparison of \Macro\adjustbox -% with the other macros. -% \else -% Mit Hilfe des \Macro\adjustbox Makros (engl.\ \emph{adjust} = anpassen, justieren) ist es m^^c3^^b6glich die selben Optionen -% die \Macro\inludegraphics f^^c3^^bcr Bilder zur Verf^^c3^^bcgung stellt auch auf beliebiges \LATeX{} Material anzuwenden. -% Die \meta{Optionen} sind dabei allerdings nicht optional, da \Macro\adjustbox ohne jegliche Optionen einem \Macro\mbox -% gleich k^^c3^^a4me. Eine Sternvariante existiert f^^c3^^bcr dieses Makro nicht. -% Es kann dazu verwendet werden Kombinationen von anderen ^^c3^^a4hnlichen Makros zu ersetzen, was in \autoref{tab:alternatives} dargestellt wird. -% \fi +% There is no starred version of this macro. +% ^^ASee also \autoref{tab:alternatives} for a comparison of \Macro\adjustbox +% ^^Awith the other macros. % -% \DescribeEnv[<\TEXT>]{adjustbox}{<includegraphics \options>} -% \ifenglish +% \DescribeEnv[<content>]{adjustbox}{<key=value, \ldots>} % The environment version of \Macro\adjustbox. -% \else -% Wie f^^c3^^bcr die anderen Makros gibt es auch f^^c3^^bcr \Macro\adjustbox eine passende Umgebung. -% \fi % % \subsubsection*{Adjust Images} % \DescribeMacro\adjustimage{<key/value pairs>}{<image filename>} @@ -509,48 +345,62 @@ % set by \Macro\adjustboxset. Most keys can be exported to \Macro\includegraphics using the \opt{export} option, but there is no support % for global keys\footnote{However some keys, but not all, can be set globally using \Macro\setkeys{Gin}{<includegraphic key/value pairs>}}. % Therefore it can make sense to use \Macro\adjustbox{<key/value pairs>}{\AlsoMacro\includegraphics{<filename>}}. -% The \Macro\adjustimage macro is a wrapper for exactly this. This does not require the \opt{export} option and therefore helps to avoid option clashes +% The \Macro\adjustimage macro is a wrapper for this. However, it does not use \Macro\includegraphics directly, but an internal macro, to allow the redefinition +% of it. +% This does not require the \opt{export} option and therefore helps to avoid option clashes % if \pkg{adjustbox} is loaded at several places. % -% \clearpage -% \ifenglish -% \section*{Examples} -% The following examples show the application of the aforementioned macros on an example text. -% The result is placed in a tight, colored frame box to show the resulting dimensions. -% \else -% \section*{Beispiele} -% Die folgenden Beispiele zeigen die Anwendung der Makros dieses Packets auf einen Beispieltext (\Macro\example). -% Das Ergebnis wird mit einer engen, farbigen Umrandung dargestellt um die entg^^c3^^bcltigen Dimensionen sichtbar zu machen. -% \fi -% \begingroup -% \def\examplecontent{\begin{tabular}{@{}|c|c|@{}} -% \hline -% A & B \\ -% \hline -% C & D \\ -% \hline -% \end{tabular}^^A -% } -% \fboxsep=0pt% -% \def\Fbox{\fcolorbox{red}{white}}% -% \def\X{\vspace*{20pt}}% -% \par\bigskip\noindent -% \begin{tabular}{@{}lc} -% \X\Macro\example & \Fbox{\examplecontent} \\ -% \X\Macro\trimbox{10 5 10 5}{\AlsoMacro\example} & \Fbox{\trimbox{10 5 10 5}{\examplecontent}} \\ -% \X\Macro\clipbox{10 5 10 5}{\AlsoMacro\example} & \Fbox{\clipbox{10 5 10 5}{\examplecontent}} \\ -% \X\Macro\trimbox*{15 5 25 30}{\AlsoMacro\example} & \Fbox{\trimbox*{15 5 25 30}{\examplecontent}} \\ -% \X\Macro\clipbox*{15 5 25 30}{\AlsoMacro\example} & \Fbox{\clipbox*{15 5 25 30}{\examplecontent}} \\ -% \X\Macro\adjustbox{trim=10 5 10 5,angle=45}{\AlsoMacro\example} & \Fbox{\adjustbox{trim=10 5 10 5,angle=45}{\examplecontent}} \\ -% \X\Macro\adjustbox{scale=1.5}{\AlsoMacro\example} & \Fbox{\adjustbox{scale=1.5}{\examplecontent}} \\ -% \X\Macro\adjustbox{width=180pt,height=20pt}{\AlsoMacro\example} & \Fbox{\adjustbox{width=40pt,height=10pt}{\examplecontent}} \\ -% \X\Macro\adjustbox{width=180pt,height=20pt,keepaspectratio}{\AlsoMacro\example} & \Fbox{\adjustbox{width=40pt,height=10pt,keepaspectratio}{\examplecontent}} \\ -% \end{tabular} -% \endgroup % -% \clearpage -% \ifenglish -% \subsection{Argument Values}\label{sec:argval} +% \DescribeMacro\adjincludegraphics[<key/value pairs>]{<image filename>} +% Like \Macro\adjustimage but in the same format as \Macro\includegraphics. +% This macro allows to use all features of \Macro\adjustbox on images, however any `|[ ]|' inside the optional argument must be wrapped in `|{ }|' to mask them. +% It is possible to redefine \Macro\includegraphics to use/be \Macro\adjincludegraphics and this is done by +% the \opt{Export} option (not to be confused with the \opt{export} option). +% +% \subsubsection{Setting keys globally} +% +% \DescribeMacro\adjustboxset{<global keys to be executed \emph{before} local keys>} +% \DescribeMacro\adjustboxset*{<global keys to be executed \emph{after} local keys>} +% Using these two macros all keys can be set globally, i.e.\ for all future \Macro\adjustbox macros and \env{adjustbox} environments. +% Note that these settings are actually \emph{local} to the current \TeX\ group and only really global if used in the preamble or outside any group. +% The normal macro will place all given keys before the keys used in first argument of \Macro\adjustbox\ / \env{adjustbox}, +% while the starred version will place them afterwards. +% +% If these macros are used several times there keys are accumulated. This happens in the given order for the normal version and in reversed order for the starred version, +% i.e.\ the keys of further \Macro\adjustboxset or \Macro\adjustboxset* are always added so they face inwards. +% If used without any keys but an empty argument, all keys previously set with the same macro are removed (from the current \TeX\ scope). +% This means \Macro\adjustboxset{} clears all keys set be previously usages of \Macro\adjustboxset{<keys>} and \Macro\adjustboxset*{} clears all set by \Macro\adjustboxset*{<keys>}. +% Such resets are again local to the current \TeX\ group. +% +% +% \begin{examples} +% The macros: +% \begin{macroquote} +% \adjustboxset{keya=1} \\ +% \adjustboxset*{keyc=3}\\ +% \adjustbox{keyb=2}{content} +% \end{macroquote} +% are effectively the same as: +% \begin{macroquote} +% \adjustbox{keya=1,keyb=2,keyc=3}{content} +% \end{macroquote} +% \par\medskip\noindent +% The macros: +% \begin{macroquote} +% \adjustboxset{keya=1,keyb=2} \\ +% \adjustboxset{keyc=3,keyd=4} \\ +% \adjustboxset*{keyg=7,keyh=8}\\ +% \adjustboxset*{keyi=9,keyj=10}\\ +% \adjustbox{keye=5,keyf=6}{content} +% \end{macroquote} +% are effectively the same as: +% \begin{codequote} +% \AlsoMacro\adjustbox'{keya=1,keyb=2,keyc=3,keyd=4,keye=5,keyf=6,'\\ +% !\hskip0pt!' keyi=9,keyj=10,keyg=7,keyh=8}'{content} +% \end{codequote} +% \end{examples} +% +% \subsubsection{Argument Values}\label{sec:argval} % All\marginpar{Parsing} length values given in the arguments of all macros and keys provided by this package are parsed by and advanced version of % \Macro\setlength (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. @@ -559,30 +409,23 @@ % % Note\marginpar{Space=Separator} 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 "{ }". -% \else -% \newpage -% \subsection{Erlaubte Werte f^^c3^^bcr Makroargumente}\label{sec:argval} -% Die numerischen Werte f^^c3^^bcr die Makros werden durch das vielseitige \Macro\pgfmathparse Makro des sowieso schon verwendeten \pkg{pgf} Paketes -% eingelesen. Dies erlaubt die Verwendung von einfachen oder komplizierten Formeln. -% Eine genaue Beschreibung der unterst^^c3^^bctzten mathematischen Operationen befindet sich im Handbuch des \pkg{pgf} Paketes. -% Dabei muss beachtet werden das die vier Werte f^^c3^^bcr die \Macro\trimbox und \Macro\clipbox Makros sowie f^^c3^^bcr die \Key{trim} und \Key{viewport} Optionen von \Macro\adjustbox -% durch Leerzeichen getrennt werden m^^c3^^bcssen. Komplizierte Angaben die ein Leerzeichen enthalten oder auf ein Makro enden (entfernt nachfolgende Leerzeichen) m^^c3^^bcssen -% deswegen in geschweifte Klammern "{ }" gesetzt werden. -% \fi % % % \DescribeMacros % \hbox{\Macro\width~~~\Macro\height~~~\Macro\depth~~~\Macro\totalheight}% % \endDescribeMacros -% \ifenglish -% These \LaTeX{} lengths hold the original dimension of \meta{text} and can be used as part of the arguments to \Macro\adjustbox, \Macro\trimbox and \Macro\clipbox. +% 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. -% \else -% Diese \LaTeX{} L^^c3^^a4ngen enthalten die Weite, H^^c3^^b6he, Tiefe bzw.\ die totale H^^c3^^b6he (H^^c3^^b6he + Tiefe) des \meta{\TEXT} Arguments bzw.\ des Inhalts der Umgebung. -% Diese L^^c3^^a4ngen k^^c3^^b6nnen in den ersten Argument von \Macro\adjustbox, \Macro\trimbox und \Macro\clipbox verwendet werden um relative ^^c3^^84nderungen vorzunehmen. -% \fi % -% If\marginpar{Default unit} no unit is provided for of the bounding box coordinates (\llx, \lly, \urx, \ury) then PostScript points +% \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. +% +% \subsubsection*{Default unit} +% If no unit is provided for of the bounding box coordinates (llx, lly, urx, ury) 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. @@ -591,89 +434,101 @@ % key (which is also usable as global package option). % % -% \subsection{Verbatim Support}\label{sec:verbatim} -% The macros read the \meta{text} as \TeX{} \Macro\hbox and not as an macro argument in order to support verbatim content. -% This functionality is now provided as dedicated package \pkg{collectbox} which can also be used independently. -% This means that the braces around the content can also be written as \Macro\bgroup and \Macro\egroup: -% \begin{macroquote} -% \trimbox{1 2 3 4}\AlsoMacro\bgroup~<\TEXT>\AlsoMacro\egroup -% \end{macroquote} -% Special care is taken to allow the \meta{text} to be a single macro (except \Macro\bgroup) without any braces: -% \begin{macroquote} -% \clipbox{1 2 3 4}\AlsoMacro\somemacro -% \end{macroquote} -% This is to support the questionable habit of some \LaTeX{} users to drop the braces for single token arguments. -% All environments support verbatim content. % -% \clearpage -% \ifenglish -% \subsection{Alternatives for existing Macros}\label{sec:alternatives} -% The flexible \Macro\adjustbox can also be used as an alternative to existing macros from the \pkg{graphics} package as shown by Table~\ref{tab:alternatives}. -% Because it is longer then the originals this is only of benefit if combinations are to be replaced or verbatim text must be supported. -% \else -% \subsection{Alternativen f^^c3^^bcr existierende Makros}\label{sec:alternatives} -% Das flexible \Macro\adjustbox Makro kann auch als Alternative f^^c3^^bcr die vorhandenen Makros des \pkg{graphics} Paketes verwenden werden. -% Dies ist in Tabelle~\ref{tab:alternatives} dargestellt. -% Die dies allerdings mehr Schreibarbeit darstellt ist es nur dann von Vorteil, falls mehrere Operationen verkn^^c3^^bcpft werden sollen -% oder wenn der entsprechende Text im \emph{verbatim} Modus eingelesen werden soll. -% \fi % -% \ifenglish -% \begin{table}[!hb] -% \else -% \begin{table}[!hb] -% \fi -% \belowcaptionskip\abovecaptionskip -% \colorlet{optional}{black} -% \ifenglish -% \caption{Alternatives for existing Macros} -% \else -% \caption{Alternativen f^^c3^^bcr existierende Makros} -% \fi -% \label{tab:alternatives} -% \hbox to \linewidth{\hss -% \begin{tabular}{ll} -% \toprule -% \ifenglish -% Original Macro (w/o content argument) & Alternative \Macro\adjustbox keys \\ -% \else -% Originales Makro (ohne Textargument) & Alternative \Macro\adjustbox Schl^^c3^^bcssel \\ -% \fi -% \midrule -% \Macro\rotatebox{<\Angle>} & \MacroArgs'angle='<\Angle> \\ -% & \MacroArgs'rotate='<\Angle> \\ -% \Macro\scalebox{<\factor>} & \MacroArgs'scale='<\factor> \\ -% \Macro\scalebox{<\xfactor>}[<\yfactor>] & \MacroArgs'width='<\xfactor>\AlsoMacro\width',height='<\yfactor>\AlsoMacro\height \\ -% \Macro\reflectbox & \MacroArgs'reflect' \\ -% & \MacroArgs'width=-'\AlsoMacro\width',height='\AlsoMacro\height \\ -% \Macro\resizebox{<\width>}{<\height>} & \MacroArgs'width='<\width>',height='<\height> \\ -% \Macro\resizebox*{<\width>}{<\totalheight>} & \MacroArgs'width='<\width>',totalheight='<\totalheight> \\ -% \Macro\trimbox{<\llx>~<\lly>~<\urx>~<\ury>} & \MacroArgs'trim='<\llx>~<\lly>~<\urx>~<\ury> \\ -% & \MacroArgs'Trim='<\llx>~<\lly>~<\urx>~<\ury> \\ -% \Macro\trimbox*{<\llx>~<\lly>~<\urx>~<\ury>} & \MacroArgs'viewport='<\llx>~<\lly>~<\urx>~<\ury> \\ -% & \MacroArgs'Viewport='<\llx>~<\lly>~<\urx>~<\ury> \\ -% \Macro\clipbox{<\llx>~<\lly>~<\urx>~<\ury>} & \MacroArgs'trim='<\llx>~<\lly>~<\urx>~<\ury>,clip \\ -% & \MacroArgs'Clip='<\llx>~<\lly>~<\urx>~<\ury> \\ -% \Macro\clipbox*{<\llx>~<\lly>~<\urx>~<\ury>} & \MacroArgs'viewport='<\llx>~<\lly>~<\urx>~<\ury>,clip \\ -% & \MacroArgs'Clip*='<\llx>~<\lly>~<\urx>~<\ury> \\ -% \bottomrule -% \end{tabular}% -% \hss}% -% \end{table} -% -% -% -% \subsection{Further Box Modification Macros}\label{sec:moremacros} -% This section lists further macros which are also defined unless the package is loaded with the \opt{minimal} option. -% Note that the authors other package \pkg{realboxes} provides variants of existing box macros -% defined by the \LaTeX\ core or common packages like \pkg{graphicx}. Like the box macros here this variants allow for verbatim content -% because they read it as real box and not as macro arguments. -% -% \DescribeMacro\marginbox{<all sites>}{<\TEXT>} -% \DescribeMacro\marginbox{<left/right>~<top/bottom>}{<\TEXT>} -% \DescribeMacro\marginbox{<\llx>~<\lly>~<\urx>~<\ury>}{<\TEXT>} -% This macro can be used to add a margin (white space) around the content. It can be seen as the opposite of \Macro\trim. -% The original baseline of the content is preserved because \meta{\lly} is added to the depth. +% \subsection{Trimming and Clipping} +% Material can be trimmed (the official size is made smaller, so the remaining material +% laps over the official boundaries) and clipped (overlapping material is not displayed). +% The original keys provided by \pkg{graphicx} are also mentioned here for comparison. +% +% +% \DescribeMacro\trimbox{<llx>~<lly>~<urx>~<ury>}{<content>} +% \DescribeMacro\trimbox{<all sites>}{<content>} +% \DescribeMacro\trimbox{<left/right>~<top/bottom>}{<content>} +% \DescribeMacro\trimbox*{<llx>~<lly>~<urx>~<ury>}{<content>} +% The macro \Macro\trimbox trims the given amount from the lower left (ll) and the upper right (ur) corner of +% the box. This means that the amount \meta{llx} is trimmed from the left side, \meta{lly} from the bottom and +% \meta{urx} and \meta{ury} from the right and top of the box, respectively. +% If only one value is given it will be used for all four sites. +% If only two values are given the first one will be used for the left and right side (llx, urx) and the second for the bottom and top side (lly, ury). +% +% If the starred version is used the four coordinates are taken as the \Key{viewport} instead, i.e. the box +% is trimmed to the rectangle described by the coordinates. In this case using all four values must be specified. +% +% +% \DescribeEnv[<content>]{trimbox}{<1, 2 or 4 trim values>} +% \vspace{-\baselineskip} +% \DescribeEnv[<content>]{trimbox*}{<llx>~<lly>~<urx>~<ury>} +% The \env{trimbox} and \env{trimbox*} environments do the same as the corresponding macros. +% +% \DescribeKey{trim}'='<llx>~<lly>~<urx>~<ury> +% \DescribeKey{trim}'='<all sites> +% \DescribeKey{trim}'='<left/right>~<top/bottom> +% This key represents the original \Key{trim} key of \Macro\includegraphics. +% It always trims the original content independent from its position. +% +% \DescribeKey{viewport}'='<llx>~<lly>~<urx>~<ury> +% 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{Trim}'='<llx>~<lly>~<urx>~<ury> +% \DescribeKey{Trim}'='<all sites> +% \DescribeKey{Trim}'='<left/right>~<top/bottom> +% \DescribeKey{Viewport}'='<llx>~<lly>~<urx>~<ury> +% The normal \Key{trim} and \Key{viewport} keys +% as described earlier are applied on the original content before any resizing +% or other effects. 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 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. +% +% +% \DescribeMacro\clipbox{<all sites>}{<content>} +% \DescribeMacro\clipbox{<left/right>~<top/bottom>}{<content>} +% \DescribeMacro\clipbox{<llx>~<lly>~<urx>~<ury>}{<content>} +% \DescribeMacro\clipbox*{<llx>~<lly>~<urx>~<ury>}{<content>} +% The \Macro\clipbox macro works like the \Macro\trimbox and trims the given amounts from the \meta{text}. +% However, in addition the trimmed material is also clipped, i.e. it is not shown in the final document. +% Note that the material will still be part of the output file but is simply not shown. +% It might be exported using special tools, so using \Macro\clipbox\relax (or \Macro\includegraphics[clip,trim=...]) +% to censor classified information would be a bad idea. +% The starred version will again use the given coordinates as \Key{viewport}. +% +% \DescribeEnv[<content>]{clipbox}{<1, 2 or 4 trim values>} +% \vspace{-\baselineskip} +% \DescribeEnv[<content>]{clipbox*}{<llx>~<lly>~<urx>~<ury>} +% The environment versions of \Macro\clipbox and \Macro\clipbox*. The same rules as for the trimming environments apply. +% +% +% \DescribeKey{clip} +% 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. +% +% \DescribeKey{Clip}'='<llx>~<lly>~<urx>~<ury> +% \DescribeKey{Clip}'='<all sites> +% \DescribeKey{Clip}'='<left/right>~<top/bottom> +% \DescribeKey{Clip*}'='<llx>~<lly>~<urx>~<ury> +% As stated above the \Key{clip} boolean key +% which will make the default \Key{trim} and \Key{viewport} keys clip the trimmed content, has no effect +% on the \Key{trim} and \Key{viewport} keys. Instead \Key{Clip} and \Key{Clip*} are provided which wrap the content internally in a \Macro\clipbox or +% \Macro\clipbox*\relax macro. They can be used several times. +% +% +% \subsection{Margins} +% +% \DescribeMacro\marginbox{<all sites>}{<content>} +% \DescribeMacro\marginbox{<left/right>~<top/bottom>}{<content>} +% \DescribeMacro\marginbox{<llx>~<lly>~<urx>~<ury>}{<content>} +% \Descsep +% \DescribeEnv[<content>]{marginbox*}{<1, 2 or 4 margin values>} +% \Descsep +% \DescribeKey{margin}'='<all sites> +% \DescribeKey{margin}'='<left/right>~<top/bottom> +% \DescribeKey{margin}'='<llx>~<lly>~<urx>~<ury> +% This feature can be used to add a margin (white space) around the content. It can be seen as the opposite of \Macro\trim. +% The original baseline of the content is preserved because \meta{lly} is added to the depth. % It is also available as \env{marginbox} environment and also usable as \Key{margin} option (see below). % % \begin{example} @@ -683,10 +538,16 @@ % \end{example} % % -% \DescribeMacro\marginbox'*'{<all sites>}{<\TEXT>} -% \DescribeMacro\marginbox'*'{<left/right>~<top/bottom>}{<\TEXT>} -% \DescribeMacro\marginbox'*'{<\llx>~<\lly>~<\urx>~<\ury>}{<\TEXT>} -% This starred version is almost identical to the normal \Macro\marginbox, but also raises the content by the \MacroArgs<\lly> +% \DescribeMacro\marginbox'*'{<all sites>}{<content>} +% \DescribeMacro\marginbox'*'{<left/right>~<top/bottom>}{<content>} +% \DescribeMacro\marginbox'*'{<llx>~<lly>~<urx>~<ury>}{<content>} +% \Descsep +% \DescribeEnv[<content>]{marginbox}{<1, 2 or 4 margin values>} +% \Descsep +% \DescribeKey{margin*}'='<all sites> +% \DescribeKey{margin*}'='<left/right>~<top/bottom> +% \DescribeKey{margin*}'='<llx>~<lly>~<urx>~<ury> +% This starred version is almost identical to the normal \Macro\marginbox, but also raises the content by the \MacroArgs<lly> % amount, so that the original depth instead of the original baseline is preserved. % Note that while \Macro\marginbox is basically the opposite of \Macro\trim, \Macro\marginbox* is not the opposite of \Macro\trim*. % Instead it also takes the same values as the normal value and not view port values like \Macro\trim*. @@ -698,8 +559,11 @@ % \end{example} % % -% \DescribeMacro\minsizebox{<width>}{<height>}{<\TEXT>} -% \DescribeMacro\minsizebox'*'{<width>}{<totalheight>}{<\TEXT>} +% +% \subsection{Minimum and Maximum Size} +% +% \DescribeMacro\minsizebox{<width>}{<height>}{<content>} +% \DescribeMacro\minsizebox'*'{<width>}{<totalheight>}{<content>} % This macro is like \Macro\resizebox of the \pkg{graphics/x} package, but only resizes the content if its natural size is smaller % than the given \meta{width} or \meta{height}. % If only one value should be set the other one can be replaced by "!". @@ -728,8 +592,8 @@ % % % -% \DescribeMacro\maxsizebox{<width>}{<height>}{<\TEXT>} -% \DescribeMacro\maxsizebox'*'{<width>}{<totalheight>}{<\TEXT>} +% \DescribeMacro\maxsizebox{<width>}{<height>}{<content>} +% \DescribeMacro\maxsizebox'*'{<width>}{<totalheight>}{<content>} % This macro is like \Macro\resizebox of the \pkg{graphics/x} package, but only resizes the content if its natural size is larger % than the given \meta{width} or \meta{height}. % If only one value should be set the other one can be replaced by "!". @@ -756,171 +620,6 @@ % \end{examplecode} % \end{examples} % -% \DescribeMacro\lapbox[<width>]{<lap amount>}{<\TEXT>} -% This macro is a generalisation of the \LaTeX\ core macros \Macro\rlap{<\TEXT>} and \Macro\llap{<\TEXT>} 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} -% -% -% \DescribeMacro\phantombox{<width>}{<height>}{<depth>} -% This macro produces an empty box with the given width, height and depth. -% It is equivalent to \Macro\phantom{\AlsoMacro\rule['-'<depth>]{<width>}{<height>'+'<depth>}} but more efficient and more user friendly. -% -% \begin{example} -% \begin{examplecode} -% Before \fbox{\phantombox{1cm}{2ex}{1ex}} After -% \end{examplecode} -% \end{example} -% -% -% \subsection{New keys for \cs{adjustbox} and \cs{includegraphics}}\label{sec:newkeys} -% This section lists provided keys usable as \Macro\adjustbox options and, if the \opt{export} package option was used, also as \Macro\includegraphics options. -% If the package is loaded with the \opt{minimal} option this code is skipped. -% -% \subsubsection{Setting keys globally} -% -% \DescribeMacro\adjustboxset{<global keys to be executed \emph{before} local keys>} -% \DescribeMacro\adjustboxset*{<global keys to be executed \emph{after} local keys>} -% Using these two macros all keys can be set globally, i.e.\ for all future \Macro\adjustbox macros and \env{adjustbox} environments. -% Note that these settings are actually \emph{local} to the current \TeX\ group and only really global if used in the preamble or outside any group. -% The normal macro will place all given keys before the keys used in first argument of \Macro\adjustbox\ / \env{adjustbox}, -% while the starred version will place them afterwards. -% -% If these macros are used several times there keys are accumulated. This happens in the given order for the normal version and in reversed order for the starred version, -% i.e.\ the keys of further \Macro\adjustboxset or \Macro\adjustboxset* are always added so they face inwards. -% If used without any keys but an empty argument, all keys previously set with the same macro are removed (from the current \TeX\ scope). -% This means \Macro\adjustboxset{} clears all keys set be previously usages of \Macro\adjustboxset{<keys>} and \Macro\adjustboxset*{} clears all set by \Macro\adjustboxset*{<keys>}. -% Such resets are again local to the current \TeX\ group. -% -% -% \begin{examples} -% The macros: -% \begin{macroquote} -% \adjustboxset{keya=1} \\ -% \adjustboxset*{keyc=3}\\ -% \adjustbox{keyb=2}{content} -% \end{macroquote} -% are effectively the same as: -% \begin{macroquote} -% \adjustbox{keya=1,keyb=2,keyc=3}{content} -% \end{macroquote} -% \par\medskip\noindent -% The macros: -% \begin{macroquote} -% \adjustboxset{keya=1,keyb=2} \\ -% \adjustboxset{keyc=3,keyd=4} \\ -% \adjustboxset*{keyg=7,keyh=8}\\ -% \adjustboxset*{keyi=9,keyj=10}\\ -% \adjustbox{keye=5,keyf=6}{content} -% \end{macroquote} -% are effectively the same as: -% \begin{codequote} -% \AlsoMacro\adjustbox'{keya=1,keyb=2,keyc=3,keyd=4,keye=5,keyf=6,'\\ -% !\hskip0pt!' keyi=9,keyj=10,keyg=7,keyh=8}'{content} -% \end{codequote} -% \end{examples} -% -% \subsubsection{Trimming and Clipping} -% -% \DescribeKey{Trim}'='<all sites> -% \DescribeKey{Trim}'='<left/right>~<top/bottom> -% \DescribeKey{Trim}'='<llx>~<lly>~<urx>~<ury> -% \DescribeKey{Viewport}'='<llx>~<lly>~<urx>~<ury> -% The normal \Key{trim} and \Key{viewport} keys -% as described earlier are applied on the original content before any resizing -% or other effects. 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 the last values will be used for the trimming, i.e. the content is only -% trimmed once. The upper case variants \Key{trim} and \Key{viewport} will wrap the content internally in a \Macro\trimbox or \Macro\trimbox*\relax -% macro which can be applied multiple times, e.g.\ before and after the content is rotated. -% These two keys awaits the same format as the original keys. However, the \Key{clip} key has no effect on them. -% -% \DescribeKey{Clip}'='<all sites> -% \DescribeKey{Clip}'='<left/right>~<top/bottom> -% \DescribeKey{Clip}'='<llx>~<lly>~<urx>~<ury> -% \DescribeKey{Clip*}'='<llx>~<lly>~<urx>~<ury> -% As stated above the \Key{clip} boolean key -% which will make the default \Key{trim} and \Key{viewport} keys clip the trimmed content, has no effect -% on the \Key{trim} and \Key{viewport} keys. Instead \Key{Clip} and \Key{Clip*} are provided which wrap the content internally in a \Macro\clipbox or -% \Macro\clipbox*\relax macro. They can be used several times. -% -% -% \subsubsection{Frame and Margin} -% -% \DescribeKey{frame} -% \DescribeKey{frame}'='<width> -% \DescribeKey{frame}'='<width>~<sep> -% This key will draw a black frame around the content. -% By default the frame lines will have a thickness of \Macro\fboxrule\relax -% (i.e.\ the same thickness like \Macro\fbox) and will be placed tightly around the content with zero separation. -% The line width and also the separation can be defined as the optional value. -% -% -% \DescribeKey{margin}'='<all sites> -% \DescribeKey{margin}'='<left/right>~<top/bottom> -% \DescribeKey{margin}'='<llx>~<lly>~<urx>~<ury> -% This key can be used to add a margin (white space) around the content (using \Macro\marginbox). -% It can be seen as the opposite of \Key{trim} (and in fact is implemented -% almost identical to it with negated signs). The four values are added to the left, bottom, right and top side of the content, respectively. -% The original baseline of the content is preserved by adding \meta{\lly} to the depth. -% If negative values are given the content is actually trimmed, but this will lead to wrong results if the absolute values are bigger -% than the available amount. This is particularly a problem with the depth. The \Key{trim} and \Key{trim} code will handle this case correctly, however. -% -% \DescribeKey{margin*}'='<all sites> -% \DescribeKey{margin*}'='<left/right>~<top/bottom> -% \DescribeKey{margin*}'='<llx>~<lly>~<urx>~<ury> -% Like \Key{margin} but also raises the content by \meta{\lly} and therefore preserves the original depth and not the original baseline. -% -% \subsubsection{Size/Scaling} % % \DescribeKey{min width}'='<width> % \DescribeKey{max width}'='<width> @@ -942,11 +641,38 @@ % 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. % +% +% \subsubsection{Scaling} +% +% \DescribeMacro\scalebox{<h-factor>}[<v-factor>]{<content>} +% With only the mandatory argument the content is evenly scaled accordantly to the given factor. With the optional argument +% a different vertical scaling factor can be given. +% This macro is provided by the loaded \pkg{graphicx} package and only mentioned here for the sake of completeness. +% The content is read as normal macro argument and therefore can't hold verbatim or similar special material. +% An alternative which boxes the content directly is provided by the author's other package \pkg{realboxes} as \Macro\Scalebox and +% as \env{Scalebox} environment. +% % \DescribeKey{scale}'='<factor> % \DescribeKey{scale}'='{<h-factor>}{<v-factor>} % The normal \Key{scale} key of \pkg{graphicx} only allows for one scale factor which is used for both the horizontal and vertical scaling. % With \pkg{adjustbox} it is also possible to provide the horizontal and vertical scale factors separately. % +% \begin{examples} +% \begin{examplecode} +% \adjustbox{scale=2}{Some text!} +% \end{examplecode} +% \begin{examplecode} +% \adjustbox{scale={2}{1}}{Some text!} +% \end{examplecode} +% \end{examples} +% +% \DescribeMacro\reflectbox{<content>} +% Reflects the content like \Macro\scalebox{-1}[1] would do. +% This macro is provided by the loaded \pkg{graphicx} package and only mentioned here for the sake of completeness. +% The content is read as normal macro argument and therefore can't hold verbatim or similar special material. +% An alternative which boxes the content directly is provided by the author's other package \pkg{realboxes} as \Macro\Reflectbox and +% as \env{Reflectbox} environment. +% % \DescribeKey{reflect} % This 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}. @@ -954,44 +680,84 @@ % % \begin{examples} % \begin{examplecode} -% \adjustbox{reflect}{\sffamily OTTO} +% \adjustbox{reflect}{Some text!} % \end{examplecode} +% \end{examples} +% +% +% \subsubsection{Frame} +% +% \DescribeKey{fbox} +% \DescribeKey{fbox}'='<rule width> +% \DescribeKey{fbox}'='<rule width>~<sep> +% \DescribeKey{fbox}'='<rule width>~<sep>~<margin> +% Draws a framed box around the content like \Macro\fbox would do. +% Using the optional space separated values the rule width, the separation (inner padding) and the outer margin can be set. +% If not they default to the values \Macro\fbox uses by default: \Macro\fboxrule, \Macro\fboxsep and zero margin. +% +% \begin{examples} % \begin{examplecode} -% \adjustbox{reflect}{\sffamily ANNA} +% \adjustbox{fbox}{Like \cs{fbox}} % \end{examplecode} % \begin{examplecode} -% \adjustbox{reflect}{Some text!} +% \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} % -% \subsubsection{Positioning and Alignment} -% -% \DescribeKey{raise}'='<amount> -% \DescribeKey{raise}'='{<amount>}{<height>} -% \DescribeKey{raise}'='{<amount>}{<height>}{<depth>} -% This key uses -% \Macro\raisebox{<amount>}{\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{<amount>}[<height>][<depth>]{\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. +% \DescribeKey{frame} +% \DescribeKey{frame}'='<rule width> +% \DescribeKey{frame}'='<rule width>~<sep> +% \DescribeKey{frame}'='<rule width>~<sep>~<margin> +% The \Key{frame} key as 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} -% Is \adjustbox{raise=1ex}{higher} -% than the normal text +% \adjustbox{frame}{Tight box} % \end{examplecode} +% \end{examples} +% +% \DescribeKey{cfbox}'='<color> +% \DescribeKey{cfbox}'='<color>~<rule width> +% \DescribeKey{cfbox}'='<color>~<rule width>~<sep> +% \DescribeKey{cfbox}'='<color>~<rule width>~<sep>~<margin> +% Identical to \Key{fbox} but uses the given color for the frame. +% The \pkg{xcolor} package must be loaded manually in order for this key to work. +% \begin{example} % \begin{examplecode} -% Is \adjustbox{raise={1ex}{\height}}{higher} -% than the normal text but sill has -% its original official height +% \adjustbox{cfbox=blue 1pt} +% {Like a blue \cs{fbox} with \cs{fboxrule}=1pt} % \end{examplecode} +% \end{example} +% +% \DescribeKey{cframe}'='<color> +% \DescribeKey{cframe}'='<color>~<rule width> +% \DescribeKey{cframe}'='<color>~<rule width>~<sep> +% \DescribeKey{cframe}'='<color>~<rule width>~<sep>~<margin> +% Identical to \Key{frame} but uses the given color for the frame. +% The \pkg{xcolor} package must be loaded manually in order for this key to work. +% \begin{example} % \begin{examplecode} -% Is \adjustbox{raise={1ex}{1ex}{0pt}}{higher and -% \rotatebox{-90}{depth}} but with limited official -% height and no depth. +% \adjustbox{cfbox=blue!50!green} +% {Like a blue and green \cs{frame}} % \end{examplecode} -% \end{examples} +% \end{example} +% +% +% \subsection{Vertical Alignment} % % \DescribeKey{valign}'='<letter> % This key allows to vertically align the content to the top, middle and bottom. The uppercase letters |T|, |M| and |B| @@ -1050,60 +816,74 @@ % \endgroup % % +% \DescribeKey{raise}'='<amount> +% \DescribeKey{raise}'='{<amount>}{<height>} +% \DescribeKey{raise}'='{<amount>}{<height>}{<depth>} +% This key uses +% \Macro\raisebox{<amount>}{\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{<amount>}[<height>][<depth>]{\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}'='<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'}[<height>]{<content>}. % -% \begin{examples} +% \begin{example} % \begin{examplecode} % \adjustbox{set height=.5\height} % {\shortstack{some stacked\\content}} % \end{examplecode} -% \end{examples} +% \end{example} % % \DescribeKey{set depth}'='<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'][<depth>]{<content>}. % -% \begin{examples} +% \begin{example} % \begin{examplecode} % \adjustbox{set depth=0pt} % {\shortstack{some stacked\\content % with \raisebox{-1ex}{depth}}} % \end{examplecode} -% \end{examples} +% \end{example} % -% \DescribeKey{lap}'='<lap amount> -% \DescribeKey{lap}'='{<length>}{<lap amount>} -% This wraps the content into a -% \Macro\lapbox{<lap amount>}{\ldots} and -% \Macro\lapbox[<length>]{<lap amount>}{\ldots}, respectively. Positive \meta{amounts} lap the content to the right -% and negative to the left. The optional \meta{length} argument allows to set the final width. +% \DescribeKey{set vsize}'='{<height>}{<depth>} +% 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{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{example} % \begin{examplecode} -% \adjustbox{lap={\width}{-\width}}{Some content} +% \adjustbox{set vsize={2pt}{1pt}} +% {\shortstack{some stacked\\content +% with \raisebox{-1ex}{depth}}} % \end{examplecode} -% \end{examples} +% \end{example} % % +% \subsection{Horizontal Alignment} +% % \DescribeKey{center} % \DescribeKey{center}'='<width> % This key places @@ -1126,6 +906,7 @@ % \end{examplecode} % \end{examples} % +% % \DescribeKey{right} % \DescribeKey{right}'='<width> % Like \Key{center} this key @@ -1158,7 +939,6 @@ % \end{examples} % % -% % \DescribeKey{inner} % \DescribeKey{inner}'='<width> % Like \Key{center}, \Key{left} and \Key{right} this key @@ -1170,14 +950,163 @@ % 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}'='<width> % Identical to \Key{inner} but aligns the content towards the outer margin. % If the content is wider than the available width it will stick into the outer inner without causing an overfull hbox warning. % % -% \subsubsection{Pixel size} +% \subsection{Lapping} +% 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. +% +% \DescribeMacro\lapbox[<width>]{<lap amount>}{<content>} +% This macro is a generalisation of the \LaTeX\ core macros \Macro\rlap{<content>} and \Macro\llap{<content>} 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} +% % +% \DescribeKey{lap}'='<lap amount> +% \DescribeKey{lap}'='{<length>}{<lap amount>} +% This wraps the content into a +% \Macro\lapbox{<lap amount>}{\ldots} and +% \Macro\lapbox[<length>]{<lap amount>}{\ldots}, respectively. Positive \meta{amounts} lap the content to the right +% and negative to the left. The optional \meta{length} argument allows to set the final width. +% +% \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} +% +% +% +% \subsubsection{Background} +% +% \DescribeKey{bgcolor}'='<color> +% \DescribeKey{bgcolor}'='{<model>}{<color>} +% 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*}'='<color macro> +% 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} +% +% +% \DescribeKey{bgimage}'='<image filename> +% \DescribeKey{bgimage}'='{<key=value pairs for image>}{<image filename>} +% 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). +% +% \DescribeMacro{\bgimagebox}[<key=value pairs>]{<image filename>} +% Standalone version of the \Key{bgimage} key. Also available as \env{bgimagebox} environment. +% +% \subsubsection{Pixel size} % \DescribeKey{dpi}'='<number (dots per inch)> % 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 @@ -1208,7 +1137,8 @@ % \end{examplecode} % \end{example} % -% \subsection{Minipage or other inner environments which change the processing of the content} +% +% \subsection{Minipage or other inner environments which change the processing of the content}\label{sec:inner} % 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. @@ -1276,11 +1206,40 @@ % \end{examples} % % +% \DescribeKey{stack} +% \DescribeKey{stack}'='<horizontal alignment> +% \DescribeKey{stack}'='{<horizontal alignment>}{<vertical alignment>} +% \Descsep +% \DescribeMacro\stackbox!\optionaloff![<horizontal alignment>][<vertical alignment>]{<content>} +% \Descsep +% \DescribeEnv[<content>]{stackbox}[<horizontal alignment>][<vertical alignment>] +% 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}'='<environment name> % \DescribeKey{innerenv}'='{<environment name>}<environment options> % 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{innerenv} or similar environment will not work here, because that code will be taken as part of the first cell. +% 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} @@ -1288,6 +1247,10 @@ % \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} % % @@ -1322,8 +1285,32 @@ % Prepends come \meta{code afterwards} the content and the already existing code around it which was added by other keys beforehand. % More complex code should be enclosed in braces. % -% \subsection{Split content} -% The following features are experimental and can be used to split a boxed content. +% \DescribeKey{execute}'='<code> +% Simply executes the code immediately. This is done in the key processing phase and is intended mostly for debugging purposes. +% Previous (normal) keys won't have an effect yet. +% +% \DescribeKey{Execute}'='<code> +% Simply executes the code immediately. This is done in the key processing phase for inner environments (see \autoref{sec:inner}) and is intended mostly for debugging purposes. +% Only previously used special keys for modifying the boxing of the content will have an effect yet. % All other keys are not yet processed. +% +% +% \section{Other} +% +% \DescribeMacro\phantombox{<width>}{<height>}{<depth>} +% This macro produces an empty box with the given width, height and depth. +% It is equivalent to \Macro\phantom{\AlsoMacro\rule['-'<depth>]{<width>}{<height>'+'<depth>}} but more efficient and more user friendly. +% +% \begin{example} +% \begin{examplecode} +% Before \fbox{\phantombox{1cm}{2ex}{1ex}} After +% \end{examplecode} +% \end{example} +% +% +% \StopEventually{} +% \subsection{Experimental Keys} +% The following features are experimental and may not work correctly yet. +% At the moment the \pkg{storebox} package must be loaded manually for this keys. % % \DescribeMacro\splitbox{<split width>}{<split height>}{<content>} % This macro boxes the given content and splits it in multiple fragments of the given width and height. @@ -1338,26 +1325,29 @@ % \DescribeEnv[<content>]{splitbox}{<split width>}{<split height>} % Environment version of \Macro\splitbox. % -% \DescribeKey{splitbox}'='{<split width>}{<split height>} -% The \Key{splitbox} key can be used with \Macro\adjustbox and uses \Macro\splitbox internally. +% \DescribeKey{split}'='{<split width>}{<split height>} +% The \Key{split} key can be used with \Macro\adjustbox and uses \Macro\splitbox internally. +% +% \DescribeMacro\pagebreakbox{<content>} +% The \Macro\pagebreakbox macro will split the content into multiple parts so that if fits on the current page. +% If it is larger than the rest of the current page and the full next page it is broken again until the last part fits on a page. +% This doesn't take any baselines into account and text line in the content may be split in two. +% This might be compensated manually by redefining the \Macro\pagebreakboxoffset macro (default: `|\ht\strutbox|'), which adjust the vertical offset +% of the first part. +% +% \DescribeEnv{pagebreakbox} +% Environment version of \Macro\pagebreakbox. +% +% \DescribeKey{pagebreak} +% The key version of \Macro\pagebreakbox. There should no be any further keys used afterwards, because they will interfere with the page breaks. +% +% +% % -% \StopEventually{} % \clearpage % \section{Implementation} % \setcounter{lstnumber}{1} -% \ifenglish\else -% Die Dokumentation des Quellcodes ist nur auf Englisch verf^^c3^^bcgbar. -% \fi % -% \iffalse -%<*de> -%% Wrapper to set language to German and jobname to 'adjustbox-de'. -%% Does not have to be included in distributions or placed on CTAN. -\expandafter\newif\csname ifenglish\endcsname -\englishfalse -\input{adjustbox.dtx} -%</de> -% \fi % % \iffalse %<*adjustbox.sty> @@ -1392,6 +1382,7 @@ % \def\adjbox@fam{adjbox} \DeclareOptionX<adjbox>{export}{\def\adjbox@fam{Gin}} +\DeclareOptionX<adjbox>{Export}{\AtEndOfPackage{\let\includegraphics\adjincludegraphics}} \DeclareOptionX<adjbox>{patch}{\AtEndOfPackage{\RequirePackage{adjgrfx}}} \DeclareOptionX<adjbox>{minimal}{\let\adjbox@maybeend\endinput} % @@ -1463,15 +1454,11 @@ % \end{macrocode} % \end{macro} % -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% \subsection{Basic commands} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% % % \begin{key}{adjbox}{viewport} % \begin{macrocode} \define@key{adjbox}{viewport}{% - \def\adjustbox@@@{% + \def\adjustbox@content{% \adjbox@parse@v{#1}% \adjbox@@viewport \adjustbox@@@trimclip @@ -1484,7 +1471,7 @@ % \begin{key}{adjbox}{trim} % \begin{macrocode} \define@key{adjbox}{trim}{% - \def\adjustbox@@@{% + \def\adjustbox@content{% \adjbox@parse@v{#1}% \adjustbox@@@trimclip }% @@ -1496,7 +1483,6 @@ % \begin{macro}{\adjustbox@@@trimclip} % \begin{macrocode} \def\adjustbox@@@trimclip{% - \Gin@viewport@code \ifGin@clip \expandafter\@clipbox \else @@ -1550,6 +1536,7 @@ % % % \begin{macro}{\adjbox@@viewport} +% Turns viewport coordinates into trim coordinates. % \begin{macrocode} \def\adjbox@@viewport{% %\advance\adjbox@tllx by -\z@ @@ -1634,7 +1621,7 @@ % This code was originally adapted from the \Macro\Gin@ii macro from the |graphicx| package. % The \emph{temp switch a} is set to |true| to indicate to |graphicx| that the % scaling should be done internal, so this package doesn't have to do it. -% The content including macro \Macro\adjustbox@@@ is but into place, +% The content including macro \Macro\adjustbox@content is but into place, % the saved options are activated and the final size is set. % The typesetting of the content is finally done by executing the token register. % \begin{macrocode} @@ -1647,7 +1634,7 @@ \expandafter \adjbox@collectbox\expandafter{\expandafter\adjustbox@\expandafter{\XKV@rm}}% } -\let\adjbox@collectbox\@collectbox +\def\adjbox@collectbox{\@collectbox} \def\adjbox@setkeys@ba{% \expandafter\expandafter \expandafter\adjbox@@setkeys@ba @@ -1666,12 +1653,21 @@ % % % \begin{macro}{\adjustbox@} +% Second part of \Macro\adjustbox, after the content has been boxed. +% This sets the dimension macros, processes the keys and finally typesets the content. % \begin{macrocode} \def\adjustbox@#1{% - \adjustbox@dimcmds + \adjbox@Width\width + \adjbox@Height\height + \adjbox@Depth\depth + \adjbox@Totalheight\totalheight + \let\Width\adjbox@Width + \let\Height\adjbox@Height + \let\Depth\adjbox@Depth + \let\Totalheight\adjbox@Totalheight \let\Gin@esetsize\adjbox@esetsize \@tempswatrue - \toks@{{\adjustbox@@@@}}% + \toks@{{\adjustbox@content}}% \def\setlength{\adjsetlength}% \setkeys{adjbox,Gin}{#1}% \adjbox@esetsize @@ -1680,14 +1676,35 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\adjustbox@@@@} -% Content wrapper which might be redefined when the size is specified. +% +% \begin{macro}{\adjustbox@content} +% The default content, which is simply the collected box. +% This macro can be redefined if required. % \begin{macrocode} -\def\adjustbox@@@@{\adjustbox@@@}% +\def\adjustbox@content{% + \usebox\collectedbox +} % \end{macrocode} % \end{macro} % % +% \begin{macro}{\adjbox@Width} +% \begin{macro}{\adjbox@Height} +% \begin{macro}{\adjbox@Depth} +% \begin{macro}{\adjbox@Totalheight} +% Dimension registers for original sizes. +% \begin{macrocode} +\newdimen\adjbox@Width +\newdimen\adjbox@Height +\newdimen\adjbox@Depth +\newdimen\adjbox@Totalheight +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% % \begin{macro}{\adjbox@esetsize} % Replacement of \Macro\Gin@esetsize. % Now always called in external mode. Checks if any size is set and, as an optimation, does nothing otherwise. @@ -1714,34 +1731,23 @@ % \end{macrocode} % \end{macro} % -% -% \begin{macro}{\adjustbox@dimcmds} -% Inits the dimension macro in an unexpandedable way. They will be redefined to the correct -% values by \Macro\collectbox. +% \begin{macro}{\adjustimage} +% Simple wrapper to use \Macro\adjustbox for images. +% It uses the internal code of \Macro\includegraphics instead +% to allow later redefinition of that macro. % \begin{macrocode} -\def\adjustbox@dimcmds{% - \let\width\relax - \let\height\relax - \let\depth\relax - \let\totalheight\relax +\newcommand*\adjustimage[2]{% + \adjustbox{#1}{\Gin@clipfalse\Gin@i{#2}}% } % \end{macrocode} % \end{macro} % -% -% \begin{macro}{\adjustbox@@@} +% \begin{macro}{\adjincludegraphics} +% Simple wrapper to use \Macro\adjustbox for images in the same format of \Macro\includegraphics. +% This allows to simply do |\let\includegraphics\adjincludegraphics|, which is done by the \opt{Export} option. % \begin{macrocode} -\def\adjustbox@@@{% - \usebox\collectedbox -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\adjustimage} -% Simple wrapper to use \Macro\adjustbox for images. -% \begin{macrocode} -\newcommand*\adjustimage[2]{% - \adjustbox{#1}{\includegraphics{#2}}% +\newcommand*\adjincludegraphics[2][]{% + \adjustbox{#1}{\Gin@clipfalse\Gin@i{#2}}% } % \end{macrocode} % \end{macro} @@ -1751,7 +1757,8 @@ % \subsubsection{Low-level trim and clip boxes} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -% \begin{macro}{\@trimbox} +% \begin{macro}{\@trimbox}[5]{<tllx>}{<tlly>}{<turx>}{<tury>}{<box register> +% Removes the four length for the left, bottom, right and top from the official size of the box register. % \begin{macrocode} \def\@trimbox#1#2#3#4#5{% \setbox#5=\hbox{% @@ -1780,18 +1787,16 @@ % % % \begin{macro}{\@clipbox} +% Clips the box using the given trim amounts. +% For this the box is first trimmed and then clipped to its official size using a driver dependent macro. % \begin{macrocode} \def\@clipbox#1#2#3#4#5{% \@trimbox{#1}{#2}{#3}{#4}{#5}% - \pdfxform#5% - \setbox#5=\hbox{% - \pdfrefxform\pdflastxform - }% + \@cliptoboxdim{#5}% } % \end{macrocode} % \end{macro} % -% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % \subsection{Driver} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1799,16 +1804,11 @@ % is used if its exists. Otherwise either the default \texttt{pdftex} implementation or the \pkg{pgf} fall-back driver % is used. % \begin{macrocode} -\RequirePackage{ifpdf} \InputIfFileExists{\adjbox@driver}{% \PackageInfo{adjustbox}{Using driver '\adjbox@driver'.}% }{% - \ifpdf - \PackageInfo{adjustbox}{Using default pdftex driver.} - \else - \input{adjpgf.def}% - \PackageInfo{adjustbox}{Using fall-back PGF driver.} - \fi + \input{adjpgf.def}% + \PackageInfo{adjustbox}{Using fall-back PGF driver.} } % \end{macrocode} % @@ -2022,6 +2022,7 @@ % % % \begin{key}{adjbox}{frame} +% As 0--3 arguments: rule width, (inner) separation and margin. % \begin{macrocode} \define@key\adjbox@fam{frame}[{{\fboxrule}}]{% \adjbox@frame{\fboxsep\z@}#1 {} {} \relax\relax\@nnil @@ -2031,6 +2032,7 @@ % % % \begin{key}{adjbox}{fbox} +% Same as \Key{frame} but with different default separation. % \begin{macrocode} \define@key\adjbox@fam{fbox}[{{\fboxrule}}]{% \adjbox@frame{}#1 {} {} {} \relax\relax\@nnil @@ -2054,6 +2056,7 @@ % \begin{key}{adjbox}{cframe} % \begin{macrocode} \define@key\adjbox@fam{cframe}{% + \adjbox@checkcolor \adjbox@cframe{\fboxsep\z@}#1 {} {} {} \relax\relax\@nnil } % \end{macrocode} @@ -2062,6 +2065,7 @@ % \begin{key}{adjbox}{cfbox} % \begin{macrocode} \define@key\adjbox@fam{cfbox}{% + \adjbox@checkcolor \adjbox@cframe{}#1 {} {} {} \relax\relax\@nnil } % \end{macrocode} @@ -2079,7 +2083,24 @@ % \end{macro} % % -% \begin{macro}{\adjbox@@frame} +% \begin{macro}{\adjbox@checkcolor} +% \begin{macrocode} +\def\adjbox@checkcolor{% + \ifcase0% + \expandafter\ifx\csname ver@xcolor.sty\endcsname\relax + \expandafter\ifx\csname ver@color.sty\endcsname\relax + \expandafter\ifx\csname ver@xxcolor.sty\endcsname\relax 1\fi\fi\fi + \relax + \global\let\adjbox@checkcolor\relax + \else + \PackageError{adjustbox}{Using a macro, envrionment or key with color\MessageBreak requires a color package to be loaded manually.\MessageBreak Recommended is 'xcolor' but 'color' is ok, too}{}. + \fi +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\adjbox@@frame}[4]{content}{rule width}{separation}{margin} % \begin{macrocode} \def\adjbox@@frame#1#2#3#4{% \ifx\@nnil#2\@nnil\else @@ -2236,6 +2257,24 @@ % \end{macro} % % +% \begin{key}{adjbox}{rlap} +% \begin{macrocode} +\define@key\adjbox@fam{rlap}[]{% + \adjbox@Gin@Add{\lapbox{\width}}% +} +% \end{macrocode} +% \end{key} +% +% +% \begin{key}{adjbox}{llap} +% \begin{macrocode} +\define@key\adjbox@fam{llap}[]{% + \adjbox@Gin@Add{\lapbox{-\width}}% +} +% \end{macrocode} +% \end{key} +% +% % \begin{key}{adjbox}{margin} % \begin{macrocode} \define@key\adjbox@fam{margin}{% @@ -2277,28 +2316,36 @@ } % \end{macrocode} % +% \begin{macrocode} +\define@key\adjbox@fam{@debug}[]{% + \showthe\toks@ +} +% \end{macrocode} +% +% \begin{macrocode} +\define@key{ADJBOX}{Execute}{% + #1% +} +% \end{macrocode} +% % % \begin{key}{adjbox}{raise} % \begin{macrocode} \define@key\adjbox@fam{raise}{% \@ifnextchar\bgroup{% - \adjbox@raisebox + \adjbox@raise }{% - \adjbox@raisebox{#1}{}{}% + \adjbox@raise{#1}{}{}% }#1{}{}{}\@nnil } % \end{macrocode} % \end{key} % % -% \begin{macro}{\adjbox@raisebox} +% \begin{macro}{\adjbox@raise} % \begin{macrocode} -\def\adjbox@raisebox#1#2#3#4\@nnil{% - \ifx\@nnil#3\@nnil - \adjbox@Gin@Add{\@irsbox{#1}[{#2}]}% - \else - \adjbox@Gin@Add{\@iirsbox{#1}[{#2}][{#3}]}% - \fi +\def\adjbox@raise#1#2#3#4\@nnil{% + \adjbox@Gin@Add{\adjbox@raisebox{#1}{#2}{#3}}% } % \end{macrocode} % \end{macro} @@ -2312,6 +2359,39 @@ % \end{key} % % +% \begin{macro}{\adjbox@raisebox}[3]{raise amount}{height}{depth} +% \begin{macrocode} +\def\adjbox@raisebox#1#2#3{% + \collectbox{\adjbox@@raisebox{#1}{#2}{#3}}% +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\adjbox@@raisebox}[3]{raise amount}{height}{depth} +% \begin{macrocode} +\def\adjbox@@raisebox#1#2#3{% + \ifx\@nnil#1\@nnil + \setbox\@tempboxa\box\collectedbox + \else + \adjsetlength\@tempdima{#1}% + \sbox\@tempboxa{\raise\@tempdima\box\collectedbox}% + \fi + \ifx\@nnil#2\@nnil\else + \adjsetlength\@tempdima{#2}% + \ht\@tempboxa\@tempdima + \fi + \ifx\@nnil#3\@nnil\else + \adjsetlength\@tempdima{#3}% + \dp\@tempboxa\@tempdima + \fi + \box\@tempboxa +} +% \end{macrocode} +% \end{macro} +% +% +% % \begin{macro}{\adjboxvtop} % \begin{macrocode} \def\adjboxvtop{\ht\strutbox} @@ -2332,7 +2412,7 @@ % \begin{macro}{\adjbox@valign@t} % \begin{macrocode} \def\adjbox@valign@t{% - \adjbox@Gin@Add{\@irsbox{-\height+\adjboxvtop}[]}% + \adjbox@Gin@Add{\adjbox@raisebox{-\height+\adjboxvtop}{}{}}% } % \end{macrocode} % \end{macro} @@ -2341,7 +2421,7 @@ % \begin{macro}{\adjbox@valign@T} % \begin{macrocode} \def\adjbox@valign@T{% - \adjbox@Gin@Add{\@irsbox{-\height}[]}% + \adjbox@Gin@Add{\adjbox@raisebox{-\height}{}{}}% } % \end{macrocode} % \end{macro} @@ -2350,7 +2430,7 @@ % \begin{macro}{\adjbox@valign@M} % \begin{macrocode} \def\adjbox@valign@M{% - \adjbox@Gin@Add{\@irsbox{.5\depth-.5\height}[]}% + \adjbox@Gin@Add{\adjbox@raisebox{.5\depth-.5\height}{}{}}% } % \end{macrocode} % \end{macro} @@ -2359,7 +2439,22 @@ % \begin{macro}{\adjbox@valign@m} % \begin{macrocode} \def\adjbox@valign@m{% - \adjbox@Gin@Add{\@irsbox{.5\depth-.5\height+\adjboxvcenter}[]}% + \adjbox@Gin@Add{\adjbox@raisebox{.5\depth-.5\height+\adjboxvcenter}{}{}}% +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\adjbox@valign@c} +% \begin{macrocode} +\def\adjbox@valign@c{% + \adjbox@Gin@Add{\@collectbox\adjbox@vcenter}% +} +\def\adjbox@vcenter{% + \leavevmode + \hbox{% + $\vcenter{\hbox{\BOXCONTENT}}\m@th$ + }% } % \end{macrocode} % \end{macro} @@ -2368,7 +2463,7 @@ % \begin{macro}{\adjbox@valign@b} % \begin{macrocode} \def\adjbox@valign@b{% - \adjbox@Gin@Add{\@irsbox{\depth+\adjboxvbottom}[]}% + \adjbox@Gin@Add{\adjbox@raisebox{\depth+\adjboxvbottom}{}{}}% } % \end{macrocode} % \end{macro} @@ -2377,15 +2472,19 @@ % \begin{macro}{\adjbox@valign@B} % \begin{macrocode} \def\adjbox@valign@B{% - \adjbox@Gin@Add{\@irsbox{\depth}[]}% + \adjbox@Gin@Add{\adjbox@raisebox{\depth}{}{}}% } % \end{macrocode} % \end{macro} % % % \begin{key}{adjbox}{bgcolor} +% Adds a colored box in the background. +% |#1| are the argument to color, i.e. either \MacroArgs<color> +% or \MacroArgs{<model>}{<color>}. % \begin{macrocode} \define@key\adjbox@fam{bgcolor}{% + \adjbox@checkcolor \@ifnextchar\bgroup{% \adjbox@bgcolor }{% @@ -2397,25 +2496,44 @@ % % % \begin{macro}{\adjbox@bgcolor} +% Parses the two possible arguments and adds the background color macro +% to the token register. % \begin{macrocode} \def\adjbox@bgcolor#1#2#3\@nnil{% - \adjbox@Gin@add{\@collectbox{\adjbox@@bgcolor{#1}{#2}}}% + \ifx\@nnil#1\@nnil + \adjbox@Gin@add{\@collectbox{\adjbox@@bgcolor{\color{#2}}}}% + \else + \adjbox@Gin@add{\@collectbox{\adjbox@@bgcolor{\color[#1]{#2}}}}% + \fi } % \end{macrocode} % \end{macro} % +% \begin{key}{adjbox}{bgcolor*} +% Adds a colored box in the background. It awaits a direct color macro, +% which gives the user more flexibility. +% \begin{macrocode} +\define@key\adjbox@fam{bgcolor*}{% + \adjbox@checkcolor + \adjbox@Gin@add{\@collectbox{\adjbox@@bgcolor{#1}}}% +} +% \end{macrocode} +% \end{key} +% % % \begin{macro}{\adjbox@@bgcolor} +% This places a colored box (vrule) with the same dimensions than +% the content, then compensates for the horizontal shift and places +% the content. This is simpler and more direct than using \Macro\rlap +% or a box macro from the \pkg{xcolor} package. +% +% The argument contains the color macro, e.g.\ \Macro\color{<color>}. % \begin{macrocode} -\def\adjbox@@bgcolor#1#2{% +\def\adjbox@@bgcolor#1{% \mbox{% \hbox{% - \ifx\@nnil#1\@nnil - \color{#2}% - \else - \color[#1]{#2}% - \fi - \vrule\@width\width\@height\height\@depth\depth + #1% + \vrule\@width\width\@height\height\@depth\depth% }% \hskip-\width \BOXCONTENT @@ -2428,7 +2546,7 @@ % \begin{key}{adjbox}{set height} % \begin{macrocode} \define@key\adjbox@fam{set height}{% - \adjbox@Gin@Add{\@irsbox\z@[{#1}]}% + \adjbox@Gin@Add{\adjbox@raisebox{}{#1}{}}% } % \end{macrocode} % \end{key} @@ -2437,11 +2555,22 @@ % \begin{key}{adjbox}{set depth} % \begin{macrocode} \define@key\adjbox@fam{set depth}{% - \adjbox@Gin@Add{\@iirsbox\z@[\height][{#1}]}% + \adjbox@Gin@Add{\adjbox@raisebox{}{}{#1}}% } % \end{macrocode} % \end{key} % +% \begin{key}{adjbox}{set vsize} +% Uses the same code like \Key{raise} but with the raise value of 0pt, +% i.e.\ only sets the height and depth. +% \begin{macrocode} +\define@key\adjbox@fam{set vsize}{% + \adjbox@Gin@Add{\adjbox@raisebox{}#1}% +} +% \end{macrocode} +% \end{key} +% +% % % \begin{macro}{\adjbox@Gin@add} % \begin{macrocode} @@ -2803,31 +2932,155 @@ % \begin{key}{ADJBOX}{minipage} % \begin{macrocode} \define@key{ADJBOX}{minipage}{% + \adjbox@page{minipage}{#1}% +} +% \end{macrocode} +% \end{key} +% +% \begin{key}{ADJBOX}{varwidth} +% \begin{macrocode} +\define@key{ADJBOX}{varwidth}{% + \adjbox@page{varwidth}{#1}% +} +% \end{macrocode} +% \end{key} +% +% \begin{macro}{\adjbox@page} +% If the value starts with "[" or "{" take the value as it is, +% otherwise assume that is a single length expression and add the required "{ }". +% \begin{macrocode} +\def\adjbox@page#1#2{% \@ifnextchar[{% - \adjbox@minipage% + \adjbox@@page{#1}% }{% - \adjbox@minipage{{#1}}\@nnil% - \remove@to@nnil - }#1\@nnil + \@ifnextchar\bgroup{% + \adjbox@@page{#1}% + }{% + \adjbox@@page{#1}{{#2}}\@nnil% + \remove@to@nnil + }% + }#2\@nnil } % \end{macrocode} -% \end{key} +% \end{macro} +% % -% \begin{macro}{\adjbox@minipage} +% \begin{macro}{\adjbox@@page} +% Sets collect-box command to use \env{minipage} or similar environment. % \begin{macrocode} -\def\adjbox@minipage#1\@nnil{% - \def\adjbox@collectbox##1{\collectbox@{\adjbox@set\begin{minipage}#1\adjbox@reset}{##1}{\end{minipage}}}% +\def\adjbox@@page#1#2\@nnil{% + \def\adjbox@collectbox##1{\collectbox@{\adjbox@set\begin{#1}#2\adjbox@reset}{##1}{\end{#1}}}% } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\adjbox@set} +% \begin{macrocode} \def\adjbox@set{% \let\adjbox@origsetlength\setlength \def\setlength{\adjsetlength}% } +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\adjbox@reset} +% \begin{macrocode} \def\adjbox@reset{% \let\setlength\adjbox@origsetlength } % \end{macrocode} % \end{macro} % +% +% \begin{macro}{\stackbox} +% \begin{macrocode} +\newcommand*\stackbox[1][c]{% + \collectboxcheckenv{stackbox}% + \@testopt{\@stackbox{#1}}{b}% +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\@stackbox} +% The \env{varwidth} environment is used because it is much simpler to use than \env{tabular}. +% The horizontal alignment is done by the usual text align macros. +% \begin{macrocode} +\def\@stackbox#1[#2]{% + \collectbox@ + {\begin{varwidth}[#2]{\linewidth}\csname adjbox@halign@#1\endcsname} + \BOXCONTENT + {\end{varwidth}}% +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{key}{ADJBOX}{stack} +% \begin{macrocode} +\define@key{ADJBOX}{stack}[{}{}]{% + \adjbox@stack#1{}{}\@nnil +} +% \end{macrocode} +% \end{key} +% +% +% \begin{macro}{\adjbox@stack} +% \begin{macrocode} +\def\adjbox@stack#1#2#3\@nnil{% + \ifx\@nnil#1\@nnil + \adjbox@@stack{c}{b}% + \else + \ifx\@nnil#2\@nnil + \adjbox@@stack{#1}{b}% + \else + \adjbox@@stack{#1}{#2}% + \fi\fi +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\adjbox@@stack} +% \begin{macrocode} +\def\adjbox@@stack#1#2{% + \def\adjbox@collectbox##1{\collectbox@{\begin{varwidth}[#2]{\linewidth}\csname adjbox@halign@#1\endcsname}{##1}{\end{varwidth}}}% +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\adjbox@halign@c} +% \begin{macro}{\adjbox@halign@l} +% \begin{macro}{\adjbox@halign@r} +% \begin{macro}{\adjbox@halign@j} +% \begin{macrocode} +\def\adjbox@halign@c{\centering} +\def\adjbox@halign@l{\raggedright} +\def\adjbox@halign@r{\raggedleft} +\def\adjbox@halign@j{\let\\\newline} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% Load the \pkg{varwidth} package if available or disable the dependent keys if not. +% \begin{macrocode} +\IfFileExists{varwidth.sty} + {\RequirePackage{varwidth}}{% + \define@key{ADJBOX}{varwidth}{% + \PackageError{adjustbox}{The 'varwidth' key requires the 'varwidth' package, which is not installed}{}% + } + \define@key{ADJBOX}{stack}{% + \PackageError{adjustbox}{The 'stack' key requires the 'varwidth' package, which is not installed}{}% + } +}% +% \end{macrocode} +% +% % \begin{key}{ADJBOX}{tabular} % \begin{macrocode} \define@key{ADJBOX}{tabular}{% @@ -2895,7 +3148,7 @@ % \begin{macrocode} \define@key{ADJBOX}{innerenv}{% \@ifnextchar\bgroup{% - \adjbox@innerenv + \adjbox@@innerenv }{% \adjbox@innerenv{#1}\@nnil% \remove@to@nnil @@ -2912,6 +3165,26 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\adjbox@innerenv} +% \begin{macro}{\adjbox@@innerenv} +% \begin{macro}{\adjbox@@@innerenv} +% Used to extract the environment arguments. The issue here is that if a single mandatory argument is used +% its braces are removed. To avoid that a `|{}|' is always added beforehand and then removed again. +% \begin{macrocode} +\def\adjbox@@innerenv#1{% + \adjbox@@@innerenv{#1}{}% +}% +\def\adjbox@@@innerenv#1#2\@nnil{% + \expandafter\adjbox@@@@innerenv\expandafter{\@gobble#2}{#1}% +}% +\def\adjbox@@@@innerenv#1#2{% + \adjbox@innerenv{#2}{#1}\@nnil +}% +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% % % \begin{key}{ADJBOX}{innercode} % \begin{macrocode} @@ -2956,6 +3229,8 @@ % \end{macro} % % \begin{key}{adjbox}{addcode} +% Adds code before and after the current boxed content. +% Syntax:~\Key{addcode}'='{<code before>}{<code afterwards>} % \begin{macrocode} \define@key{adjbox}{Addcode}{% \adjust@@addcode#1{}\@nnil% @@ -2986,6 +3261,7 @@ % \end{key} % % \begin{key}{adjbox}{Precode} +% Same as \Key{precode} but does not set the size yet. % \begin{macrocode} \define@key{adjbox}{Precode}{% \adjust@addcode{#1}{}% @@ -3014,6 +3290,8 @@ % % \subsection{New, experimental macros and keys} % +% +% % \begin{macro}{\bgimagebox} % \begin{macrocode} \newcommand*\bgimagebox[2][]{% @@ -3029,8 +3307,8 @@ \def\@bgimagebox#1#2{% \mbox{% \lower\depth\hbox{% - \edef\@tempa{\noexpand\includegraphics% - [#1,width=\the\width,totalheight=\the\totalheight]% + \edef\@tempa{\noexpand\adjustimage + {#1,width=\the\width,totalheight=\the\totalheight}% {#2}% }% \@tempa @@ -3044,6 +3322,7 @@ % % % \begin{key}{adjbox}{bgimage} +% One or two arguments, the first optional one are further \Macro\includegraphics keys. % \begin{macrocode} \define@key{adjbox}{bgimage}{% \@ifnextchar\bgroup{% @@ -3066,7 +3345,7 @@ % % % \begin{macrocode} -\RequirePackage{storebox} +%%\RequirePackage{storebox} % \end{macrocode} % % \begin{macro}{\splitbox} @@ -3213,7 +3492,7 @@ % \end{macrocode} % \end{macro} % -% \begin{key}{adjbox}{split} +% \begin{key}{adjbox}{pagebreak} % \begin{macrocode} \define@key\adjbox@fam{pagebreak}[]{% \adjbox@Gin@Add{\@collectbox{\@pagebreakbox}}% @@ -3570,12 +3849,36 @@ \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\adjbox@default##1##2{% + \begingroup + \message{^^J\detokenize{##2}^^J}% + \def\calc@post@scan####1!{% + \def\@tempa{####1}% + \ifx\@tempa\@empty + \endgroup% to end calc processing + % is number only + \global\@adjbox@needsdefaulttrue + \else + \endgroup% to end calc processing + % full expression + \global\@adjbox@needsdefaultfalse + \fi + }% + \calc@assign@skip{##1}{##2 \adjbox@defaultunit}% + \endgroup + \if@adjbox@needsdefault + ##1=##2 \adjbox@defaultunit\relax + \else + \calc@assign@skip{##1}{##2}% + \fi + }% \def\adjbox@checkdefault##1\@nnil##2##3{% \ifx\relax##1\relax\else \calc@assign@skip{##2}{##3}% \fi }% } +\newif\if@adjbox@needsdefault % \end{macrocode} % \end{macro} % @@ -3617,34 +3920,202 @@ % \iffalse %<*adjpgf.def> % \fi +% \iffalse +%<!COPYRIGHT> +% \fi +% \begin{macrocode} +\ProvidesFile{adjpgf.def}[% +%<!DATE> +%<!VERSION> +%<*DRIVER> + 2099/01/01 develop +%</DRIVER> + adjustbox fall-back clip driver using PGF] +% \end{macrocode} +% % \begin{macrocode} \RequirePackage{pgf} % \end{macrocode} % -% \begin{macro}{\@trimbox} +% \begin{macro}{\@cliptoboxdim} +% Clips to official box dimension. % \begin{macrocode} -\def\@clipbox#1#2#3#4#5{% - \@trimbox{#1}{#2}{#3}{#4}{#5}% - \setbox#5\hbox{\begin{pgfpicture}% - \pgfpathmoveto{\pgfqpoint\z@{-\dp#5}}% - \pgfpathlineto{\pgfqpoint\z@{\ht#5}}% - \pgfpathlineto{\pgfqpoint{\wd#5}{\ht#5}}% - \pgfpathlineto{\pgfqpoint{\wd#5}{-\dp#5}}% +\def\@cliptoboxdim#1{% + \setbox#1\hbox{\begin{pgfpicture}% + \pgfpathmoveto{\pgfqpoint\z@{-\dp#1}}% + \pgfpathlineto{\pgfqpoint\z@{\ht#1}}% + \pgfpathlineto{\pgfqpoint{\wd#1}{\ht#1}}% + \pgfpathlineto{\pgfqpoint{\wd#1}{-\dp#1}}% \pgfpathclose \pgfusepathqclip \pgfset{inner sep=\z@,outer sep=\z@,minimum size=\z@}% - \pgfnode{rectangle}{base west}{\usebox#5}{}{}% + \pgfnode{rectangle}{base west}{\usebox#1}{}{}% \pgfsetbaselinepointnow{\pgfpoint\z@\z@}% \end{pgfpicture}}% } % \end{macrocode} % \end{macro} -%<VIM> vim: ft=tex % % \iffalse +% vim: ft=tex +% \fi +% \iffalse %</adjpgf.def> % \fi % % +% \iffalse +%<*adjpdftex.def> +% \fi +% \iffalse +%<!COPYRIGHT> +% \fi +% \begin{macrocode} +\ProvidesFile{adjpdftex.def}[% +%<!DATE> +%<!VERSION> +%<*DRIVER> + 2099/01/01 develop +%</DRIVER> + adjustbox clip driver for pdftex] +% \end{macrocode} +% +% +% \begin{macro}{\@cliptoboxdim} +% Clips to official box dimension. +% +% Uses a PDF X-Object which has the side-effect of clipping. +% TODO: Rewrite to use clipping path? +% \begin{macrocode} +\def\@cliptoboxdim#1{% + \pdfxform#1% + \setbox#1=\hbox{% + \pdfrefxform\pdflastxform + }% +} +% \end{macrocode} +% \end{macro} +% +% \iffalse +% vim: ft=tex +% \fi +% \iffalse +%</adjpdftex.def> +% \fi +% +% +% \iffalse +%<*adjdvips.def> +% \fi +% \iffalse +%<!COPYRIGHT> +% \fi +% \begin{macrocode} +\ProvidesFile{adjdvips.def}[% +%<!DATE> +%<!VERSION> +%<*DRIVER> + 2099/01/01 develop +%</DRIVER> + adjustbox clip driver for dvips] +% \end{macrocode} +% +% +% \begin{macro}{\@cliptoboxdim}[1]{box register to clip} +% Clips to official box dimension. +% +% The following clipping code was suggested by +% Joseph Wright (LaTeX3 project), but slightly modified +% for this package. +% \begin{macrocode} +\def\@cliptoboxdim#1{% + \setbox#1=\hbox{% + \adjsetlength\@tempdima{\ht#1+\dp#1}% + \edef\TOTALHEIGHT{-\strip@pt\@tempdima\space}% + \edef\DEPTH{\strip@pt\dp#1\space}% + \edef\WIDTH{\strip@pt\wd#1\space}% + \special{% + ps: + /mtrxc matrix currentmatrix def + currentpoint gsave + translate + Resolution 72 div VResolution 72 div + scale + newpath + 0 \DEPTH \WIDTH \TOTALHEIGHT rectclip + newpath + mtrxc setmatrix + }% + \box#1% + \special{ps: grestore }% + }% +} +% \end{macrocode} +% \end{macro} +% +% \iffalse +% vim: ft=tex +% \fi +% \iffalse +%</adjdvips.def> +% \fi +% +% +% \iffalse +%<*adjxetex.def> +% \fi +% \iffalse +%<!COPYRIGHT> +% \fi +% \begin{macrocode} +\ProvidesFile{adjpdftex.def}[% +%<!DATE> +%<!VERSION> +%<*DRIVER> + 2099/01/01 develop +%</DRIVER> + adjustbox clip driver for pdftex] +% \end{macrocode} +% +% +% \begin{macro}{\@cliptoboxdim} +% Clips to official box dimension. +% +% The following clipping code was suggested by +% Joseph Wright (LaTeX3 project), but slightly modified +% for this package. +% \begin{macrocode} +\def\@cliptoboxdim#1{% + \setbox#1=\hbox{% + \Gin@defaultbp\WIDTH{\wd#1}% + \Gin@defaultbp\DEPTH{\dp#1}% + \@tempdima\ht#1% + \advance\@tempdima\dp#1% + \Gin@defaultbp\TOTALHEIGHT{\@tempdima}% + \special{pdf:content q }% + \special{% + pdf:literal direct + 0 -\DEPTH\space \WIDTH\space \TOTALHEIGHT\space re + }% + \special{pdf:literal direct W }% + \special{pdf:literal direct n }% + \special{pdf:literal direct -1 0 0 -1 0 0 cm }% + \special{pdf:content q }% + \special{pdf:literal direct -1 0 0 -1 0 0 cm }% + \box#1% + \special{pdf:literal direct Q }% + \special{pdf:literal direct Q }% + }% +} +% \end{macrocode} +% \end{macro} +% +% \iffalse +% vim: ft=tex +% \fi +% \iffalse +%</adjxetex.def> +% \fi +% % \Finale % \endinput |