[latex3-commits] [git/LaTeX3-latex3-latex3] clear-drop: Move docs for \box_use_drop:N [ci skip] (42f90ae)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : clear-drop
Link       : https://github.com/latex3/latex3/commit/42f90ae1602fa3d7b7019065f3977493e7d422c5

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

commit 42f90ae1602fa3d7b7019065f3977493e7d422c5
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Thu Jan 17 08:00:45 2019 +0000

    Move docs for \box_use_drop:N [ci skip]


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

42f90ae1602fa3d7b7019065f3977493e7d422c5
 l3kernel/l3box.dtx |   54 +++++++++++++++-------------------------------------
 1 file changed, 15 insertions(+), 39 deletions(-)

diff --git a/l3kernel/l3box.dtx b/l3kernel/l3box.dtx
index e7204dc..2069816 100644
--- a/l3kernel/l3box.dtx
+++ b/l3kernel/l3box.dtx
@@ -142,42 +142,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}
@@ -642,9 +606,8 @@
 % 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
+% 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 }
@@ -663,6 +626,19 @@
 % These functions should be preferred when the content of the box is no
 % longer required after use.
 %
+% \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}
+%
 % \section{Affine transformations}
 %
 % Affine transformations are changes which (informally) preserve straight