Debian Codegraph @

texmf-dist/source/latex/grabbox/grabbox.dtx

raw
1 % \iffalse meta-comment
2 %
3 % File: grabbox.dtx Copyright (C) 2018-2019 Jonathan P. Spratte
4 %
5 % It may be distributed and/or modified under the conditions of the LaTeX
6 % Project Public License (LPPL), either version 1.3c of this license or (at your
7 % option) any later version. The latest version of this license is in the file
8 %
9 % https://www.latex-project.org/lppl.txt
10 %
11 % ------------------------------------------------------------------------------
12 %
13 %<*driver>
14 \def\nameofplainTeX{plain}
15 \ifx\fmtname\nameofplainTeX\else
16 \expandafter\begingroup
17 \fi
18 \input l3docstrip.tex
19 \askforoverwritefalse
20 \preamble
21
22 --------------------------------------------------------------
23 grabbox -- utilities to get an argument as a box
24 E-mail: [email protected]
25 Released under the LaTeX Project Public License v1.3c or later
26 See http://www.latex-project.org/lppl.txt
27 --------------------------------------------------------------
28
29 Copyright (C) 2018-2019 Jonathan P. Spratte
30
31 This work may be distributed and/or modified under the conditions of the
32 LaTeX Project Public License (LPPL), either version 1.3c of this license or
33 (at your option) any later version. The latest version of this license is in
34 the file:
35
36 http://www.latex-project.org/lppl.txt
37
38 This work is "maintained" (as per LPPL maintenance status) by
39 Jonathan P. Spratte.
40
41 This work consists of the file grabbox.dtx
42 and the derived files grabbox.pdf and
43 grabbox.sty.
44
45 \endpreamble
46 % stop docstrip adding \endinput
47 \postamble
48 \endpostamble
49 \generate{\file{grabbox.sty}{\from{grabbox.dtx}{pkg}}}
50 \ifx\fmtname\nameofplainTeX
51 \expandafter\endbatchfile
52 \else
53 \expandafter\endgroup
54 \fi
55 %</driver>
56 %
57 %<*driver>
58 \ProvidesFile{grabbox.dtx}
59 [%
60 \csname grabbox@date\endcsname\space
61 utilities to get an argument as a box%
62 ]
63 \expandafter\def\csname @classoptionslist\endcsname{}
64 \RequirePackage[british]{babel}
65 \documentclass{l3doc}
66 \usepackage{duckuments}
67 \usepackage{microtype}
68 \usepackage{grabbox}
69 \renewcommand*{\thefootnote}{\fnsymbol{footnote}}
70 \let\metaOrig\meta
71 \renewcommand\meta[1]
72 {%
73 \texttt{\metaOrig{#1}}%
74 }
75 \begin{document}
76 \DocInput{grabbox.dtx}
77 \end{document}
78 %</driver>
79 %<*pkg>
80 \newcommand*\grabbox@date{2019-05-08}
81 \newcommand*\grabbox@version{1.4}
82 \ProvidesPackage{grabbox}
83 [%
84 \grabbox@date\space v\grabbox@version\space utilities to get an argument as
85 a box%
86 ]
87 %</pkg>
88 % \fi
89 %
90 % \begin{center}
91 % \LARGE The \pkg{grabbox} package\\[\bigskipamount]
92 % \large
93 % \setcounter{footnote}{1}%
94 % Jonathan P. Spratte\footnotemark\\[\medskipamount]
95 % Version \csname grabbox@version\endcsname\\[\smallskipamount]
96 % Released \csname grabbox@date\endcsname
97 % \end{center}
98 % \footnotetext{E-mail: [email protected]}
99 %
100 % \tableofcontents
101 %
102 % \begin{documentation}
103 %
104 % \section{Introduction}
105 %
106 % Sometimes I happen to write macros and environments which don't care for the
107 % exact contents of an argument but only for that contents' typeset
108 % representation and its dimensions. In that case I personally dislike the fact
109 % that those arguments couldn't contain verbatim material if coded straight
110 % forward for macros. For environments this is quite easy to create thanks to
111 % \env{lrbox}, for macros this approach unfortunately doesn't work without the
112 % enduser's cooperation. Thus the macros distributed hereby came into existence.
113 %
114 % This package provides \cs{grabbox} to grab an argument inside of a box. The
115 % used mechanism allows category code changes in that argument as long as it is
116 % used in a place allowing category code changes (so not inside of another
117 % argument).
118 %
119 % It is written as a docstrip file: executing |latex grabbox.dtx| generates the
120 % \file{grabbox.sty} file and typesets this documentation; execute
121 % |tex grabbox.dtx| to only generate \file{grabbox.sty}.
122 %
123 % \section{Acknowledgement}
124 %
125 % I want to thank Enrico Gregorio for helping me develop first versions of the
126 % used mechanisms for the second iteration of my \pkg{ducksay} package. If he
127 % hadn't helped me back then, I wouldn't have considered the used method
128 % further -- because the user interface would've been too clumsy and require
129 % strange markup like |\foo arg}| -- and therefore this package wouldn't have
130 % been created.
131 %
132 % Additionally I want to thank David Carlisle for helping me making \cs{grabbox}
133 % respect surrounding text colours.
134 %
135 % \section{The macro}
136 %
137 % \begin{function}{\grabbox}
138 % \begin{syntax}
139 % \cs{grabbox}\meta{*}\oarg{inject pre pre}\ignorespaces^^A
140 % \marg{box register}\oarg{inject pre}\marg{box type}\ignorespaces^^A
141 % \oarg{inject post}\marg{afterwards}
142 % \end{syntax}
143 % grabs the next braced argument and stores it inside of the box \meta{box
144 % register}. The box is of \meta{box type}, which should be one of \cs{hbox}
145 % or \cs{vbox} or \cs{vtop}. The contents of the box except for
146 % \meta{inject pre pre} and \meta{inject post} will be contained in an
147 % additional level of grouping to ensure colour safety (similar to \LaTeX's
148 % \cs{sbox}). \meta{inject pre pre} will be injected at the beginning of the
149 % box before this additional group is opened, \meta{inject pre} will be
150 % injected at the beginning of the box and can affect its contents,
151 % \meta{inject post} will be injected at the end of the box but can't be
152 % affected by stuff inside of \meta{inject pre} or added content unless they
153 % are using global definitions -- \meta{inject pre pre} however can affect the
154 % contents of \meta{inject post}.
155 % Unless the \meta{*} is given leading and trailing spaces will be stripped
156 % from the box. After the box is read in \meta{afterwards} will be inserted.
157 % The complete contents of the box will be something like:
158 % \begin{center}
159 % \csname verbatim@font\endcsname
160 % \meta{inject pre pre}^^A
161 % \{\cs{set@color}\meta{inject pre}\meta{argument}\}^^A
162 % \meta{inject post}
163 % \end{center}
164 % \end{function}
165 %
166 % \smallskip
167 % All assignments are made local. Currently it is not safe to nest macros
168 % which use \cs{grabbox}. It should become safe if your macros use
169 % \cs{grabbox} inside of a group, so the inner \cs{grabbox} doesn't affect the
170 % outer one.
171 %
172 % \cs{grabbox} uses \cs{afterassignment} and \cs{aftergroup} to do its magic.
173 % The former should be safe where it is used, the latter is used inside of the
174 % boxed argument before any contents are inserted.
175 %
176 % Since \cs{grabbox} works by setting a boxregister using \cs{setbox} (and a
177 % bunch of temporary macros), it is of course not expandable and defined
178 % \cs{protected}.
179 %
180 % \begin{function}{\@grabbox}
181 % \begin{syntax}
182 % \cs{@grabbox}\meta{*}\marg{inject pre pre}\ignorespaces^^A
183 % \marg{box register}\marg{inject pre}\marg{box type}\ignorespaces^^A
184 % \marg{inject post}\marg{afterwards}
185 % \end{syntax}
186 % This is a variant of \cs{grabbox} that should be faster because it doesn't
187 % parse for optional arguments. Instead every argument is mandatory except for
188 % the star, just leave the arguments empty if you'd otherwise not use the
189 % corresponding optional argument in \cs{grabbox}.
190 % \end{function}
191 %
192 % \section{Useless Example!}
193 %
194 % First we need to reserve us a box register for this example:
195 % \begin{verbatim}
196 % \newsavebox\ourbox
197 % \end{verbatim}
198 % Next we define a macro which takes some arguments and uses \cs{grabbox}:
199 % \begin{verbatim}
200 % \newcommand\examplecmd[2]
201 % {%
202 % \begingroup
203 % \grabbox\ourbox[\itshape]\hbox[ \sffamily is]{\examplecmdOut{#1}{#2}}
204 % }
205 % \end{verbatim}
206 % And we need our helper macro which is executed after \cs{grabbox}:
207 % \begin{verbatim}
208 % \newcommand\examplecmdOut[3]
209 % {%
210 % \begin{tabular}[t]{@{}ll@{}}
211 % Arg1: & #1\\
212 % Arg2: & #2\\
213 % Box: & \unhbox\ourbox\\
214 % Arg3: & #3
215 % \end{tabular}%
216 % \endgroup
217 % }
218 % \end{verbatim}
219 %
220 % The result is a macro that takes two ordinary arguments, after those a
221 % box in horizontal mode and finally another ordinary argument. If we use this
222 % macro we get the following:
223 % \begin{center}
224 % \newsavebox\ourbox
225 % \newcommand\examplecmd[2]
226 % {%
227 % \begingroup
228 % \grabbox\ourbox[\itshape]\hbox[ \sffamily is]{\examplecmdOut{#1}{#2}}
229 % }%
230 % \newcommand\examplecmdOut[3]
231 % {%
232 % \begin{tabular}[t]{@{}ll@{}}
233 % Arg1: & #1\\
234 % Arg2: & #2\\
235 % Box: & \unhbox\ourbox\\
236 % Arg3: & #3
237 % \end{tabular}%
238 % \endgroup
239 % }%
240 % \examplecmd{Hi,}{my}{\verb|\name|}{Steve!}
241 % \end{center}
242 % One can see that \verb|\sffamily is| in \meta{inject post} is not affected by
243 % the |\itshape| in \meta{inject pre}. The used code to generate that table was:
244 %
245 % \begin{verbatim}
246 % \examplecmd{Hi,}{my}{\verb|\name|}{Steve!}
247 % \end{verbatim}
248 %
249 % \section{Useful Example?}
250 %
251 % This example provides a macro which typesets its mandatory argument in a block
252 % of a definable number of lines, it is meant for a single paragraph.
253 %
254 % \begin{verbatim}
255 % % Getting a box register:
256 % \newsavebox\RectangleBox
257 % % Defining the main macro:
258 % \newcommand\Rectangle[1][4]
259 % {%
260 % \begingroup
261 % \grabbox\RectangleBox\hbox
262 % {%
263 % % Since we don't want to read more arguments after the box,
264 % % we don't need a second macro and can put the output routine
265 % % here.
266 % \begin{minipage}{\dimexpr\wd\RectangleBox/#1\relax}
267 % \parfillskip0pt
268 % \unhbox\RectangleBox
269 % \end{minipage}%
270 % \endgroup
271 % }%
272 % }
273 % \end{verbatim}
274 %
275 % As you can see, this macro uses \cs{grabbox} in a group delimited by
276 % \cs{begingroup} and \cs{endgroup} -- like the useless example. It should
277 % therefore be safe to nest it inside other macros using \cs{grabbox}.
278 %
279 % Finally a usage example of our new macro (with the \pkg{duckuments} package
280 % loaded):
281 %
282 % \begin{verbatim}
283 % \begin{center}
284 % \Rectangle[9]{\blindduck}
285 % \end{center}
286 % \end{verbatim}
287 % Results in:
288 % \begin{center}
289 % \newsavebox\RectangleBox
290 % \newcommand\Rectangle[1][4]
291 % {%
292 % \begingroup
293 % \grabbox\RectangleBox\hbox
294 % {%
295 % \begin{minipage}{\dimexpr\wd\RectangleBox/#1\relax}
296 % \parfillskip0pt
297 % \unhbox\RectangleBox
298 % \end{minipage}%
299 % \endgroup
300 % }%
301 % }
302 % \Rectangle[9]{\blindduck}
303 % \end{center}
304 %
305 % \end{documentation}
306 %
307 % \begin{implementation}
308 %
309 % \section{Implementation}
310 %
311 % \begin{macrocode}
312 %<*pkg>
313 % \end{macrocode}
314 %
315 % \begin{macrocode}
316 \@ifdefinable{\if@grabbox@spaces@}{\newif\if@grabbox@spaces@}
317 \@ifdefinable{\grabbox@def}
318 {\long\def\grabbox@def#1#2#{\grabbox@def@a{}#1{#2}}}
319 \@ifdefinable{\grabbox@ldef}
320 {\long\def\grabbox@ldef#1#2#{\grabbox@def@a\long#1{#2}}}
321 \@ifdefinable{\grabbox@def@a}
322 {%
323 \protected\long\def\grabbox@def@a#1#2#3#4%
324 {\@ifdefinable#2{\protected#1\def#2#3{#4}}}%
325 }
326 \newcommand\grabbox@def@step[4]
327 {%
328 \grabbox@def#1##1{\def#2{##1}\grabbox@opt#3#4}%
329 }
330 \grabbox@def\grabbox@opt#1#2%
331 {%
332 \@ifnextchar[
333 {\grabbox@opt@get#1#2}
334 {\def#1{}#2}%
335 }
336 \grabbox@ldef\grabbox@opt@get#1#2[#3]%
337 {%
338 \def#1{#3}#2%
339 }
340 \grabbox@def\grabbox@set@color
341 {%
342 \@ifundefined{set@color}{}
343 {\global\let\grabbox@set@color\set@color\grabbox@set@color}%
344 }
345 \AtBeginDocument
346 {%
347 \@ifundefined{set@color}
348 {\gdef\grabbox@set@color{}}
349 {\global\let\grabbox@set@color\set@color}%
350 }%
351 \newcommand*\grabbox@unskip@space
352 {%
353 \ifhmode\unskip\fi
354 }
355 \grabbox@def\grabbox
356 {%
357 \@ifstar
358 {\@grabbox@spaces@true\grabbox@a}
359 {\@grabbox@spaces@false\grabbox@a}%
360 }
361 \grabbox@def\grabbox@a
362 {%
363 \grabbox@opt\grabbox@into@prepre\grabbox@b
364 }
365 \grabbox@def@step\grabbox@b\grabbox@name\grabbox@into@pre\grabbox@c
366 \grabbox@def@step\grabbox@c\grabbox@type\grabbox@into@post\grabbox@d
367 \grabbox@ldef\grabbox@d#1%
368 {%
369 \def\grabbox@final{#1}%
370 \afterassignment\grabbox@intermediate
371 \setbox\grabbox@name\grabbox@type
372 }
373 \grabbox@def\@grabbox
374 {%
375 \@ifstar
376 {\@grabbox@spaces@true\@grabbox@a}
377 {\@grabbox@spaces@false\@grabbox@a}%
378 }
379 \grabbox@ldef\@grabbox@a#1#2#3#4#5%
380 {%
381 \def\grabbox@into@prepre{#1}%
382 \def\grabbox@name {#2}%
383 \def\grabbox@into@pre {#3}%
384 \def\grabbox@type {#4}%
385 \def\grabbox@into@post {#5}%
386 \grabbox@d
387 }
388 \grabbox@def\grabbox@intermediate
389 {%
390 \grabbox@into@prepre
391 \bgroup
392 \if@grabbox@spaces@
393 \else
394 \aftergroup\grabbox@unskip@space
395 \fi
396 \grabbox@set@color
397 \aftergroup\grabbox@after
398 \grabbox@into@pre
399 \if@grabbox@spaces@
400 \else
401 \ignorespaces
402 \fi
403 }
404 \newcommand*\grabbox@after@aux@b[1]
405 {%
406 \grabbox@after@aux@a
407 }
408 \grabbox@def\grabbox@after@aux@a
409 {%
410 \@ifnextchar\reset@color
411 {\reset@color\grabbox@after@aux@b}
412 {\egroup\grabbox@final}%
413 }
414 \grabbox@def\grabbox@after
415 {%
416 \grabbox@into@post
417 \endgraf
418 \grabbox@after@aux@a
419 }
420 % \end{macrocode}
421 %
422 % \begin{macrocode}
423 \endinput
424 % \end{macrocode}
425 %
426 % \end{implementation}
427 %
428 % \begin{macrocode}
429 %</pkg>
430 % \end{macrocode}