summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3box.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3box.dtx551
1 files changed, 378 insertions, 173 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
index 281c910e1ce..747d32fc7b3 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
@@ -1,6 +1,8 @@
% \iffalse meta-comment
%
-%% File: l3box.dtx Copyright (C) 2005-2019 The LaTeX3 Project
+%% File: l3box.dtx
+%
+% Copyright (C) 2005-2019 The LaTeX3 Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -41,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2019-01-13}
+% \date{Released 2019-01-28}
%
% \maketitle
%
@@ -92,30 +94,6 @@
% Sets the content of \meta{box_1} equal to that of \meta{box_2}.
% \end{function}
%
-% \begin{function}
-% {
-% \box_set_eq_clear:NN, \box_set_eq_clear:cN,
-% \box_set_eq_clear:Nc, \box_set_eq_clear:cc
-% }
-% \begin{syntax}
-% \cs{box_set_eq_clear:NN} \meta{box_1} \meta{box_2}
-% \end{syntax}
-% Sets the content of \meta{box_1} within the current \TeX{} group
-% equal to that of \meta{box_2}, then clears \meta{box_2} globally.
-% \end{function}
-%
-% \begin{function}
-% {
-% \box_gset_eq_clear:NN, \box_gset_eq_clear:cN,
-% \box_gset_eq_clear:Nc, \box_gset_eq_clear:cc
-% }
-% \begin{syntax}
-% \cs{box_gset_eq_clear:NN} \meta{box_1} \meta{box_2}
-% \end{syntax}
-% Sets the content of \meta{box_1} equal to that of \meta{box_2}, then
-% clears \meta{box_2}. These assignments are global.
-% \end{function}
-%
% \begin{function}[EXP, pTF, added=2012-03-03]
% {\box_if_exist:N, \box_if_exist:c}
% \begin{syntax}
@@ -140,42 +118,6 @@
% \end{texnote}
% \end{function}
%
-% \begin{function}{\box_use_drop:N, \box_use_drop:c}
-% \begin{syntax}
-% \cs{box_use_drop:N} \meta{box}
-% \end{syntax}
-% Inserts the current content of the \meta{box} onto the current
-% list for typesetting. An error is raised if the variable does
-% not exist or if it is invalid.
-%
-% The \meta{box} is then cleared at the group level the
-% box was set at, \emph{i.e.}~the current content is \enquote{dropped} entirely.
-% For example, with
-% \begin{verbatim}
-% \hbox_set:Nn \l_tmpa_box { A }
-% \group_begin:
-% \hbox_set:Nn \l_tmpa_box { B }
-% \group_begin:
-% \box_use_drop:N \l_tmpa_box
-% \group_end:
-% \box_show:N \l_tmpa_box
-% \group_end:
-% \box_show:N \l_tmpa_box
-% \end{verbatim}
-% the first use of \cs{box_show:N} will show an entirely cleared (void) box, and the
-% second will show the letter |A| in the box.
-%
-% This function is useful as boxes can contain an open-ended amount of material. As
-% such, they can have a significant memory impact on \TeX{}. At the same time, it is
-% often the case that once a box has been inserted, it is no longer needed at all.
-% Using \cs{box_use_drop:N} in these circumstances therefore offers improved memory
-% use and performance. It should therefore be preferred over \cs{box_use:N} where
-% it is clear that the content is no longer needed in the variable.
-% \begin{texnote}
-% This is the \TeX{} primitive \tn{box}.
-% \end{texnote}
-% \end{function}
-%
% \begin{function}{\box_move_right:nn, \box_move_left:nn}
% \begin{syntax}
% \cs{box_move_right:nn} \Arg{dimexpr} \Arg{box function}
@@ -237,28 +179,40 @@
% \end{texnote}
% \end{function}
%
-% \begin{function}[updated = 2011-10-22]{\box_set_dp:Nn, \box_set_dp:cn}
+% \begin{function}[updated = 2019-01-22]
+% {
+% \box_set_dp:Nn, \box_set_dp:cn,
+% \box_gset_dp:Nn, \box_gset_dp:cn
+% }
% \begin{syntax}
% \cs{box_set_dp:Nn} \meta{box} \Arg{dimension expression}
% \end{syntax}
% Set the depth (below the baseline) of the \meta{box} to the value of
-% the \Arg{dimension expression}. This is a global assignment.
+% the \Arg{dimension expression}.
% \end{function}
%
-% \begin{function}[updated = 2011-10-22]{\box_set_ht:Nn, \box_set_ht:cn}
+% \begin{function}[updated = 2019-01-22]
+% {
+% \box_set_ht:Nn, \box_set_ht:cn,
+% \box_gset_ht:Nn, \box_gset_ht:cn
+% }
% \begin{syntax}
% \cs{box_set_ht:Nn} \meta{box} \Arg{dimension expression}
% \end{syntax}
% Set the height (above the baseline) of the \meta{box} to the value of
-% the \Arg{dimension expression}. This is a global assignment.
+% the \Arg{dimension expression}.
% \end{function}
%
-% \begin{function}[updated = 2011-10-22]{\box_set_wd:Nn, \box_set_wd:cn}
+% \begin{function}[updated = 2019-01-22]
+% {
+% \box_set_wd:Nn, \box_set_wd:cn,
+% \box_gset_wd:Nn, \box_gset_wd:cn
+% }
% \begin{syntax}
% \cs{box_set_wd:Nn} \meta{box} \Arg{dimension expression}
% \end{syntax}
% Set the width of the \meta{box} to the value of the
-% \Arg{dimension expression}. This is a global assignment.
+% \Arg{dimension expression}.
% \end{function}
%
% \section{Box conditionals}
@@ -475,18 +429,6 @@
% \end{texnote}
% \end{function}
%
-% \begin{function}{\hbox_unpack_clear:N, \hbox_unpack_clear:c}
-% \begin{syntax}
-% \cs{hbox_unpack_clear:N} \meta{box}
-% \end{syntax}
-% Unpacks the content of the horizontal \meta{box}, retaining any stretching
-% or shrinking applied when the \meta{box} was set. The \meta{box} is
-% then cleared globally.
-% \begin{texnote}
-% This is the \TeX{} primitive \tn{unhbox}.
-% \end{texnote}
-% \end{function}
-%
% \section{Vertical mode boxes}
%
% Vertical boxes inherit their baseline from their contents. The
@@ -623,13 +565,91 @@
% \end{texnote}
% \end{function}
%
-% \begin{function}{\vbox_unpack_clear:N, \vbox_unpack_clear:c}
+% \section{Using boxes efficiently}
+%
+% The functions above for using box contents work in exactly the same
+% way as for any other \pkg{expl3} variable. However, for efficiency
+% reasons, it is also useful to have functions which \emph{drop} box
+% contents on use. When a box is dropped, the box becomes empty at the group
+% level \emph{where the box was originally set} rather than necessarily
+% \emph{at the current group level}. For example, with
+% \begin{verbatim}
+% \hbox_set:Nn \l_tmpa_box { A }
+% \group_begin:
+% \hbox_set:Nn \l_tmpa_box { B }
+% \group_begin:
+% \box_use_drop:N \l_tmpa_box
+% \group_end:
+% \box_show:N \l_tmpa_box
+% \group_end:
+% \box_show:N \l_tmpa_box
+% \end{verbatim}
+% the first use of \cs{box_show:N} will show an entirely cleared (void) box, and the
+% second will show the letter |A| in the box.
+%
+% These functions should be preferred when the content of the box is no
+% longer required after use. Note that due to the unusual scoping behaviour of
+% \texttt{drop} functions they may be applied to both local and global boxes:
+% the latter will naturally be set and thus cleared at a global level.
+%
+% \begin{function}{\box_use_drop:N, \box_use_drop:c}
+% \begin{syntax}
+% \cs{box_use_drop:N} \meta{box}
+% \end{syntax}
+% Inserts the current content of the \meta{box} onto the current
+% list for typesetting then drops the box content. An error is raised if the
+% variable does not exist or if it is invalid. This function may be applied to
+% local or global boxes.
+% \begin{texnote}
+% This is the \tn{box} primitive.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[added = 2019-01-17]
+% {
+% \box_set_eq_drop:NN, \box_set_eq_drop:cN,
+% \box_set_eq_drop:Nc, \box_set_eq_drop:cc
+% }
% \begin{syntax}
-% \cs{vbox_unpack:N} \meta{box}
+% \cs{box_set_eq_drop:NN} \meta{box_1} \meta{box_2}
+% \end{syntax}
+% Sets the content of \meta{box_1} equal to that of \meta{box_2}, then
+% drops \meta{box_2}.
+% \end{function}
+%
+% \begin{function}[added = 2019-01-17]
+% {
+% \box_gset_eq_drop:NN, \box_gset_eq_drop:cN,
+% \box_gset_eq_drop:Nc, \box_gset_eq_drop:cc
+% }
+% \begin{syntax}
+% \cs{box_gset_eq_drop:NN} \meta{box_1} \meta{box_2}
+% \end{syntax}
+% Sets the content of \meta{box_1} globally equal to that of \meta{box_2},
+% then drops \meta{box_2}.
+% \end{function}
+%
+% \begin{function}[added = 2019-01-17]
+% {\hbox_unpack_drop:N, \hbox_unpack_drop:c}
+% \begin{syntax}
+% \cs{hbox_unpack_drop:N} \meta{box}
+% \end{syntax}
+% Unpacks the content of the horizontal \meta{box}, retaining any stretching
+% or shrinking applied when the \meta{box} was set. The original \meta{box}
+% is then dropped.
+% \begin{texnote}
+% This is the \TeX{} primitive \tn{unhbox}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[added = 2019-01-17]
+% {\vbox_unpack_drop:N, \vbox_unpack_drop:c}
+% \begin{syntax}
+% \cs{vbox_unpack_drop:N} \meta{box}
% \end{syntax}
% Unpacks the content of the vertical \meta{box}, retaining any stretching
-% or shrinking applied when the \meta{box} was set. The \meta{box}
-% is then cleared globally.
+% or shrinking applied when the \meta{box} was set. The original \meta{box}
+% is then dropped.
% \begin{texnote}
% This is the \TeX{} primitive \tn{unvbox}.
% \end{texnote}
@@ -643,8 +663,11 @@
% On the other hand, rotation and resizing of boxed material can best be
% handled by modifying boxes. These transformations are described here.
%
-% \begin{function}[added = 2017-04-04]
-% {\box_autosize_to_wd_and_ht:Nnn, \box_autosize_to_wd_and_ht:cnn}
+% \begin{function}[added = 2017-04-04, updated = 2019-01-22]
+% {
+% \box_autosize_to_wd_and_ht:Nnn, \box_autosize_to_wd_and_ht:cnn,
+% \box_gautosize_to_wd_and_ht:Nnn, \box_gautosize_to_wd_and_ht:cnn,
+% }
% \begin{syntax}
% \cs{box_autosize_to_wd_and_ht:Nnn} \meta{box} \Arg{x-size} \Arg{y-size}
% \end{syntax}
@@ -658,12 +681,16 @@
% sizes cause the material in the \meta{box} to be reversed in direction,
% but the reference point of the \meta{box} is unchanged. Thus a negative
% \meta{y-size} results in the \meta{box} having a depth dependent on the
-% height of the original and \emph{vice versa}. The resizing applies within
-% the current \TeX{} group level.
+% height of the original and \emph{vice versa}.
% \end{function}
%
-% \begin{function}[added = 2017-04-04]
-% {\box_autosize_to_wd_and_ht_plus_dp:Nnn, \box_autosize_to_wd_and_ht_plus_dp:cnn}
+% \begin{function}[added = 2017-04-04, updated = 2019-01-22]
+% {
+% \box_autosize_to_wd_and_ht_plus_dp:Nnn,
+% \box_autosize_to_wd_and_ht_plus_dp:cnn,
+% \box_gautosize_to_wd_and_ht_plus_dp:Nnn,
+% \box_gautosize_to_wd_and_ht_plus_dp:cnn
+% }
% \begin{syntax}
% \cs{box_autosize_to_wd_and_ht_plus_dp:Nnn} \meta{box} \Arg{x-size} \Arg{y-size}
% \end{syntax}
@@ -677,12 +704,14 @@
% sizes cause the material in the \meta{box} to be reversed in direction,
% but the reference point of the \meta{box} is unchanged. Thus a negative
% \meta{y-size} results in the \meta{box} having a depth dependent on the
-% height of the original and \emph{vice versa}. The resizing applies within
-% the current \TeX{} group level.
+% height of the original and \emph{vice versa}.
% \end{function}
%
-% \begin{function}
-% {\box_resize_to_ht:Nn, \box_resize_to_ht:cn}
+% \begin{function}[updated = 2019-01-22]
+% {
+% \box_resize_to_ht:Nn, \box_resize_to_ht:cn,
+% \box_gresize_to_ht:Nn, \box_gresize_to_ht:cn
+% }
% \begin{syntax}
% \cs{box_resize_to_ht:Nn} \meta{box} \Arg{y-size}
% \end{syntax}
@@ -694,12 +723,14 @@
% material in the \meta{box} to be reversed in direction, but the reference
% point of the \meta{box} is unchanged. Thus a negative \meta{y-size}
% results in the \meta{box} having a depth dependent on the height of the
-% original and \emph{vice versa}. The resizing applies within the current
-% \TeX{} group level.
+% original and \emph{vice versa}.
% \end{function}
%
-% \begin{function}
-% {\box_resize_to_ht_plus_dp:Nn, \box_resize_to_ht_plus_dp:cn}
+% \begin{function}[updated = 2019-01-22]
+% {
+% \box_resize_to_ht_plus_dp:Nn, \box_resize_to_ht_plus_dp:cn,
+% \box_gresize_to_ht_plus_dp:Nn, \box_gresize_to_ht_plus_dp:cn,
+% }
% \begin{syntax}
% \cs{box_resize_to_ht_plus_dp:Nn} \meta{box} \Arg{y-size}
% \end{syntax}
@@ -711,11 +742,14 @@
% the material in the \meta{box} to be reversed in direction, but the
% reference point of the \meta{box} is unchanged. Thus a negative
% \meta{y-size} results in the \meta{box} having a depth dependent on the
-% height of the original and \emph{vice versa}. The resizing applies within
-% the current \TeX{} group level.
+% height of the original and \emph{vice versa}.
% \end{function}
%
-% \begin{function}{\box_resize_to_wd:Nn, \box_resize_to_wd:cn}
+% \begin{function}[updated = 2019-01-22]
+% {
+% \box_resize_to_wd:Nn, \box_resize_to_wd:cn,
+% \box_gresize_to_wd:Nn, \box_gresize_to_wd:cn
+% }
% \begin{syntax}
% \cs{box_resize_to_wd:Nn} \meta{box} \Arg{x-size}
% \end{syntax}
@@ -726,12 +760,14 @@
% material in the \meta{box} to be reversed in direction, but the reference
% point of the \meta{box} is unchanged. Thus a negative \meta{x-size}
% results in the \meta{box} having a depth dependent on the height of the
-% original and \emph{vice versa}. The resizing applies within the current
-% \TeX{} group level.
+% original and \emph{vice versa}.
% \end{function}
%
-% \begin{function}[added = 2014-07-03]
-% {\box_resize_to_wd_and_ht:Nnn, \box_resize_to_wd_and_ht:cnn}
+% \begin{function}[added = 2014-07-03, updated = 2019-01-22]
+% {
+% \box_resize_to_wd_and_ht:Nnn, \box_resize_to_wd_and_ht:cnn,
+% \box_gresize_to_wd_and_ht:Nnn, \box_gresize_to_wd_and_ht:cnn
+% }
% \begin{syntax}
% \cs{box_resize_to_wd_and_ht:Nnn} \meta{box} \Arg{x-size} \Arg{y-size}
% \end{syntax}
@@ -743,12 +779,16 @@
% the \meta{box} to be reversed in direction, but the reference point of the
% \meta{box} is unchanged. Thus a negative \meta{y-size} results in
% the \meta{box} having a depth dependent on the height of the original and
-% \emph{vice versa}. The resizing applies within the current \TeX{} group
-% level.
+% \emph{vice versa}.
% \end{function}
%
-% \begin{function}[added = 2017-04-06]
-% {\box_resize_to_wd_and_ht_plus_dp:Nnn, \box_resize_to_wd_and_ht_plus_dp:cnn}
+% \begin{function}[added = 2017-04-06, updated = 2019-01-22]
+% {
+% \box_resize_to_wd_and_ht_plus_dp:Nnn,
+% \box_resize_to_wd_and_ht_plus_dp:cnn,
+% \box_gresize_to_wd_and_ht_plus_dp:Nnn,
+% \box_gresize_to_wd_and_ht_plus_dp:cnn
+% }
% \begin{syntax}
% \cs{box_resize_to_wd_and_ht_plus_dp:Nnn} \meta{box} \Arg{x-size} \Arg{y-size}
% \end{syntax}
@@ -760,11 +800,14 @@
% the \meta{box} to be reversed in direction, but the reference point of the
% \meta{box} is unchanged. Thus a negative \meta{y-size} results in
% the \meta{box} having a depth dependent on the height of the original and
-% \emph{vice versa}. The resizing applies within the current \TeX{} group
-% level.
+% \emph{vice versa}.
% \end{function}
%
-% \begin{function}{\box_rotate:Nn, \box_rotate:cn}
+% \begin{function}[updated = 2019-01-22]
+% {
+% \box_rotate:Nn, \box_rotate:cn,
+% \box_grotate:Nn, \box_grotate:cn
+% }
% \begin{syntax}
% \cs{box_rotate:Nn} \meta{box} \Arg{angle}
% \end{syntax}
@@ -773,10 +816,13 @@
% horizontally such that it is at the left side of the smallest rectangle
% enclosing the rotated material. The updated \meta{box} is an |hbox|,
% irrespective of the nature of the \meta{box} before the rotation is applied.
-% The rotation applies within the current \TeX{} group level.
% \end{function}
%
-% \begin{function}{\box_scale:Nnn, \box_scale:cnn}
+% \begin{function}[updated = 2019-01-22]
+% {
+% \box_scale:Nnn, \box_scale:cnn,
+% \box_gscale:Nnn, \box_gscale:cnn
+% }
% \begin{syntax}
% \cs{box_scale:Nnn} \meta{box} \Arg{x-scale} \Arg{y-scale}
% \end{syntax}
@@ -787,8 +833,7 @@
% scalings cause the material in the \meta{box} to be reversed in
% direction, but the reference point of the \meta{box} is unchanged.
% Thus a negative \meta{y-scale} results in the \meta{box} having a depth
-% dependent on the height of the original and \emph{vice versa}. The resizing
-% applies within the current \TeX{} group level.
+% dependent on the height of the original and \emph{vice versa}.
% \end{function}
%
% \section{Primitive box conditionals}
@@ -941,27 +986,25 @@
%
% \begin{macro}
% {
-% \box_set_eq_clear:NN, \box_set_eq_clear:cN,
-% \box_set_eq_clear:Nc, \box_set_eq_clear:cc
+% \box_set_eq_drop:NN, \box_set_eq_drop:cN,
+% \box_set_eq_drop:Nc, \box_set_eq_drop:cc
% }
-% \testfile*
% \begin{macro}
% {
-% \box_gset_eq_clear:NN, \box_gset_eq_clear:cN,
-% \box_gset_eq_clear:Nc, \box_gset_eq_clear:cc
+% \box_gset_eq_drop:NN, \box_gset_eq_drop:cN,
+% \box_gset_eq_drop:Nc, \box_gset_eq_drop:cc
% }
-% \testfile*
-% Assigning the contents of a box to be another box.
-% This clears the second box globally (that's how \TeX{} does it).
+% Assigning the contents of a box to be another box, then drops the
+% original box.
% \begin{macrocode}
\__kernel_patch:nnNNpn { \__kernel_chk_var_local:N #1 } { }
-\cs_new_protected:Npn \box_set_eq_clear:NN #1#2
+\cs_new_protected:Npn \box_set_eq_drop:NN #1#2
{ \tex_setbox:D #1 \tex_box:D #2 }
\__kernel_patch:nnNNpn { \__kernel_chk_var_global:N #1 } { }
-\cs_new_protected:Npn \box_gset_eq_clear:NN #1#2
+\cs_new_protected:Npn \box_gset_eq_drop:NN #1#2
{ \tex_global:D \tex_setbox:D #1 \tex_box:D #2 }
-\cs_generate_variant:Nn \box_set_eq_clear:NN { c , Nc , cc }
-\cs_generate_variant:Nn \box_gset_eq_clear:NN { c , Nc , cc }
+\cs_generate_variant:Nn \box_set_eq_drop:NN { c , Nc , cc }
+\cs_generate_variant:Nn \box_gset_eq_drop:NN { c , Nc , cc }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -998,20 +1041,38 @@
% \begin{macro}{\box_set_ht:Nn, \box_set_ht:cn}
% \begin{macro}{\box_set_dp:Nn, \box_set_dp:cn}
% \begin{macro}{\box_set_wd:Nn, \box_set_wd:cn}
-% Setting the size is easy: all primitive work. These primitives are not
-% expandable, so the derived functions are not either.
+% Setting the size whilst respecting local scope requires copying;
+% the same issue does not come up when working globally.
% When debugging, the dimension expression |#2| is surrounded by
% parentheses to catch early termination.
% \begin{macrocode}
\cs_new_protected:Npn \box_set_dp:Nn #1#2
+ {
+ \tex_setbox:D #1 = \tex_copy:D #1
+ \box_dp:N #1 \@@_dim_eval:n {#2}
+ }
+\cs_generate_variant:Nn \box_set_dp:Nn { c }
+\cs_new_protected:Npn \box_gset_dp:Nn #1#2
{ \box_dp:N #1 \@@_dim_eval:n {#2} }
+\cs_generate_variant:Nn \box_gset_dp:Nn { c }
\cs_new_protected:Npn \box_set_ht:Nn #1#2
+ {
+ \tex_setbox:D #1 = \tex_copy:D #1
+ \box_ht:N #1 \@@_dim_eval:n {#2}
+ }
+\cs_generate_variant:Nn \box_set_ht:Nn { c }
+\cs_new_protected:Npn \box_gset_ht:Nn #1#2
{ \box_ht:N #1 \@@_dim_eval:n {#2} }
+\cs_generate_variant:Nn \box_gset_ht:Nn { c }
\cs_new_protected:Npn \box_set_wd:Nn #1#2
- { \box_wd:N #1 \@@_dim_eval:n {#2} }
-\cs_generate_variant:Nn \box_set_ht:Nn { c }
-\cs_generate_variant:Nn \box_set_dp:Nn { c }
+ {
+ \tex_setbox:D #1 = \tex_copy:D #1
+ \box_wd:N #1 \@@_dim_eval:n {#2}
+ }
\cs_generate_variant:Nn \box_set_wd:Nn { c }
+\cs_new_protected:Npn \box_gset_wd:Nn #1#2
+ { \box_wd:N #1 \@@_dim_eval:n {#2} }
+\cs_generate_variant:Nn \box_gset_wd:Nn { c }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -1355,14 +1416,14 @@
% \end{macro}
%
% \begin{macro}{\hbox_unpack:N, \hbox_unpack:c}
-% \begin{macro}{\hbox_unpack_clear:N, \hbox_unpack_clear:c}
+% \begin{macro}{\hbox_unpack_drop:N, \hbox_unpack_drop:c}
% \testfile*
% Unpacking a box and if requested also clear it.
% \begin{macrocode}
\cs_new_eq:NN \hbox_unpack:N \tex_unhcopy:D
-\cs_new_eq:NN \hbox_unpack_clear:N \tex_unhbox:D
+\cs_new_eq:NN \hbox_unpack_drop:N \tex_unhbox:D
\cs_generate_variant:Nn \hbox_unpack:N { c }
-\cs_generate_variant:Nn \hbox_unpack_clear:N { c }
+\cs_generate_variant:Nn \hbox_unpack_drop:N { c }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -1537,14 +1598,14 @@
% \end{macro}
%
% \begin{macro}{\vbox_unpack:N, \vbox_unpack:c}
-% \begin{macro}{\vbox_unpack_clear:N, \vbox_unpack_clear:c}
+% \begin{macro}{\vbox_unpack_drop:N, \vbox_unpack_drop:c}
% \testfile*
% Unpacking a box and if requested also clear it.
% \begin{macrocode}
\cs_new_eq:NN \vbox_unpack:N \tex_unvcopy:D
-\cs_new_eq:NN \vbox_unpack_clear:N \tex_unvbox:D
+\cs_new_eq:NN \vbox_unpack_drop:N \tex_unvbox:D
\cs_generate_variant:Nn \vbox_unpack:N { c }
-\cs_generate_variant:Nn \vbox_unpack_clear:N { c }
+\cs_generate_variant:Nn \vbox_unpack_drop:N { c }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -1627,7 +1688,12 @@
% \end{macrocode}
% \end{variable}
%
-% \begin{macro}{\box_rotate:Nn}
+% \begin{macro}
+% {
+% \box_rotate:Nn, \box_rotate:cn,
+% \box_grotate:Nn, \box_grotate:cn
+% }
+% \begin{macro}{\@@_rotate:NnN}
% \begin{macro}{\@@_rotate:N}
% \begin{macro}{\@@_rotate_xdir:nnN, \@@_rotate_ydir:nnN}
% \begin{macro}
@@ -1640,8 +1706,14 @@
% clearer
% \begin{macrocode}
\cs_new_protected:Npn \box_rotate:Nn #1#2
+ { \@@_rotate:NnN #1 {#2} \hbox_set:Nn }
+\cs_generate_variant:Nn \box_rotate:Nn { c }
+\cs_new_protected:Npn \box_grotate:Nn #1#2
+ { \@@_rotate:NnN #1 {#2} \hbox_gset:Nn }
+\cs_generate_variant:Nn \box_grotate:Nn { c }
+\cs_new_protected:Npn \@@_rotate:NnN #1#2#3
{
- \hbox_set:Nn #1
+ #3 #1
{
\fp_set:Nn \l_@@_angle_fp {#2}
\fp_set:Nn \l_@@_sin_fp { sind ( \l_@@_angle_fp ) }
@@ -1664,7 +1736,7 @@
% The next step is to work out the $x$ and $y$ coordinates of vertices of
% the rotated box in relation to its original coordinates. The box can be
% visualized with vertices $B$, $C$, $D$ and $E$ is illustrated
-% (Figure~\ref{fig:l3candidates:rotation}). The vertex $O$ is the reference point
+% (Figure~\ref{fig:l3box:rotation}). The vertex $O$ is the reference point
% on the baseline, and in this implementation is also the centre of rotation.
% \begin{figure}
% \centering
@@ -1682,7 +1754,7 @@
% \put(21,59){O}
% \end{picture}
% \caption{Co-ordinates of a box prior to rotation.}
-% \label{fig:l3candidates:rotation}
+% \label{fig:l3box:rotation}
% \end{figure}
% The formulae are, for a point $P$ and angle $\alpha$:
% \[
@@ -1830,6 +1902,7 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \begin{variable}{\l_@@_scale_x_fp, \l_@@_scale_y_fp}
% Scaling is potentially-different in the two axes.
@@ -1840,7 +1913,13 @@
% \end{variable}
%
% \begin{macro}
-% {\box_resize_to_wd_and_ht_plus_dp:Nnn, \box_resize_to_wd_and_ht_plus_dp:cnn}
+% {
+% \box_resize_to_wd_and_ht_plus_dp:Nnn,
+% \box_resize_to_wd_and_ht_plus_dp:cnn,
+% \box_gresize_to_wd_and_ht_plus_dp:Nnn,
+% \box_gresize_to_wd_and_ht_plus_dp:cnn
+% }
+% \begin{macro}{\@@_resize_to_wd_and_ht_plus_dp:NnnN}
% \begin{macro}{\@@_resize_set_corners:N}
% \begin{macro}{\@@_resize:N}
% \begin{macro}{\@@_resize:NNN}
@@ -1849,7 +1928,19 @@
% \begin{macrocode}
\cs_new_protected:Npn \box_resize_to_wd_and_ht_plus_dp:Nnn #1#2#3
{
- \hbox_set:Nn #1
+ \@@_resize_to_wd_and_ht_plus_dp:NnnN #1 {#2} {#3}
+ \hbox_set:Nn
+ }
+\cs_generate_variant:Nn \box_resize_to_wd_and_ht_plus_dp:Nnn { c }
+\cs_new_protected:Npn \box_gresize_to_wd_and_ht_plus_dp:Nnn #1#2#3
+ {
+ \@@_resize_to_wd_and_ht_plus_dp:NnnN #1 {#2} {#3}
+ \hbox_gset:Nn
+ }
+\cs_generate_variant:Nn \box_gresize_to_wd_and_ht_plus_dp:Nnn { c }
+\cs_new_protected:Npn \@@_resize_to_wd_and_ht_plus_dp:NnnN #1#2#3#4
+ {
+ #4 #1
{
\@@_resize_set_corners:N #1
% \end{macrocode}
@@ -1873,7 +1964,6 @@
\@@_resize:N #1
}
}
-\cs_generate_variant:Nn \box_resize_to_wd_and_ht_plus_dp:Nnn { c }
\cs_new_protected:Npn \@@_resize_set_corners:N #1
{
\dim_set:Nn \l_@@_top_dim { \box_ht:N #1 }
@@ -1908,11 +1998,32 @@
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
%
-% \begin{macro}{\box_resize_to_ht:Nn, \box_resize_to_ht:cn}
-% \begin{macro}{\box_resize_to_ht_plus_dp:Nn, \box_resize_to_ht_plus_dp:cn}
-% \begin{macro}{\box_resize_to_wd:Nn, \box_resize_to_wd:cn}
-% \begin{macro}{\box_resize_to_wd_and_ht:Nnn, \box_resize_to_wd_and_ht:cnn}
+% \begin{macro}
+% {
+% \box_resize_to_ht:Nn, \box_resize_to_ht:cn,
+% \box_gresize_to_ht:Nn, \box_gresize_to_ht:cn
+% }
+% \begin{macro}{\@@_resize_to_ht:NnN}
+% \begin{macro}
+% {
+% \box_resize_to_ht_plus_dp:Nn, \box_resize_to_ht_plus_dp:cn,
+% \box_gresize_to_ht_plus_dp:Nn, \box_gresize_to_ht_plus_dp:cn
+% }
+% \begin{macro}{\@@_resize_to_ht_plus_dp:NnN}
+% \begin{macro}
+% {
+% \box_resize_to_wd:Nn, \box_resize_to_wd:cn,
+% \box_gresize_to_wd:Nn, \box_gresize_to_wd:cn
+% }
+% \begin{macro}{\@@_resize_to_wd:NnN}
+% \begin{macro}
+% {
+% \box_resize_to_wd_and_ht:Nnn, \box_resize_to_wd_and_ht:cnn,
+% \box_gresize_to_wd_and_ht:Nnn, \box_gresize_to_wd_and_ht:cnn
+% }
+% \begin{macro}{\@@_resize_to_wd_ht:NnnN}
% Scaling to a (total) height or to a width is a simplified version of the main
% resizing operation, with the scale simply copied between the two parts. The
% internal auxiliary is called using the scaling value twice, as the sign for
@@ -1920,8 +2031,14 @@
% for the general case).
% \begin{macrocode}
\cs_new_protected:Npn \box_resize_to_ht:Nn #1#2
+ { \@@_resize_to_ht:NnN #1 {#2} \hbox_set:Nn }
+\cs_generate_variant:Nn \box_resize_to_ht:Nn { c }
+\cs_new_protected:Npn \box_gresize_to_ht:Nn #1#2
+ { \@@_resize_to_ht:NnN #1 {#2} \hbox_gset:Nn }
+\cs_generate_variant:Nn \box_gresize_to_ht:Nn { c }
+\cs_new_protected:Npn \@@_resize_to_ht:NnN #1#2#3
{
- \hbox_set:Nn #1
+ #3 #1
{
\@@_resize_set_corners:N #1
\fp_set:Nn \l_@@_scale_y_fp
@@ -1933,8 +2050,13 @@
\@@_resize:N #1
}
}
-\cs_generate_variant:Nn \box_resize_to_ht:Nn { c }
\cs_new_protected:Npn \box_resize_to_ht_plus_dp:Nn #1#2
+ { \@@_resize_to_ht_plus_dp:NnN #1 {#2} \hbox_set:Nn }
+\cs_generate_variant:Nn \box_resize_to_ht_plus_dp:Nn { c }
+\cs_new_protected:Npn \box_gresize_to_ht_plus_dp:Nn #1#2
+ { \@@_resize_to_ht_plus_dp:NnN #1 {#2} \hbox_gset:Nn }
+\cs_generate_variant:Nn \box_gresize_to_ht_plus_dp:Nn { c }
+\cs_new_protected:Npn \@@_resize_to_ht_plus_dp:NnN #1#2#3
{
\hbox_set:Nn #1
{
@@ -1948,10 +2070,15 @@
\@@_resize:N #1
}
}
-\cs_generate_variant:Nn \box_resize_to_ht_plus_dp:Nn { c }
\cs_new_protected:Npn \box_resize_to_wd:Nn #1#2
+ { \@@_resize_to_wd:NnN #1 {#2} \hbox_set:Nn }
+\cs_generate_variant:Nn \box_resize_to_wd:Nn { c }
+\cs_new_protected:Npn \box_gresize_to_wd:Nn #1#2
+ { \@@_resize_to_wd:NnN #1 {#2} \hbox_gset:Nn }
+\cs_generate_variant:Nn \box_gresize_to_wd:Nn { c }
+\cs_new_protected:Npn \@@_resize_to_wd:NnN #1#2#3
{
- \hbox_set:Nn #1
+ #3 #1
{
\@@_resize_set_corners:N #1
\fp_set:Nn \l_@@_scale_x_fp
@@ -1960,10 +2087,15 @@
\@@_resize:N #1
}
}
-\cs_generate_variant:Nn \box_resize_to_wd:Nn { c }
\cs_new_protected:Npn \box_resize_to_wd_and_ht:Nnn #1#2#3
+ { \@@_resize_to_wd_and_ht:NnnN #1 {#2} {#3} \hbox_set:Nn }
+\cs_generate_variant:Nn \box_resize_to_wd_and_ht:Nnn { c }
+\cs_new_protected:Npn \box_gresize_to_wd_and_ht:Nnn #1#2#3
+ { \@@_resize_to_wd_and_ht:NnnN #1 {#2} {#3} \hbox_gset:Nn }
+\cs_generate_variant:Nn \box_gresize_to_wd_and_ht:Nnn { c }
+\cs_new_protected:Npn \@@_resize_to_wd_and_ht:NnnN #1#2#3#4
{
- \hbox_set:Nn #1
+ #4 #1
{
\@@_resize_set_corners:N #1
\fp_set:Nn \l_@@_scale_x_fp
@@ -1976,15 +2108,23 @@
\@@_resize:N #1
}
}
-\cs_generate_variant:Nn \box_resize_to_wd_and_ht:Nnn { c }
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
%
-% \begin{macro}{\box_scale:Nnn, \box_scale:cnn}
-% \begin{macro}{\@@_scale_aux:N}
+% \begin{macro}
+% {
+% \box_scale:Nnn, \box_scale:cnn,
+% \box_gscale:Nnn, \box_gscale:cnn
+% }
+% \begin{macro}{\@@_scale:NnnN}
+% \begin{macro}{\@@_scale:N}
% When scaling a box, setting the scaling itself is easy enough. The
% new dimensions are also relatively easy to find, allowing only for
% the need to keep them positive in all cases. Once that is done then
@@ -1993,16 +2133,21 @@
% with the auto-resizing functions.
% \begin{macrocode}
\cs_new_protected:Npn \box_scale:Nnn #1#2#3
+ { \@@_scale:NnnN #1 {#2} {#3} \hbox_set:Nn }
+\cs_generate_variant:Nn \box_scale:Nnn { c }
+\cs_new_protected:Npn \box_gscale:Nnn #1#2#3
+ { \@@_scale:NnnN #1 {#2} {#3} \hbox_gset:Nn }
+\cs_generate_variant:Nn \box_gscale:Nnn { c }
+\cs_new_protected:Npn \@@_scale:NnnN #1#2#3#4
{
- \hbox_set:Nn #1
+ #4 #1
{
\fp_set:Nn \l_@@_scale_x_fp {#2}
\fp_set:Nn \l_@@_scale_y_fp {#3}
- \@@_scale_aux:N #1
+ \@@_scale:N #1
}
}
-\cs_generate_variant:Nn \box_scale:Nnn { c }
-\cs_new_protected:Npn \@@_scale_aux:N #1
+\cs_new_protected:Npn \@@_scale:N #1
{
\dim_set:Nn \l_@@_top_dim { \box_ht:N #1 }
\dim_set:Nn \l_@@_bottom_dim { -\box_dp:N #1 }
@@ -2019,35 +2164,52 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \begin{macro}
% {
-% \box_autosize_to_wd_and_ht:Nnn ,
-% \box_autosize_to_wd_and_ht:cnn ,
-% \box_autosize_to_wd_and_ht_plus_dp:Nnn ,
-% \box_autosize_to_wd_and_ht_plus_dp:cnn
+% \box_autosize_to_wd_and_ht:Nnn ,
+% \box_autosize_to_wd_and_ht:cnn ,
+% \box_gautosize_to_wd_and_ht:Nnn ,
+% \box_gautosize_to_wd_and_ht:cnn ,
+% \box_autosize_to_wd_and_ht_plus_dp:Nnn ,
+% \box_autosize_to_wd_and_ht_plus_dp:cnn ,
+% \box_gautosize_to_wd_and_ht_plus_dp:Nnn ,
+% \box_gautosize_to_wd_and_ht_plus_dp:cnn
% }
-% \begin{macro}{\@@_autosize:Nnnn}
+% \begin{macro}{\@@_autosize:NnnnN}
% Although autosizing a box uses dimensions, it has more in common in
% implementation with scaling. As such, most of the real work here is
% done elsewhere.
% \begin{macrocode}
\cs_new_protected:Npn \box_autosize_to_wd_and_ht:Nnn #1#2#3
- { \@@_autosize:Nnnn #1 {#2} {#3} { \box_ht:N #1 } }
+ { \@@_autosize:NnnnN #1 {#2} {#3} { \box_ht:N #1 } \hbox_set:Nn }
+\cs_generate_variant:Nn \box_autosize_to_wd_and_ht:Nnn { c }
+\cs_new_protected:Npn \box_gautosize_to_wd_and_ht:Nnn #1#2#3
+ { \@@_autosize:NnnnN #1 {#2} {#3} { \box_ht:N #1 } \hbox_gset:Nn }
\cs_generate_variant:Nn \box_autosize_to_wd_and_ht:Nnn { c }
\cs_new_protected:Npn \box_autosize_to_wd_and_ht_plus_dp:Nnn #1#2#3
- { \@@_autosize:Nnnn #1 {#2} {#3} { \box_ht:N #1 + \box_dp:N #1 } }
+ {
+ \@@_autosize:NnnnN #1 {#2} {#3} { \box_ht:N #1 + \box_dp:N #1 }
+ \hbox_set:Nn
+ }
\cs_generate_variant:Nn \box_autosize_to_wd_and_ht_plus_dp:Nnn { c }
-\cs_new_protected:Npn \@@_autosize:Nnnn #1#2#3#4
+\cs_new_protected:Npn \box_gautosize_to_wd_and_ht_plus_dp:Nnn #1#2#3
{
- \hbox_set:Nn #1
+ \@@_autosize:NnnnN #1 {#2} {#3} { \box_ht:N #1 + \box_dp:N #1 }
+ \hbox_gset:Nn
+ }
+\cs_generate_variant:Nn \box_gautosize_to_wd_and_ht_plus_dp:Nnn { c }
+\cs_new_protected:Npn \@@_autosize:NnnnN #1#2#3#4#5
+ {
+ #5 #1
{
\fp_set:Nn \l_@@_scale_x_fp { ( #2 ) / \box_wd:N #1 }
\fp_set:Nn \l_@@_scale_y_fp { ( #3 ) / ( #4 ) }
\fp_compare:nNnTF \l_@@_scale_x_fp > \l_@@_scale_y_fp
{ \fp_set_eq:NN \l_@@_scale_x_fp \l_@@_scale_y_fp }
{ \fp_set_eq:NN \l_@@_scale_y_fp \l_@@_scale_x_fp }
- \@@_scale_aux:N #1
+ \@@_scale:N #1
}
}
% \end{macrocode}
@@ -2108,6 +2270,49 @@
% \end{macrocode}
% \end{macro}
%
+% \subsection{Deprecated functions}
+%
+% \begin{macro}
+% {
+% \box_set_eq_clear:NN, \box_set_eq_clear:cN,
+% \box_set_eq_clear:Nc, \box_set_eq_clear:cc
+% }
+% \begin{macro}
+% {
+% \box_gset_eq_clear:NN, \box_gset_eq_clear:cN,
+% \box_gset_eq_clear:Nc, \box_gset_eq_clear:cc
+% }
+% \begin{macrocode}
+\__kernel_patch_deprecation:nnNNpn { 2020-12-31 } { \box_set_eq_drop:N }
+\cs_new_protected:Npn \box_set_eq_clear:NN #1#2
+ { \tex_setbox:D #1 \tex_box:D #2 }
+\__kernel_patch_deprecation:nnNNpn { 2020-12-31 } { \box_gset_eq_drop:N }
+\cs_new_protected:Npn \box_gset_eq_clear:NN #1#2
+ { \tex_global:D \tex_setbox:D #1 \tex_box:D #2 }
+\cs_generate_variant:Nn \box_set_eq_clear:NN { c , Nc , cc }
+\cs_generate_variant:Nn \box_gset_eq_clear:NN { c , Nc , cc }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\hbox_unpack_clear:N, \hbox_unpack_clear:c}
+% \begin{macrocode}
+\__kernel_patch_deprecation:nnNNpn { 2020-12-31 } { \hbox_unpack_drop:N }
+\cs_new_protected:Npn \hbox_unpack_clear:N
+ { \hbox_unpack_drop:N }
+\cs_generate_variant:Nn \hbox_unpack_clear:N { c }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\vbox_unpack_clear:N, \vbox_unpack_clear:c}
+% \begin{macrocode}
+\__kernel_patch_deprecation:nnNNpn { 2020-12-31 } { \vbox_unpack_drop:N }
+\cs_new_protected:Npn \vbox_unpack_clear:N
+ { \vbox_unpack_drop:N }
+\cs_generate_variant:Nn \vbox_unpack_clear:N { c }
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macrocode}
%</initex|package>
% \end{macrocode}