[latex3-commits] [git/LaTeX3-latex3-latex2e] gh479: Add ltnews33 entry for \NewModuleRelease (45ee60ac)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex2e
On branch  : gh479
Link       : https://github.com/latex3/latex2e/commit/45ee60ac79fec05b22c220500c129ab676d2edf4

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

commit 45ee60ac79fec05b22c220500c129ab676d2edf4
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Thu Mar 18 23:11:45 2021 -0300

    Add ltnews33 entry for \NewModuleRelease


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

45ee60ac79fec05b22c220500c129ab676d2edf4
 base/doc/ltnews33.tex | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/base/doc/ltnews33.tex b/base/doc/ltnews33.tex
index bfe01dff..225d4216 100644
--- a/base/doc/ltnews33.tex
+++ b/base/doc/ltnews33.tex
@@ -463,6 +463,60 @@ the file name.
 
 
 
+\subsection{Extending \pkg{latexrelease} to declare an entire module}
+
+In the 2020-10-01 release, \LaTeX's new hook management system was added to the
+kernel (see \cite{33:ltnews32}) and, as with all changes to the kernel, it was
+added to \pkg{latexrelease}, so that it is possible to roll back to a date where
+such module didn't exist yet, or roll forward from an older release and have the
+hook management system by loading the \pkg{latexrelease} package.
+
+However rolling back from a later release to the 2020-10-01 release didn't quite
+work because it would try to define all the commands from \pkg{lthooks} again,
+and that would result in hundreds of errors.
+
+To solve this issue, now \pkg{latexrelease} has a new command,
+\cs{NewModuleRelease} (and \cs{EndModuleRelease}) so that completely new modules
+can be defined, and then when rolling back or forward, \pkg{latexrelease} will
+know if the code of the module has to be read or completely ignored.
+Additionally, changes to such module can still be declared with the well-known
+\cs{IncludeInRelease} command, and these changes will be applied when necessary.
+
+An example new module can be created with:
+\begin{verbatim}
+\NewModuleRelease{mymodule}{2020-10-01}
+\newcommand\cmdA{foo}
+
+\newcommand\cmdB{}
+\IncludeInRelease{2020-05-01}{\cmdB}
+                 {Change \cmdB}
+\renewcommand\cmdB{changed version of cmdB}
+\EndIncludeInRelease
+
+\IncludeInRelease{2020-10-01}{\cmdB}
+                 {Change \cmdB}
+\renewcommand\cmdB{bar}
+\EndIncludeInRelease
+
+\IncludeInRelease{0000-00-00}{mymodule}
+                 {Undefine module 'mymodule'}
+\let\cmdA\@undefined
+\let\cmdB\@undefined
+\EndModuleRelease
+\end{verbatim}
+In this example, the module \texttt{mymodule} is declared from 2020-10-01
+onwards, and a command \cs{cmdA} is defined with \cs{newcommand}, and this
+definition is only read if rolling forward from before the declared date, so
+there will be no \enquote{command already defined} issues here.  Then, \cs{cmdB}
+gets a dummy definition, to make sure it exists if rolling forward, then two
+versions are declared, in which it is redefined with \cs{renewcommand}.
+Finally, a chunk of code dated 0000-00-00 is declared to undefine the module
+(this part is optional), and the module ends with \cs{EndModuleRelease}.
+%
+\githubissue{479}
+
+
+
 \subsection{\ldots}
 
 \emph{to be written}
@@ -541,6 +595,10 @@ existing documents, a rollback to \pkg{longtable 4.13}
   \emph{\LaTeX{} Tagged PDF — A blueprint for a large project}.\\
   \url{https://latex-project.org/publications/indexbyyear/2020/}
 
+\bibitem{33:ltnews32} \LaTeX{} Project Team:
+  \emph{\LaTeXe{} news 31}.\\
+  \url{https://latex-project.org/news/latex2e-news/ltnews31.pdf}
+
 \end{thebibliography}