[latex3-commits] [latex3/latex2e] templates: Extend ltnews entry (5d8bb19c)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : templates
Link       : https://github.com/latex3/latex2e/commit/5d8bb19c9118152e1b1c56c7090cf741bfde9ee2

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

commit 5d8bb19c9118152e1b1c56c7090cf741bfde9ee2
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Thu Feb 1 13:40:32 2024 +0000

    Extend ltnews entry


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

5d8bb19c9118152e1b1c56c7090cf741bfde9ee2
 base/doc/ltnews39.tex | 57 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 51 insertions(+), 6 deletions(-)

diff --git a/base/doc/ltnews39.tex b/base/doc/ltnews39.tex
index cd39f4bc..64cba9a4 100644
--- a/base/doc/ltnews39.tex
+++ b/base/doc/ltnews39.tex
@@ -259,12 +259,57 @@ well.
 
 \section{Providing \pkg{xtemplate} in the format}
 
-In \LaTeX{} News~32, we described the move of one long-term experimental
-idea into the kernel: the package \pkg{xparse}, which was integrated as
-\pkg{ltcmd}. With this edition, we move another long-term development
-idea to stable status: \emph{templates}.
-
-For documentation see \texttt{texdoc lttemplates-doc} for now.
+In \LaTeX{} News~32, we described the move of one long-term experimental idea
+into the kernel: the package \pkg{xparse}, which was integrated as \pkg{ltcmd}.
+With this edition, we move another long-term development idea to stable status:
+\emph{templates}.
+
+In this context, templates are a mechanism to abstract out various elements of a
+document (such as \enquote{sectioning}) in such a way that different
+implementations can be interchanged, and design decisions are set up efficiently
+and controllably.
+
+In contrast to \pkg{ltcmd}, which provides a mechanism that many document
+authors will exploit routinely, templates are a more specialised tool. We
+anticipate that they will be used by a small number of programmers, providing
+generic ideas that will then be used within document classes. Most document
+authors will therefore likely encounter templates directly only rarely.
+We anticipate though that they will be \emph{using} templates provided
+by the team or others.
+
+The template system requires three separate ideas
+\begin{itemize}
+  \item Template \emph{type}: the \enquote{thing} we are using templates
+    for, such as \enquote{sectioning} or \enquote{enumerated-list}
+  \item A template: a combination of code and keys that can be used
+    to implement a type. Here for example we might have
+    \enquote{standard-\LaTeX{}-sectioning} as a template for 
+    \enquote{sectioning}
+  \item One or more \emph{instances}: a specific use case of a template
+    where (some) keys are set to known values. We might for example see
+    \enquote{\LaTeX{}-section}, \enquote{\LaTeX{}-subsection}, etc.
+\end{itemize}
+
+As part of the move from the experimental \pkg{xtemplate} to kernel integration,
+the team have revisited the commands provided. The stable set now comprises
+\begin{itemize}
+  \item \cs{NewTemplateType}
+  \item \cs{NewTemplateInterface}
+  \item \cs{NewTemplateCode}
+  \item \cs{NewTemplateCopy}
+  \item \cs{EditTemplateDefault}
+  \item \cs{UseTemplate}
+  \item \cs{NewInstance}
+  \item \cs{NewInstanceCopy}
+  \item \cs{EditInstance}
+  \item \cs{UseInstance}
+\end{itemize}
+
+To support existing package authors, we have released an updated version of
+\pkg{xtemplate} which will work smoothly with the new kernel-level code. The
+existing commands provided in \pkg{xtemplate} will continue to work, but those
+starting \cs{Declare\dots} are formally deprecated. We strongly encourage
+package authors using templates to transition to the new structures.
 
 \section{Code improvements}