% \iffalse meta-comment % % Copyright (C) 2011 by Martin Scharrer % --------------------------------------------------------------------------- % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 % of this license or (at your option) any later version. % The latest version of this license is in % http://www.latex-project.org/lppl.txt % and version 1.3 or later is part of all distributions of LaTeX % version 2005/12/01 or later. % % This work has the LPPL maintenance status `maintained'. % % The Current Maintainer of this work is Martin Scharrer. % % This work consists of the files collectbox.dtx and collectbox.ins % and the derived filebase collectbox.sty. % % \fi % % \iffalse %<*driver> \ProvidesFile{collectbox.dtx} % % %<*driver> \documentclass{ydoc} \usepackage{collectbox}[2011/07/23] \EnableCrossrefs \CodelineIndex \RecordChanges %\OnlyDescription \begin{document} \DocInput{collectbox.dtx} \PrintChanges \PrintIndex \end{document} % % \fi % % \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 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z % Digits \0\1\2\3\4\5\6\7\8\9 % Exclamation \! Double quote \" Hash (number) \# % Dollar \$ Percent \% Ampersand \& % Acute accent \' Left paren \( Right paren \) % Asterisk \* Plus \+ Comma \, % Minus \- Point \. Solidus \/ % Colon \: Semicolon \; Less than \< % Equals \= Greater than \> Question mark \? % Commercial at \@ Left bracket \[ Backslash \\ % Right bracket \] Circumflex \^ Underscore \_ % Grave accent \` Left brace \{ Vertical bar \| % Right brace \} Tilde \~} % % % \changes{v0.1}{2011/07/18}{First release.} % \changes{v0.2}{2011/07/20}{Added \cs{collectboxto} and \cs{@collectboxto} macros.} % \changes{v0.2}{2011/07/23}{Added \cs{collectboxcheckenv}.} % % \DoNotIndex{\newcommand,\newenvironment} % % \providecommand*{\url}{\texttt} % \GetFileInfo{collectbox.dtx} % \title{The \textsf{collectbox} package} % \author{Martin Scharrer\\ \url{martin@scharrer-online.de}} % \date{\fileversion~from \filedate} % % \maketitle % % \begin{abstract} % This package provides macros to collect and process an macro argument (i.e.\ something which looks like a macro argument) % as horizontal box instead as a real macro argument. % These ``arguments'' will be stored like when using \Macro\savebox, \Macro\sbox or the \env{lrbox} environment % and allow verbatim or other special code. % Instead of explicit braces also implicit braces in the form of \Macro\bgroup % and \Macro\egroup are supported. This allows to split the begin and end over different macros or to place them % in the begin and end code of an environment. % The provided macros are mainly intended to be used inside other macros or environments. % % {\bfseries\color{red}Disclaimer: This is an beta release of this package and the code might still change in future releases.} % \end{abstract} % % \section{Quick overview} % The following macros are provided for users (document authors) and \LaTeX\ package authors/programmers and described in the following sections. % The \MacroArgs* and \MacroArgs[<\ldots>] arguments are as always optional. The \MacroArgs{} can also be written as % \Macro\bgroup\AlsoMacro\egroup and be split across macro boundaries. % % \begingroup % \descindent=\parindent % \DescribeMacro\collectbox*[]{}[]{} % \DescribeMacro\collectboxto{}{}{} % \DescribeMacro\collectboxcheckenv{} % % \DescribeMacro\collectbox@{}{}{}{} % \DescribeMacro\@collectbox{}{} % \DescribeMacro\@collectboxto{}{}{} % \DescribeMacro\nocollectbox@{}{}{} % \endgroup % % \section{Dependencies, Compatibility and Installation} % This package does not depend on any other \LaTeX\ package or class. % It should be compatible with all versions of \LaTeX (DVI-\LaTeX, pdf\LaTeX, Xe\LaTeX\ and Lua\LaTeX). % Colored content will be correctly handled. % % This package should be (soon) part of the standard distributions TeXLive and MikTeX and can be installed over the % provided package manager (i.e.\ TeXLive: |tlmgr install collectcell|). % This package can be also manually unpacked from |collectbox.dtx| by compiling the file |collectbox.ins| with \LaTeX\ or \TeX. % This documentation can be created by compiling |collectbox.dtx| using pdf\LaTeX\ in DVI or PDF mode. % The unpackaged package file |collectbox.sty| should be copied to a newly created directory |$TEXMF/tex/latex/collectbox/| under Linux % or |%TEXMF%\tex\latex\collectbox\| under MS Windows where |$TEXMF| and |%TEXMF%| represents the local \TeX\ tree. % The documentation and README file can be copied to |$TEXMF/doc/latex/collectbox/|. % Some \TeX\ distributions require to update the list of files in the \TeX\ tree, e.g.\ by running |texmf $TEXMF| afterwards. % MikTeX users can use the graphical interface of the package manager. % % % \section{User Interface} % The following macros are provided on the user level. % % \subsection{Macros to collect boxes} % \DescribeMacro\collectbox{}{} % \DescribeMacro\collectbox{}\AlsoMacro\bgroup\AlsoMacro\egroup % In its basic form this macro is written as \Macro\collectbox{} and collects the following `group' in explicit (|{ .. }|) or implicit (|\bgroup .. \egroup|) braces % as box (here represented as \MacroArgs{}). Afterwards the user provided \MacroArgs is executed. This code is processed inside an internal group % and has access to the just collected content using \Macro\BOXCONTENT and other macros described further below. Usually the code does some calculations and/or modifications % on the collected box and then typesets it using \Macro\BOXCONTENT. % % An example is % \codeline{\Macro\collectbox{\AlsoMacro\fbox{\AlsoMacro\BOXCONTENT}}'{\verb+verbatim stuff \space\empty+}'} % which results in % \codeline{\collectbox{\fbox{\BOXCONTENT}}{\verb+verbatim stuff \space\empty+}} % % \DescribeMacro\collectbox*{}{} % \DescribeMacro\collectbox*{}\AlsoMacro\bgroup\AlsoMacro\egroup % Because very often the \Macro\BOXCONTENT is simply fed as argument to a macro at the end of the \MacroArgs a star version exists which adds \MacroArgs{\AlsoMacro\BOXCONTENT} automatically % to the end of the code. % % An above example can be therefore simplified as: % \codeline{\Macro\collectbox*{\AlsoMacro\fbox}'{\verb+verbatim stuff \space\empty+}'} % which results in: % \codeline{\collectbox*{\fbox}{\verb+verbatim stuff \space\empty+}} % % \noindent % Using this macro a \Macro\fbox variant can be defined which reads its content as real box and not as macro argument: % \codeline{\Macro\newcommand{\AlsoMacro\Fbox}{\AlsoMacro\collectbox*{\AlsoMacro\fbox}}} % % \DescribeMacro\collectbox []{}[]{} % \DescribeMacro\collectbox []{}[]\AlsoMacro\bgroup\AlsoMacro\egroup % \DescribeMacro\collectbox*[]{}[]{} % \DescribeMacro\collectbox*[]{}[]\AlsoMacro\bgroup\AlsoMacro\egroup % Finally two optional arguments exists which allow the placement of further code at the beginning and end of the collected box. % This code is part of the box and is expanded before the main \MacroArgs which is expanded after the box is fully collected. % In other words \Macro\collectbox!\optionaloff! []{}[]{} is basically the same as % \Macro\collectbox{}{<.><.>}, with the difference that the first form allows an user defined macro % to set the begin and end code while the box content is provided by the user. % Note that there is also some internal code \meta{.} between \meta{code at begin} and \meta{box content} as well as between \meta{box content} and \meta{code at end}. % % \paragraph{Example:} \leavevmode\Macro\fbox like macro which reads its ``argument'' as box and sets it green first: % \begin{macroquote} % \newcommand!\optionaloff!{\AlsoMacro\GFbox}{\AlsoMacro\collectbox*[\AlsoMacro\color{green}]{\AlsoMacro\fbox}}\\ % \GFbox{'test $a=4$ \verb|\relax|'} % \end{macroquote} % will result in: % {\newcommand{\GFbox}{\collectbox*[\color{green}]{\fbox}}% % \GFbox{test $a=4$ \verb|\relax|}} % % % \DescribeMacro\collectedbox % This macro represents the box register defined by \Macro\newsavebox\relax which holds the collected box. % It can be used with the \LaTeX's macro \Macro\usebox{} or with plain\TeX\ % macros like \Macro\box, \Macro\copy, \Macro\unhbox or \Macro\unhcopy. % % \DescribeMacro\BOXCONTENT % This macro is short for \Macro\usebox{\AlsoMacro\collectedbox} and will place the collected box into the document. It can be used multiple times inside \MacroArgs. % % \DescribeMacro\width % \DescribeMacro\height % \DescribeMacro\depth % \DescribeMacro\totalheight % These macros represent the dimension of the collected box and can be used inside \MacroArgs\relax. Here \Macro\height is the height of the box above the baseline % and \Macro\depth the lengths how far the box is going below the baseline. Both values added together are provides as \Macro\totalheight. % The box width is given by \Macro\width. % % % \DescribeMacro\collectboxto{}[]{}[]{} % \DescribeMacro\collectboxto{}[]{}[]\AlsoMacro\bgroup\AlsoMacro\egroup % This macro collects its last ``argument'' as horizontal box and stores into into the user provided \meta{box register}. % The \meta{code at begin} and \meta{code at end} are executed at begin and end of the \meta{box content} as part of the box. % Afterwards the user provided \meta{code} is executed. In contrast to \Macro\collectbox no group is added for both the box register assignment or the code % and also none of the above auxiliary macros for the box dimensions and content can be used. The collected box can be typeset using \Macro\usebox{} % and its width, height and depth dimensions can be accessed using the \TeX\ primitives \Macro\wd, \Macro\ht, \Macro\dp. % % Appropriate grouping must be added manually if the overall code should be kept local. Proper places to open and close the group is somewhere before % the \Macro\collectboxto macro and in the \meta{code} after the box was used, respectively. % The box register must be declared beforehand using \Macro\newsavebox\relax (\LaTeX) or \Macro\newbox (\TeX). % The provided box register \Macro\collectedbox can be used here but will be overwritten by further usages of most of the macros of this package. % The \LaTeX\ code also provides \Macro\@tempboxa for temporary usages. % % This macro can be used to create macros which collect more than one argument as box. For this two box registers are required and the \meta{code} of the % first \Macro\collectboxto usage must call it second time. The second \meta{code} then typesets the two boxes. % % \subsection{Support for environments} % % \DescribeMacro\collectboxcheckenv{} % This macro allows macros which use \Macro\collectbox to also be used as an environment. % For this \Macro\collectboxcheckenv must be used before \Macro\collectbox with the macro name as argument. % It then detects if the macro is used by itself or is called by \Macro\begin{} and adjusts the internal configuration % accordantly. In macro-mode it does not change anything, but in environment-mode a \Macro\begingroup is used to keep the configuration changes local. % The corresponding \Macro\end macro need to close then both the box group using \Macro\egroup and then close the outer group \Macro\engroup. % A suitable version is automatically defined if this macro doesn't exists yet. % In environment-mode starting and trailing spaces are ignored which is also the normal behaviour of similar environments like \env{minipage}. % % \paragraph{Example:} Defines \Macro\foobar macro which can also be used as \env{foobar} environment. % \begin{codequote} % \AlsoMacro\newcommand'*'{\Macro\foobar}'{%'\\ % !\mbox{}!~~~~\AlsoMacro\collectboxcheckenv{foobar}'%'\\ % !\mbox{}!~~~~\AlsoMacro\collectbox'*'{\Macro\fbox}'%'\\ % '}'% % \end{codequote} % % % \section{Programmers Interface} % % For the package author/programmer and more advanced users the following internal macros are provided. % If used inside a document file they must be wrapped inside \Macro\makeatletter and \Macro\makeatother\relax (outside the macro which uses them). % % \DescribeMacro\collectbox@{}{}{}{} % This macro is the internal form of \Macro\collectbox with the optional arguments replaced by mandatory ones. % The \Macro\collectbox macro itself uses it after checking for and reading the optional arguments. % If this macro is to be used in other macros this overhead can be avoided by using the internal form directly. % Not used optional arguments can be simply kept empty. The star version is not supported but can be easily substituted by % manually placing the \MacroArgs{\Macro\BOXCONTENT} at the end of \MacroArgs. % % The above example can therefore be written in the faster processed form: % \begin{macroquote} % \makeatletter\\ % \newcommand!\optionaloff!{\AlsoMacro\GFbox}{\AlsoMacro\collectbox@{\AlsoMacro\color{green}}{\AlsoMacro\fbox}{}}\\ % \makeatother\\ % \GFbox{test $a=4$ \verb|\relax|}% % \end{macroquote} % which results in: % {\makeatletter % \newcommand{\GFbox}{\collectbox@{\color{green}}{\fbox{\BOXCONTENT}}{}}% % \makeatother % \tracingall % \GFbox{test $a=4$ \verb|\relax|}% % } % % % \DescribeMacro\@collectbox{}{} % This macro is a short version of \Macro\collectbox and only accepts one argument \MacroArgs besides the later \meta{box content}. % It is intended for quick version for macros which do not need to insert code at begin or after the box content. % % \DescribeMacro\collectboxto@{}{}{}{} % This macro is the internal form of \Macro\collectboxto with the optional arguments replaced by mandatory ones. % The \Macro\collectboxto macro itself uses it after checking for and reading the optional arguments. % If this macro is to be used in other macros this overhead can be avoided by using the internal form directly. % Not used optional arguments can be simply kept empty. % % \DescribeMacro\@collectboxto{}{}{} % This macro is a short version of \Macro\collectboxto and only accepts one \meta{code} argument. % It is intended for quick version for macros which do not need to insert code at begin or after the box content. % % \DescribeMacro\nocollectbox@{}{}{} % Turns a following brace group into basically \Macro\hbox{}. % This is useful if a box needs to be build like that but no actual processing of the content is required, e.g.\ for horizontal alignment only. % Note that there are some internal code between the three code arguments. % % % \StopEventually{} % % \section{Implementation} % % \iffalse %<*package> % \fi % \begin{macrocode} \NeedsTeXFormat{LaTeX2e}[1999/12/01] \ProvidesPackage{collectbox}[2011/07/23 v0.2 Collect macro arguments as boxes] % \end{macrocode} % % \begin{macro}{\collectedbox} % Box register used to store collected box. % \begin{macrocode} \newsavebox\collectedbox % \end{macrocode} % \end{macro} % % \begin{macro}{\collectbox} % User level interface. Scans for potential star and optional arguments. % \begin{macrocode} \newcommand*\collectbox{% \@ifstar {\collectbox@a{{\BOXCONTENT}}}% {\collectbox@a{}}% } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectbox@a} % \begin{macrocode} \long\def\collectbox@a#1{% \@ifnextchar[% {\collectbox@b{#1}}% {\collectbox@b{#1}[]}% } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectbox@b} % \begin{macrocode} \long\def\collectbox@b#1[#2]#3{% \@ifnextchar[% {\collectbox@c{#2}{#3#1}}% {\collectbox@c{#2}{#3#1}[]}% } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectbox@c} % \begin{macrocode} \long\def\collectbox@c#1#2[#3]{% \collectbox@{#1}{#2}{#3}% } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectbox@} % The box is saved using |\setbox|. Color is supported by using |\collectbox@setgroup|. % A brace group is then opened using |\bgroup| which will replace the opening brace of the % ``argument''. The end code is installed in this group using |\aftergroup|. % The opening brace written by the user is then removed by assigning it as token to a dummy variable. % If no |{| or |\bgroup| follows the next token is taken as sole content. % \begin{macrocode} \newcommand\collectbox@[3]{% \begingroup \leavevmode \@temptokena{#3\collectbox@end#2\endgroup}% \setbox\collectedbox\hbox\bgroup \collectbox@setgroup #1\bgroup \aftergroup\the \aftergroup\@temptokena \collectbox@bgroup } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectbox@bgroup} % \begin{macrocode} \def\collectbox@macro@bgroup{% \@ifnextchar\bgroup {\let\@let@token=}% {\collectbox@arg}% } % \end{macrocode} % \end{macro} % % \begin{macro}{\collectbox@env@bgroup} % \begin{macrocode} \def\collectbox@env@bgroup{% \let\collectbox@endcode\relax \let\collectbox@bgroup\collectbox@macro@bgroup \ignorespaces } % \end{macrocode} % \end{macro} % % \begin{macrocode} \let\collectbox@bgroup\collectbox@macro@bgroup % \end{macrocode} % % % \begin{macro}{\collectbox@setgroup} % Used at the very begin of the stored box. % \begin{macrocode} \def\collectbox@setgroup{% \color@setgroup } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectbox@endgroup} % Used at the very end of the stored box. % \begin{macrocode} \def\collectbox@endgroup{% \collectbox@endcode \color@endgroup } \let\collectbox@endcode\relax % \end{macrocode} % \end{macro} % % % \begin{macro}{\@collectbox} % Simpler and quicker version of \Macro\collectbox. % \begin{macrocode} \newcommand\@collectbox[1]{% \begingroup \leavevmode \@temptokena{\collectbox@end#1\endgroup}% \setbox\collectedbox\hbox\bgroup \collectbox@setgroup\bgroup \aftergroup\the \aftergroup\@temptokena \collectbox@bgroup } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectbox@arg} % Supports |\collectbox{}\somemacro| in addition to % |\collectbox{}{\somemacro}|. The first following token is read and the inner brace group is closed % to trigger the |\aftergroup| code. % \begin{macrocode} \def\collectbox@arg#1{% \collectbox@begin#1\egroup } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectbox@end} % The color group is first closed, followed by the closing brace of the |\setbox| command. % The user dimension macros are then defined. % Direct after this code the users code is processed and concluded with a |\endgroup|. % \begin{macrocode} \def\collectbox@end{% \collectbox@endgroup \egroup \def\BOXCONTENT{\usebox\collectedbox}% \def\width{\wd\collectedbox}% \def\height{\ht\collectedbox}% \def\depth{\dp\collectedbox}% \let\totalheight\@ovri \totalheight\height \advance\totalheight\depth } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectbox@code} % Global storage macro for user code. % \begin{macrocode} \let\collectbox@code\empty % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectboxto} % User level interface. Reads box register and checks for optional argument. % \begin{macrocode} \newcommand\collectboxto[1]{% \@ifnextchar[% {\collectboxto@a{#1}}% {\collectboxto@a{#1}[]}% } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectboxto@a} % Reads first optional and next mandatory arguments. % \begin{macrocode} \long\def\collectboxto@a#1[#2]#3{% \@ifnextchar[% {\collectboxto@b{#1}{#2}{#3}}% {\collectboxto@b{#1}{#2}{#3}[]}% } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectboxto@b} % Reads second optional argument. % \begin{macrocode} \long\def\collectboxto@b#1#2#3[#4]{% \collectboxto@{#1}{#2}{#3}{#4}% } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectboxto@}[4]{box register}{code at begin}{code}{code at end} % Installs code and starts to collect the box. % \begin{macrocode} \newcommand\collectboxto@[4]{% \leavevmode \setbox#1\hbox\bgroup \def\collectbox@code{#4\collectbox@endgroup\egroup#3}% \collectbox@setgroup#2\bgroup \aftergroup\collectbox@code \collectbox@bgroup } % \end{macrocode} % \end{macro} % % % \begin{macro}{\@collectboxto} % Collects the next brace group as hbox into box register |#1| and executes token |#2| afterwards. % \begin{macrocode} \newcommand\@collectboxto[2]{% \leavevmode \setbox#1\hbox\bgroup \def\collectbox@code{\collectbox@endgroup\egroup#2}% \collectbox@setgroup\bgroup \aftergroup\collectbox@code \collectbox@bgroup } % \end{macrocode} % \end{macro} % % % \begin{macro}{\nocollectbox@}[3]{}{}{} % Turns a brace group into \Macro\hbox{}. % \begin{macrocode} \newcommand\nocollectbox@[3]{% \leavevmode \hbox\bgroup \def\collectbox@code{#3\egroup#2}% #1\bgroup \aftergroup\collectbox@code \collectbox@bgroup } % \end{macrocode} % \end{macro} % % % \begin{macro}{\collectboxcheckenv} % Checks if current macro is used as environment given by |#1|. % If so the |bgroup| eating macro is redefined. % A suitable end-macro is provided if non exists. All of this is done inside % a group to keep thing local. % \begin{macrocode} \newcommand*\collectboxcheckenv[1]{% \begingroup \def\@tempa{#1}% \ifx\@currenvir\@tempa \edef\@currenvir{\@currenvir\noexpand\empty}% \let\collectbox@bgroup\collectbox@env@bgroup \def\collectbox@endcode{\ifhmode\unskip\fi}% \ifcsname end#1\endcsname\else \@namedef{end#1}{\egroup\endgroup}% \fi \else \endgroup \fi } % \end{macrocode} % \end{macro} % % \endinput % \iffalse % % \fi % % \Finale \endinput