summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/ltnews34.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/ltnews34.tex')
-rw-r--r--macros/latex-dev/base/ltnews34.tex512
1 files changed, 507 insertions, 5 deletions
diff --git a/macros/latex-dev/base/ltnews34.tex b/macros/latex-dev/base/ltnews34.tex
index 94d2d595df..7497b71879 100644
--- a/macros/latex-dev/base/ltnews34.tex
+++ b/macros/latex-dev/base/ltnews34.tex
@@ -106,14 +106,18 @@
\let\finalvspace\vspace % for document layout fixes
-
+% Undo ltnews's \verbatim@font with active < and >
+\makeatletter
+\def\verbatim@font{%
+ \normalsize\ttfamily}
+\makeatletter
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\providecommand\tubcommand[1]{}
\tubcommand{\input{tubltmac}}
\publicationmonth{November}
-\publicationyear{2021 --- Draft Version}
+\publicationyear{2021 --- Draft Version (with many unfinished blocks)}
\publicationissue{34}
@@ -138,13 +142,313 @@
\emph{write}
-\section{???}
-\emph{write}
+
+
+\section{Hook business}
+
+After the introduction of the hook management system in the 2020
+release of \LaTeX{}~\cite{34:ltnews32} package developers have started
+to make more and more use of the new functionality. This resulted in a
+number of queries showing that some of the documentation was not
+precise enough and that one or the other clarification was
+needed. This has now been addressed in the documentation. The extended
+usage also showed a small number of deficiencies that we thought
+should be corrected now while the adoption rate is still relatively
+small. These are addressed in this release and documented below.
+
+
+\subsection{Providing \cs{ActivateGenericHook}}
+
+The hook management system offers a number of generic hooks, i.e.,
+hooks whose names contain a variable component, for example the name
+of an environment. Predeclaring such hooks as not really feasible
+which is why these hooks use a different mechanism: they are
+implicitly available end spring into life the moment a package or the
+user in the preamble adds code to them using \cs{AddToHook}. The
+kernel offers such hooks for environments \texttt{env/...}, commands
+\texttt{cmd/...}, and files, package or classes, \texttt{file/...},
+\texttt{include/...}, \texttt{package/...}, and \texttt{class/...}.
+
+It is possible to offer generic hooks in packages, e.g., if you have
+hooks that depend on the current language and therefore need the
+language name as part of the hook name and you don't know all possible
+names beforehand.
+
+If you want to offer your generic hooks you do this by using
+\cs{UseHook} or \cs{UseOneTimeHook} in your (package) code, but
+\emph{without declaring the hook} with \cs{NewHook}. Without any
+further work a call to \cs{UseHook} with an undeclared hook name does
+nothing. So as an additional setup step, it is necessary to explicitly
+activate the generic hook with \cs{ActivateGenericHook}.\footnote{Note
+ that in the previous release we offered \cs{ProvideHook} as a means
+ to achieve this effect, but the name was badly chosen so we decided
+ to deprecate it and now offer \cs{ActivateGenericHook} instead
+ because that is what it is meant for.}
+
+Assuming
+that you don't know all the different hook names up front it will
+remain the task of the users of your package to activate the hook
+themselves before adding code to it. For example, Babel offers hooks
+such as \texttt{babel/afterextras/\meta{language}} enabling the user
+to add language specific declarations there. They can then write
+\begin{verbatim}
+\ActivateGenericHook
+ {babel/afterextras/ngerman}
+\AddToHook{babel/afterextras/ngerman}
+ {\color{blue}}
+\end{verbatim}
+after which all German words would be colored blue in the text.
+
+Note that a generic hook produced in this way is always a normal hook.
+
+
+
+
+\subsection{Clear extra hook code for next invocation}
+
+There are a few use cases where it would be helpful if one can cancel
+an earlier use of \cs{AddToHookNext}, for example, when a page is
+discarded with \cs{DiscardShipoutBox} because only some pages of the
+document are printed. For such situations the new command
+\cs{ClearHookNext} is provided.
+%
+\githubissue{565}
+
+
+
+\subsection{Clean up after \cs{UseOneTimeHook}}
+
+Some hooks are meant to be used only once in a document, and any
+further attempt to add code to them causes the code to be executed
+immediately instead of being added to the hook. The initial implementation of
+this concept was very simple and didn't anticipate that packages may try to
+execute a one-time hook several times resulting in the hook code
+being executed repeatedly. Thus, the implementation was fine for
+simple usages (e.g., the \hook{begindocument} hook), but caused
+trouble if the one-time hook was intended, for example, as an
+initialization hook that is used once when a command is first
+called, but then ignored in further calls.
+
+This deficiency has been addressed, and now a one-time hook will only be executed once
+and the hook code is removed after usage to free up the memory.
+%
+\githubissue{565}
+
+
+
+\subsection{Class, package, and include hook improvements}
+
+Classes, packages and include files can only be loaded once in a
+\LaTeX{} document. For that reasons hooks that are specific to such
+files have been made one-time hooks. Beside being more efficient this
+supports the following important use case
+\begin{verbatim}
+\AddToHook{package/varioref/after}
+ { ... apply my customizations if the package
+ gets loaded (or was loaded already) ... }
+\end{verbatim}
+without the need to first test if the package was already loaded
+before.
+%
+\githubissue{623}
+
+
+\subsection{Standardizing generic hook names}
+
+The initial set of generic hooks provided by the \LaTeXe{} kernel had
+two patterns of hook names: ones like
+\verb|env/|\meta{name}\verb|/after|, with the variable (\meta{name})
+part in the middle position, and ones like
+\verb|file/after/|\meta{name}, with the variable part in the third
+position. The coexistence of these two types caused confusion, because
+the user had to remember in which position was the variable part
+supposed to go, and made the code more complicated and slower.
+
+The file-related hooks have been renamed so that the variable part of
+their is in the middle, as with other hooks. The changes were:
+\begin{center}
+ \small\ttfamily
+ \begin{tabular}{l@{\;$\rightarrow$\;}l}
+ \hline
+ \multicolumn{1}{l}{Old name} & \rmfamily New name \\
+ \hline
+ file/before/\meta{name} & file/\meta{name}/before \\
+ file/after/\meta{name} & file/\meta{name}/after \\
+ package/before/\meta{name} & package/\meta{name}/before \\
+ package/after/\meta{name} & package/\meta{name}/after \\
+ class/before/\meta{name} & class/\meta{name}/before \\
+ class/after/\meta{name} & class/\meta{name}/after \\
+ include/before/\meta{name} & include/\meta{name}/before \\
+ include/end/\meta{name} & include/\meta{name}/end \\
+ include/after/\meta{name} & include/\meta{name}/after \\
+ \hline
+ \end{tabular}
+\end{center}
+
+Since this is a breaking change, the old names will still work for a
+while, so that users and package authors have enough time to adjust, and
+a warning will be issued when the old names are used. Eventually the
+deprecated names will be turned into errors and then removed completely.
+%
+\githubissue{648}
+
+
+
+\subsection{Changed how \cs{RemoveFromHook} treats code that isn't in the hook}
+
+In the first version of \cs{RemoveFromHook}, in case the code label
+being removed didn't exist in the hook, a ``removal order'' would be
+queued, and the next time something tried to add that label to the hook,
+the \cs{AddToHook} would be cancelled by the removal order, and no code
+would be added that once. This was so that in principle package loading
+order wouldn't matter. However this implementation didn't work quite as
+intended, because while two \cs{AddToHook} to a given label would be
+removed by a single \cs{RemoveFromHook}, one \cs{RemoveFromHook} could
+not cancel two \cs{AddToHook} to that label, and this asymmetry caused
+confusion and was a recipe for further problems.
+
+The implementation was changed and now \cs{RemoveFromHook} only removes
+labels that already exist in a hook, and will display a warning if they
+don't. For usage across packages, for removing code in a hook, the
+\texttt{voids} relation should be used instead: this relation is
+non-destructive (meaning it can be later reverted with another one), and
+it is truly independent of package loading order, so it should be
+preferred.
+%
+\githubissue{625}
+
+
+
+
+\subsection{???}
+
+%
+\githubissue{000}
+
+
\section{New or improved commands}
+
+\subsection{Added \cs{PackageNote} and \cs{ClassNote}}
+
+\LaTeX{} offers \cs{PackageError} to signal errors that stop
+processing, \cs{PackageWarning} that generates a warning message on the
+terminal, but continues with the processing and also \cs{PackageInfo}
+to provide some information that is only written to the \texttt{.log}
+file. What hasn't existed up to now is a way to provide some
+information on the terminal that is identifying itself as coming from
+a specific package but which isn't claiming to be a warning. Thus,
+packages that wanted to write to the terminal used \cs{PackageWarning}
+even though the information wasn't really warning the user. For this
+we now have \cs{PackageNote} and \cs{PackageNoteNoLine}, that identify
+themselves as \enquote{informational}, but still go to the terminal and
+not only to the transcript.
+
+Similar commands exist for classes and there we have added the missing
+\cs{ClassNote} and \cs{ClassNoteNoLine} as well.
+%
+\githubissue{613}
+
+
+\subsection{New implementation for \cs{counterwithin}}
+
+New implementation for \cs{counterwithout} and \cs{counterwithin} with
+an additional optional arg so it becomes a drop-in replacement for
+amsmath \cs{numberwithin}.
+
+\emph{write appropriate description}
+
+
+
+\subsection{New default for \cs{tracinglostchars}}
+
+In 2021 the \TeX{} engines got enhanced so that \cs{tracinglostchars}
+is now also supporting the value \texttt{3}, turning missing
+characters into errors and not just warnings. This change made us
+realize that \LaTeX{} should use a better default for this parameter
+(so far the warning was only written to the transcript file).
+Using the now available \texttt{3} would really be the best, but for
+compatibility reasons we only set it to \texttt{2} in the kernel.
+However, we recommend adding \cs{tracinglostchars}\texttt{=3} to the
+preamble of documents, because missing glyphs in the output are an
+error and should therefore be properly looked at.
+
+
+
+
+
+
+\subsection{Provide tests for package and class loading}
+
+To test if a package was loaded you can now use \cs{IfPackageLoadedTF}
+\Arg{package} \Arg{true} \Arg{false} and based on the result execute
+different code. It is also possible to check if the package was loaded
+with certain options. This is done with
+\cs{IfPackageLoadedWithOptionsTF}. It takes four arguments:
+\Arg{package}\Arg{option-list}\Arg{true}\Arg{false}. It uses the
+\meta{false} code if at least one option in the \meta{option-list} has
+not been used during loading or if the package hasn't been loaded at
+all.
+%
+Both commands can be used anywhere in the document, i.e., they are not
+restricted to the preamble.\footnote{This is now also true for the
+ corresponding internal commands, e.g., \cs{@ifpackageloaded}, that
+ had this restriction in the past.}
+
+For classes similar commands (\texttt{Package} replaced by
+\texttt{Class} in the name) are provided.
+%
+\githubissue{621}
+
+
+
+
+
+
+
+
+
+\subsection{New \cs{ShowFloat} command}
+
+The package \pkg{fltrace} offers a (fairly low-level but very
+detailed) way to trace \LaTeX's float mechanism. This can help to
+understand why a certain float is placed into a certain region or why
+it shows up unexpectedly on a later page. \LaTeX{} stores floats in
+registers named \cs{bx@A}, \cs{bx@B}, etc., and these names show up in
+the tracing information.
+%
+To display their contents you can now say
+\verb=\ShowFloat{=\textit{identifier}\verb=}= where
+\textit{identifier} is the uppercase letter (or letters) after
+\texttt{bx@} in the register name shown in the tracing. If additional
+registers have been allocated with \cs{extrafloats}, the
+\textit{identifier} can also be a number. The command is generally
+available, whether or not you have loaded \pkg{fltrace}, because it is
+also useful when interpreting the tracing output of the
+\pkg{fewerfloatpages} package.
+
+
+\subsection{Add \pkg{ltcmd} support for \cs{NewCommandCopy} and \cs{ShowCommand}}
+
+Since the 2020-10-01 release (see~\cite{34:ltnews32}), \LaTeX{} provides
+\cs{NewCommandCopy} to copy robust commands, and \cs{ShowCommand} to
+show their definition in the terminal. In the same release, the
+\pkg{xparse} package was integrated in the kernel (now called
+\pkg{ltcmd}). However, the extended support for \cs{NewCommandCopy} and
+\cs{ShowCommand} was not implemented in \pkg{ltcmd}. The present
+\LaTeX{} release ships with that support implemented, so now commands
+defined with \pkg{xparse}/\pkg{ltcmd} can be copied and their definition
+can be easily shown in the terminal without \cs{csname} gymnastics.
+%
+\githubissue{569}
+
+
+
+
+
\subsection{???}
%
@@ -155,6 +459,68 @@
\section{Code improvements}
+\subsection{Detect ``\cs{endfoo}'' when using \cs{NewDocumentEnvironment}}
+
+The \cs{newenvironment} command has always checked that both \cs{foo} and
+\cs{endfoo} do not exist before creating a \texttt{foo} environment. In
+contrast, \cs{NewDocumentEnvironment} has only to date checked for \cs{foo};
+this reflects the fact that historically the code was designed around the
+target of an entirely new format. The behavior of \cs{NewDocumentEnvironment}
+now aligns with \cs{newenvironment}, except that it gives separate errors
+for the existence of \cs{foo} and \cs{endfoo}.
+
+\subsection{Improve ``\cs{begin} ended by'' error message}
+
+In the past it was possible to get an error message stating something
+like \verb=\begin{foo} ended by \end{foo}=. This could happen when the
+environment name was partly hidden inside a macro, because the test was
+comparing the literal strings while the error message expanded the
+strings fully. This has now been changed to show a more sensible error
+message in this instance.
+%
+\githubissue{587}
+
+
+
+\subsection{Additional Extended Latin characters predefined}
+Some additional characters such as \'k (U+1E131) are now pre-defined and
+will work without needing \verb|\DeclareUnicodeCharacter| declarations.
+%
+\githubissue{593}
+
+
+\subsection{Use OpenType version of Latin Modern Upright Italic}
+When Latin Modern is used with the TU encoding under \XeTeX\ or \LuaTeX\
+and fontshape \texttt{ui} is requested, \LaTeX\ now uses the OpenType
+version instead of substituting the (T1 encoded) Type 1 version.
+
+
+\subsection{Pick up all arguments to \cs{contentsline}}
+
+The \cs{contentsline} commands in the TOC file are always followed by
+four arguments, the last one being empty by default and only used by
+\pkg{hyperref}. The \cs{contentsline} command itself only used the
+first three arguments and relied on the fourth being empty (and thus
+doing no harm). But this assumption is not always correct, e.g., if
+you use \pkg{hyperref} and then remove it from the preamble.
+
+So now we pick up all four arguments and save the last one away, so
+that it can be used by \pkg{hyperref}.
+%
+\githubissue{633}
+
+
+\subsection{Fix dropping math lists in \LuaTeX\ callbacks}
+
+The \LuaTeX\ callbacks \texttt{pre\_mlist\_to\_hlist\_filter}
+and \texttt{post\_mlist\_to\_hlist\_filter} no longer create an error if
+the callback handler indicates to remove the entire math block.
+%
+\githubissue{644}
+
+
+
+
\subsection{???}
%
@@ -163,7 +529,82 @@
-\section{Changes to packages in the \pkg{graphics} category}
+\section{Bug fixes}
+
+\subsection{Replicate argument processors for all embellishments}
+
+There was a bug in \pkg{ltcmd} (former \pkg{xparse}) that caused
+commands to misbehave if they were defined with embellishments and
+argument processors. In that case, only one (possibly void) argument
+processor would be added to the full set of embellishment arguments,
+resulting in too few processors in some cases, leading to unpredictable
+behavior. This bug has been fixed by applying the same argument
+processors to all the embellishments in a set, so a declaration like:
+\begin{verbatim}
+\NewDocumentCommand\foo{>{\TrimSpaces}e{_^}}
+ {(#1)[#2]}
+\foo^{ a }_{ b }
+\end{verbatim}
+will now correctly apply \cs{TrimSpaces} to both arguments.
+%
+\githubissue{639}
+
+
+
+\subsection{Correct case changes for \cs{ij} and \cs{IJ}}
+
+
+The ligatures \enquote{\ij} and \enquote{\IJ}, as used in Dutch,
+are only available in most \TeX{} fonts, if the commands \cs{ij} or
+\cs{IJ} are used or when you enter them as UTF-8 characters U+0133 or
+U+0132.
+%
+However, when using \texttt{OT1} or \texttt{T1} encoded fonts in
+\pdfTeX, the upper or lower casing with \cs{MakeUppercase} and
+\cs{MakeLowercase} would always fail regardless of the input method.
+This has now been corrected. At the same time we improved the
+hyphenation results for words containing this ligature (when
+typesetting is done in \texttt{OT1} encoding).
+%
+\githubissue{658}
+
+
+
+\subsection{Improve handling of legacy \cs{bfdefault} changes}
+
+In the past, changes to the font series defaults were made by directly
+altering \cs{bfdefault} or \cs{mddefault}. Since 2020 there is now
+\cs{DeclareFontSeriesDefault} that allows more granular control,
+i.e., with that declaration you can alter the default for individual meta
+font families, for example, by only altering the bold settings for the
+sans serif family without changing it for \cs{rmfamily} or \cs{ttfamily}.
+See~\cite{34:ltnews31} for more details.
+
+For backwards compatibility, changing \cs{bfdefault} with
+\cs{renewcommand} remained possible. If used, it alters the setting
+for all meta families in one go. This cannot be done when the
+\cs{renewcommand} happens and was therefore delayed until the next
+time \cs{bfseries} or \cs{mdseries} was executed.
+
+However, the problem with that
+approach was that any call to \cs{DeclareFontSeriesDefault} that
+happened in the mean time was overwritten---the two approaches didn't
+work well side by side. This is a problem because older font packages
+use the legacy method while newer ones use
+\cs{DeclareFontSeriesDefault}. This has now been corrected by changing
+\cs{DeclareFontSeriesDefault} to do any necessary resetting prior to
+setting new defaults.
+%
+\githubissue{663}
+
+
+\subsection{Use of \# in \cs{textbf} and similar commands}
+Previously you could not use the macro parameter character \# in inline functions
+in the argument of \cs{texbf} and similar text font commands.
+An internal definition is now guarded with \cs{unexpanded}
+so that \# does not generate an error.
+%
+\githubissue{665}
\subsection{???}
@@ -173,8 +614,56 @@
+
+
+
+\section{Changes to packages in the \pkg{graphics} category}
+
+
+\subsection{Key for alt text}
+A new key \texttt{alt} has been added to \verb|\includegraphics| allowing specification
+of an alternative text for accessibility.
+This is unused by default but may be used by extension packages and possible future use.
+%
+\githubissue{651}
+
+
+
\section{Changes to packages in the \pkg{tools} category}
+\subsection{\pkg{varioref}: Improve missing label handling}
+
+If an undefined label is referenced, \pkg{varioref} makes a default
+definition so that later processing finds the right structure (two
+brace groups inside \cs{r@}\meta{label}) However, if \pkg{nameref} or
+\pkg{hyperref} is loaded, the data structure changes to five
+arguments, resulting in low-evel errors in some cases. The code has
+been changed to avoid these errors.
+%
+\sxissue{603948}
+
+
+\subsection{\pkg{array}: Cancel \cs{mathsurround} for \env{tabular}}
+
+A \env{tabular} environment is internally typeset as an \env{array}
+environment with special settings and therefore in math mode. This
+math group should not get any \cs{mathsuround} added as it isn't a
+real formula because otherwise the spacing around the \env{tabular}
+changes. This bug has been there forever (which means not many people
+use \cs{mathsurround} or noticed the difference). Anyhow, this now got
+fixed.
+%
+\githubissue{614}
+
+\subsection{\pkg{longtable}: Improve behavior after a section heading}
+The \env{longtable} environment now sets the \cs{@nobreakfalse} flag so that
+spacing and indentation changes after a section heading are not triggered by
+a paragraph which follows a table which starts a section. Similarly a test for
+\cs{if@noskipsec} added so that a table follows a run-in heading
+rather than appearing before it.
+%
+\githubissue[s]{131 and 173}
+
\subsection{???}
%
@@ -182,6 +671,15 @@
\section{Changes to packages in the \pkg{amsmath} category}
+\subsection{Improve compability with hyperref}
+
+When \pkg{hyperref} is used, incrementing a counter creates anchors and this can affect spacing.
+For a long time \pkg{hyperref} patched the \env{equation} environment to
+avoid some of the side effects. This patch has now been moved directly into \pkg{amsmath}.
+Additionally,
+a \cs{mathopen} has been added to avoid that the anchor affects a following unary symbol.
+%
+\githubissue{652}
\subsection{???}
@@ -205,6 +703,10 @@
\emph{\LaTeX{} documentation on the \LaTeX{} Project Website}.\\
\url{https://latex-project.org/help/documentation/}
+\bibitem{34:ltnews31} \LaTeX{} Project Team:
+ \emph{\LaTeXe{} news 31}.\\
+ \url{https://latex-project.org/news/latex2e-news/ltnews31.pdf}
+
\bibitem{34:ltnews32} \LaTeX{} Project Team:
\emph{\LaTeXe{} news 32}.\\
\url{https://latex-project.org/news/latex2e-news/ltnews32.pdf}