diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3box.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3box.dtx | 551 |
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} |