[latex3-commits] [git/LaTeX3-latex3-latex2e] develop: A bit more documentation in ltnews. (79185126)

[Joseph Wright]

Repository : https://github.com/latex3/latex2e
On branch  : develop
Link       : https://github.com/latex3/latex2e/commit/79185126aa12348663c03067f8825f4ebf3fa5c7

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

commit 79185126aa12348663c03067f8825f4ebf3fa5c7
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Thu Sep 1 17:41:25 2022 +0200

    A bit more documentation in ltnews.


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

79185126aa12348663c03067f8825f4ebf3fa5c7
 base/doc/ltnews36.tex | 56 ++++++++++++++++++++++++++++++++-------------------
 1 file changed, 35 insertions(+), 21 deletions(-)

diff --git a/base/doc/ltnews36.tex b/base/doc/ltnews36.tex
index 4677b36e..29a51d59 100644
--- a/base/doc/ltnews36.tex
+++ b/base/doc/ltnews36.tex
@@ -146,6 +146,41 @@
 \emph{to be written}
 
 
+\subsection{Auto-detecting key--value arguments}
+
+To allow extension of the core \LaTeX{} syntax, \pkg{ltcmd} now supports
+a \texttt{={...}} modifier when grabbing arguments. This modifier instructs
+\LaTeX{} that the argument should be passed to the underlying code as
+a set of keyvals. If the argument does not \enquote{look like} a set
+of keyvals, it will be converted into a single key--value pair, with
+the argument to \texttt{=} specifying the name of that key. For
+example, the \cs{caption} command could be defined as
+\begin{verbatim}
+  \DeclareDocumentCommand\caption
+         {s ={short-text}+O{#3} +m}
+         {...}
+\end{verbatim}
+which would mean that if the optional argument does \emph{not}
+contain keyval data, it will be converted to a single keyval
+pair with the key name \texttt{short-text}.
+
+Arguments which begin with \texttt{=,} are always interpreted as
+keyvals even if they do not contain further \texttt{=} signs.
+Any \texttt{=} signs enclosed within \verb|$...$| or \verb|\(...\)|,
+i.e.~in inline math mode, are ignored, meaning that
+only \texttt{=} outside of math mode will generally cause
+interpretation as keyval material.
+
+In case the argument contains a \enquote{textual} \texttt{=} sign that
+is mistaken as key/value indicator you can hide it using a brace
+group as you would do in other places, e.g.,
+\begin{verbatim}
+\caption[{Use of = signs}]
+        {Use of = signs in optional arguments}
+\end{verbatim}
+However, because a \texttt{=} sign in math mode are already ignored, this
+should seldom be necessary.
+
 \subsection{Encoding subsets for \texttt{TS1} encoded fonts}
 
 The text companion encoding \texttt{TS1} is unfortunately not very
@@ -206,28 +241,7 @@ font instead.
 %
 \githubissue{879}
 
-\subsection{Auto-detecting key--value arguments}
-
-To allow extension of the core \LaTeX{} syntax, \pkg{ltcmd} now supports
-a \texttt{={...}} modifier when grabbing arguments. This modifier instructs
-\LaTeX{} that the argument should be passed to the underlying code as
-a set of keyvals. If the argument does not \enquote{look like} a set
-of keyvals, it will be converted into a single key--value pair, with
-the argument to \texttt{=} specifying the name of that key. For
-example, the \cs{caption} command could be defined as
-\begin{verbatim}
-  \DeclareDocumentCommand\caption{s ={short-text}+O{#3} +m}
-\end{verbatim}
-which would mean that if the optional argument does \emph{not}
-contain keyval data, it will be converted to a single keyval
-pair with the key name \texttt{short-text}.
 
-Arguments which begin with \texttt{=,} are always interpreted as
-keyvals even if they do not contain further \texttt{=} signs.
-Any \texttt{=} signs enclosed within \verb|$...$| or \verb|\(...\)|,
-i.e.~in inline math mode, are ignored, meaning that
-only \texttt{=} outside of math mode will generally cause
-interpretation as keyval material.
 
 \subsection{\LuaTeX\ callback efficiency improvement}