[latex3-commits] [git/LaTeX3-latex3-latex3] morechk: improve doc around checking for :c variants (415b165)
Will Robertson
wspr81 at gmail.com
Mon Apr 15 13:44:45 CEST 2019
Repository : https://github.com/latex3/latex3
On branch : morechk
Link : https://github.com/latex3/latex3/commit/415b1655716f0b92c6fc7ada8dbe6d3059c289b6
>---------------------------------------------------------------
commit 415b1655716f0b92c6fc7ada8dbe6d3059c289b6
Author: Will Robertson <wspr81 at gmail.com>
Date: Wed Jan 16 14:47:12 2019 +1030
improve doc around checking for :c variants
>---------------------------------------------------------------
415b1655716f0b92c6fc7ada8dbe6d3059c289b6
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 4a45989..8d4f6b4 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 b68e3a9..6312a2c 100644
--- a/l3kernel/l3int.dtx
+++ b/l3kernel/l3int.dtx
@@ -304,10 +304,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 0f8329a..ba38049 100644
--- a/l3kernel/l3skip.dtx
+++ b/l3kernel/l3skip.dtx
@@ -462,10 +462,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.
@@ -750,10 +754,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.
@@ -964,10 +972,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.
More information about the latex3-commits
mailing list