docs(math): Update description of atoms and TeX-like pre-defined cons…

…tructs

packages/math/init.lua

@@ -132,8 +132,7 @@ The \autodoc:package{math} package provides typesetting of formulas directly in
 As such, it lacks some features and may contain bugs.
 Feedback and contributions are always welcome.}
 
-\noindent To typeset mathematics, you will need an OpenType math font installed on your system.%
-%\footnote{A list of freely available math fonts can be found at \href[src=https://www.ctan.org/pkg/unicode-math]{https://www.ctan.org/pkg/unicode-math}}
+\noindent To typeset mathematics, you will need an OpenType math font installed on your system.
 By default, this package uses Libertinus Math, so it will fail if Libertinus Math can’t be found.
 Another font may be specified via the setting \autodoc:setting{math.font.family}.
 If required, you can set the font style and weight via \autodoc:setting{math.font.style} and \autodoc:setting{math.font.weight}.
@@ -212,28 +211,39 @@ Its main difference from the SILE syntax is that \code{\\mycommand\{arg1\}\{arg2
 If it’s more convenient, you can use these Unicode characters directly.
 The symbol shorthands are the same as in the TeX package \href[src=https://www.ctan.org/pkg/unicode-math]{\code{unicode-math}}.
 
+The TeX-like syntax also supports several familiar constructs, pre-defined with appropriate spacing, movable limits and other properties, such as \code{\\sin}, \code{\\cos}, \code{\\lim}, etc.
+These are just macro-definitions (see further below); for instance, \code{\\lim} is a shorthand for \code{\\mo[atom=op, movablelimits=true]\{lim\}}.
+\begin[mode=display]{math}
+    \sin 2\theta = 2\sin \theta \cos \theta
+\end{math}
+\begin[mode=display]{math}
+    \math{\lim_{n\to\infty} F(n) = 0}
+\end{math}
+
 \code{\{formula\}} is a shorthand for \code{\\mrow\{formula\}}.
-Since parentheses—among other glyphs—stretch vertically to the size of their englobing \code{mrow}, this is useful to typeset parentheses of different sizes on the same line:
+Delimiters—among other glyphs—stretch vertically to the size of their englobing \code{mrow}, which is useful for their size to adapt to the content.
+SILE automatically wraps paired delimiters in such a construct, so these adapt to their inner content only.
 
 \begin[type=autodoc:codeblock]{raw}
 \Gamma (\frac{\zeta}{2}) + x^2(x+1)
 \end{raw}
 
-\noindent renders as
+\noindent directly renders as
 
 \begin[mode=display]{math}
     \Gamma (\frac{\zeta}{2}) + x^2(x+1)
 \end{math}
 
-\noindent which is ugly.
-To keep parentheses around \math{x+1} small, you should put braces around the expression:
+\noindent which is neat.
+But for cases when stretchy delimiters are not paired in an obvious way, these can end up too large.
+To keep them small, you should put braces around the expression:
 
 \begin[type=autodoc:codeblock]{raw}
-\Gamma (\frac{\zeta}{2}) + x^2{(x+1)}
+\Vert v \Vert = \sqrt{x^2 + y^2} \text{ vs. } {\Vert v \Vert} = \sqrt{x^2 + y^2}
 \end{raw}
 
 \begin[mode=display]{math}
-    \Gamma (\frac{\zeta}{2}) + x^2{(x+1)}
+\Vert v \Vert = \sqrt{x^2 + y^2} \text{ vs. } {\Vert v \Vert} = \sqrt{x^2 + y^2}
 \end{math}
 
 \noindent To print a brace in a formula, you need to escape it with a backslash.
@@ -246,10 +256,11 @@ To avoid that, you can specify that \math{\mi{sin}} is an identifier by writing
 If you prefer it in “double struck” style, this is permitted by the \code{mathvariant} attribute: \code{\\mi[mathvariant=double-struck]\{sin\}(x)} renders as \math{\mi[mathvariant=double-struck]{sin}(x)}.
 
 \paragraph{Atom types and spacing}
+The current implementation does not follow the MathML rules for spacing, but rather the rules defined in the TeXbook, based on atom types.
 Each token automatically gets assigned an atom type from the list below:
 \begin{itemize}
   \item{\code{ord}: \code{mi} and \code{mn} tokens, as well as unclassified operators}
-  \item{\code{big}: big operators like ‘\math{\sum}’ or ‘\math{\prod}’}
+  \item{\code{op}: large operators like ‘\math{\sum}’ or ‘\math{\prod}’}
   \item{\code{bin}: binary operators like ‘\math{+}’ or ‘\math{\%}’}
   \item{\code{rel}: relation operators like ‘\math{=}’ or ‘\math{<}’}
   \item{\code{open}: opening operators like ‘\math{(}’ or ‘\math{[}’}
@@ -260,8 +271,7 @@ Each token automatically gets assigned an atom type from the list below:
   %\item{\code{over}}
   %\item{\code{under}}
   %\item{\code{accent}}
-  %\item{\code{radical}}
-  %\item{\code{vcenter}}
+  %\item{\code{bothaccent}}
 \end{itemize}
 \noindent The spacing between any two successive tokens is set automatically based on their atom types, and hence may not reflect the actual spacing used in the input.
 To make an operator behave like it has a certain atom type, you can use the \code{atom} attribute. For example, \code{a \\mo[atom=bin]\{div\} b} renders as \math[mode=display]{a \mo[atom=bin]{div} b.}