[latex3-commits] [latex3/latex3] main: Re-work explanation of expansion speed (see #1340) (66d321db1)

[github at latex-project.org]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/66d321db10ce36446e1c2778c16fc9262ac0043b

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

commit 66d321db10ce36446e1c2778c16fc9262ac0043b
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Mon Nov 27 10:48:26 2023 +0000

    Re-work explanation of expansion speed (see #1340)


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

66d321db10ce36446e1c2778c16fc9262ac0043b
 l3kernel/l3expan.dtx | 24 ++++++++++--------------
 1 file changed, 10 insertions(+), 14 deletions(-)

diff --git a/l3kernel/l3expan.dtx b/l3kernel/l3expan.dtx
index f422ffac6..63929ec16 100644
--- a/l3kernel/l3expan.dtx
+++ b/l3kernel/l3expan.dtx
@@ -310,23 +310,19 @@
 %
 % When speed is essential (for functions that do very little work and
 % whose variants are used numerous times in a document) the following
-% considerations apply because internal functions for argument expansion
-% come in two flavours, some faster than others.
+% considerations apply because the speed of internal functions that
+% expand the arguments of a base function depend on what needs doing
+% with each argument and where this happens in the list of arguments:
 % \begin{itemize}
 %   \item
-%     Arguments that might need expansion should come first in the list
-%     of arguments.
+%     Arguments that are \emph{unchanged} by expansion (|N|- and |n|-type)
+%     should come last: the internal functions then avoid absorbing these
+%     entirely, giving a small speed gain.
 %   \item
-%     Arguments that should consist of single tokens |N|, |c|, |V|, or
-%     |v| should come first among these.
-%   \item
-%     Arguments that appear after the first multi-token argument |n|,
-%     |f|, |e|, or |o| require slightly slower special processing to be
-%     expanded.  Therefore it is best to use the optimized functions,
-%     namely those that contain only |N|, |c|, |V|, and |v|, and, in the
-%     last position, |o|, |f|, |e|, with possible trailing |N| or |n| or
-%     |T| or |F|, which are not expanded.  Any |x|-type argument causes
-%     slightly slower processing.
+%     Expansion to an |N|-type argument gives an internal result that
+%     can be manipulated faster than ones that expand to an |n|-type
+%     argument; thus any |c|-type expansion should come before |V|-,
+%     |v|-, |o|-, |e|-, |f|- or |x|-type.
 % \end{itemize}
 %
 % \section{Manipulating the first argument}