[latex3-commits] [l3svn] r7401 - Add checks to l3doc's syntax environment (fixes #381)
noreply at latex-project.org
noreply at latex-project.org
Wed Jul 19 06:00:55 CEST 2017
Author: bruno
Date: 2017-07-19 06:00:55 +0200 (Wed, 19 Jul 2017)
New Revision: 7401
Modified:
trunk/l3kernel/l3doc.dtx
trunk/l3kernel/l3fp-expo.dtx
trunk/l3kernel/l3fp-parse.dtx
Log:
Add checks to l3doc's syntax environment (fixes #381)
Now using two "syntax" environments in the same function causes
an error (previously the first "syntax" environment was discarded).
In this commit I also use "syntax" environment in a few places in
the implementation part. Not sure I like it (semantically).
Modified: trunk/l3kernel/l3doc.dtx
===================================================================
--- trunk/l3kernel/l3doc.dtx 2017-07-19 03:58:39 UTC (rev 7400)
+++ trunk/l3kernel/l3doc.dtx 2017-07-19 04:00:55 UTC (rev 7401)
@@ -1234,6 +1234,16 @@
{ The~deprecated~function(s)~'#1'~should~have~been~removed~on~#2. }
\msg_new:nnn { l3doc } { date-format }
{ The~date~'#1'~should~be~given~in~YYYY-MM-DD~format. }
+\msg_new:nnn { l3doc } { syntax-nested-function }
+ {
+ The~'syntax'~environment~should~be~used~in~the~
+ innermost~'function'~environment.
+ }
+\msg_new:nnn { l3doc } { multiple-syntax }
+ {
+ The~'syntax'~environment~should~only~be~used~once~in~
+ a~'function'~environment.
+ }
% \end{macrocode}
%
% \subsection{Options and configuration}
@@ -2252,10 +2262,13 @@
% \end{macro}
%
% \begin{macro}[aux]{\@@_function_init:}
-% Clear various variables.
+% Complain if \texttt{function} environments are nested. Clear
+% various variables.
% \begin{macrocode}
\cs_new_protected:Npn \@@_function_init:
{
+ \box_if_empty:NF \g_@@_syntax_box
+ { \msg_error:nn { l3doc } { syntax-nested-function } }
\coffin_clear:N \l_@@_descr_coffin
\box_gclear:N \g_@@_syntax_box
\coffin_clear:N \l_@@_syntax_coffin
@@ -2342,7 +2355,7 @@
\cs_new_protected:Npn \@@_function_assemble:
{
\hcoffin_set:Nn \l_@@_syntax_coffin
- { \box_use:N \g_@@_syntax_box }
+ { \box_use_clear:N \g_@@_syntax_box }
\bool_if:NTF \l_@@_long_name_bool
{
\coffin_join:NnnNnnnn
@@ -2527,6 +2540,8 @@
\dim_new:N \l_@@_syntax_dim
\cs_new_protected:Npn \@@_syntax:w
{
+ \box_if_empty:NF \g_@@_syntax_box
+ { \msg_error:nn { l3doc } { multiple-syntax } }
\dim_set:Nn \l_@@_syntax_dim
{
\textwidth
@@ -2551,8 +2566,10 @@
\hbox_gset_end:
\bool_if:NF \l_@@_in_function_bool
{
- \mode_leave_vertical:
- \box_use:N \g_@@_syntax_box
+ \begin{quote}
+ \mode_leave_vertical:
+ \box_use_clear:N \g_@@_syntax_box
+ \end{quote}
}
}
% \end{macrocode}
Modified: trunk/l3kernel/l3fp-expo.dtx
===================================================================
--- trunk/l3kernel/l3fp-expo.dtx 2017-07-19 03:58:39 UTC (rev 7400)
+++ trunk/l3kernel/l3fp-expo.dtx 2017-07-19 04:00:55 UTC (rev 7401)
@@ -191,15 +191,13 @@
% \end{macro}
%
% \begin{macro}[aux, EXP]{\@@_ln_significand:NNNNnnnN}
-% \begin{quote}
-% \cs{@@_ln_significand:NNNNnnnN} \meta{X_1} \Arg{X_2} \Arg{X_3}
-% \Arg{X_4} \meta{continuation}
-% \end{quote}
+% \begin{syntax}
+% \cs{@@_ln_significand:NNNNnnnN} \meta{X_1} \Arg{X_2} \Arg{X_3} \Arg{X_4} \meta{continuation}
+% \end{syntax}
% This function expands to
-% \begin{quote}
-% \meta{continuation} \Arg{Y_1} \Arg{Y_2} \Arg{Y_3} \Arg{Y_4}
-% \Arg{Y_5} \Arg{Y_6} |;|
-% \end{quote}
+% \begin{syntax}
+% \meta{continuation} \Arg{Y_1} \Arg{Y_2} \Arg{Y_3} \Arg{Y_4} \Arg{Y_5} \Arg{Y_6} |;|
+% \end{syntax}
% where $Y = - \ln(X)$ as an extended fixed point.
% \begin{macrocode}
\cs_new:Npn \@@_ln_significand:NNNNnnnN #1#2#3#4
@@ -316,10 +314,9 @@
% a faithful rounding).
% ^^A todo: doc
%
-% \begin{quote}
-% \cs{@@_ln_x_iv:wnnnnnnnn}
-% \meta{1 or 2} \meta{8d} |;| \Arg{4d} \Arg{4d} \meta{fixed-tl}
-% \end{quote}
+% \begin{syntax}
+% \cs{@@_ln_x_iv:wnnnnnnnn} \meta{1 or 2} \meta{8d} |;| \Arg{4d} \Arg{4d} \meta{fixed-tl}
+% \end{syntax}
% The number is $x$. Compute $y$ by adding 1 to the five first digits.
% \begin{macrocode}
\cs_new:Npn \@@_ln_x_iv:wnnnnnnnn #1; #2#3#4#5 #6#7#8#9
@@ -357,7 +354,7 @@
% We now have essentially
% ^^A todo: determine error on $Q_{6}$ (probably $6.7$),
% ^^A todo: conclude the final result is off by $<10^{-23}$
-% \begin{quote}
+% \begin{syntax}
% \cs{@@_ln_div_after:Nw} \meta{fixed tl}
% \cs{@@_div_significand_pack:NNN} $10^6 + Q_{1}$
% \cs{@@_div_significand_pack:NNN} $10^6 + Q_{2}$
@@ -366,16 +363,17 @@
% \cs{@@_div_significand_pack:NNN} $10^6 + Q_{5}$
% \cs{@@_div_significand_pack:NNN} $10^6 + Q_{6}$ |;|
% \meta{exponent} |;| \meta{continuation}
-% \end{quote}
+% \end{syntax}
% where \meta{fixed tl} holds the logarithm of a number
% in $[1,10]$, and \meta{exponent} is
% the exponent. Also, the expansion is done backwards. Then
% \cs{@@_div_significand_pack:NNN} puts things in the
% correct order to add the $Q_{i}$ together and put semicolons
% between each piece. Once those have been expanded, we get
-% \begin{quote}
-% \cs{@@_ln_div_after:Nw} \meta{fixed-tl} \meta{1d} |;| \meta{4d} |;| \meta{4d} |;| \meta{4d} |;| \meta{4d} |;| \meta{4d} |;| \meta{4d} |;| \meta{exponent} |;|
-% \end{quote}
+% \begin{syntax}
+% \cs{@@_ln_div_after:Nw} \meta{fixed-tl} \meta{1d} |;| \meta{4d} |;| \meta{4d} |;|
+% ~~\meta{4d} |;| \meta{4d} |;| \meta{4d} |;| \meta{4d} |;| \meta{exponent} |;|
+% \end{syntax}
% ^^A todo: redoc.
% Just as with division, we know that the first two digits
% are |1| and |0| because of bounds on the final result of
@@ -407,9 +405,11 @@
}
% \end{macrocode}
%
-% \begin{quote}
-% \cs{@@_ln_t_large:NNw} \meta{sign}\meta{fixed tl} \meta{t_1}|;| \meta{t_2} |;| \meta{t_3}|;| \meta{t_4}|;| \meta{t_5} |;| \meta{t_6}|;| \meta{exponent} |;| \meta{continuation}
-% \end{quote}
+% \begin{syntax}
+% \cs{@@_ln_t_large:NNw} \meta{sign} \meta{fixed tl}
+% ~~\meta{t_1}|;| \meta{t_2} |;| \meta{t_3}|;| \meta{t_4}|;| \meta{t_5} |;| \meta{t_6}|;|
+% ~~\meta{exponent} |;| \meta{continuation}
+% \end{syntax}
% Compute the square $|t|^2$, and keep $|t|$ at the end with its
% sign. We know that $|t|<0.1765$, so every piece has at most $4$
% digits. However, since we were not careful in \cs{@@_ln_t_small:w},
@@ -455,13 +455,13 @@
%
% \begin{macro}{\@@_ln_Taylor:wwNw}
% Denoting $T=t^2$, we get
-% \begin{quote}
+% \begin{syntax}
% \cs{@@_ln_Taylor:wwNw}
-% \Arg{T_1} \Arg{T_2} \Arg{T_3} \Arg{T_4} \Arg{T_5} \Arg{T_6} |;| |;|
-% \Arg{(2t)_1} \Arg{(2t)_2} \Arg{(2t)_3} \Arg{(2t)_4} \Arg{(2t)_5} \Arg{(2t)_6} |;|
-% |{| \cs{@@_ln_c:NwNw} \meta{sign} |}|
-% \meta{fixed tl} \meta{exponent} |;| \meta{continuation}
-% \end{quote}
+% ~~\Arg{T_1} \Arg{T_2} \Arg{T_3} \Arg{T_4} \Arg{T_5} \Arg{T_6} |;| |;|
+% ~~\Arg{(2t)_1} \Arg{(2t)_2} \Arg{(2t)_3} \Arg{(2t)_4} \Arg{(2t)_5} \Arg{(2t)_6} |;|
+% ~~|{| \cs{@@_ln_c:NwNw} \meta{sign} |}|
+% ~~\meta{fixed tl} \meta{exponent} |;| \meta{continuation}
+% \end{syntax}
% And we want to compute
% \[
% \ln\left(\frac{1+t}{1-t}\right)
@@ -508,11 +508,11 @@
% \end{macro}
%
% \begin{macro}{\@@_ln_c:NwNw}
-% \begin{quote}
+% \begin{syntax}
% \cs{@@_ln_c:NwNw} \meta{sign}
-% \Arg{r_1} \Arg{r_2} \Arg{r_3} \Arg{r_4} \Arg{r_5} \Arg{r_6} |;|
-% \meta{fixed tl} \meta{exponent} |;| \meta{continuation}
-% \end{quote}
+% ~~\Arg{r_1} \Arg{r_2} \Arg{r_3} \Arg{r_4} \Arg{r_5} \Arg{r_6} |;|
+% ~~\meta{fixed tl} \meta{exponent} |;| \meta{continuation}
+% \end{syntax}
% We are now reduced to finding $\ln(c)$ and $\meta{exponent}\ln(10)$
% in a table, and adding it to the mixture. The first step is to
% get $\ln(c) - \ln(x) = - \ln(a)$, then we get $|b|\ln(10)$ and add
@@ -535,11 +535,11 @@
% \end{macro}
%
% \begin{macro}{\@@_ln_exponent:wn}
-% \begin{quote}\raggedright
+% \begin{syntax}
% \cs{@@_ln_exponent:wn}
-% \Arg{s_1} \Arg{s_2} \Arg{s_3} \Arg{s_4} \Arg{s_5} \Arg{s_6} |;|
-% \Arg{exponent}
-% \end{quote}
+% ~~\Arg{s_1} \Arg{s_2} \Arg{s_3} \Arg{s_4} \Arg{s_5} \Arg{s_6} |;|
+% ~~\Arg{exponent}
+% \end{syntax}
% Compute \meta{exponent} times $\ln(10)$. Apart from the cases where
% \meta{exponent} is $0$ or $1$, the result is necessarily at
% least $\ln(10) \simeq 2.3$ in magnitude. We can thus drop the least
Modified: trunk/l3kernel/l3fp-parse.dtx
===================================================================
--- trunk/l3kernel/l3fp-parse.dtx 2017-07-19 03:58:39 UTC (rev 7400)
+++ trunk/l3kernel/l3fp-parse.dtx 2017-07-19 04:00:55 UTC (rev 7401)
@@ -181,11 +181,10 @@
% be values of registers. Assume that one number, say, $12345$, has
% already been found, and that we want to parse the next number. The
% current status of the code may look as follows.
-% \begin{quote}\ttfamily
-% \cs{exp_after:wN} |\add:ww|
-% \cs{__int_value:w} 12345 \cs{exp_after:wN} ; \newline
+% \begin{syntax}
+% \cs{exp_after:wN} |\add:ww| \cs{__int_value:w} 12345 \cs{exp_after:wN} ;
% \cs{exp:w} |\operand:w| \meta{stuff}
-% \end{quote}
+% \end{syntax}
% One step of expansion expands \cs{exp_after:wN}, which triggers the
% primitive \cs{__int_value:w}, which reads the five digits we have
% already found, |12345|. This integer is unfinished, causing the
@@ -194,19 +193,19 @@
% what follows and make a number out of it, then leave \cs{exp_end:}, the
% number, and a semicolon in the input stream. Once |\operand:w| is
% done expanding, we obtain essentially
-% \begin{quote}\ttfamily
-% \cs{exp_after:wN} |\add:ww| \cs{__int_value:w} 12345 ; \newline
+% \begin{syntax}
+% \cs{exp_after:wN} |\add:ww| \cs{__int_value:w} 12345 ;
% \cs{exp:w} \cs{exp_end:} 333444 ;
-% \end{quote}
+% \end{syntax}
% where in fact \cs{exp_after:wN} has already been expanded,
% \cs{__int_value:w} has already seen |12345|, and
% \cs{exp:w} is still looking for a number. It finds
% \cs{exp_end:}, hence expands to nothing. Now, \cs{__int_value:w} sees
% the \texttt{;}, which cannot be part of a number. The expansion
% stops, and we are left with
-% \begin{quote}\ttfamily
+% \begin{syntax}
% |\add:ww| 12345 ; 333444 ;
-% \end{quote}
+% \end{syntax}
% which can safely perform the addition by grabbing two arguments
% delimited by~|;|.
%
@@ -290,10 +289,10 @@
% of this function is that it reads one \meta{number}, performing no
% computation, and finds the following binary \meta{operator}. Then it
% expands to
-% \begin{quote}
-% \meta{number} \newline
-% ~~|\__fp_parse_infix_|\meta{operator}|:N| \meta{precedence}
-% \end{quote}
+% \begin{syntax}
+% \meta{number}
+% | \__fp_parse_infix_|\meta{operator}|:N| \meta{precedence}
+% \end{syntax}
% expanding the \texttt{infix} auxiliary before leaving the above in the
% input stream.
%
@@ -310,17 +309,17 @@
% auxiliary for the following \meta{operator}, to know whether to
% perform the computation of the \meta{operator}. If it should not be
% performed, the \texttt{infix} auxiliary expands to
-% \begin{quote}
+% \begin{syntax}
% |@| \cs{use_none:n} |\__fp_parse_infix_|\meta{operator}|:N|
-% \end{quote}
+% \end{syntax}
% and otherwise it calls \cs{@@_parse_operand:Nw} with the precedence of
% the \meta{operator} to find its second operand \meta{number_2} and the
% next \meta{operator_2}, and expands to
-% \begin{quote}
-% |@| \cs{@@_parse_apply_binary:NwNwN} \newline
-% ~~~~\meta{operator} \meta{number_2} \newline
+% \begin{syntax}
+% |@| \cs{@@_parse_apply_binary:NwNwN}
+% ~~~~\meta{operator} \meta{number_2}
% |@| |\__fp_parse_infix_|\meta{operator_2}|:N|
-% \end{quote}
+% \end{syntax}
% The \texttt{infix} function is responsible for comparing precedences,
% but cannot directly call the computation functions, because the first
% operand \meta{number} is before the \texttt{infix} function in the
@@ -329,57 +328,57 @@
%
% A definition of \cs{@@_parse_operand:Nw} \meta{precedence} with some
% of the expansion control removed is
-% \begin{quote}
-% \cs{exp_after:wN} \cs{@@_parse_continue:NwN} \newline
-% \cs{exp_after:wN} \meta{precedence} \newline
-% \cs{exp:w} \cs{exp_end_continue_f:w} \newline
+% \begin{syntax}
+% \cs{exp_after:wN} \cs{@@_parse_continue:NwN}
+% \cs{exp_after:wN} \meta{precedence}
+% \cs{exp:w} \cs{exp_end_continue_f:w}
% ~~\cs{@@_parse_one:Nw} \meta{precedence}
-% \end{quote}
+% \end{syntax}
% This expands \cs{@@_parse_one:Nw} \meta{precedence} completely, which
% finds a number, wraps the next \meta{operator} into an \texttt{infix}
% function, feeds this function the \meta{precedence}, and expands it,
% yielding either
-% \begin{quote}
-% \cs{@@_parse_continue:NwN} \meta{precedence} \newline
-% \meta{number} |@| \newline
+% \begin{syntax}
+% \cs{@@_parse_continue:NwN} \meta{precedence}
+% \meta{number} |@|
% \cs{use_none:n} |\__fp_parse_infix_|\meta{operator}|:N|
-% \end{quote}
+% \end{syntax}
% or
-% \begin{quote}
-% \cs{@@_parse_continue:NwN} \meta{precedence} \newline
-% \meta{number} |@| \newline
-% \cs{@@_parse_apply_binary:NwNwN} \newline
-% ~~\meta{operator} \meta{number_2} \newline
+% \begin{syntax}
+% \cs{@@_parse_continue:NwN} \meta{precedence}
+% \meta{number} |@|
+% \cs{@@_parse_apply_binary:NwNwN}
+% ~~\meta{operator} \meta{number_2}
% |@| |\__fp_parse_infix_|\meta{operator_2}|:N|
-% \end{quote}
+% \end{syntax}
% The definition of \cs{@@_parse_continue:NwN} is then very simple:
-% \begin{verbatim}
-% \cs_new:Npn \__fp_parse_continue:NwN #1#2@#3 { #3 #1 #2 @ }
-% \end{verbatim}
+% \begin{syntax}
+% |\cs_new:Npn \__fp_parse_continue:NwN #1#2@#3 { #3 #1 #2 @ }|
+% \end{syntax}
% In the first case, |#3|~is \cs{use_none:n}, yielding
-% \begin{quote}
-% \cs{use_none:n} \meta{precedence} \meta{number} |@| \newline
+% \begin{syntax}
+% \cs{use_none:n} \meta{precedence} \meta{number} |@|
% |\__fp_parse_infix_|\meta{operator}|:N|
-% \end{quote}
+% \end{syntax}
% then \meta{number} |@| |\__fp_parse_infix_|\meta{operator}|:N|. In
% the second case, |#3|~is \cs{@@_parse_apply_binary:NwNwN}, whose role
% is to compute \meta{number} \meta{operator} \meta{number_2} and to
% prepare for the next comparison of precedences: first we get
-% \begin{quote}
-% \cs{@@_parse_apply_binary:NwNwN} \newline
-% ~~\meta{precedence} \meta{number} |@| \newline
-% ~~\meta{operator} \meta{number_2} \newline
+% \begin{syntax}
+% \cs{@@_parse_apply_binary:NwNwN}
+% ~~\meta{precedence} \meta{number} |@|
+% ~~\meta{operator} \meta{number_2}
% |@| |\__fp_parse_infix_|\meta{operator_2}|:N|
-% \end{quote}
+% \end{syntax}
% then
-% \begin{quote}
-% \cs{exp_after:wN} \cs{@@_parse_continue:NwN} \newline
-% \cs{exp_after:wN} \meta{precedence} \newline
-% \cs{exp:w} \cs{exp_end_continue_f:w} \newline
-% |\__fp_|\meta{operator}|_o:ww| \meta{number} \meta{number_2} \newline
-% \cs{exp:w} \cs{exp_end_continue_f:w} \newline
+% \begin{syntax}
+% \cs{exp_after:wN} \cs{@@_parse_continue:NwN}
+% \cs{exp_after:wN} \meta{precedence}
+% \cs{exp:w} \cs{exp_end_continue_f:w}
+% |\__fp_|\meta{operator}|_o:ww| \meta{number} \meta{number_2}
+% \cs{exp:w} \cs{exp_end_continue_f:w}
% |\__fp_parse_infix_|\meta{operator_2}|:N| \meta{precedence}
-% \end{quote}
+% \end{syntax}
% where |\__fp_|\meta{operator}|_o:ww| computes \meta{number}
% \meta{operator} \meta{number_2} and expands after the result, thus
% triggers the comparison of the precedence of the \meta{operator_2} and
@@ -679,9 +678,9 @@
% functions read tokens one by one, and output digits into the input
% stream, until meeting a non-digit, or up to a number of digits equal
% to their index. The full expansion is
-% \begin{quote}
+% \begin{syntax}
% \meta{digits} |;| \meta{filling 0} |;| \meta{length}
-% \end{quote}
+% \end{syntax}
% where \meta{filling 0} is a string of zeros such that \meta{digits}
% \meta{filling 0} has the length given by the index of the function,
% and \meta{length} is the number of zeros in the \meta{filling 0}
@@ -1574,11 +1573,11 @@
%
% Expansion is a little bit tricky here, in part because we accept input
% where multiplication is implicit.
-% \begin{verbatim}
-% \@@_parse:n { 3.2 erf(0.1) }
-% \@@_parse:n { 3.2 e\l_my_int }
-% \@@_parse:n { 3.2 \c_pi_fp }
-% \end{verbatim}
+% \begin{syntax}
+% \cs{@@_parse:n} |{ 3.2 erf(0.1) }|
+% \cs{@@_parse:n} |{ 3.2 e\l_my_int }|
+% \cs{@@_parse:n} |{ 3.2 \c_pi_fp }|
+% \end{syntax}
% The first case indicates that just looking one character ahead for an
% \enquote{\texttt{e}} is not enough, since we would mistake the
% function \texttt{erf} for an exponent of \enquote{\texttt{rf}}. An
More information about the latex3-commits
mailing list