[latex3-commits] [l3svn] r7032 - Document that boolean expressions will become eager [ci skip]

[noreply at latex-project.org]

Author: bruno
Date: 2017-03-29 15:29:20 +0200 (Wed, 29 Mar 2017)
New Revision: 7032

Modified:
   trunk/l3kernel/l3prg.dtx
Log:
Document that boolean expressions will become eager [ci skip]

Next commit will move candidates bool_lazy to l3prg


Modified: trunk/l3kernel/l3prg.dtx
===================================================================
--- trunk/l3kernel/l3prg.dtx	2017-03-28 08:31:13 UTC (rev 7031)
+++ trunk/l3kernel/l3prg.dtx	2017-03-29 13:29:20 UTC (rev 7032)
@@ -174,8 +174,8 @@
 %     \cs{prg_new_eq_conditional:NNn} \cs[no-index]{\meta{name_1}:\meta{arg spec_1}} \cs[no-index]{\meta{name_2}:\meta{arg spec_2}} \Arg{conditions}
 %   \end{syntax}
 %   These functions copy a family of conditionals. The \texttt{new} version
-%   will check for existing definitions (\emph{cf.}~\cs{cs_new:Npn}) whereas
-%   the \texttt{set} version will not (\emph{cf.}~\cs{cs_set:Npn}). The
+%   will check for existing definitions (\emph{cf.}~\cs{cs_new_eq:NN}) whereas
+%   the \texttt{set} version will not (\emph{cf.}~\cs{cs_set_eq:NN}). The
 %   conditionals copied are depended on the comma-separated list of
 %   \meta{conditions}, which should be one or more of \texttt{p}, \texttt{T},
 %   \texttt{F} and \texttt{TF}.
@@ -186,7 +186,7 @@
 %     \cs{prg_return_true:}
 %     \cs{prg_return_false:}
 %   \end{syntax}
-%   These `return' functions define the logical state of a conditional statement.
+%   These \enquote{return} functions define the logical state of a conditional statement.
 %   They appear within the code for a conditional
 %   function generated by \cs{prg_set_conditional:Npnn}, \emph{etc}, to indicate
 %   when a true or false branch should be taken.
@@ -194,7 +194,7 @@
 %   the execution of the conditional must result in the expansion of one of these
 %   two functions \emph{exactly once}.
 %
-%   The return functions trigger what is internally an f-expansion process to complete
+%   The return functions trigger what is internally an \texttt{f}-expansion process to complete
 %   the evaluation of the conditional. Therefore, after \cs{prg_return_true:} or \cs{prg_return_false:}
 %   there must be no non-expandable material in the input stream for the remainder of
 %   the expansion of the conditional code. This includes other instances of either of these functions.
@@ -267,7 +267,7 @@
 %   \begin{syntax}
 %     \cs{bool_set_eq:NN} \meta{boolean_1} \meta{boolean_2}
 %   \end{syntax}
-%   Sets the content of \meta{boolean_1} equal to that of \meta{boolean_2}.
+%   Sets \meta{boolean_1} to the current value of \meta{boolean_2}.
 % \end{function}
 %
 % \begin{function}[updated = 2012-07-08]
@@ -369,8 +369,19 @@
 % is a valid boolean expression.
 %
 % At present, the infix operators |&&| and \verb"||" perform lazy
-% evaluation as well, but this will change in a future release.
+% evaluation, but this will change in the near future.
+% Contrarily to some other programming languages, the operators |&&| and
+% \verb"||" will evaluate both operands in all cases, even when the first
+% operand is enough to determine the result.  This \enquote{eager}
+% evaluation should be contrasted with the \enquote{lazy} evaluation of
+% \cs[no-index]{bool_lazy_\ldots{}} functions.
 %
+% \begin{texnote}
+%   The eager evaluation of boolean expressions is unfortunately
+%   necessary.  Indeed, a lazy parser can get confused if |&&| and
+%   \verb"||" appear as (unbraced) arguments of some predicates.
+% \end{texnote}
+%
 % \begin{function}[EXP, pTF, updated = 2012-07-08]{\bool_if:n}
 %   \begin{syntax}
 %     \cs{bool_if_p:n} \Arg{boolean expression}