[latex3-commits] [latex3/latex2e] develop: Add template documenation (91cbfe1c)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : develop
Link       : https://github.com/latex3/latex2e/commit/91cbfe1ce0b85d3ecbad5f91e234c1626052e143

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

commit 91cbfe1ce0b85d3ecbad5f91e234c1626052e143
Author: Joseph Wright <joseph at texdev.net>
Date:   Tue Sep 10 17:32:10 2024 +0100

    Add template documenation


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

91cbfe1ce0b85d3ecbad5f91e234c1626052e143
 base/changes.txt              |  7 +++++++
 base/doc/clsguide.tex         | 21 ++++++++++++++++++++-
 base/doc/lttemplates-code.tex |  5 +++++
 base/doc/lttemplates-doc.tex  |  8 ++++++++
 4 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/base/changes.txt b/base/changes.txt
index 6adc4e13..f859015c 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,13 @@ to completeness or accuracy and it contains some references to files that are
 not part of the distribution.
 ================================================================================
 
+2024-09-15  Joseph Wright  <Joseph.Wright at latex-project.org>
+
+	* lttemplates-doc.tex, lttemplates-code.tex:
+	New files
+	* clsguide.tex
+	Link to template documentation
+
 2024-09-12 Ulrike Fischer <Ulrike.Fischer at latex-project.org>
 	* ltproperties.dtx: remove @filesw-test in \__property_record:nn,
 	see https://github.com/latex3/tagging-project/issues/696
diff --git a/base/doc/clsguide.tex b/base/doc/clsguide.tex
index 84c3b3e4..e7adc9da 100644
--- a/base/doc/clsguide.tex
+++ b/base/doc/clsguide.tex
@@ -42,7 +42,7 @@
     \texttt{clsguide.tex} for full details.}%
 }
 
-\date{2024-09-02}
+\date{2024-09-15}
 
 \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
 \NewDocumentCommand\marg{m}{\arg{#1}}
@@ -1397,6 +1397,25 @@ modern packages, that use the L3 programming layer of \LaTeX{}. The
 \texttt{expl3} commands and more details can be found in
 \texttt{ltproperties-doc.pdf}.
 
+\subsubsection{Templates (protoype document commands)}
+
+\emph{Templates} as defined by \LaTeX{} are a mechanism to cleanly separate the
+three layers needed for writing a document
+\begin{enumerate}
+  \item authoring of the text with mark-up;
+  \item document layout design;
+  \item implementation (with \TeX{} programming) of the design.
+\end{enumerate}
+They allow document authors to modify design without altering code, and allow
+programmers to make portable changes to classes.
+
+Implementing this mechanism requires a number of steps and a family of commands
+which allow variation in outcomes. A typical use of templates will make use of
+most or all of |\NewTemplateType|, |\DeclareTemplateInterface|,
+|\DeclareTemplateCode|, |\DeclareInstance| and |\UseInstance|, plus potentially
+some more specialised commands. These are descrined in \texttt{lttemplates-doc}
+in full detail.
+
 \subsection{Preparing link targets}
 
 Active links in a document need targets to which they can jump to. Such
diff --git a/base/doc/lttemplates-code.tex b/base/doc/lttemplates-code.tex
new file mode 100644
index 00000000..b85e2230
--- /dev/null
+++ b/base/doc/lttemplates-code.tex
@@ -0,0 +1,5 @@
+% This will typeset documentation + code
+%
+
+\AtBeginDocument{\AlsoImplementation}
+\input{lttemplates.dtx}
diff --git a/base/doc/lttemplates-doc.tex b/base/doc/lttemplates-doc.tex
new file mode 100644
index 00000000..18b2ac11
--- /dev/null
+++ b/base/doc/lttemplates-doc.tex
@@ -0,0 +1,8 @@
+% This will typeset only documentation but not the code
+%
+
+\AtBeginDocument{\OnlyDescription
+%                 \let\tableofcontents\relax
+                  \RenewCommandCopy\MaybeStop\StopEventually
+                 }
+\input{lttemplates.dtx}