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.dtx62
1 files changed, 47 insertions, 15 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
index 4a1d1b34627..d864dc55b4c 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3box.dtx
@@ -41,7 +41,7 @@
% }^^A
% }
%
-% \date{Released 2017/07/19}
+% \date{Released 2017/09/18}
%
% \maketitle
%
@@ -67,7 +67,7 @@
% \cs{box_clear:N} \meta{box}
% \end{syntax}
% Clears the content of the \meta{box} by setting the box equal to
-% \cs{c_void_box}.
+% \cs{c_empty_box}.
% \end{function}
%
% \begin{function}
@@ -139,13 +139,34 @@
% \end{texnote}
% \end{function}
%
-% \begin{function}{\box_use_clear:N, \box_use_clear:c}
+% \begin{function}{\box_use_drop:N, \box_use_drop:c}
% \begin{syntax}
-% \cs{box_use_clear:N} \meta{box}
+% \cs{box_use_drop:N} \meta{box}
% \end{syntax}
% Inserts the current content of the \meta{box} onto the current
-% list for typesetting, then globally clears the content of the
-% \meta{box}.
+% list for typesetting. 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 |\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 |\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}
@@ -170,7 +191,7 @@
% \end{syntax}
% This function operates in horizontal mode, and inserts the
% material specified by the \meta{box function}
-% such that its reference point is displaced vertical by the given
+% such that its reference point is displaced vertically by the given
% \meta{dimexpr} from the reference point for typesetting, up
% or down as appropriate. The \meta{box function} should be
% a box operation such as |\box_use:N \<box>| or a \enquote{raw}
@@ -283,6 +304,9 @@
% \begin{variable}[updated = 2012-11-04]{\c_empty_box}
% This is a permanently empty box, which is neither set as horizontal
% nor vertical.
+% \begin{texnote}
+% At the \TeX{} level this is a void box.
+% \end{texnote}
% \end{variable}
%
% \section{Scratch boxes}
@@ -604,7 +628,7 @@
% \end{texnote}
% \end{function}
%
-% \subsection{Affine transformations}
+% \section{Affine transformations}
%
% Affine transformations are changes which (informally) preserve straight
% lines. Simple translations are affine transformations, but are better handled
@@ -968,14 +992,14 @@
%
% \subsection{Using boxes}
%
-% \begin{macro}{\box_use_clear:N, \box_use_clear:c}
+% \begin{macro}{\box_use_drop:N, \box_use_drop:c}
% \begin{macro}{\box_use:N, \box_use:c}
% Using a \meta{box}. These are just \TeX{} primitives with meaningful
% names.
% \begin{macrocode}
-\cs_new_eq:NN \box_use_clear:N \tex_box:D
+\cs_new_eq:NN \box_use_drop:N \tex_box:D
\cs_new_eq:NN \box_use:N \tex_copy:D
-\cs_generate_variant:Nn \box_use_clear:N { c }
+\cs_generate_variant:Nn \box_use_drop:N { c }
\cs_generate_variant:Nn \box_use:N { c }
% \end{macrocode}
% \end{macro}
@@ -1166,7 +1190,7 @@
% \end{macrocode}
% \end{macro}
%
-% \subsection{Horizontal mode boxes}
+% \subsection{Horizontal mode boxes}
%
% \begin{macro}{\hbox:n}
% \testfile{m3box002.lvt}
@@ -1629,7 +1653,7 @@
\box_set_dp:Nn \l_@@_internal_box { -\l_@@_bottom_new_dim }
\box_set_wd:Nn \l_@@_internal_box
{ \l_@@_right_new_dim - \l_@@_left_new_dim }
- \box_use:N \l_@@_internal_box
+ \box_use_drop:N \l_@@_internal_box
}
% \end{macrocode}
% \end{macro}
@@ -1982,7 +2006,7 @@
\hbox_to_wd:nn { \l_@@_right_new_dim }
{
\tex_kern:D \l_@@_right_new_dim
- \box_use:N \l_@@_internal_box
+ \box_use_drop:N \l_@@_internal_box
\tex_hss:D
}
}
@@ -1991,7 +2015,7 @@
\hbox:n
{
\tex_kern:D \c_zero_dim
- \box_use:N \l_@@_internal_box
+ \box_use_drop:N \l_@@_internal_box
\tex_hss:D
}
}
@@ -2002,6 +2026,7 @@
% \subsection{Deprecated functions}
%
% \begin{macro}[deprecated = 2018-12-31]{\box_resize:Nnn, \box_resize:cnn}
+% \begin{macro}[deprecated = 2018-12-31]{\box_use_clear:N, \box_use_clear:c}
% \begin{macrocode}
\__debug_deprecation:nnNNpn
{ 2018-12-31 } { \box_resize_to_wd_and_ht_plus_dp:Nnn }
@@ -2011,8 +2036,15 @@
{ 2018-12-31 } { \box_resize_to_wd_and_ht_plus_dp:cnn }
\cs_new_protected:Npn \box_resize:cnn
{ \box_resize_to_wd_and_ht_plus_dp:cnn }
+\__debug_deprecation:nnNNpn
+ { 2018-12-31 } { \box_use_clear:N }
+\cs_new_protected:Npn \box_use_clear:N { \box_use_drop:N }
+\__debug_deprecation:nnNNpn
+ { 2018-12-31 } { \box_use_clear:c }
+\cs_new_protected:Npn \box_use_clear:c { \box_use_drop:c }
% \end{macrocode}
% \end{macro}
+% \end{macro}
%
% \begin{macrocode}
%</initex|package>