[latex3-commits] [git/LaTeX3-latex3-latex2e] gh005: documentation added for #5 ; warning added when bracket grou is picked up by mistakr; test extended and fixed (766494a1)
Frank Mittelbach
frank.mittelbach at latex-project.org
Tue Mar 10 23:05:35 CET 2020
Repository : https://github.com/latex3/latex2e
On branch : gh005
Link : https://github.com/latex3/latex2e/commit/766494a1714a0b74ffb95b8437576894aa9153a2
>---------------------------------------------------------------
commit 766494a1714a0b74ffb95b8437576894aa9153a2
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Tue Mar 10 23:05:35 2020 +0100
documentation added for #5 ;
warning added when bracket grou is picked up by mistakr;
test extended and fixed
>---------------------------------------------------------------
766494a1714a0b74ffb95b8437576894aa9153a2
base/doc/ltnews32.tex | 62 +++++++++-----
required/amsmath/amsmath.dtx | 53 ++++++++++--
required/amsmath/changes.txt | 9 +-
.../testfiles/github-amsmath-0005.luatex.tlg | 98 ++++++++++++++++++----
required/amsmath/testfiles/github-amsmath-0005.lvt | 12 +--
required/amsmath/testfiles/github-amsmath-0005.tlg | 98 ++++++++++++++++++----
6 files changed, 263 insertions(+), 69 deletions(-)
diff --git a/base/doc/ltnews32.tex b/base/doc/ltnews32.tex
index da271c99..cab79d7a 100644
--- a/base/doc/ltnews32.tex
+++ b/base/doc/ltnews32.tex
@@ -143,23 +143,25 @@ This document is under construction \ldots
\section{Providing \pkg{xparse} in the format}
-The official interface in the \LaTeXe{} kernel for creating document-level
-commands has always been \cs{newcommand}. However, this is very limited in the
-types of command it can create: those taking at most one optional argument in
-square brackets, then zero or more mandatory arguments. Richer syntaxes
-required use of the \TeX{} \cs{def} primitive along with appropriate macro
-programming.
-
-The \LaTeX{} team started work on a comprehensive document-command parser,
-\pkg{xparse}, in the late 1990s. In the past decade, the experimental ideas it
-provides have been carefully worked through and moved to a stable footing. As
-such, \pkg{xparse} is now used to define a very large number of document
-commands. It does this by providing a rich and self-consistent syntax to
-describe a wide range interfaces seen in \LaTeX{} packages.
-
-The ideas developed in \pkg{xparse} are now sufficiently well-tested that
-the majority can be transferred into the \LaTeX{} kernel. Thus the following
-commands have been added
+The official interface in the \LaTeXe{} kernel for creating
+document-level commands has always been \cs{newcommand}. This was a
+big step forward from \LaTeX~2.09. However, it was still very limited
+in the types of command it can create: those taking at most one
+optional argument in square brackets, then zero or more mandatory
+arguments. Richer syntaxes required use of the \TeX{} \cs{def}
+primitive along with appropriate low-level macro programming.
+
+The \LaTeX{} team started work on a comprehensive document-command
+parser, \pkg{xparse}, in the late 1990s. In the past decade, the
+experimental ideas it provides have been carefully worked through and
+moved to a stable footing. As such, \pkg{xparse} is now used to define
+a very large number of document and package commands. It does this by
+providing a rich and self-consistent syntax to describe a wide range
+interfaces seen in \LaTeX{} packages.
+
+The ideas developed in \pkg{xparse} are now sufficiently well-tested
+that the majority can be transferred into the \LaTeX{} kernel. Thus
+the following commands have been added
\begin{itemize}
\item \cs{NewDocumentCommand}, \cs{RenewDocumentCommand},
\cs{ProvideDocumentCommand}, \cs{DeclareDocumentCommand}
@@ -177,11 +179,12 @@ commands have been added
\cs{GetDocumentEnvironmentArgSpec}
\end{itemize}
-The full list of argument types defined by \pkg{xparse} are \emph{not}
-supported at the kernel level. In particular, the types \texttt{g}/\texttt{G}, \texttt{l} and
-\texttt{u} are not provided by the kernel code; these are deprecated but still
-available by explicitly loading \pkg{xparse}. All other argument types
-\emph{are} now available directly within the \LaTeXe{} kernel.
+Most, but not all, of the argument types defined by \pkg{xparse} are
+now supported at the kernel level. In particular, the types
+\texttt{g}/\texttt{G}, \texttt{l} and \texttt{u} are \emph{not} provided by
+the kernel code; these are deprecated but still available by
+explicitly loading \pkg{xparse}. All other argument types \emph{are}
+now available directly within the \LaTeXe{} kernel.
\section{Other changes to the \LaTeX{} kernel}
@@ -292,5 +295,20 @@ were not at the same baseline. This has been corrected.
%
\githubissue{126}
+\subsection{Fixes to \texttt{aligned} and \texttt{gathered}}
+
+The environments \texttt{aligned} and \texttt{gathered} have a
+trailing optional argument to specify the vertical position of the
+environment with respect to the rest of the line. Allowed values are
+\texttt{t}, \texttt{b} and \texttt{c} but the code only tested for
+\texttt{b} and \texttt{t} and assumed anything else is must be
+\texttt{c}. As a result, a formula starting with a bracket group would
+get mangled without warning---the group being dropped and interpreted
+as a request for centering. After more than 25 years this has now been
+corrected. If such a group is found a warning is given and the data is
+processed as part of the formula.
+%
+\githubissue{5}
+
\end{document}
diff --git a/required/amsmath/amsmath.dtx b/required/amsmath/amsmath.dtx
index 59d7d620..1029616f 100644
--- a/required/amsmath/amsmath.dtx
+++ b/required/amsmath/amsmath.dtx
@@ -1633,8 +1633,8 @@ Foreign command \@backslashchar#1;\MessageBreak
% \begin{macro}{\dddot}
% \begin{macro}{\ddddot}
% Triple and quadruple dot accents.
-% \changes{v2.17f}{2020/02/20}{Add a kern so that a single char is not verticaly
-% shifted and move the dots slightly to the right (gh/126)}
+% \changes{v2.17f}{2020/02/20}{Add a kern so that a single char is not
+% vertically shifted and move the dots slightly to the right (gh/126)}
% \begin{macrocode}
\ams at newcommand{\dddot}[1]{%
{\mathop{\kern\z@#1}\limits^{\vbox to-1.4\ex@{\kern-\tw@\ex@
@@ -3440,7 +3440,8 @@ and fix things up.}
% \end{macro}
%
% \begin{macro}{\black@}
-% \changes{v2.17a}{2017/09/02}{add fixed width box so overfull warning generated in centred environments in lists}
+% \changes{v2.17a}{2017/09/02}{Add fixed width box so overfull warning
+% generated in centred environments in lists}
% This macro is made to produce an overfull box message and
% possibly (depending on the value of \cs{overfullrule})
% a rule in the margin if the total width of an alignment
@@ -3659,16 +3660,47 @@ and fix things up.}
%
%
% \begin{macro}{\ams at start@box}
-%
+% This macro tests the optional positioning argument (in
+% \texttt{gathered} or \texttt{aligned}. It explicitly tests for the
+% value \texttt{b}, \texttt{c} and \texttt{t) and if the value is
+% different then we assume that it is a bracket group that belongs
+% to the formula instead of being an misspelled optional argument.
+% (In earlier versions of the code anything other than \texttt{b}
+% or \texttt{t} was interpreted as \texttt{c} and the data was
+% otherwise dropped.
% \changes{v2.17g}{2020/03/10}{Explicity test for b/t/c and return
% optional argument is different (gh/5)}
% \begin{macrocode}
\def\ams at start@box#1{%
+% \end{macrocode}
+% As we may pick up an arbitrary part of the formula by mistake, we
+% need to be very careful with the testing to avoid low-level
+% errors. This is why we use \cs{detokenize}. The code assumes that
+% the default is correctly set up (which in this case is \texttt{c}).
+% \begin{macrocode}
\edef\reserved at a{\csname ams at pos@\detokenize{#1}\endcsname}%
\expandafter\ifx\reserved at a\relax
+% \end{macrocode}
+% If the argument is neither \texttt{b}, \texttt{c} or \texttt{t}
+% we save it in \cs{ams at return@opt at arg}, so it can later be
+% returned as part of the environment body. We could at this point
+% also issue a warning that bracket group was found at the start of
+% the formula and that it is safer to add a \cs{relax} before it.
+% \begin{macrocode}
+ \PackageWarning{amsmath}{%
+ Bracket group \detokenize{[#1]} at formula start!\MessageBreak
+ It could be a misspelled positional argument.\MessageBreak
+ If it belongs to the formula add a \relax in\MessageBreak
+ front to hide it}%
\def\ams at return@opt at arg{[#1]}\vcenter
+% \end{macrocode}
+% If the argument was identified then we clear
+% \cs{ams at return@opt at arg} (just in case somebod ever nests these
+% environment.
+% \begin{macrocode}
\else
- \let\ams at return@opt at arg\@empty\reserved at a \fi
+ \let\ams at return@opt at arg\@empty\reserved at a
+ \fi
}
% \end{macrocode}
%
@@ -3710,6 +3742,9 @@ and fix things up.}
% to the margin.
% \begin{macrocode}
\alignedspace at left
+% \end{macrocode}
+% Select the right kind of box based on the optional argument \verb=#1=.
+% \begin{macrocode}
\ams at start@box{#1}\bgroup
\maxfields@#2\relax
\ifnum\maxfields@>\m at ne
@@ -3754,7 +3789,8 @@ and fix things up.}
\tabskip\alignsep@
\crcr
% \end{macrocode}
-%
+% If we picked up a bracket group by mistake here is the place to
+% return it for processing.
% \changes{v2.17g}{2020/03/10}{Explicity test for b/t/c and return
% optional argument is different (gh/5)}
% \begin{macrocode}
@@ -3843,6 +3879,9 @@ and fix things up.}
\nonmatherr@{\begin{gathered}}%
\fi
\alignedspace at left
+% \end{macrocode}
+% Select the right kind of box based on the optional argument \verb=#1=.
+% \begin{macrocode}
\ams at start@box{#1}\bgroup
\Let@ \chardef\dspbrk at context\@ne \restore at math@cr
\spread at equation
@@ -3850,7 +3889,7 @@ and fix things up.}
\hfil\strut@$\m at th\displaystyle##$\hfil
\crcr
% \end{macrocode}
-%
+% And put a mistaking picked up bracket group back:
% \changes{v2.17g}{2020/03/10}{Explicity test for b/t/c and return
% optional argument is different (gh/5)}
% \begin{macrocode}
diff --git a/required/amsmath/changes.txt b/required/amsmath/changes.txt
index 9581bb66..7d417743 100644
--- a/required/amsmath/changes.txt
+++ b/required/amsmath/changes.txt
@@ -1,3 +1,9 @@
+2020-03-10 Frank Mittelbach <Frank.Mittelbach at latex-project.org>
+
+ * amsmath.dtx (subsection{Simple aligning environments}):
+ Explicity test for b,t,c and return optional argument is
+ different (gh/5)
+
#########################
# 2020-02-02 Release
#########################
@@ -28,7 +34,8 @@
2019-10-11 David Carlisle <David.Carlisle at latex-project.org>
- * build.lua: package amsmath-2018-12-01.sty (only ctan build script no source changes)
+ * build.lua: package amsmath-2018-12-01.sty (only ctan build script
+ no source changes)
#########################
# 2019-10-01 Release
diff --git a/required/amsmath/testfiles/github-amsmath-0005.luatex.tlg b/required/amsmath/testfiles/github-amsmath-0005.luatex.tlg
index 2e34afe7..82551596 100644
--- a/required/amsmath/testfiles/github-amsmath-0005.luatex.tlg
+++ b/required/amsmath/testfiles/github-amsmath-0005.luatex.tlg
@@ -1,21 +1,21 @@
This is a generated file for the LaTeX2e validation system.
Don't change this file in any respect.
-! LaTeX Error: \begin{aligned} on input line ... ended by \end{gathered}.
-See the LaTeX manual or LaTeX Companion for explanation.
-Type H <return> for immediate help.
- ...
-l. ...\end{gathered}
-Your command was ignored.
-Type I <command> <return> to replace it with another command,
-or <return> to continue without it.
-! LaTeX Error: \begin{aligned} on input line ... ended by \end{gathered}.
-See the LaTeX manual or LaTeX Companion for explanation.
-Type H <return> for immediate help.
- ...
-l. ...\end{gathered}
-Your command was ignored.
-Type I <command> <return> to replace it with another command,
-or <return> to continue without it.
+Package amsmath Warning: Bracket group [p] at formula start!
+(amsmath) It could be a misspelled positional argument.
+(amsmath) If it belongs to the formula add a \relax in
+(amsmath) front to hide it on input line ....
+Package amsmath Warning: Bracket group [aa] at formula start!
+(amsmath) It could be a misspelled positional argument.
+(amsmath) If it belongs to the formula add a \relax in
+(amsmath) front to hide it on input line ....
+Package amsmath Warning: Bracket group [p] at formula start!
+(amsmath) It could be a misspelled positional argument.
+(amsmath) If it belongs to the formula add a \relax in
+(amsmath) front to hide it on input line ....
+Package amsmath Warning: Bracket group [aa] at formula start!
+(amsmath) It could be a misspelled positional argument.
+(amsmath) If it belongs to the formula add a \relax in
+(amsmath) front to hide it on input line ....
Completed box being shipped out [1]
\vbox(633.0+0.0)x407.0, direction TLT
.\glue 16.0
@@ -41,7 +41,7 @@ Completed box being shipped out [1]
...\penalty 10000
...\glue(\abovedisplayshortskip) 0.0 plus 3.0
...\glue(\lineskip) 1.0
-...\hbox(23.39996+18.60004)x24.63889, shifted 160.18056, direction TLT
+...\hbox(23.39996+18.60004)x40.22571, shifted 152.38715, direction TLT
....\hbox(0.0+0.0)x0.0, direction TLT
....\vbox(8.39996+18.60004)x9.06943, direction TLT
.....\hbox(8.39996+3.60004)x9.06943, direction TLT
@@ -142,6 +142,70 @@ Completed box being shipped out [1]
.......\kern0.71527 (italic)
.......\mathoff
......\glue(\tabskip) 0.0
+....\hbox(0.0+0.0)x0.0, direction TLT
+....\vbox(16.0+11.0)x7.50002, direction TLT
+.....\hbox(8.39996+3.60004)x7.50002, direction TLT
+......\glue(\tabskip) 0.0
+......\hbox(8.39996+3.60004)x7.50002, direction TLT
+.......\glue 0.0 plus 1.0fil
+.......\hbox(8.39996+3.60004)x0.0, direction TLT
+........\vbox(8.39996+3.60004)x0.0, direction TLT
+.........\kern0.0
+.........\hbox(8.39996+3.60004)x0.0, direction TLT
+..........\rule(8.39996+3.60004)x0.0
+.......\mathon
+.......\OML/cmm/m/it/10 A
+.......\mathoff
+......\glue(\tabskip) 0.0
+.....\glue 0.0
+.....\glue(\baselineskip) 3.0
+.....\hbox(8.39996+3.60004)x7.50002, direction TLT
+......\glue(\tabskip) 0.0
+......\hbox(8.39996+3.60004)x7.50002, direction TLT
+.......\glue 0.0 plus 1.0fil
+.......\hbox(8.39996+3.60004)x0.0, direction TLT
+........\vbox(8.39996+3.60004)x0.0, direction TLT
+.........\kern0.0
+.........\hbox(8.39996+3.60004)x0.0, direction TLT
+..........\rule(8.39996+3.60004)x0.0
+.......\mathon
+.......\OML/cmm/m/it/10 A
+.......\mathoff
+......\glue(\tabskip) 0.0
+....\hbox(0.0+0.0)x0.0, direction TLT
+....\vbox(16.0+11.0)x8.0868, direction TLT
+.....\hbox(8.39996+3.60004)x8.0868, direction TLT
+......\glue(\tabskip) 0.0
+......\hbox(8.39996+3.60004)x8.0868, direction TLT
+.......\glue 0.0 plus 1.0fil
+.......\hbox(8.39996+3.60004)x0.0, direction TLT
+........\vbox(8.39996+3.60004)x0.0, direction TLT
+.........\kern0.0
+.........\hbox(8.39996+3.60004)x0.0, direction TLT
+..........\rule(8.39996+3.60004)x0.0
+.......\mathon
+.......\OML/cmm/m/it/10 B
+.......\kern0.50172 (italic)
+.......\mathoff
+.......\glue 0.0 plus 1.0fil
+......\glue(\tabskip) 0.0
+.....\glue 0.0
+.....\glue(\baselineskip) 3.0
+.....\hbox(8.39996+3.60004)x8.0868, direction TLT
+......\glue(\tabskip) 0.0
+......\hbox(8.39996+3.60004)x8.0868, direction TLT
+.......\glue 0.0 plus 1.0fil
+.......\hbox(8.39996+3.60004)x0.0, direction TLT
+........\vbox(8.39996+3.60004)x0.0, direction TLT
+.........\kern0.0
+.........\hbox(8.39996+3.60004)x0.0, direction TLT
+..........\rule(8.39996+3.60004)x0.0
+.......\mathon
+.......\OML/cmm/m/it/10 B
+.......\kern0.50172 (italic)
+.......\mathoff
+.......\glue 0.0 plus 1.0fil
+......\glue(\tabskip) 0.0
...\penalty 0
...\glue(\belowdisplayshortskip) 6.0 plus 3.0 minus 3.0
...\glue(\parskip) 0.0 plus 1.0
diff --git a/required/amsmath/testfiles/github-amsmath-0005.lvt b/required/amsmath/testfiles/github-amsmath-0005.lvt
index 5d11a2ae..bfd9374f 100644
--- a/required/amsmath/testfiles/github-amsmath-0005.lvt
+++ b/required/amsmath/testfiles/github-amsmath-0005.lvt
@@ -11,9 +11,11 @@
\START
\[
-\begin{gathered}[t] X \\ X \end{gathered}
-\begin{gathered}[c] Y \\ Y\end{gathered}
-\begin{aligned}[b] Z \\ Z \end{aligned}
+ \begin{gathered}[t] X \\ X \end{gathered}
+ \begin{gathered}[c] Y \\ Y\end{gathered}
+ \begin{aligned}[b] Z \\ Z \end{aligned}
+ \begin{aligned} A \\ A \end{aligned}
+ \begin{gathered} B \\ B \end{gathered}
\]
\[
@@ -36,7 +38,7 @@ Equally bad:
\begin{aligned}
[p] = 100 \\
[v] = 200
-\end{gathered}
+\end{aligned}
\]
Equally bad:
@@ -44,7 +46,7 @@ Equally bad:
\begin{aligned}
[aa] = 100 \\ % read as "t"
[v] = 200
-\end{gathered}
+\end{aligned}
\]
\end{document}
diff --git a/required/amsmath/testfiles/github-amsmath-0005.tlg b/required/amsmath/testfiles/github-amsmath-0005.tlg
index dc84acef..69c42b8d 100644
--- a/required/amsmath/testfiles/github-amsmath-0005.tlg
+++ b/required/amsmath/testfiles/github-amsmath-0005.tlg
@@ -1,21 +1,21 @@
This is a generated file for the LaTeX2e validation system.
Don't change this file in any respect.
-! LaTeX Error: \begin{aligned} on input line ... ended by \end{gathered}.
-See the LaTeX manual or LaTeX Companion for explanation.
-Type H <return> for immediate help.
- ...
-l. ...\end{gathered}
-Your command was ignored.
-Type I <command> <return> to replace it with another command,
-or <return> to continue without it.
-! LaTeX Error: \begin{aligned} on input line ... ended by \end{gathered}.
-See the LaTeX manual or LaTeX Companion for explanation.
-Type H <return> for immediate help.
- ...
-l. ...\end{gathered}
-Your command was ignored.
-Type I <command> <return> to replace it with another command,
-or <return> to continue without it.
+Package amsmath Warning: Bracket group [p] at formula start!
+(amsmath) It could be a misspelled positional argument.
+(amsmath) If it belongs to the formula add a \relax in
+(amsmath) front to hide it on input line ....
+Package amsmath Warning: Bracket group [aa] at formula start!
+(amsmath) It could be a misspelled positional argument.
+(amsmath) If it belongs to the formula add a \relax in
+(amsmath) front to hide it on input line ....
+Package amsmath Warning: Bracket group [p] at formula start!
+(amsmath) It could be a misspelled positional argument.
+(amsmath) If it belongs to the formula add a \relax in
+(amsmath) front to hide it on input line ....
+Package amsmath Warning: Bracket group [aa] at formula start!
+(amsmath) It could be a misspelled positional argument.
+(amsmath) If it belongs to the formula add a \relax in
+(amsmath) front to hide it on input line ....
Completed box being shipped out [1]
\vbox(633.0+0.0)x407.0
.\glue 16.0
@@ -36,7 +36,7 @@ Completed box being shipped out [1]
...\penalty 10000
...\glue(\abovedisplayshortskip) 0.0 plus 3.0
...\glue(\lineskip) 1.0
-...\hbox(23.39996+18.60004)x24.63889, shifted 160.18056, display
+...\hbox(23.39996+18.60004)x40.22571, shifted 152.38715, display
....\hbox(0.0+0.0)x0.0
....\vbox(8.39996+18.60004)x9.06943
.....\hbox(8.39996+3.60004)x9.06943
@@ -137,6 +137,70 @@ Completed box being shipped out [1]
.......\kern0.71527
.......\mathoff
......\glue(\tabskip) 0.0
+....\hbox(0.0+0.0)x0.0
+....\vbox(16.0+11.0)x7.50002
+.....\hbox(8.39996+3.60004)x7.50002
+......\glue(\tabskip) 0.0
+......\hbox(8.39996+3.60004)x7.50002
+.......\glue 0.0 plus 1.0fil
+.......\hbox(8.39996+3.60004)x0.0
+........\vbox(8.39996+3.60004)x0.0
+.........\kern 0.0
+.........\hbox(8.39996+3.60004)x0.0
+..........\rule(8.39996+3.60004)x0.0
+.......\mathon
+.......\OML/cmm/m/it/10 A
+.......\mathoff
+......\glue(\tabskip) 0.0
+.....\glue 0.0
+.....\glue(\baselineskip) 3.0
+.....\hbox(8.39996+3.60004)x7.50002
+......\glue(\tabskip) 0.0
+......\hbox(8.39996+3.60004)x7.50002
+.......\glue 0.0 plus 1.0fil
+.......\hbox(8.39996+3.60004)x0.0
+........\vbox(8.39996+3.60004)x0.0
+.........\kern 0.0
+.........\hbox(8.39996+3.60004)x0.0
+..........\rule(8.39996+3.60004)x0.0
+.......\mathon
+.......\OML/cmm/m/it/10 A
+.......\mathoff
+......\glue(\tabskip) 0.0
+....\hbox(0.0+0.0)x0.0
+....\vbox(16.0+11.0)x8.0868
+.....\hbox(8.39996+3.60004)x8.0868
+......\glue(\tabskip) 0.0
+......\hbox(8.39996+3.60004)x8.0868
+.......\glue 0.0 plus 1.0fil
+.......\hbox(8.39996+3.60004)x0.0
+........\vbox(8.39996+3.60004)x0.0
+.........\kern 0.0
+.........\hbox(8.39996+3.60004)x0.0
+..........\rule(8.39996+3.60004)x0.0
+.......\mathon
+.......\OML/cmm/m/it/10 B
+.......\kern0.50172
+.......\mathoff
+.......\glue 0.0 plus 1.0fil
+......\glue(\tabskip) 0.0
+.....\glue 0.0
+.....\glue(\baselineskip) 3.0
+.....\hbox(8.39996+3.60004)x8.0868
+......\glue(\tabskip) 0.0
+......\hbox(8.39996+3.60004)x8.0868
+.......\glue 0.0 plus 1.0fil
+.......\hbox(8.39996+3.60004)x0.0
+........\vbox(8.39996+3.60004)x0.0
+.........\kern 0.0
+.........\hbox(8.39996+3.60004)x0.0
+..........\rule(8.39996+3.60004)x0.0
+.......\mathon
+.......\OML/cmm/m/it/10 B
+.......\kern0.50172
+.......\mathoff
+.......\glue 0.0 plus 1.0fil
+......\glue(\tabskip) 0.0
...\penalty 0
...\glue(\belowdisplayshortskip) 6.0 plus 3.0 minus 3.0
...\glue(\parskip) 0.0 plus 1.0
More information about the latex3-commits
mailing list.