summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/grabbox
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-12-30 22:12:59 +0000
committerKarl Berry <karl@freefriends.org>2018-12-30 22:12:59 +0000
commitf415e2c9d5a865727094a8bca5778bc3de7225ce (patch)
tree841883ce56206ad009dadc71779299fd4b4ecb6e /Master/texmf-dist/source/latex/grabbox
parentfd0e6a66494a3aa9c7e6c66896ba52e83550804e (diff)
grabbox (30dec18)
git-svn-id: svn://tug.org/texlive/trunk@49546 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/grabbox')
-rw-r--r--Master/texmf-dist/source/latex/grabbox/grabbox.dtx102
1 files changed, 61 insertions, 41 deletions
diff --git a/Master/texmf-dist/source/latex/grabbox/grabbox.dtx b/Master/texmf-dist/source/latex/grabbox/grabbox.dtx
index e2a89b96537..98e02ed13b1 100644
--- a/Master/texmf-dist/source/latex/grabbox/grabbox.dtx
+++ b/Master/texmf-dist/source/latex/grabbox/grabbox.dtx
@@ -77,8 +77,8 @@ and the derived files grabbox.pdf and
\end{document}
%</driver>
%<*pkg>
-\newcommand*\grabbox@date{2018-11-29}
-\newcommand*\grabbox@version{1.2}
+\newcommand*\grabbox@date{2018-12-29}
+\newcommand*\grabbox@version{1.3}
\ProvidesPackage{grabbox}
[%
\grabbox@date\space v\grabbox@version\space utilities to get an argument as
@@ -104,7 +104,7 @@ and the derived files grabbox.pdf and
% \section{Introduction}
%
% Sometimes I happen to write macros and environments which don't care for the
-% exact contents of an argument but only for that contents typeset
+% exact contents of an argument but only for that contents' typeset
% representation and its dimensions. In that case I personally dislike the fact
% that those arguments couldn't contain verbatim material if coded straight
% forward for macros. For environments this is quite easy to create thanks to
@@ -128,23 +128,39 @@ and the derived files grabbox.pdf and
% further -- because the user interface would've been too clumsy and require
% strange markup like |\foo arg}| -- and therefore this package wouldn't have
% been created.
+%
+% Additionally I want to thank David Carlisle for helping me making \cs{grabbox}
+% respect surrounding text colours.
%
% \section{The macro}
%
% \begin{function}{\grabbox}
% \begin{syntax}
-% \cs{grabbox}\meta{*}\marg{box register}\ignorespaces^^A
-% \oarg{inject pre}\marg{box type}\oarg{inject post}\ignorespaces^^A
-% \marg{afterwards}
+% \cs{grabbox}\meta{*}\oarg{inject pre pre}\ignorespaces^^A
+% \marg{box register}\oarg{inject pre}\marg{box type}\ignorespaces^^A
+% \oarg{inject post}\marg{afterwards}
% \end{syntax}
% grabs the next braced argument and stores it inside of the box \meta{box
% register}. The box is of \meta{box type}, which should be one of \cs{hbox}
-% or \cs{vbox} or \cs{vtop}. \meta{inject pre} will be injected at the
-% beginning of the box and can affect its contents, \meta{inject post} will be
-% injected at the end of the box but can't be affected by stuff inside of
-% \meta{inject pre} or added content unless they are using global definitions.
+% or \cs{vbox} or \cs{vtop}. The contents of the box except for
+% \meta{inject pre pre} and \meta{inject post} will be contained in an
+% additional level of grouping to ensure colour safety (similar to \LaTeX's
+% \cs{sbox}). \meta{inject pre pre} will be injected at the beginning of the
+% box before this additional group is opened, \meta{inject pre} will be
+% injected at the beginning of the box and can affect its contents,
+% \meta{inject post} will be injected at the end of the box but can't be
+% affected by stuff inside of \meta{inject pre} or added content unless they
+% are using global definitions -- \meta{inject pre pre} however can affect the
+% contents of \meta{inject post}.
% Unless the \meta{*} is given leading and trailing spaces will be stripped
% from the box. After the box is read in \meta{afterwards} will be inserted.
+% The complete contents of the box will be something like:
+% \begin{center}
+% \csname verbatim@font\endcsname
+% \meta{inject pre pre}^^A
+% \{\cs{set@color}\meta{inject pre}\meta{argument}\}^^A
+% \meta{inject post}
+% \end{center}
% \end{function}
%
% \smallskip
@@ -159,8 +175,7 @@ and the derived files grabbox.pdf and
%
% Since \cs{grabbox} works by setting a boxregister using \cs{setbox} (and a
% bunch of temporary macros), it is of course not expandable and defined
-% \cs{protected}. Bear in mind that macros created with \cs{grabbox} are
-% not expandable.
+% \cs{protected}.
%
% \section{Useless Example!}
%
@@ -212,7 +227,7 @@ and the derived files grabbox.pdf and
% }%
% \examplecmd{Hi,}{my}{\verb|\name|}{Steve!}
% \end{center}
-% One can see that \verb|\sffamily is| of \meta{inject post} is not affected by
+% One can see that \verb|\sffamily is| in \meta{inject post} is not affected by
% the |\itshape| in \meta{inject pre}. The used code to generate that table was:
%
% \begin{verbatim}
@@ -246,8 +261,8 @@ and the derived files grabbox.pdf and
% \end{verbatim}
%
% As you can see, this macro uses \cs{grabbox} in a group delimited by
-% \cs{begingroup} and \cs{endgroup}. It should therefore be safe to nest it
-% inside other macros using \cs{grabbox}.
+% \cs{begingroup} and \cs{endgroup} -- like the useless example. It should
+% therefore be safe to nest it inside other macros using \cs{grabbox}.
%
% Finally a usage example of our new macro (with the \pkg{duckuments} package
% loaded):
@@ -287,31 +302,46 @@ and the derived files grabbox.pdf and
%
% \begin{macrocode}
\@ifdefinable{\if@grabbox@spaces@}{\newif\if@grabbox@spaces@}
-
-\@ifdefinable{\grabbox@def}{\long\def\grabbox@def#1#2#{\grabbox@def@a{#1}{#2}}}
+\@ifdefinable{\grabbox@def}
+ {\long\def\grabbox@def#1#2#{\grabbox@def@a{}#1{#2}}}
+\@ifdefinable{\grabbox@ldef}
+ {\long\def\grabbox@ldef#1#2#{\grabbox@def@a\long#1{#2}}}
\@ifdefinable{\grabbox@def@a}
{%
- \protected\long\def\grabbox@def@a#1#2#3%
- {\@ifdefinable#1{\protected\def#1#2{#3}}}%
+ \protected\long\def\grabbox@def@a#1#2#3#4%
+ {\@ifdefinable#2{\protected#1\def#2#3{#4}}}%
}
\newcommand\grabbox@def@step[4]
{%
- \@ifdefinable#1{\grabbox@def#1##1{\def#2{##1}\grabbox@opt#3#4}}%
+ \grabbox@def#1##1{\def#2{##1}\grabbox@opt#3#4}%
}
\long\def\grabbox@afterelsefi#1\else#2\fi{\fi#1}
\long\def\grabbox@afterfi#1\fi{\fi#1}
-\long\def\grabbox@afterelsefiA\else#1\fi#2#3{\fi#2}
-\long\def\grabbox@afterfiB\fi#1#2{\fi#2}
\grabbox@def\grabbox@opt#1#2%
{%
\@ifnextchar[
{\grabbox@opt@get#1#2}
{\def#1{}#2}%
}
-\protected\long\def\grabbox@opt@get#1#2[#3]%
+\grabbox@ldef\grabbox@opt@get#1#2[#3]%
{%
\def#1{#3}#2%
}
+\grabbox@def\grabbox@set@color
+ {%
+ \@ifundefined{set@color}{}
+ {\global\let\grabbox@set@color\set@color\grabbox@set@color}%
+ }
+\AtBeginDocument
+ {%
+ \@ifundefined{set@color}
+ {\gdef\grabbox@set@color{}}
+ {\global\let\grabbox@set@color\set@color}%
+ }%
+\newcommand*\grabbox@unskip@space
+ {%
+ \ifhmode\unskip\fi
+ }
\grabbox@def\grabbox@unpack
{%
\begingroup
@@ -331,31 +361,21 @@ and the derived files grabbox.pdf and
{\@grabbox@spaces@true\grabbox@a}
{\@grabbox@spaces@false\grabbox@a}%
}
-\grabbox@def@step\grabbox@a\grabbox@name\grabbox@into@pre\grabbox@b
-\grabbox@def@step\grabbox@b\grabbox@type\grabbox@into@post\grabbox@c
-\protected\long\def\grabbox@c#1%
+\grabbox@def\grabbox@a
+ {%
+ \grabbox@opt\grabbox@into@prepre\grabbox@b
+ }
+\grabbox@def@step\grabbox@b\grabbox@name\grabbox@into@pre\grabbox@c
+\grabbox@def@step\grabbox@c\grabbox@type\grabbox@into@post\grabbox@d
+\grabbox@ldef\grabbox@d#1%
{%
\def\grabbox@final{#1}%
\afterassignment\grabbox@intermediate
\setbox\grabbox@name\grabbox@type
}
-\grabbox@def\grabbox@set@color
- {%
- \@ifundefined{set@color}{}
- {\global\let\grabbox@set@color\set@color\grabbox@set@color}%
- }
-\AtBeginDocument
- {%
- \@ifundefined{set@color}
- {\gdef\grabbox@set@color{}}
- {\global\let\grabbox@set@color\set@color}%
- }%
-\newcommand*\grabbox@unskip@space
- {%
- \ifhmode\unskip\fi
- }
\grabbox@def\grabbox@intermediate
{%
+ \grabbox@into@prepre
\bgroup
\if@grabbox@spaces@
\else