diff options
Diffstat (limited to 'macros/latex-dev/base/ltnews34.tex')
-rw-r--r-- | macros/latex-dev/base/ltnews34.tex | 512 |
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} |