[latex3-commits] [l3svn] branch master updated: Rename \box_use_clear:N to \box_use_drop:N
noreply at latex-project.org
noreply at latex-project.org
Tue Sep 12 10:20:08 CEST 2017
This is an automated email from the git hooks/post-receive script.
joseph pushed a commit to branch master
in repository l3svn.
The following commit(s) were added to refs/heads/master by this push:
new a5abd83 Rename \box_use_clear:N to \box_use_drop:N
a5abd83 is described below
commit a5abd83b4ca08d01c1520354b33cfd1bcd667958
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Tue Sep 12 09:15:32 2017 +0100
Rename \box_use_clear:N to \box_use_drop:N
---
l3kernel/l3box.dtx | 43 ++++++++++++++++++++++++++-----
l3kernel/l3doc.dtx | 4 +--
l3kernel/l3obsolete.txt | 2 ++
l3kernel/testfiles/m3box001.lvt | 6 ++---
l3kernel/testfiles/m3expl001.luatex.tlg | 6 +++--
l3kernel/testfiles/m3expl001.ptex.tlg | 6 +++--
l3kernel/testfiles/m3expl001.tlg | 6 +++--
l3kernel/testfiles/m3expl001.uptex.tlg | 6 +++--
l3kernel/testfiles/m3expl001.xetex.tlg | 6 +++--
l3kernel/testfiles/m3expl003.luatex.tlg | 6 +++--
l3kernel/testfiles/m3expl003.ptex.tlg | 6 +++--
l3kernel/testfiles/m3expl003.tlg | 6 +++--
l3kernel/testfiles/m3expl003.uptex.tlg | 6 +++--
l3kernel/testfiles/m3expl003.xetex.tlg | 6 +++--
14 files changed, 83 insertions(+), 32 deletions(-)
diff --git a/l3kernel/l3box.dtx b/l3kernel/l3box.dtx
index a1b3281..68a083b 100644
--- a/l3kernel/l3box.dtx
+++ b/l3kernel/l3box.dtx
@@ -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}
@@ -971,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}
@@ -2005,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 }
@@ -2014,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>
diff --git a/l3kernel/l3doc.dtx b/l3kernel/l3doc.dtx
index 0692cd6..187c32a 100644
--- a/l3kernel/l3doc.dtx
+++ b/l3kernel/l3doc.dtx
@@ -2435,7 +2435,7 @@ and all files in that bundle must be distributed together.
\cs_new_protected:Npn \@@_function_assemble:
{
\hcoffin_set:Nn \l_@@_syntax_coffin
- { \box_use_clear:N \g_@@_syntax_box }
+ { \box_use_drop:N \g_@@_syntax_box }
\bool_if:NTF \l_@@_long_name_bool
{
\coffin_join:NnnNnnnn
@@ -2648,7 +2648,7 @@ and all files in that bundle must be distributed together.
{
\begin{quote}
\mode_leave_vertical:
- \box_use_clear:N \g_@@_syntax_box
+ \box_use_drop:N \g_@@_syntax_box
\end{quote}
}
}
diff --git a/l3kernel/l3obsolete.txt b/l3kernel/l3obsolete.txt
index 4db8952..4aec455 100644
--- a/l3kernel/l3obsolete.txt
+++ b/l3kernel/l3obsolete.txt
@@ -18,6 +18,8 @@ Function Expires end
\c_minus_one 2018
\box_resize:cnn 2018
\box_resize:Nnn 2018
+\box_use_clear:c 2018
+\box_use_clear:N 2018
\file_add_path:nN 2018
\file_if_exist_input:nT 2017
\file_if_exist_input:nTF 2017
diff --git a/l3kernel/testfiles/m3box001.lvt b/l3kernel/testfiles/m3box001.lvt
index 0355059..d40ca81 100644
--- a/l3kernel/testfiles/m3box001.lvt
+++ b/l3kernel/testfiles/m3box001.lvt
@@ -227,8 +227,8 @@
\TIMO
\box_use:N \l_tempa_box
\box_use:c {l_tempb_box}
- \box_use_clear:N \l_tempc_box
- \box_use_clear:c {l_tempd_box}
+ \box_use_drop:N \l_tempc_box
+ \box_use_drop:c {l_tempd_box}
\box_show:N \l_tempa_box
\box_show:N \l_tempb_box
\box_show:N \l_tempc_box
@@ -292,7 +292,7 @@
\box_show:N \l_tempc_box
\hbox_set:Nn \l_tempc_box { \box_move_down:nn {10pt} { \box_use:N \l_tempa_box } }
\box_show:N \l_tempc_box
- \hbox_set:Nn \l_tempc_box { \box_move_down:nn {5pt} { \box_use_clear:N \l_tempb_box } }
+ \hbox_set:Nn \l_tempc_box { \box_move_down:nn {5pt} { \box_use_drop:N \l_tempb_box } }
\box_show:N \l_tempc_box
% now void
\hbox_set:Nn \l_tempc_box { \box_move_down:nn {99pt}
diff --git a/l3kernel/testfiles/m3expl001.luatex.tlg b/l3kernel/testfiles/m3expl001.luatex.tlg
index d86a5fe..9b7b433 100644
--- a/l3kernel/testfiles/m3expl001.luatex.tlg
+++ b/l3kernel/testfiles/m3expl001.luatex.tlg
@@ -5010,9 +5010,9 @@ Defining \box_set_wd:Nn on line ...
Defining \box_set_ht:cn on line ...
Defining \box_set_dp:cn on line ...
Defining \box_set_wd:cn on line ...
-Defining \box_use_clear:N on line ...
+Defining \box_use_drop:N on line ...
Defining \box_use:N on line ...
-Defining \box_use_clear:c on line ...
+Defining \box_use_drop:c on line ...
Defining \box_use:c on line ...
Defining \box_move_left:nn on line ...
Defining \box_move_right:nn on line ...
@@ -5184,6 +5184,8 @@ Defining \__box_autosize:Nnnn on line ...
Defining \__box_resize_common:N on line ...
Defining \box_resize:Nnn on line ...
Defining \box_resize:cnn on line ...
+Defining \box_use_clear:N on line ...
+Defining \box_use_clear:c on line ...
Defining \l__coffin_internal_box on line ...
\l__coffin_internal_box=\box62
Defining \l__coffin_internal_dim on line ...
diff --git a/l3kernel/testfiles/m3expl001.ptex.tlg b/l3kernel/testfiles/m3expl001.ptex.tlg
index e910285..755a196 100644
--- a/l3kernel/testfiles/m3expl001.ptex.tlg
+++ b/l3kernel/testfiles/m3expl001.ptex.tlg
@@ -5000,9 +5000,9 @@ Defining \box_set_wd:Nn on line ...
Defining \box_set_ht:cn on line ...
Defining \box_set_dp:cn on line ...
Defining \box_set_wd:cn on line ...
-Defining \box_use_clear:N on line ...
+Defining \box_use_drop:N on line ...
Defining \box_use:N on line ...
-Defining \box_use_clear:c on line ...
+Defining \box_use_drop:c on line ...
Defining \box_use:c on line ...
Defining \box_move_left:nn on line ...
Defining \box_move_right:nn on line ...
@@ -5174,6 +5174,8 @@ Defining \__box_autosize:Nnnn on line ...
Defining \__box_resize_common:N on line ...
Defining \box_resize:Nnn on line ...
Defining \box_resize:cnn on line ...
+Defining \box_use_clear:N on line ...
+Defining \box_use_clear:c on line ...
Defining \l__coffin_internal_box on line ...
\l__coffin_internal_box=\box62
Defining \l__coffin_internal_dim on line ...
diff --git a/l3kernel/testfiles/m3expl001.tlg b/l3kernel/testfiles/m3expl001.tlg
index 164d68b..733a254 100644
--- a/l3kernel/testfiles/m3expl001.tlg
+++ b/l3kernel/testfiles/m3expl001.tlg
@@ -5000,9 +5000,9 @@ Defining \box_set_wd:Nn on line ...
Defining \box_set_ht:cn on line ...
Defining \box_set_dp:cn on line ...
Defining \box_set_wd:cn on line ...
-Defining \box_use_clear:N on line ...
+Defining \box_use_drop:N on line ...
Defining \box_use:N on line ...
-Defining \box_use_clear:c on line ...
+Defining \box_use_drop:c on line ...
Defining \box_use:c on line ...
Defining \box_move_left:nn on line ...
Defining \box_move_right:nn on line ...
@@ -5174,6 +5174,8 @@ Defining \__box_autosize:Nnnn on line ...
Defining \__box_resize_common:N on line ...
Defining \box_resize:Nnn on line ...
Defining \box_resize:cnn on line ...
+Defining \box_use_clear:N on line ...
+Defining \box_use_clear:c on line ...
Defining \l__coffin_internal_box on line ...
\l__coffin_internal_box=\box62
Defining \l__coffin_internal_dim on line ...
diff --git a/l3kernel/testfiles/m3expl001.uptex.tlg b/l3kernel/testfiles/m3expl001.uptex.tlg
index 5676f0e..f468c5f 100644
--- a/l3kernel/testfiles/m3expl001.uptex.tlg
+++ b/l3kernel/testfiles/m3expl001.uptex.tlg
@@ -4998,9 +4998,9 @@ Defining \box_set_wd:Nn on line ...
Defining \box_set_ht:cn on line ...
Defining \box_set_dp:cn on line ...
Defining \box_set_wd:cn on line ...
-Defining \box_use_clear:N on line ...
+Defining \box_use_drop:N on line ...
Defining \box_use:N on line ...
-Defining \box_use_clear:c on line ...
+Defining \box_use_drop:c on line ...
Defining \box_use:c on line ...
Defining \box_move_left:nn on line ...
Defining \box_move_right:nn on line ...
@@ -5172,6 +5172,8 @@ Defining \__box_autosize:Nnnn on line ...
Defining \__box_resize_common:N on line ...
Defining \box_resize:Nnn on line ...
Defining \box_resize:cnn on line ...
+Defining \box_use_clear:N on line ...
+Defining \box_use_clear:c on line ...
Defining \l__coffin_internal_box on line ...
\l__coffin_internal_box=\box62
Defining \l__coffin_internal_dim on line ...
diff --git a/l3kernel/testfiles/m3expl001.xetex.tlg b/l3kernel/testfiles/m3expl001.xetex.tlg
index ca3c40a..bed7148 100644
--- a/l3kernel/testfiles/m3expl001.xetex.tlg
+++ b/l3kernel/testfiles/m3expl001.xetex.tlg
@@ -4988,9 +4988,9 @@ Defining \box_set_wd:Nn on line ...
Defining \box_set_ht:cn on line ...
Defining \box_set_dp:cn on line ...
Defining \box_set_wd:cn on line ...
-Defining \box_use_clear:N on line ...
+Defining \box_use_drop:N on line ...
Defining \box_use:N on line ...
-Defining \box_use_clear:c on line ...
+Defining \box_use_drop:c on line ...
Defining \box_use:c on line ...
Defining \box_move_left:nn on line ...
Defining \box_move_right:nn on line ...
@@ -5162,6 +5162,8 @@ Defining \__box_autosize:Nnnn on line ...
Defining \__box_resize_common:N on line ...
Defining \box_resize:Nnn on line ...
Defining \box_resize:cnn on line ...
+Defining \box_use_clear:N on line ...
+Defining \box_use_clear:c on line ...
Defining \l__coffin_internal_box on line ...
\l__coffin_internal_box=\box62
Defining \l__coffin_internal_dim on line ...
diff --git a/l3kernel/testfiles/m3expl003.luatex.tlg b/l3kernel/testfiles/m3expl003.luatex.tlg
index d86a5fe..9b7b433 100644
--- a/l3kernel/testfiles/m3expl003.luatex.tlg
+++ b/l3kernel/testfiles/m3expl003.luatex.tlg
@@ -5010,9 +5010,9 @@ Defining \box_set_wd:Nn on line ...
Defining \box_set_ht:cn on line ...
Defining \box_set_dp:cn on line ...
Defining \box_set_wd:cn on line ...
-Defining \box_use_clear:N on line ...
+Defining \box_use_drop:N on line ...
Defining \box_use:N on line ...
-Defining \box_use_clear:c on line ...
+Defining \box_use_drop:c on line ...
Defining \box_use:c on line ...
Defining \box_move_left:nn on line ...
Defining \box_move_right:nn on line ...
@@ -5184,6 +5184,8 @@ Defining \__box_autosize:Nnnn on line ...
Defining \__box_resize_common:N on line ...
Defining \box_resize:Nnn on line ...
Defining \box_resize:cnn on line ...
+Defining \box_use_clear:N on line ...
+Defining \box_use_clear:c on line ...
Defining \l__coffin_internal_box on line ...
\l__coffin_internal_box=\box62
Defining \l__coffin_internal_dim on line ...
diff --git a/l3kernel/testfiles/m3expl003.ptex.tlg b/l3kernel/testfiles/m3expl003.ptex.tlg
index e910285..755a196 100644
--- a/l3kernel/testfiles/m3expl003.ptex.tlg
+++ b/l3kernel/testfiles/m3expl003.ptex.tlg
@@ -5000,9 +5000,9 @@ Defining \box_set_wd:Nn on line ...
Defining \box_set_ht:cn on line ...
Defining \box_set_dp:cn on line ...
Defining \box_set_wd:cn on line ...
-Defining \box_use_clear:N on line ...
+Defining \box_use_drop:N on line ...
Defining \box_use:N on line ...
-Defining \box_use_clear:c on line ...
+Defining \box_use_drop:c on line ...
Defining \box_use:c on line ...
Defining \box_move_left:nn on line ...
Defining \box_move_right:nn on line ...
@@ -5174,6 +5174,8 @@ Defining \__box_autosize:Nnnn on line ...
Defining \__box_resize_common:N on line ...
Defining \box_resize:Nnn on line ...
Defining \box_resize:cnn on line ...
+Defining \box_use_clear:N on line ...
+Defining \box_use_clear:c on line ...
Defining \l__coffin_internal_box on line ...
\l__coffin_internal_box=\box62
Defining \l__coffin_internal_dim on line ...
diff --git a/l3kernel/testfiles/m3expl003.tlg b/l3kernel/testfiles/m3expl003.tlg
index 164d68b..733a254 100644
--- a/l3kernel/testfiles/m3expl003.tlg
+++ b/l3kernel/testfiles/m3expl003.tlg
@@ -5000,9 +5000,9 @@ Defining \box_set_wd:Nn on line ...
Defining \box_set_ht:cn on line ...
Defining \box_set_dp:cn on line ...
Defining \box_set_wd:cn on line ...
-Defining \box_use_clear:N on line ...
+Defining \box_use_drop:N on line ...
Defining \box_use:N on line ...
-Defining \box_use_clear:c on line ...
+Defining \box_use_drop:c on line ...
Defining \box_use:c on line ...
Defining \box_move_left:nn on line ...
Defining \box_move_right:nn on line ...
@@ -5174,6 +5174,8 @@ Defining \__box_autosize:Nnnn on line ...
Defining \__box_resize_common:N on line ...
Defining \box_resize:Nnn on line ...
Defining \box_resize:cnn on line ...
+Defining \box_use_clear:N on line ...
+Defining \box_use_clear:c on line ...
Defining \l__coffin_internal_box on line ...
\l__coffin_internal_box=\box62
Defining \l__coffin_internal_dim on line ...
diff --git a/l3kernel/testfiles/m3expl003.uptex.tlg b/l3kernel/testfiles/m3expl003.uptex.tlg
index 5676f0e..f468c5f 100644
--- a/l3kernel/testfiles/m3expl003.uptex.tlg
+++ b/l3kernel/testfiles/m3expl003.uptex.tlg
@@ -4998,9 +4998,9 @@ Defining \box_set_wd:Nn on line ...
Defining \box_set_ht:cn on line ...
Defining \box_set_dp:cn on line ...
Defining \box_set_wd:cn on line ...
-Defining \box_use_clear:N on line ...
+Defining \box_use_drop:N on line ...
Defining \box_use:N on line ...
-Defining \box_use_clear:c on line ...
+Defining \box_use_drop:c on line ...
Defining \box_use:c on line ...
Defining \box_move_left:nn on line ...
Defining \box_move_right:nn on line ...
@@ -5172,6 +5172,8 @@ Defining \__box_autosize:Nnnn on line ...
Defining \__box_resize_common:N on line ...
Defining \box_resize:Nnn on line ...
Defining \box_resize:cnn on line ...
+Defining \box_use_clear:N on line ...
+Defining \box_use_clear:c on line ...
Defining \l__coffin_internal_box on line ...
\l__coffin_internal_box=\box62
Defining \l__coffin_internal_dim on line ...
diff --git a/l3kernel/testfiles/m3expl003.xetex.tlg b/l3kernel/testfiles/m3expl003.xetex.tlg
index ca3c40a..bed7148 100644
--- a/l3kernel/testfiles/m3expl003.xetex.tlg
+++ b/l3kernel/testfiles/m3expl003.xetex.tlg
@@ -4988,9 +4988,9 @@ Defining \box_set_wd:Nn on line ...
Defining \box_set_ht:cn on line ...
Defining \box_set_dp:cn on line ...
Defining \box_set_wd:cn on line ...
-Defining \box_use_clear:N on line ...
+Defining \box_use_drop:N on line ...
Defining \box_use:N on line ...
-Defining \box_use_clear:c on line ...
+Defining \box_use_drop:c on line ...
Defining \box_use:c on line ...
Defining \box_move_left:nn on line ...
Defining \box_move_right:nn on line ...
@@ -5162,6 +5162,8 @@ Defining \__box_autosize:Nnnn on line ...
Defining \__box_resize_common:N on line ...
Defining \box_resize:Nnn on line ...
Defining \box_resize:cnn on line ...
+Defining \box_use_clear:N on line ...
+Defining \box_use_clear:c on line ...
Defining \l__coffin_internal_box on line ...
\l__coffin_internal_box=\box62
Defining \l__coffin_internal_dim on line ...
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the latex3-commits
mailing list