[latex3-commits] [git/LaTeX3-latex3-latex3] clear-drop: Initial notes no drop vs clear [ci skip] (521a372)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : clear-drop
Link       : https://github.com/latex3/latex3/commit/521a372688fce45d1b733b372489ae10b0eec371

>---------------------------------------------------------------

commit 521a372688fce45d1b733b372489ae10b0eec371
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Thu Jan 17 07:58:28 2019 +0000

    Initial notes no drop vs clear [ci skip]


>---------------------------------------------------------------

521a372688fce45d1b733b372489ae10b0eec371
 l3kernel/l3box.dtx |   28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/l3kernel/l3box.dtx b/l3kernel/l3box.dtx
index 7118b9e..8b87356 100644
--- a/l3kernel/l3box.dtx
+++ b/l3kernel/l3box.dtx
@@ -637,6 +637,34 @@
 %   \end{texnote}
 % \end{function}
 %
+% \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. This consideration \emph{only applies to local boxes}.
+% When such 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.
+%
 % \section{Affine transformations}
 %
 % Affine transformations are changes which (informally) preserve straight