[latex3-commits] [latex3/latex3] develop: Extend docs for dim/str case functions (39e8bbd85)

[github at latex-project.org]

Repository : https://github.com/latex3/latex3
On branch  : develop
Link       : https://github.com/latex3/latex3/commit/39e8bbd85d1e4f6e80721753053f41a17733b039

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

commit 39e8bbd85d1e4f6e80721753053f41a17733b039
Author: Joseph Wright <joseph at texdev.net>
Date:   Fri Sep 6 09:16:55 2024 +0100

    Extend docs for dim/str case functions


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

39e8bbd85d1e4f6e80721753053f41a17733b039
 l3kernel/l3skip.dtx | 7 ++++++-
 l3kernel/l3str.dtx  | 3 ++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/l3kernel/l3skip.dtx b/l3kernel/l3skip.dtx
index 2a4130845..e294c9d9d 100644
--- a/l3kernel/l3skip.dtx
+++ b/l3kernel/l3skip.dtx
@@ -277,7 +277,8 @@
 %   \end{syntax}
 %   This function evaluates the \meta{test dim expr} and
 %   compares this in turn to each of the
-%   \meta{dim expr cases}. If the two are equal then the
+%   \meta{dim expr cases} until a a match is found.
+%   If the two are equal then the
 %   associated \meta{code} is left in the input stream
 %   and other cases are discarded. If any of the
 %   cases are matched, the \meta{true code} is also inserted into the
@@ -297,6 +298,10 @@
 %       { No idea! }
 %    \end{verbatim}
 %    leaves \enquote{\texttt{Medium}} in the input stream.
+%   Since evaluation of the test expressions stops at the first
+%   successful case, the order of possible matches should normally
+%   be that the most likely are earlier: this will reduce the average
+%   steps required to complete expansion.
 % \end{function}
 %
 % \section{Dimension expression loops}
diff --git a/l3kernel/l3str.dtx b/l3kernel/l3str.dtx
index 0f95bcc89..bba755780 100644
--- a/l3kernel/l3str.dtx
+++ b/l3kernel/l3str.dtx
@@ -303,7 +303,8 @@
 %     ~~\Arg{false code}
 %   \end{syntax}
 %   Compares the \meta{test string} in turn with each
-%   of the \meta{string case}s (all token lists are converted to strings).
+%   of the \meta{string case}s until a match is found
+%   (all token lists are converted to strings).
 %   If the two are equal (as described for
 %   \cs{str_if_eq:nnTF}) then the associated \meta{code} is left in the
 %   input stream and other cases are discarded. If any of the