[latex3-commits] [git/LaTeX3-latex3-latex3] morechk: improve doc around checking for :c variants (2d6fc44)

[Will Robertson]

Repository : https://github.com/latex3/latex3
On branch  : morechk
Link       : https://github.com/latex3/latex3/commit/2d6fc44747b58c90eba724fde6d78a2c719f82c7

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

commit 2d6fc44747b58c90eba724fde6d78a2c719f82c7
Author: Will Robertson <wspr81 at gmail.com>
Date:   Wed Jan 16 14:47:12 2019 +1030

    improve doc around checking for :c variants


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

2d6fc44747b58c90eba724fde6d78a2c719f82c7
 l3kernel/l3box.dtx  |   48 ++++++++++++++++++++++++++++++++++++++++++++++--
 l3kernel/l3int.dtx  |    8 ++++++--
 l3kernel/l3skip.dtx |   24 ++++++++++++++++++------
 3 files changed, 70 insertions(+), 10 deletions(-)

diff --git a/l3kernel/l3box.dtx b/l3kernel/l3box.dtx
index 6f3b790..7f89ad7 100644
--- a/l3kernel/l3box.dtx
+++ b/l3kernel/l3box.dtx
@@ -111,13 +111,57 @@
 %     \cs{box_use: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.
+%   list for typesetting.
+%
+%   For \cs{box_use:c}, if the \texttt{check-declarations} option is in effect,
+%   an error is raised if the variable does not exist or if it is invalid.
+%   For \cs{box_use:N}, no checking is performed and lower-level errors will result
+%   if invalid or non-existent variables are used.
 %   \begin{texnote}
 %     This is the \TeX{} primitive \tn{copy}.
 %   \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.
+%
+%   For \cs{box_use_drop:c}, if the \texttt{check-declarations} option is in effect,
+%   an error is raised if the variable does not exist or if it is invalid.
+%   For \cs{box_use_drop:N}, no checking is performed and lower-level errors will result
+%   if invalid or non-existent variables are used.
+%
+%   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}
diff --git a/l3kernel/l3int.dtx b/l3kernel/l3int.dtx
index ac127fc..0cb4696 100644
--- a/l3kernel/l3int.dtx
+++ b/l3kernel/l3int.dtx
@@ -275,10 +275,14 @@
 %     \cs{int_use:N} \meta{integer}
 %   \end{syntax}
 %   Recovers the content of an \meta{integer} and places it directly
-%   in the input stream. An error is raised if the variable does
-%   not exist or if it is invalid. Can be omitted in places where an
+%   in the input stream. Can be omitted in places where an
 %   \meta{integer} is required (such as in the first and third arguments
 %   of \cs{int_compare:nNnTF}).
+%
+%   For \cs{int_use:c}, if the \texttt{check-declarations} option is in effect,
+%   an error is raised if the variable does not exist or if it is invalid.
+%   For \cs{int_use:N}, no checking is performed and lower-level errors will result
+%   if invalid or non-existent variables are used.
 %   \begin{texnote}
 %     \cs{int_use:N} is the \TeX{} primitive \tn{the}: this is one of
 %     several \LaTeX3 names for this primitive.
diff --git a/l3kernel/l3skip.dtx b/l3kernel/l3skip.dtx
index 319c9b0..5fa4649 100644
--- a/l3kernel/l3skip.dtx
+++ b/l3kernel/l3skip.dtx
@@ -458,10 +458,14 @@
 %     \cs{dim_use:N} \meta{dimension}
 %   \end{syntax}
 %   Recovers the content of a \meta{dimension} and places it directly
-%   in the input stream. An error is raised if the variable does
-%   not exist or if it is invalid. Can be omitted in places where a
+%   in the input stream.
+%   Can be omitted in places where a
 %   \meta{dimension} is required (such as in the argument of
 %   \cs{dim_eval:n}).
+%   For \cs{dim_use:c}, if the \texttt{check-declarations} option is in effect,
+%   an error is raised if the variable does not exist or if it is invalid.
+%   For \cs{dim_use:N}, no checking is performed and lower-level errors will result
+%   if invalid or non-existent variables are used.
 %   \begin{texnote}
 %     \cs{dim_use:N} is the \TeX{} primitive \tn{the}: this is one of
 %     several \LaTeX3 names for this primitive.
@@ -746,10 +750,14 @@
 %     \cs{skip_use:N} \meta{skip}
 %   \end{syntax}
 %   Recovers the content of a \meta{skip} and places it directly
-%   in the input stream. An error is raised if the variable does
-%   not exist or if it is invalid. Can be omitted in places where a
+%   in the input stream. Can be omitted in places where a
 %   \meta{dimension} or \meta{skip} is required (such as in the argument of
 %   \cs{skip_eval:n}).
+%
+%   For \cs{skip_use:c}, if the \texttt{check-declarations} option is in effect,
+%   an error is raised if the variable does not exist or if it is invalid.
+%   For \cs{skip_use:N}, no checking is performed and lower-level errors will result
+%   if invalid or non-existent variables are used.
 %   \begin{texnote}
 %     \cs{skip_use:N} is the \TeX{} primitive \tn{the}: this is one of
 %     several \LaTeX3 names for this primitive.
@@ -960,10 +968,14 @@
 %     \cs{muskip_use:N} \meta{muskip}
 %   \end{syntax}
 %   Recovers the content of a \meta{skip} and places it directly
-%   in the input stream. An error is raised if the variable does
-%   not exist or if it is invalid. Can be omitted in places where a
+%   in the input stream. Can be omitted in places where a
 %   \meta{dimension} is required (such as in the argument of
 %   \cs{muskip_eval:n}).
+%
+%   For \cs{int_use:c}, if the \texttt{check-declarations} option is in effect,
+%   an error is raised if the variable does not exist or if it is invalid.
+%   For \cs{int_use:N}, no checking is performed and lower-level errors will result
+%   if invalid or non-existent variables are used.
 %   \begin{texnote}
 %     \cs{muskip_use:N} is the \TeX{} primitive \tn{the}: this is one of
 %     several \LaTeX3 names for this primitive.